# Stage 2 quality journal

Date: 2026-07-13  
Scope: stabilize and optimize the real local Reliora agent workflow without adding new infrastructure categories.

## Objective and baseline

Stage 1/Part 1 proved a deterministic local CLI and an opt-in Codex/generic instruction lifecycle. The starting Stage 2 baseline still had several workflow gaps:

- the README was 362 lines and delayed the Codex-first value path;
- generated instructions used one command spelling across platforms;
- feedback was a binary success/failure counter without effect, impact, or safe notes;
- retrieval returned an opaque number rather than evidence-calibrated levels and components;
- there was no compact `list`, aggregate `stats`, lineage, stable logical locator, or duplicate warning;
- reflection did not explicitly search the candidate before saving;
- managed instructions were version 1;
- Part 1 compatibility existed only implicitly rather than as a fixture-backed guarantee.

The implementation retained the working local storage, validation, secret screening, atomic writes, corrupt-record isolation, explained lexical retrieval, JSON envelopes, stdin record path, package layout, and safe managed-marker lifecycle.

## Synthetic HookVault evaluation data

Stage 2 uses a deliberately synthetic, repository-owned fixture set rather than claiming access to an external product dataset:

| Fixture | Retrieval pressure |
| --- | --- |
| Atomic file deduplication | race safety, content identity, atomic rename |
| Stripe raw-body verification | provider-specific signing bytes and middleware order |
| Slack signature verification | provider-specific base string and replay window |
| Filename identity migration | collision preflight, restartability, migration evidence |
| Generic webhook note | plausible but low-specificity competitor |

The fixture test confirms Stripe queries rank the Stripe/raw-body lesson first and filename migration queries rank the migration lesson above the generic note. This validates relative relevance and truthful levels without presenting the corpus as production evidence.

## Implemented changes

### Discoverability and platform behavior

- Replaced the long README with a short Codex-first first screen and nine focused guides.
- Generated commands use `reliora.cmd` on Windows and `reliora` on Unix.
- Documented PowerShell 5.1, PowerShell 7, Command Prompt, global, local/npm-exec, and tarball paths without recommending execution-policy changes.
- Added `list` filters/sorting and local `stats`, both with compact versioned JSON contracts and corrupt-record warnings.

### Experience evidence

- Added outcomes `success`, `partial`, `failure`, `not-applicable`, and `outdated` while preserving `--success`, `--failure`, `successes`, and `failures`.
- Added optional low/medium/high impact, 500-character secret-screened notes, and a bounded 100-event audit trail.
- Added optional `derivedFrom` and `appliedExperiences` with UUID, existence, duplicate, cross-list duplicate, and self-reference validation.
- Added stable `reliora://project/.../experience/...` locators that do not expose storage paths.

### Retrieval and reflection

- Preserved the raw deterministic score and exposed the actual weighted/scaled components.
- Added strong/moderate/weak levels derived from explicit query coverage and relevance thresholds.
- Kept feedback influence bounded so generic popularity cannot dominate relevance.
- Added soft, non-blocking similarity warnings before record writes.
- Upgraded managed instructions to workflow v2: top-three review, trust boundary, effect-based feedback, candidate pre-search, lineage rules, and concise notifications.

### Compatibility and migration

- Kept stored experience schema version 1 and JSON envelope output version 1.
- A checked-in Part 1 fixture without lineage or extended feedback loads with zero/empty defaults.
- There is no eager library rewrite. Only a record receiving new feedback is normalized on write.
- Legacy `storageId`, nested `experience`, flat success/failure search counters, and binary feedback flags remain available.
- Managed instruction v1→v2 setup replaces only the marked block, preserves text before/after it and line endings, writes one block, and updates metadata. Ambiguous markers or unsafe state still fail closed.

## Rejected or deferred changes

The following were intentionally not added because they expand the product category or hide unverified behavior:

- MCP servers, editor hooks, shell observation, background daemons, chat ingestion, and command interception;
- embeddings, vector databases, remote ranking, LLM calls, network sync, telemetry, and cloud accounts;
- automatic acceptance of a strong match or automatic recording without agent judgment and task verification;
- blocking duplicate enforcement, which would collapse legitimate context/applicability refinements;
- global schema rewrites and filesystem paths as public identifiers;
- execution-policy modification on Windows;
- claims that synthetic HookVault fixtures represent production usage.

Semantic retrieval, richer recovery tooling, team synchronization, policy-controlled sharing, and larger empirical ranking calibration remain possible Stage 3 work. They are not simulated in Stage 2.

## Verification evidence

Final local verification on Windows used Node.js 24.17.0 while CI remains pinned to the documented minimum Node.js 20 on both `windows-latest` and `ubuntu-latest`.

| Gate | Result |
| --- | --- |
| Offline clean install from integrity-matched npm cache | Pass: removed the existing tree and installed all 110 development packages from the lockfile |
| `npm.cmd test` | Pass: 44 unit/integration tests, including 11 Stage 2 tests |
| `npm.cmd run typecheck` | Pass |
| `npm.cmd run lint` | Pass |
| `npm.cmd run demo` | Pass |
| `npm.cmd run test:package` | Pass: installed human CLI cycle and required files |
| `npm.cmd run test:agent-package` | Pass: installed managed-agent lifecycle |
| `npm.cmd run test:stage2-package` | Pass: 22 checkpoints |
| `npm.cmd pack --dry-run` | Pass; docs, Stage 2 runtime, templates, README, and license included |
| `npm.cmd audit --offline --audit-level=high` | Pass against the machine's existing npm advisory/cache state: 0 vulnerabilities |

The sandbox rejected a live registry audit because it would disclose dependency metadata without separate authorization. No network workaround was attempted. Instead, the clean install and exact audit were run with `--offline` against a temporary cache seeded only with the 110 lockfile integrity-addressed tarballs and existing npm index/advisory cache. This proves lockfile reproducibility and the cached vulnerability result, but it does not claim that the advisory cache is newer than the local machine state.

The 22-checkpoint tarball smoke uses a clean temporary project and verifies the platform command shim, npm-exec resolution, isolated global prefix, Codex v2 setup, template compatibility, stdin record, locator, soft duplicate warning, valid lineage, ranking level/breakdown, show, legacy and extended feedback, list filters, stats, v1 upgrade, safe removal, and experience preservation.

Manual shell validation on this machine is recorded separately in the final verification pass:

| Surface | Result |
| --- | --- |
| Windows PowerShell 5.1.26100.8655 | Pass: installed tarball, v2 setup, legacy UTF-16 `>` template redirection, record/locator, strong explained search, partial feedback, list, stats, safe remove, and preserved user text/data; no policy change |
| PowerShell 7 | Unavailable on this machine; platform rendering remains covered by tests and cross-OS CI |
| Command Prompt | Pass: the installed `.cmd` shim drove the 22-checkpoint Stage 2 package workflow through `cmd.exe` |
| npm-exec/npx local resolution | Pass with installed local tarball, 0.1.0 |
| isolated global tarball prefix | Pass with installed global shim, 0.1.0 |

## Quality scoring

Scores are evidence-based self-assessment, not a claim of perfection. Every category clears the Stage 2 target of 90 while leaving room for the documented limitations.

| Category | Score | Evidence and remaining gap |
| --- | ---: | --- |
| Functional completeness | 96 | Requested CLI/model/workflow behavior is implemented; semantic retrieval is deferred. |
| Part 1 compatibility | 96 | Fixture, aliases, counters, envelope fields, and installed flows pass; broader historical corpora are unavailable. |
| Ranking truthfulness | 94 | Real components and deterministic thresholds are tested; thresholds are not calibrated on a large empirical corpus. |
| Agent workflow quality | 95 | v2 covers search, trust, feedback, reflection, duplicates, lineage, and notification; real-agent behavior still depends on the host agent. |
| Human CLI usability | 94 | Compact list/stats, help, remediation, and stable locators pass; no interactive TUI is intended. |
| Security and privacy | 95 | Local/no-network architecture, strict validation, secret screening, and fail-closed instruction management; pattern screening cannot guarantee discovery of every secret. |
| Windows and Unix portability | 94 | Platform rendering and Windows shims are tested, CI spans both OS families; every shell distribution cannot be reproduced locally. |
| Packaging and release confidence | 96 | Three clean tarball smokes, 22 Stage 2 checkpoints, npm-exec/global paths, and dry-run contents; registry publication is out of scope. |
| Documentation and discoverability | 95 | Short Codex-first README plus focused linked guides and link regression test; user-study evidence is not available. |
| Maintainability and testability | 93 | Separated model/ranking/observability/locator/duplicate modules and 44 tests; fixed-weight ranking will require deliberate future calibration. |

## Stage 2 guarantees

Within the tested scope, Stage 2 guarantees deterministic local operation, no runtime network or LLM dependency, opt-in agent instructions, bounded validated records and notes, transparent Part 1 loading, non-destructive managed upgrades/removal, evidence-exposing lexical ranking, advisory duplicates, project-local lineage, stable logical locators, and package behavior through the installed command shim.

It does not guarantee that an agent will obey instructions, that a retrieved lesson is correct, that lexical search finds every semantic equivalent, or that secret pattern matching catches arbitrary sensitive information. Those boundaries are explicit in the product workflow and documentation.

## Completion matrix

| Objective requirement | Authoritative evidence |
| --- | --- |
| Short Codex-first README and focused docs | README is 102 lines; documentation-link regression test reads all nine active guides |
| Platform-aware Windows/Unix commands | `platformCliCommand` unit coverage, v2 instruction tests, PS 5.1/CMD manual shims, npm-exec/global tarball checks, and Windows/Ubuntu CI matrix |
| `list` and `stats` | source contract tests plus installed Stage 2 checkpoints 20–21 |
| Extended compatible feedback | all five outcomes, impact, secret-screened bounded notes, 100-event cap, legacy aliases/counters, CLI JSON, and installed checks 15–19 |
| Optional validated lineage | UUID/existence/duplicate/cross-list/self/foreign-project tests and installed lineage checkpoint 12 |
| Truthful match levels and score breakdown | component reconstruction test, threshold documentation, HookVault ranking checks, and installed checkpoint 13 |
| Reflection v2 and soft duplicates | managed-instruction assertions, duplicate non-blocking source test, and installed checkpoint 11 |
| Stable logical locators | round-trip/no-filesystem test and installed record/search/show checks |
| Transparent Part 1 loading | checked-in legacy fixture, default assertions, byte-for-byte no-rewrite assertion, and preserved legacy package flows |
| Safe managed v1→v2 upgrade | user-text/single-marker unit test and installed checkpoint 22 with safe removal/data preservation |
| Synthetic HookVault patterns | five labeled repository fixtures and two provider/migration retrieval assertions |
| Comprehensive package verification | human package smoke, agent package smoke, 22-checkpoint Stage 2 tarball smoke, package dry-run, local npm-exec, and isolated global install |
| Evidence-backed 90+ quality | ten scored categories above, each 93–96 with an explicit residual limitation |
| Local-only architecture and no Stage 3 expansion | zero runtime dependencies, no network/LLM/daemon adapter in `src`, explicit trust boundary, and deferred-scope list |