@dailephd/my-frontend-observer 0.9.1 → 0.10.1

package/docs/DEVELOPMENT.md

@@ -1,237 +1,240 @@
-# Development
-
-The released v0.9.1 package is published as
-`@dailephd/my-frontend-observer@0.9.1` (CLI `my-frontend-observer`). It keeps
-the v0.8.1 project workflow and adds structured visual annotation.
-
-The v0.8.1 workflow is exercised through unit and real-Chromium tests. Project fixtures use `init`, `capture baseline`, and `check`; coding-agent consumers use bounded `check --json`. `tests/browser/projectCheckWorkflow.test.ts` covers REVIEW_REQUIRED, contract FAIL-to-PASS, reference FAIL/PASS/BLOCKED, incomparable BLOCKED, current history, and contained acceptance paths. `scripts/ci/runPackedViewerSmoke.mjs` is the single installed-package viewer/project-workflow smoke owner: it repeats REVIEW_REQUIRED and unchanged-contract FAIL-to-PASS before alias-aware viewer proof. Run the full unit, browser, security, build, documentation, and packed-consumer validations before release readiness.
-
-Install the current scaffold with `npm install`. Node.js 24+ is required.
-
-Since Batch 2, the package depends on `playwright` for the Chromium browser
-boundary. Install the browser binary once per machine with:
-
-```powershell
-npx playwright install chromium
-```
-
-The applicable foundation validation chain is:
-
-```powershell
-npm run typecheck
-npm run lint
-npm test
-npm run test:browser
-npm run build
-npm run check:docs
-npm pack --dry-run
-```
-
-`npm test` runs the fast unit suite only (`tests/unit/`; as of v0.8 Batch 8,
-1156 passing tests across 63 files, including the v0.6 bounded-agent-context
-projection/correlation and v0.8 viewer-server coverage). `npm run
-test:browser` runs the real-Chromium integration suite (`tests/browser/`; as
-of v0.8 Batch 8, 178 passing tests across 19 files, including the v0.8
-viewer/PWA real-browser proof) against deterministic local fixtures under
-`tests/fixtures/` and requires the Chromium binary above to be installed
-first; it is kept out of `npm test` because it launches a real browser and
-is slower. Exact counts drift as the suite grows - run the commands above
-for the current numbers rather than trusting this document.
-
-## Hard/security/acceptance gate isolation
-
-Tests explicitly designated `HARD GATE`, `SECURITY GATE`, or
-`ACCEPTANCE GATE` must be independently reproducible. A passing full suite is
-not sufficient evidence if the gate itself only succeeds because another test
-ran first or because a prior run left browser/cache/filesystem state behind.
-
-For browser-based gates, the gate must own or explicitly establish every
-precondition material to its claim. That includes disposable evidence state,
-servers, browser profiles/contexts, service-worker control, relevant cache
-state, and cleanup. Fixed persistent profiles must not be used as hidden
-fixtures for a hard acceptance claim.
-
-v0.9.1 applies this rule to the PWA server-down safety proof in
-`tests/browser/pwaHardening.test.ts`. The hard gate owns its evidence root,
-viewer server, temporary Chromium profile, and context. It must pass when
-selected alone and must also continue to pass in the complete browser and
-security suites.
-
-Run the gate by itself with:
-
-```powershell
-npm run test:pwa-hard-gate
-```
-
-Run this command when working on PWA, service-worker, viewer-server, or
-security behavior. It must pass on its own, not only after other tests have
-run. `npm run test:security` also runs it after the rest of the security
-suite. See `docs/plans/v0.9.1-implementation-plan.md`.
-
-ROADMAP v0.1 and Project Milestone 1 require browser-level validation once the
-observation capability is planned and implemented. Static checks must not later
-be substituted for that required browser evidence. `npm run test:browser` is
-that required browser evidence and covers the full source-checkout v0.1
-workflow end to end: page/target evidence, atomic artifact persistence, and
-the real `observe` CLI (including a built `node dist/cli.js observe ...`
-smoke run) are all implemented and covered, including a deterministic
-real-navigation-failure case (distinct from a readiness timeout or a
-pre-launch safety rejection).
-
-For maintainers validating the package boundary itself (not required for
-routine development): `npm pack --dry-run` inspects the tarball contents;
-installing the real tarball (`npm pack --json`, then `npm install
-<tarball>` in a clean temporary directory) and running the installed bin
-against a disposable local HTTP target is the way to confirm the packaged
-CLI performs a real observation independent of the source checkout. This is
-local package validation only, not a release procedure.
-
-`npm run test:security` runs only the safety-relevant subset of the suite
-(`tests/unit/policy.test.ts` plus the real-Chromium enforcement cases in
-`tests/browser/chromiumAdapter.test.ts`) - a discoverable entry point for
-security review tooling, not a replacement for `npm test`/`npm run
-test:browser`.
-
-`scripts/ci/runPackedObservationSmoke.mjs <tarball-path>` is the same
-packed-candidate smoke described above, packaged as a reusable script: it
-installs the given tarball into a fresh temporary consumer directory,
-installs Chromium via that consumer's own Playwright dependency, runs the
-installed bin against a disposable local HTTP target it creates itself, and
-validates the resulting artifact - exiting nonzero on any contract failure.
-It is what `.github/workflows/pre-release-readiness.yml` runs identically on
-Windows, Linux, and macOS against one shared candidate tarball (see
-`docs/CI_CD.md`); it can also be run locally the same way the workflow runs
-it. It is readiness/CI infrastructure only, not part of the published
-package and never imported by production code. In the same run it
-exercises the legacy CSS-shorthand `--target` packed-observation shape,
-the structured semantic `--targets-file` shape, a `window-scroll-by`
-scroll scenario, and a `target-scroll-by` scroll scenario - see
-`docs/CI_CD.md` for the current readiness coverage.
-
-`scripts/dev/builtCliTargetsFileSmoke.mjs` is a separate, narrower v0.2
-development smoke, added alongside the `--targets-file` implementation: it
-runs the built `dist/cli.js` directly (`node dist/cli.js observe
---targets-file ...`) against an inline disposable local HTTP fixture and a
-temporary JSON target file, proving a real semantic observation persists a
-valid schema-`1.2.0` artifact with no packed-tarball step involved. Run it
-locally after `npm run build`:
-
-```powershell
-node scripts/dev/builtCliTargetsFileSmoke.mjs
-```
-
-`scripts/dev/builtCliScrollScenarioSmoke.mjs` is the v0.3 equivalent, added
-alongside the `--scroll-scenario-file` implementation: it runs the built
-`dist/cli.js` directly against an inline disposable local HTTP fixture,
-once with a temporary `window-scroll-by` scenario file and once with a
-temporary structured `--targets-file` plus a `target-scroll-by` scenario
-file, proving both real runtime scroll actions persist a valid
-schema-`1.2.0` artifact with populated `scrollScenarioEvidence`,
-scenario-file path privacy, and target-application immutability. Run it
-locally after `npm run build`:
-
-```powershell
-node scripts/dev/builtCliScrollScenarioSmoke.mjs
-```
-
-`scripts/dev/builtCliCompareSmoke.mjs` is the v0.4 equivalent, added
-alongside the `compare` command implementation (shipped as part of the
-published `0.4.0` package - see `docs/CURRENT_STATE.md`): it runs the built
-`dist/cli.js` twice as
-`observe` against an inline disposable local HTTP fixture whose served
-content changes deterministically between the two runs (a real moved/
-resized target, and a page-width transition from fitting to exceeding the
-viewport), then runs the built `dist/cli.js compare` against the two
-resulting persisted observation artifacts. It validates artifact kind/
-schema `1.0.0`, `comparability: "comparable"`, source observation
-references, at least one real `moved` difference and one real page-width
-relationship change, that the comparison directory contains `manifest.json`
-only, that no operational filesystem path leaked into the persisted
-manifest, and that both source observation manifests are byte-identical
-before and after the comparison ran. Run it locally after `npm run build`:
-
-```powershell
-node scripts/dev/builtCliCompareSmoke.mjs
-```
-
-`scripts/dev/builtCliFrontendContractsSmoke.mjs` is the v0.5 equivalent,
-added alongside the `approve-baseline`/`save-change-contract`/
-`evaluate-contract` command implementations (shipped as part of the
-published `0.5.0` package - see `docs/CURRENT_STATE.md`). Unlike the other dev smokes, it needs no Chromium
-at all: it hand-writes deterministic, schema-`1.2.0`-valid observation
-manifests directly to a temporary directory (preserving the public
-observation artifact contract without a real browser capture), then runs
-the built `dist/cli.js` for `compare`, `approve-baseline`,
-`save-change-contract`, and `evaluate-contract` - twice for the final
-step, once without `--enforce` and once with it, against the same
-milestone-signature contract (requested navigation shrink = pass, expected
-workspace expansion = pass, protected right-rail width = fail, preserved
-unclipped navigation = fail, overall = `FAIL`). It validates both exit
-codes (`0` without `--enforce`, nonzero with it), that both invocations
-persist byte-for-byte semantically identical evaluation evidence
-(`evaluationRequestId` and `clauseResults` equal), that the evaluation
-directory contains `manifest.json` only, that no operational filesystem
-path leaked into either persisted evaluation manifest, and that every
-source observation/comparison/contract artifact remains unmodified. Run it
-locally after `npm run build`:
-
-```powershell
-node scripts/dev/builtCliFrontendContractsSmoke.mjs
-```
-
-`scripts/dev/builtCliFrontendContractsBrowserSmoke.mjs` is the v0.5 Batch 5
-real-browser equivalent, added alongside
-`tests/browser/cliFrontendContracts.test.ts`. Unlike the Chromium-free
-`scripts/dev/builtCliFrontendContractsSmoke.mjs` above, this one launches a
-real disposable local HTTP fixture and real Playwright Chromium, then drives
-the built `dist/cli.js` through the complete `observe` → `approve-baseline`
-→ `save-change-contract` → `observe` → `compare` → `evaluate-contract`
-sequence twice: once against a candidate whose served content produces a
-fully successful contract change (all clauses `pass`, overall `PASS`), and
-once against a candidate that reproduces the milestone-signature failure - a
-real observed navigation clipping regression and a real observed right-rail
-width regression alongside an otherwise-successful requested/expected-
-dependent change (overall `FAIL`). It validates the same `--enforce`
-exit-code/identity behavior, screenshot-free evaluation directory, source
-immutability, and path-privacy properties as the Chromium-free smoke, but
-against genuine rendered geometry instead of hand-constructed artifacts. Run
-it locally after `npm run build` (Chromium must already be installed):
-
-```powershell
-node scripts/dev/builtCliFrontendContractsBrowserSmoke.mjs
-```
-
-Since v0.8 Batch 1, `npm run build` also builds the browser-side viewer app
-(`viewer/`) with Vite into `dist/viewer` (see `docs/ARCHITECTURE.md` "v0.8
-Batch 1"). `npm run typecheck` additionally type-checks `viewer/tsconfig.json`
-alongside the existing `tsconfig.json`. To smoke-test the built viewer
-locally after `npm run build`:
-
-```powershell
-node dist/cli.js view --root <evidence-root> --no-open
-```
-
-optionally adding `--bindings-file <json-file>` and/or `--context-file
-<json-file>` (see `docs/COMMANDS.md#view` for their exact shapes), then open
-the printed `http://127.0.0.1:4319` URL in a browser (or stop with Ctrl+C).
-This starts a real, loopback-only server serving the actual built PWA. As of
-v0.8 (all eight implementation batches), it reads `--root` only for bounded,
-read-only evidence discovery through the existing canonical
-readers/classifiers - it never writes to `--root` or modifies any artifact
-under it. The v0.9 annotation authoring surface (implemented, not yet
-released) is available only from the project-aware `node dist/cli.js view`
-inside an initialized project, never from `--root`. Its end-to-end browser
-proof is `tests/browser/v09IntegratedAcceptance.test.ts`, and its packed
-installed proof is `scripts/ci/runPackedV09AnnotationSmoke.mjs`.
-
-Unlike `scripts/ci/runPackedObservationSmoke.mjs`, none of these five dev
-smokes is wired into any CI workflow or is a release gate - they are
-source-checkout development evidence only, proving the built CLI's
-`--targets-file`/`--scroll-scenario-file`/`compare`/frontend-contract
-command behavior without installing a packed tarball or requiring
-cross-platform infrastructure. None is part of the published package.
-Cross-platform packed validation of the v0.1-v0.5 observation/compare/
-contract behavior is `scripts/ci/runPackedObservationSmoke.mjs`'s
-responsibility (see `docs/CI_CD.md`) - the same script, against the same
-single candidate tarball per platform, now including the v0.5 contract/
-evaluation CLI.
+# Development
+
+The current released package is
+`@dailephd/my-frontend-observer@0.10.1` (CLI `my-frontend-observer`). It
+includes the v0.8.1 project workflow, structured visual annotation, and the
+v0.10 Visual Change workflow and v0.10.1 project-check baseline-context
+replay. Explicit-state replay preserves declared identity metadata and does
+not establish application or session state.
+
+The v0.8.1 workflow is exercised through unit and real-Chromium tests. Project fixtures use `init`, `capture baseline`, and `check`; coding-agent consumers use bounded `check --json`. `tests/browser/projectCheckWorkflow.test.ts` covers REVIEW_REQUIRED, contract FAIL-to-PASS, reference FAIL/PASS/BLOCKED, incomparable BLOCKED, current history, and contained acceptance paths. `scripts/ci/runPackedViewerSmoke.mjs` is the single installed-package viewer/project-workflow smoke owner: it repeats REVIEW_REQUIRED and unchanged-contract FAIL-to-PASS before alias-aware viewer proof. Run the full unit, browser, security, build, documentation, and packed-consumer validations before release readiness.
+
+Install the current scaffold with `npm install`. Node.js 24+ is required.
+
+Since Batch 2, the package depends on `playwright` for the Chromium browser
+boundary. Install the browser binary once per machine with:
+
+```powershell
+npx playwright install chromium
+```
+
+The applicable foundation validation chain is:
+
+```powershell
+npm run typecheck
+npm run lint
+npm test
+npm run test:browser
+npm run build
+npm run check:docs
+npm pack --dry-run
+```
+
+`npm test` runs the fast unit suite only (`tests/unit/`; as of v0.8 Batch 8,
+1156 passing tests across 63 files, including the v0.6 bounded-agent-context
+projection/correlation and v0.8 viewer-server coverage). `npm run
+test:browser` runs the real-Chromium integration suite (`tests/browser/`; as
+of v0.8 Batch 8, 178 passing tests across 19 files, including the v0.8
+viewer/PWA real-browser proof) against deterministic local fixtures under
+`tests/fixtures/` and requires the Chromium binary above to be installed
+first; it is kept out of `npm test` because it launches a real browser and
+is slower. Exact counts drift as the suite grows - run the commands above
+for the current numbers rather than trusting this document.
+
+## Hard/security/acceptance gate isolation
+
+Tests explicitly designated `HARD GATE`, `SECURITY GATE`, or
+`ACCEPTANCE GATE` must be independently reproducible. A passing full suite is
+not sufficient evidence if the gate itself only succeeds because another test
+ran first or because a prior run left browser/cache/filesystem state behind.
+
+For browser-based gates, the gate must own or explicitly establish every
+precondition material to its claim. That includes disposable evidence state,
+servers, browser profiles/contexts, service-worker control, relevant cache
+state, and cleanup. Fixed persistent profiles must not be used as hidden
+fixtures for a hard acceptance claim.
+
+v0.9.1 applies this rule to the PWA server-down safety proof in
+`tests/browser/pwaHardening.test.ts`. The hard gate owns its evidence root,
+viewer server, temporary Chromium profile, and context. It must pass when
+selected alone and must also continue to pass in the complete browser and
+security suites.
+
+Run the gate by itself with:
+
+```powershell
+npm run test:pwa-hard-gate
+```
+
+Run this command when working on PWA, service-worker, viewer-server, or
+security behavior. It must pass on its own, not only after other tests have
+run. `npm run test:security` also runs it after the rest of the security
+suite. See `docs/plans/v0.9.1-implementation-plan.md`.
+
+ROADMAP v0.1 and Project Milestone 1 require browser-level validation once the
+observation capability is planned and implemented. Static checks must not later
+be substituted for that required browser evidence. `npm run test:browser` is
+that required browser evidence and covers the full source-checkout v0.1
+workflow end to end: page/target evidence, atomic artifact persistence, and
+the real `observe` CLI (including a built `node dist/cli.js observe ...`
+smoke run) are all implemented and covered, including a deterministic
+real-navigation-failure case (distinct from a readiness timeout or a
+pre-launch safety rejection).
+
+For maintainers validating the package boundary itself (not required for
+routine development): `npm pack --dry-run` inspects the tarball contents;
+installing the real tarball (`npm pack --json`, then `npm install
+<tarball>` in a clean temporary directory) and running the installed bin
+against a disposable local HTTP target is the way to confirm the packaged
+CLI performs a real observation independent of the source checkout. This is
+local package validation only, not a release procedure.
+
+`npm run test:security` runs only the safety-relevant subset of the suite
+(`tests/unit/policy.test.ts` plus the real-Chromium enforcement cases in
+`tests/browser/chromiumAdapter.test.ts`) - a discoverable entry point for
+security review tooling, not a replacement for `npm test`/`npm run
+test:browser`.
+
+`scripts/ci/runPackedObservationSmoke.mjs <tarball-path>` is the same
+packed-candidate smoke described above, packaged as a reusable script: it
+installs the given tarball into a fresh temporary consumer directory,
+installs Chromium via that consumer's own Playwright dependency, runs the
+installed bin against a disposable local HTTP target it creates itself, and
+validates the resulting artifact - exiting nonzero on any contract failure.
+It is what `.github/workflows/pre-release-readiness.yml` runs identically on
+Windows, Linux, and macOS against one shared candidate tarball (see
+`docs/CI_CD.md`); it can also be run locally the same way the workflow runs
+it. It is readiness/CI infrastructure only, not part of the published
+package and never imported by production code. In the same run it
+exercises the legacy CSS-shorthand `--target` packed-observation shape,
+the structured semantic `--targets-file` shape, a `window-scroll-by`
+scroll scenario, and a `target-scroll-by` scroll scenario - see
+`docs/CI_CD.md` for the current readiness coverage.
+
+`scripts/dev/builtCliTargetsFileSmoke.mjs` is a separate, narrower v0.2
+development smoke, added alongside the `--targets-file` implementation: it
+runs the built `dist/cli.js` directly (`node dist/cli.js observe
+--targets-file ...`) against an inline disposable local HTTP fixture and a
+temporary JSON target file, proving a real semantic observation persists a
+valid schema-`1.2.0` artifact with no packed-tarball step involved. Run it
+locally after `npm run build`:
+
+```powershell
+node scripts/dev/builtCliTargetsFileSmoke.mjs
+```
+
+`scripts/dev/builtCliScrollScenarioSmoke.mjs` is the v0.3 equivalent, added
+alongside the `--scroll-scenario-file` implementation: it runs the built
+`dist/cli.js` directly against an inline disposable local HTTP fixture,
+once with a temporary `window-scroll-by` scenario file and once with a
+temporary structured `--targets-file` plus a `target-scroll-by` scenario
+file, proving both real runtime scroll actions persist a valid
+schema-`1.2.0` artifact with populated `scrollScenarioEvidence`,
+scenario-file path privacy, and target-application immutability. Run it
+locally after `npm run build`:
+
+```powershell
+node scripts/dev/builtCliScrollScenarioSmoke.mjs
+```
+
+`scripts/dev/builtCliCompareSmoke.mjs` is the v0.4 equivalent, added
+alongside the `compare` command implementation (shipped as part of the
+published `0.4.0` package - see `docs/CURRENT_STATE.md`): it runs the built
+`dist/cli.js` twice as
+`observe` against an inline disposable local HTTP fixture whose served
+content changes deterministically between the two runs (a real moved/
+resized target, and a page-width transition from fitting to exceeding the
+viewport), then runs the built `dist/cli.js compare` against the two
+resulting persisted observation artifacts. It validates artifact kind/
+schema `1.0.0`, `comparability: "comparable"`, source observation
+references, at least one real `moved` difference and one real page-width
+relationship change, that the comparison directory contains `manifest.json`
+only, that no operational filesystem path leaked into the persisted
+manifest, and that both source observation manifests are byte-identical
+before and after the comparison ran. Run it locally after `npm run build`:
+
+```powershell
+node scripts/dev/builtCliCompareSmoke.mjs
+```
+
+`scripts/dev/builtCliFrontendContractsSmoke.mjs` is the v0.5 equivalent,
+added alongside the `approve-baseline`/`save-change-contract`/
+`evaluate-contract` command implementations (shipped as part of the
+published `0.5.0` package - see `docs/CURRENT_STATE.md`). Unlike the other dev smokes, it needs no Chromium
+at all: it hand-writes deterministic, schema-`1.2.0`-valid observation
+manifests directly to a temporary directory (preserving the public
+observation artifact contract without a real browser capture), then runs
+the built `dist/cli.js` for `compare`, `approve-baseline`,
+`save-change-contract`, and `evaluate-contract` - twice for the final
+step, once without `--enforce` and once with it, against the same
+milestone-signature contract (requested navigation shrink = pass, expected
+workspace expansion = pass, protected right-rail width = fail, preserved
+unclipped navigation = fail, overall = `FAIL`). It validates both exit
+codes (`0` without `--enforce`, nonzero with it), that both invocations
+persist byte-for-byte semantically identical evaluation evidence
+(`evaluationRequestId` and `clauseResults` equal), that the evaluation
+directory contains `manifest.json` only, that no operational filesystem
+path leaked into either persisted evaluation manifest, and that every
+source observation/comparison/contract artifact remains unmodified. Run it
+locally after `npm run build`:
+
+```powershell
+node scripts/dev/builtCliFrontendContractsSmoke.mjs
+```
+
+`scripts/dev/builtCliFrontendContractsBrowserSmoke.mjs` is the v0.5 Batch 5
+real-browser equivalent, added alongside
+`tests/browser/cliFrontendContracts.test.ts`. Unlike the Chromium-free
+`scripts/dev/builtCliFrontendContractsSmoke.mjs` above, this one launches a
+real disposable local HTTP fixture and real Playwright Chromium, then drives
+the built `dist/cli.js` through the complete `observe` → `approve-baseline`
+→ `save-change-contract` → `observe` → `compare` → `evaluate-contract`
+sequence twice: once against a candidate whose served content produces a
+fully successful contract change (all clauses `pass`, overall `PASS`), and
+once against a candidate that reproduces the milestone-signature failure - a
+real observed navigation clipping regression and a real observed right-rail
+width regression alongside an otherwise-successful requested/expected-
+dependent change (overall `FAIL`). It validates the same `--enforce`
+exit-code/identity behavior, screenshot-free evaluation directory, source
+immutability, and path-privacy properties as the Chromium-free smoke, but
+against genuine rendered geometry instead of hand-constructed artifacts. Run
+it locally after `npm run build` (Chromium must already be installed):
+
+```powershell
+node scripts/dev/builtCliFrontendContractsBrowserSmoke.mjs
+```
+
+Since v0.8 Batch 1, `npm run build` also builds the browser-side viewer app
+(`viewer/`) with Vite into `dist/viewer` (see `docs/ARCHITECTURE.md` "v0.8
+Batch 1"). `npm run typecheck` additionally type-checks `viewer/tsconfig.json`
+alongside the existing `tsconfig.json`. To smoke-test the built viewer
+locally after `npm run build`:
+
+```powershell
+node dist/cli.js view --root <evidence-root> --no-open
+```
+
+optionally adding `--bindings-file <json-file>` and/or `--context-file
+<json-file>` (see `docs/COMMANDS.md#view` for their exact shapes), then open
+the printed `http://127.0.0.1:4319` URL in a browser (or stop with Ctrl+C).
+This starts a real, loopback-only server serving the actual built PWA. As of
+v0.8 (all eight implementation batches), it reads `--root` only for bounded,
+read-only evidence discovery through the existing canonical
+readers/classifiers - it never writes to `--root` or modifies any artifact
+under it. The v0.9 annotation authoring surface (implemented, not yet
+released) is available only from the project-aware `node dist/cli.js view`
+inside an initialized project, never from `--root`. Its end-to-end browser
+proof is `tests/browser/v09IntegratedAcceptance.test.ts`, and its packed
+installed proof is `scripts/ci/runPackedV09AnnotationSmoke.mjs`.
+
+Unlike `scripts/ci/runPackedObservationSmoke.mjs`, none of these five dev
+smokes is wired into any CI workflow or is a release gate - they are
+source-checkout development evidence only, proving the built CLI's
+`--targets-file`/`--scroll-scenario-file`/`compare`/frontend-contract
+command behavior without installing a packed tarball or requiring
+cross-platform infrastructure. None is part of the published package.
+Cross-platform packed validation of the v0.1-v0.5 observation/compare/
+contract behavior is `scripts/ci/runPackedObservationSmoke.mjs`'s
+responsibility (see `docs/CI_CD.md`) - the same script, against the same
+single candidate tarball per platform, now including the v0.5 contract/
+evaluation CLI.

package/docs/DOCUMENTATION_PRESERVATION_POLICY.md

@@ -1,50 +1,50 @@
-# Documentation Preservation Policy
-
-Current explicit user decisions have highest authority. The complete
-repository-local Project Description then owns durable product intent, and the
-complete repository-local Project Milestones owns capability ordering, major
-requirements, acceptance expectations, and cross-milestone rules. ROADMAP
-derives version-level direction from both. Actual repository evidence is the
-authority for claims about current implementation and release state. Accepted
-greenfield artifacts may prove an approved design decision but do not alone
-prove implementation. Reconnaissance informs decisions but does not replace
-intent.
-
-Responsibilities are distinct:
-
-- `PROJECT_DESCRIPTION.md` contains complete durable product intent, the three
-  primary jobs, long-term product model, principles, and ecosystem boundaries.
-- `PROJECT_MILESTONES.md` contains the complete ordered capability design,
-  acceptance expectations, and cross-milestone rules.
-- `ROADMAP.md` owns version-level goals, constraints, dependencies, exclusions,
-  ecosystem implications, acceptance, and unresolved planning decisions.
-- `docs/plans/<version>-implementation-plan.md`, when present, owns the frozen
-  concrete implementation plan produced at version start after the roadmap and
-  current repository state have been inspected. It may contain implementation
-  architecture decisions, batch structure, sequencing, batch acceptance gates,
-  validation expectations, explicit exclusions, and the post-implementation
-  handoff into documentation reconciliation and release-readiness workflows.
-  It is a planning authority only and never proves that a batch or version was
-  actually implemented.
-- `CURRENT_STATE.md` describes only actual implementation, scaffold, validation,
-  and release state.
-- `ARCHITECTURE.md` describes implemented architecture and may include clearly
-  labeled durable or planned extension constraints.
-- `PROJECT_OVERVIEW.md` is concise navigation and orientation; it does not
-  replace the complete authorities.
-
-Once a version-specific implementation plan is explicitly frozen, coding-agent
-prompts for that version must preserve its scope and batch order unless the user
-explicitly revises the plan. Batch execution reports may document what happened
-but do not silently rewrite the plan. If implementation evidence requires a
-change, record the explicit plan revision in the version plan before subsequent
-batches are treated as governed by the new sequence.
-
-ROADMAP must not override Project Description or Project Milestones on durable
-intent, and it must never contain prewritten implementation batches, command
-transcripts, or execution bookkeeping. A version plan must not promote a
-future-version capability into the current version or contradict the roadmap's
-version-level scope. Current-state documents do not override future product
-intent merely because implementation is incomplete. Before deleting,
-relocating, or replacing a source document, verify that all unique information
-and useful historical provenance remain.
+# Documentation Preservation Policy
+
+Current explicit user decisions have highest authority. The complete
+repository-local Project Description then owns durable product intent, and the
+complete repository-local Project Milestones owns capability ordering, major
+requirements, acceptance expectations, and cross-milestone rules. ROADMAP
+derives version-level direction from both. Actual repository evidence is the
+authority for claims about current implementation and release state. Accepted
+greenfield artifacts may prove an approved design decision but do not alone
+prove implementation. Reconnaissance informs decisions but does not replace
+intent.
+
+Responsibilities are distinct:
+
+- `PROJECT_DESCRIPTION.md` contains complete durable product intent, the three
+  primary jobs, long-term product model, principles, and ecosystem boundaries.
+- `PROJECT_MILESTONES.md` contains the complete ordered capability design,
+  acceptance expectations, and cross-milestone rules.
+- `ROADMAP.md` owns version-level goals, constraints, dependencies, exclusions,
+  ecosystem implications, acceptance, and unresolved planning decisions.
+- `docs/plans/<version>-implementation-plan.md`, when present, owns the frozen
+  concrete implementation plan produced at version start after the roadmap and
+  current repository state have been inspected. It may contain implementation
+  architecture decisions, batch structure, sequencing, batch acceptance gates,
+  validation expectations, explicit exclusions, and the post-implementation
+  handoff into documentation reconciliation and release-readiness workflows.
+  It is a planning authority only and never proves that a batch or version was
+  actually implemented.
+- `CURRENT_STATE.md` describes only actual implementation, scaffold, validation,
+  and release state.
+- `ARCHITECTURE.md` describes implemented architecture and may include clearly
+  labeled durable or planned extension constraints.
+- `PROJECT_OVERVIEW.md` is concise navigation and orientation; it does not
+  replace the complete authorities.
+
+Once a version-specific implementation plan is explicitly frozen, coding-agent
+prompts for that version must preserve its scope and batch order unless the user
+explicitly revises the plan. Batch execution reports may document what happened
+but do not silently rewrite the plan. If implementation evidence requires a
+change, record the explicit plan revision in the version plan before subsequent
+batches are treated as governed by the new sequence.
+
+ROADMAP must not override Project Description or Project Milestones on durable
+intent, and it must never contain prewritten implementation batches, command
+transcripts, or execution bookkeeping. A version plan must not promote a
+future-version capability into the current version or contradict the roadmap's
+version-level scope. Current-state documents do not override future product
+intent merely because implementation is incomplete. Before deleting,
+relocating, or replacing a source document, verify that all unique information
+and useful historical provenance remain.