@dailephd/my-frontend-observer 0.10.0 → 0.10.1

package/docs/reports/v0.10-implementation-completeness-documentation-reconciliation.md

@@ -1,344 +1,344 @@
-# v0.10 Implementation Completeness and Documentation Reconciliation
-
-## 1. Verdict
-
-`PASS_V0_10_IMPLEMENTATION_COMPLETE_DOCS_RECONCILED_READY_FOR_PRERELEASE`
-
-This verdict means the frozen v0.10 implementation is complete, current
-documentation is reconciled to repository evidence, and local validation is
-green. It does not mean release-ready, publish-ready, or cross-platform-ready.
-
-## 2. Repository state
-
-- Repository: `C:\Users\daile\Projects\my-frontend-observer`
-- Branch: `feature/v0.10-full-visual-workflow`
-- Starting HEAD: `d164886dd665a140a9fc783f25c87f57cbc01ebb`
-- Ending HEAD: the documentation-reconciliation commit created after this
-  report; the final task response records its exact identity.
-- Local package: `@dailephd/my-frontend-observer@0.9.1`
-- Latest npm-published package: `0.9.1`
-- `v0.10.0` local/remote tag: absent
-- Latest GitHub Release: `v0.9.1`; no v0.10 release exists
-- v0.10 release state: implemented and documentation-reconciled, unreleased
-
-## 3. Retrieval and audit index
-
-- Resolved `@dailephd/my-dev-kit`: `1.12.4`; CLI identity matched.
-- Install: `.my-dev-kit-workflow/tools/v0.10-documentation-reconciliation/`
-- Index: `.my-dev-kit-context/indexes/my-frontend-observer-v0.10-doc-reconciliation-20260922T145706`
-- Command: `my-dev-kit index --root . --src src --src viewer/src --src tests --src scripts --language typescript --out <index> --call-graph --progress --json`
-- Result: 319 files, 2,567 symbols, 4,989 edges, zero top-level warnings/errors.
-- Partial analyzers: data-model (872 warnings) and classification (2,517
-  warnings). Syntax, call graph, frontend semantic, and frontend reachability
-  completed. Android analyzers were inapplicable; model-view lineage did not
-  run.
-
-Retrieval-first search, symbol lookup, bounded source, continuation, and local
-dependency inspection established the v0.10 owners and public surface. No
-whole source/test fallback was required.
-
-## 4. Evidence inspected
-
-All eight v0.10 implementation reports were inspected. The frozen v0.10 plan,
-documentation preservation policy, durable project description/milestones,
-all canonical current documents, README, CHANGELOG, release guidance, the two
-v0.7/v0.8 completeness-audit precedents, package metadata, Git tags, npm state,
-built CLI help, public exports, Viewer routes, tests, packed-smoke scripts, and
-the readiness workflow were inspected. Current source/tests/package evidence
-was used over historical report text wherever relevant.
-
-## 5. Package and script inventory
-
-- Package: `@dailephd/my-frontend-observer`, ESM, Node `>=24`.
-- Runtime dependency: `playwright ^1.62.1`; no my-dev-kit or orchestrator
-  runtime dependency.
-- Public bin: `my-frontend-observer -> dist/cli.js`.
-- Public export: package root -> `dist/index.js`.
-- Package allowlist: `dist`, README, CHANGELOG, `docs`, LICENSE.
-- Current scripts: prebuild, build, typecheck, lint, unit tests, browser tests,
-  security tests, isolated PWA hard gate, and documentation check.
-- Test inventory before this docs-only change: 101 unit files and 32 browser
-  files.
-
-## 6. CLI command inventory
-
-Built help exposes exactly twelve top-level commands:
-
-1. `init`
-2. `capture <alias>`
-3. `check [baseline]`
-4. `view`
-5. `observe`
-6. `compare`
-7. `approve-baseline`
-8. `save-change-contract`
-9. `evaluate-contract`
-10. `import-reference`
-11. `approve-reference`
-12. `evaluate-reference-fidelity`
-
-`--version` reports `0.9.1`. v0.10 adds no command. Visual Change actions are
-project-aware Viewer/API operations. `check <baseline> --json` remains the
-post-edit machine operation. A stale `view --help` description was corrected
-to describe the implemented guarded Visual Change mutations and explicit
-reference approval without changing behavior or flags.
-
-## 7. Viewer action and API inventory
-
-The top-level Viewer modes are Evidence, Bounded context, and Visual changes.
-Standalone `view --root` permits inspection only. Project-aware sessions may
-save annotations, promote runtime intent, materialize reference intent,
-approve an imported reference, create actual/reference workflows, activate,
-run a check, restore acceptance, prepare a handoff, review, and record an
-already-completed governance result.
-
-The v0.10 routes are:
-
-- `GET /api/visual-changes/:handle/view`
-- `POST /api/visual-changes`
-- `POST /api/visual-changes/:handle/activate`
-- `POST /api/visual-changes/:handle/check`
-- `POST /api/visual-changes/:handle/restore-acceptance`
-- `POST /api/visual-changes/:handle/prepare-handoff`
-- `POST /api/visual-changes/:handle/review`
-- `POST /api/visual-changes/:handle/governance`
-- `POST /api/annotations/:handle/start-visual-change`
-- `POST /api/references/:handle/approve`
-- `POST /api/references/:handle/start-visual-change`
-
-They reuse exact Host/Origin, memory-only token, JSON content type, compression,
-body-bound, closed-shape, containment, serialization, and no-store controls.
-
-## 8. Public programmatic API
-
-`src/index.ts` publicly exports the workflow contract/constants/validator and
-identity helpers; workflow writer/reader/persistence; project creation,
-activation, restore, snapshot, and check; handoff contract/validator/serializer
-and preparation; cycle derivation; review; and governance recording. Viewer
-adapters, HTTP handlers, route matching, and React hooks/components remain
-internal/Viewer-only. The public API is programmatic; it is not a hidden CLI
-command family.
-
-## 9. Schema and protocol inventory
-
-| Contract | Kind | Version | Source owner | Changed in v0.10 |
-|---|---|---:|---|---|
-| Observation | persisted artifact | 1.2.0 | `domain/schema.ts` | No |
-| Comparison | persisted artifact | 1.0.0 | `domain/comparison.ts` | No |
-| Frontend contract | persisted artifact | 1.0.0 | `domain/frontendContracts.ts` | No |
-| Contract evaluation | persisted artifact | 1.0.0 | `domain/frontendContractEvaluationArtifact.ts` | No |
-| Bounded agent context | transfer artifact | 1.0.0 | `domain/boundedAgentContext.ts` | No |
-| External reference | persisted artifact | 1.0.0 | `domain/externalReference.ts` | No |
-| Visual annotation | persisted artifact | 1.0.0 | `domain/visualAnnotation.ts` | No |
-| Visual change workflow | persisted artifact | 1.0.0 | `domain/visualChangeWorkflow.ts` | Yes, new |
-| Agent handoff | non-persisted transfer contract | 1.0.0 | `domain/visualChangeAgentHandoff.ts` | Yes, new |
-| Viewer protocol | HTTP/UI protocol | 1.3.0 | `viewerServer/httpServer.ts` | No |
-
-The workflow kind is
-`my-frontend-observer/visual-change-workflow`. The handoff kind is
-`my-frontend-observer/visual-change-agent-handoff`. No other persisted v0.10
-evidence family was introduced.
-
-## 10. v0.10 implementation-completeness matrix
-
-Each row gives requirement, owner/source witness, test witness, interface/docs,
-and status.
-
-| # | Requirement | Implementation/source witness | Test witness | Interface/document witness | Status |
-|---:|---|---|---|---|---|
-| 1 | Workflow artifact foundation | workflow domain, reader/writer, persistence | `visualChangeWorkflow.test.ts` | public API, CONTRACTS | IMPLEMENTED |
-| 2 | Request/workflow/attempt identities | workflow identity owner | workflow identity tests | public API, CONTRACTS | IMPLEMENTED |
-| 3 | Immutable workflow revisions | persistence service | workflow/project/review immutability tests | Visual changes, WORKFLOWS | IMPLEMENTED |
-| 4 | Project-contained activation | project workflow service | project workflow service tests | Activate action | IMPLEMENTED |
-| 5 | Canonical check attempt recording | project workflow service -> `checkProject` | project workflow/correction tests | Run check | IMPLEMENTED |
-| 6 | Visual Changes workspace | Viewer workspace/projection | workspace browser tests | project-aware `view` | IMPLEMENTED |
-| 7 | Actual visual entry | runtime authoring adapter | actual-entry and integrated browser gates | Viewer | IMPLEMENTED |
-| 8 | Reference visual entry | reference approval/authoring adapters | reference-entry and integrated gates | Viewer | IMPLEMENTED |
-| 9 | Explicit workflow bindings | reference binding domain/workflow writer | reference authoring/workspace tests | Viewer Add/Remove binding | IMPLEMENTED |
-| 10 | Handoff contract | handoff domain | handoff contract tests | public API/Viewer | IMPLEMENTED |
-| 11 | Bounded context | existing projection reused | bounded-context/handoff tests | handoff | IMPLEMENTED |
-| 12 | Supplemental static-context ownership | handoff service coherence gate | handoff service tests | explicit `--context-file` | IMPLEMENTED |
-| 13 | Optional orchestrator correlation | handoff metadata validator | handoff and review tests | Viewer optional fields | IMPLEMENTED |
-| 14 | Post-edit check command | handoff exact command | handoff/UI tests | `check <baseline> --json` | IMPLEMENTED |
-| 15 | Pending-review human gate | cycle helper/check/handoff gates | Batch 7 service/browser gates | Viewer controls | IMPLEMENTED |
-| 16 | Correction-requested loop | review service | correction acceptance gates | Viewer | IMPLEMENTED |
-| 17 | Two-attempt lineage | check append owner | actual/reference correction gates | attempt history | IMPLEMENTED |
-| 18 | PASS-only acceptance | review service | latest-PASS/non-PASS tests | Viewer Accept | IMPLEMENTED |
-| 19 | Abandon | review service | transition/terminal tests | Viewer Abandon | IMPLEMENTED |
-| 20 | Explicit restore separation | project workflow service | review/browser tests | Restore acceptance | IMPLEMENTED |
-| 21 | Reference-correction identity trace | existing v0.7 builders reused | reference two-candidate tests | attempt metadata | IMPLEMENTED |
-| 22 | Governance after canonical governance | review/governance service | canonical baseline/reference governance tests | Viewer recording actions | IMPLEMENTED |
-| 23 | Baseline/reference governance separation | canonical approval owners plus recorder | governance tests | CONTRACTS/WORKFLOWS | IMPLEMENTED |
-| 24 | Standalone read-only | server authoring state | Viewer/security/packed tests | `view --root` | IMPLEMENTED |
-| 25 | Authoring security | shared authoring gate | security suites | SECURITY | IMPLEMENTED |
-| 26 | PWA no-stale-evidence | PWA/service worker | isolated hard gate | SECURITY | IMPLEMENTED |
-| 27 | Packed installed v0.10 surface | package exports/dist | packed v0.10 smoke | CI/CD | IMPLEMENTED |
-| 28 | Same-candidate CI wiring | readiness workflow | Batch 8 same-tarball proof | CI/CD | IMPLEMENTED |
-| 29 | No source editing | service boundaries | browser/source immutability tests | ARCHITECTURE/SECURITY | IMPLEMENTED_BY_DESIGN_NO_PUBLIC_COMMAND |
-| 30 | No second evaluator | services call canonical owners | call-count/integration tests | ARCHITECTURE | IMPLEMENTED_BY_DESIGN_NO_PUBLIC_COMMAND |
-| 31 | No automatic approval/retry | explicit transitions | entry/review/governance tests | WORKFLOWS | IMPLEMENTED_BY_DESIGN_NO_PUBLIC_COMMAND |
-| 32 | v0.7-v0.9.1 regression preservation | unchanged owners | complete unit/browser/security/PWA suites | historical docs | IMPLEMENTED |
-
-No `MISSING_IMPLEMENTATION`, `MISSING_TEST`, `MISSING_DOCUMENTATION`, or
-`DOCUMENTATION_DRIFT` remains after this reconciliation.
-
-## 11. Milestone and roadmap acceptance
-
-`V0_10_MILESTONE_ACCEPTANCE: PASS`
-
-The applicable graphical interaction, visual scope, external edit, canonical
-evaluation, correction, human acceptance, evidence immutability, and ecosystem
-boundary criteria map to rows 1-32 and the Batch 4-8 acceptance gates.
-
-`V0_10_ROADMAP_ACCEPTANCE: PASS`
-
-Both entry modes converge on one frozen workflow; explicit activation,
-handoff, canonical check, review/correction, PASS-only acceptance, and separate
-governance are implemented and tested. Frozen exclusions remain excluded.
-
-## 12. Batch 1-8 gate audit
-
-| Batch | Frozen goal | Current source witness | Current test witness | Documentation witness | Status |
-|---:|---|---|---|---|---|
-| 1 | Workflow foundation | workflow domain/artifacts | workflow tests | CONTRACTS | PASS |
-| 2 | Project composition/check | project workflow service | project workflow tests | ARCHITECTURE/WORKFLOWS | PASS |
-| 3 | Viewer workspace | server projection/UI workspace | workspace/security tests | COMMANDS | PASS |
-| 4 | Actual entry | runtime start/promotion owners | actual-entry gate | WORKFLOWS | PASS |
-| 5 | Reference entry | approval/reference start owners | reference-entry gate | WORKFLOWS | PASS |
-| 6 | Agent handoff | handoff domain/service | handoff unit/browser tests | CONTRACTS | PASS |
-| 7 | Correction/review/governance | cycle/review services | correction/governance gates | WORKFLOWS | PASS |
-| 8 | Integrated/packed/docs wiring | integrated suite/smoke/CI | integrated and packed proofs | Batch 8 report/CI docs | PASS |
-
-Report PASS was not accepted alone; every row has current HEAD witnesses.
-
-## 13. Cross-version regression audit
-
-The final validation protects v0.1 observation, v0.2 semantic targets, v0.3
-scrolling/runtime behavior, v0.4 comparison, v0.5 contracts, v0.6 bounded
-context, v0.7 reference correction, v0.8 Viewer, v0.8.1 project workflow,
-v0.9 annotation, and v0.9.1 isolated PWA hard-gate behavior. Historical
-release documents were preserved.
-
-## 14. Document audit ledger
-
-| Document | Role | Changed | Claim/release/future result | Preservation |
-|---|---|---:|---|---|
-| README | first-use/current overview | Yes | reconciled v0.10 status; 0.9.1 remains published | preserved |
-| CHANGELOG | unreleased/release history | No | `[Unreleased]` already correct | all history preserved |
-| PROJECT_DESCRIPTION | durable intent | No | no stale status claim | complete authority preserved |
-| PROJECT_MILESTONES | capability/acceptance | No | requirements mapped and satisfied | complete authority preserved |
-| ROADMAP | version-level direction | Yes | reconciliation complete; readiness next | v0.1-v0.10 preserved; no batches |
-| PROJECT_OVERVIEW | concise orientation | Yes | stale future claim repaired | earlier version orientation preserved |
-| CURRENT_STATE | current facts | Yes | reconciliation complete; unreleased | historical sections preserved |
-| ARCHITECTURE | implemented ownership | Yes | stale v0.10 future claim repaired | earlier architecture preserved |
-| CONTRACTS | canonical contracts | No | workflow/handoff already accurate | all contract history preserved |
-| COMMANDS | implemented commands | Yes | project-aware writes corrected; no command invented | command families preserved |
-| WORKFLOWS | current procedures | No | complete loop already accurate | prior workflows preserved |
-| QUICKSTART | concise entry | Yes | source v0.10 vs published 0.9.1 clarified | simpler workflow preserved |
-| DEVELOPMENT | contributor workflow | No | no contradictory v0.10 status | retained |
-| CI_CD | CI/readiness boundary | No | four-smoke same-candidate wiring already accurate | retained |
-| RELEASE | release state/process | Yes | reconciliation complete; readiness pending | release history preserved |
-| SECURITY | safety boundary | Yes | v0.10 guarded mutations and external boundary added | v0.1-v0.9 controls preserved |
-| DOCUMENTATION_PRESERVATION_POLICY | authority rules | No | followed | unchanged |
-| v0.10 implementation plan | frozen plan/history | No | remains planning authority | unchanged |
-| Batch 1-8 reports | execution evidence | No | historically scoped claims retained | unchanged |
-
-## 15. Stale-claim repair ledger
-
-| Document | Old claim | Classification | Evidence | Correction |
-|---|---|---|---|---|
-| PROJECT_OVERVIEW | v0.10 future/unimplemented/planned | STALE_CLAIM | current source/tests and eight PASS batches | implemented, reconciled, unreleased; readiness next |
-| ARCHITECTURE | graphical workflow future/unimplemented | STALE_CLAIM | workflow/handoff/review owners | implemented/unreleased architecture |
-| CURRENT_STATE | reconciliation pending/next | STALE_CLAIM after this task | this audit and validation | reconciliation complete; readiness next |
-| ROADMAP | reconciliation remained next gate | STALE_CLAIM after this task | this audit | version-level reconciled status |
-| README | implemented but not reconciliation status | INCOMPLETE_CURRENT_FACT | this audit | concise reconciled/unreleased wording |
-| QUICKSTART | standalone Viewer phrasing implied all Viewer use was inspect-only | MISPLACED_DETAIL | project-aware routes/UI | distinguishes project-aware authoring from standalone |
-| COMMANDS and built `view --help` | only three v0.9 writes / never approves references | STALE_CLAIM | current route inventory | guarded v0.10 actions and explicit approval boundary |
-| SECURITY | v0.9 “any other POST” wording lacked current v0.10 extension | HISTORICAL_FACT_WITH_CURRENT_AMBIGUITY | route/security tests | scoped to v0.9 and added current v0.10 boundary |
-| RELEASE | reconciliation still pending implicitly | INCOMPLETE_CURRENT_FACT | this audit | reconciliation complete; readiness still pending |
-
-Matches in frozen plans and historical reports were classified as
-HISTORICAL_RELEASE_FACT or IMPLEMENTATION_PROMPT_RESIDUE and intentionally
-left unchanged.
-
-## 16. Planning and history preservation
-
-No document, roadmap version, future-version statement, product pillar,
-architecture subsystem, command family, workflow family, report, or release
-entry was removed. ROADMAP remains version-level and contains v0.1-v0.10 with
-no `Batch N` bookkeeping. CHANGELOG retains `[Unreleased]` and every historical
-release entry. The v0.10 plan and Batch 1-8 reports remain historical evidence.
-
-## 17. Documentation-check audit and hardening
-
-`DOC_CHECK_HARDENING: REQUIRED`
-
-The existing checker already protected all 17 required documents, ROADMAP
-v0.1-v0.10 retention, absence of Batch bookkeeping, package/lock version
-agreement, and `[Unreleased]`. It could not detect the exact regression found:
-current canonical documents could still describe completed v0.10 as future or
-leave reconciliation/readiness state contradictory.
-
-The existing `scripts/check-docs.mjs` owner now adds narrow semantic markers:
-no current v0.10 future/unimplemented claim, CURRENT_STATE implementation and
-reconciliation completion with readiness still next/pending, ROADMAP
-implementation-complete/documentation-reconciled status, and retention of both
-canonical v0.10 contract kind markers. It does not hardcode paragraphs or
-create a parallel preservation framework. `npm run check:docs` is the
-regression proof.
-
-## 18. Validation
-
-Final results are recorded after the complete post-edit run:
-
-- `npm run typecheck`: PASS
-- `npm run lint`: PASS
-- `npm test`: PASS
-- `npm run test:browser`: PASS
-- `npm run test:security`: PASS
-- `npm run test:pwa-hard-gate`: PASS
-- `npm run build`: PASS
-- `npm run check:docs`: PASS
-- targeted stale-claim search: PASS; remaining matches are historical
-- `git diff --check`: PASS
-- `npm pack --dry-run`: PASS; package remains 0.9.1 and contains compiled
-  v0.10/public Viewer assets without generated state
-
-This is local implementation/completeness validation, not formal multi-OS
-pre-release readiness.
-
-## 19. Changed and unchanged files
-
-Documentation changed: README, CURRENT_STATE, ROADMAP, PROJECT_OVERVIEW,
-ARCHITECTURE, COMMANDS, QUICKSTART, SECURITY, RELEASE, and this report.
-Documentation inspected but unchanged: CHANGELOG, PROJECT_DESCRIPTION,
-PROJECT_MILESTONES, CONTRACTS, WORKFLOWS, DEVELOPMENT, CI_CD, preservation
-policy, implementation plan, and Batch 1-8 reports.
-
-Tooling changed: the existing docs checker. Production behavior changed: none.
-Two user-facing documentation strings/comments in `src/cli.ts` and
-`src/viewerServer/httpServer.ts`, plus the existing CLI-help assertion, were
-updated to remove false route/security claims. No executable semantics changed.
-
-## 20. Change boundaries
-
-- Schema/protocol changes: none.
-- Package-version changes: none.
-- Dependency changes: none.
-- Product feature changes: none.
-- Release operations: none.
-- Remaining implementation gaps: none.
-- Remaining documentation ambiguities: none material.
-
-## 21. Exact next workflow
-
-Run the separate v0.10 pre-release readiness workflow: exact-candidate
-cross-platform validation, security validation, and readiness audit. Do not
-perform release preparation or publication yet.
-
-## 22. Full-file fallback accounting
-
-Canonical documentation and reports were inspected as documentation
-authorities. Source/test work used retrieval-first bounded inspection.
-
-Full source/test file reads: none.
+# v0.10 Implementation Completeness and Documentation Reconciliation
+
+## 1. Verdict
+
+`PASS_V0_10_IMPLEMENTATION_COMPLETE_DOCS_RECONCILED_READY_FOR_PRERELEASE`
+
+This verdict means the frozen v0.10 implementation is complete, current
+documentation is reconciled to repository evidence, and local validation is
+green. It does not mean release-ready, publish-ready, or cross-platform-ready.
+
+## 2. Repository state
+
+- Repository: `C:\Users\daile\Projects\my-frontend-observer`
+- Branch: `feature/v0.10-full-visual-workflow`
+- Starting HEAD: `d164886dd665a140a9fc783f25c87f57cbc01ebb`
+- Ending HEAD: the documentation-reconciliation commit created after this
+  report; the final task response records its exact identity.
+- Local package: `@dailephd/my-frontend-observer@0.9.1`
+- Latest npm-published package: `0.9.1`
+- `v0.10.0` local/remote tag: absent
+- Latest GitHub Release: `v0.9.1`; no v0.10 release exists
+- v0.10 release state: implemented and documentation-reconciled, unreleased
+
+## 3. Retrieval and audit index
+
+- Resolved `@dailephd/my-dev-kit`: `1.12.4`; CLI identity matched.
+- Install: `.my-dev-kit-workflow/tools/v0.10-documentation-reconciliation/`
+- Index: `.my-dev-kit-context/indexes/my-frontend-observer-v0.10-doc-reconciliation-20260922T145706`
+- Command: `my-dev-kit index --root . --src src --src viewer/src --src tests --src scripts --language typescript --out <index> --call-graph --progress --json`
+- Result: 319 files, 2,567 symbols, 4,989 edges, zero top-level warnings/errors.
+- Partial analyzers: data-model (872 warnings) and classification (2,517
+  warnings). Syntax, call graph, frontend semantic, and frontend reachability
+  completed. Android analyzers were inapplicable; model-view lineage did not
+  run.
+
+Retrieval-first search, symbol lookup, bounded source, continuation, and local
+dependency inspection established the v0.10 owners and public surface. No
+whole source/test fallback was required.
+
+## 4. Evidence inspected
+
+All eight v0.10 implementation reports were inspected. The frozen v0.10 plan,
+documentation preservation policy, durable project description/milestones,
+all canonical current documents, README, CHANGELOG, release guidance, the two
+v0.7/v0.8 completeness-audit precedents, package metadata, Git tags, npm state,
+built CLI help, public exports, Viewer routes, tests, packed-smoke scripts, and
+the readiness workflow were inspected. Current source/tests/package evidence
+was used over historical report text wherever relevant.
+
+## 5. Package and script inventory
+
+- Package: `@dailephd/my-frontend-observer`, ESM, Node `>=24`.
+- Runtime dependency: `playwright ^1.62.1`; no my-dev-kit or orchestrator
+  runtime dependency.
+- Public bin: `my-frontend-observer -> dist/cli.js`.
+- Public export: package root -> `dist/index.js`.
+- Package allowlist: `dist`, README, CHANGELOG, `docs`, LICENSE.
+- Current scripts: prebuild, build, typecheck, lint, unit tests, browser tests,
+  security tests, isolated PWA hard gate, and documentation check.
+- Test inventory before this docs-only change: 101 unit files and 32 browser
+  files.
+
+## 6. CLI command inventory
+
+Built help exposes exactly twelve top-level commands:
+
+1. `init`
+2. `capture <alias>`
+3. `check [baseline]`
+4. `view`
+5. `observe`
+6. `compare`
+7. `approve-baseline`
+8. `save-change-contract`
+9. `evaluate-contract`
+10. `import-reference`
+11. `approve-reference`
+12. `evaluate-reference-fidelity`
+
+`--version` reports `0.9.1`. v0.10 adds no command. Visual Change actions are
+project-aware Viewer/API operations. `check <baseline> --json` remains the
+post-edit machine operation. A stale `view --help` description was corrected
+to describe the implemented guarded Visual Change mutations and explicit
+reference approval without changing behavior or flags.
+
+## 7. Viewer action and API inventory
+
+The top-level Viewer modes are Evidence, Bounded context, and Visual changes.
+Standalone `view --root` permits inspection only. Project-aware sessions may
+save annotations, promote runtime intent, materialize reference intent,
+approve an imported reference, create actual/reference workflows, activate,
+run a check, restore acceptance, prepare a handoff, review, and record an
+already-completed governance result.
+
+The v0.10 routes are:
+
+- `GET /api/visual-changes/:handle/view`
+- `POST /api/visual-changes`
+- `POST /api/visual-changes/:handle/activate`
+- `POST /api/visual-changes/:handle/check`
+- `POST /api/visual-changes/:handle/restore-acceptance`
+- `POST /api/visual-changes/:handle/prepare-handoff`
+- `POST /api/visual-changes/:handle/review`
+- `POST /api/visual-changes/:handle/governance`
+- `POST /api/annotations/:handle/start-visual-change`
+- `POST /api/references/:handle/approve`
+- `POST /api/references/:handle/start-visual-change`
+
+They reuse exact Host/Origin, memory-only token, JSON content type, compression,
+body-bound, closed-shape, containment, serialization, and no-store controls.
+
+## 8. Public programmatic API
+
+`src/index.ts` publicly exports the workflow contract/constants/validator and
+identity helpers; workflow writer/reader/persistence; project creation,
+activation, restore, snapshot, and check; handoff contract/validator/serializer
+and preparation; cycle derivation; review; and governance recording. Viewer
+adapters, HTTP handlers, route matching, and React hooks/components remain
+internal/Viewer-only. The public API is programmatic; it is not a hidden CLI
+command family.
+
+## 9. Schema and protocol inventory
+
+| Contract | Kind | Version | Source owner | Changed in v0.10 |
+|---|---|---:|---|---|
+| Observation | persisted artifact | 1.2.0 | `domain/schema.ts` | No |
+| Comparison | persisted artifact | 1.0.0 | `domain/comparison.ts` | No |
+| Frontend contract | persisted artifact | 1.0.0 | `domain/frontendContracts.ts` | No |
+| Contract evaluation | persisted artifact | 1.0.0 | `domain/frontendContractEvaluationArtifact.ts` | No |
+| Bounded agent context | transfer artifact | 1.0.0 | `domain/boundedAgentContext.ts` | No |
+| External reference | persisted artifact | 1.0.0 | `domain/externalReference.ts` | No |
+| Visual annotation | persisted artifact | 1.0.0 | `domain/visualAnnotation.ts` | No |
+| Visual change workflow | persisted artifact | 1.0.0 | `domain/visualChangeWorkflow.ts` | Yes, new |
+| Agent handoff | non-persisted transfer contract | 1.0.0 | `domain/visualChangeAgentHandoff.ts` | Yes, new |
+| Viewer protocol | HTTP/UI protocol | 1.3.0 | `viewerServer/httpServer.ts` | No |
+
+The workflow kind is
+`my-frontend-observer/visual-change-workflow`. The handoff kind is
+`my-frontend-observer/visual-change-agent-handoff`. No other persisted v0.10
+evidence family was introduced.
+
+## 10. v0.10 implementation-completeness matrix
+
+Each row gives requirement, owner/source witness, test witness, interface/docs,
+and status.
+
+| # | Requirement | Implementation/source witness | Test witness | Interface/document witness | Status |
+|---:|---|---|---|---|---|
+| 1 | Workflow artifact foundation | workflow domain, reader/writer, persistence | `visualChangeWorkflow.test.ts` | public API, CONTRACTS | IMPLEMENTED |
+| 2 | Request/workflow/attempt identities | workflow identity owner | workflow identity tests | public API, CONTRACTS | IMPLEMENTED |
+| 3 | Immutable workflow revisions | persistence service | workflow/project/review immutability tests | Visual changes, WORKFLOWS | IMPLEMENTED |
+| 4 | Project-contained activation | project workflow service | project workflow service tests | Activate action | IMPLEMENTED |
+| 5 | Canonical check attempt recording | project workflow service -> `checkProject` | project workflow/correction tests | Run check | IMPLEMENTED |
+| 6 | Visual Changes workspace | Viewer workspace/projection | workspace browser tests | project-aware `view` | IMPLEMENTED |
+| 7 | Actual visual entry | runtime authoring adapter | actual-entry and integrated browser gates | Viewer | IMPLEMENTED |
+| 8 | Reference visual entry | reference approval/authoring adapters | reference-entry and integrated gates | Viewer | IMPLEMENTED |
+| 9 | Explicit workflow bindings | reference binding domain/workflow writer | reference authoring/workspace tests | Viewer Add/Remove binding | IMPLEMENTED |
+| 10 | Handoff contract | handoff domain | handoff contract tests | public API/Viewer | IMPLEMENTED |
+| 11 | Bounded context | existing projection reused | bounded-context/handoff tests | handoff | IMPLEMENTED |
+| 12 | Supplemental static-context ownership | handoff service coherence gate | handoff service tests | explicit `--context-file` | IMPLEMENTED |
+| 13 | Optional orchestrator correlation | handoff metadata validator | handoff and review tests | Viewer optional fields | IMPLEMENTED |
+| 14 | Post-edit check command | handoff exact command | handoff/UI tests | `check <baseline> --json` | IMPLEMENTED |
+| 15 | Pending-review human gate | cycle helper/check/handoff gates | Batch 7 service/browser gates | Viewer controls | IMPLEMENTED |
+| 16 | Correction-requested loop | review service | correction acceptance gates | Viewer | IMPLEMENTED |
+| 17 | Two-attempt lineage | check append owner | actual/reference correction gates | attempt history | IMPLEMENTED |
+| 18 | PASS-only acceptance | review service | latest-PASS/non-PASS tests | Viewer Accept | IMPLEMENTED |
+| 19 | Abandon | review service | transition/terminal tests | Viewer Abandon | IMPLEMENTED |
+| 20 | Explicit restore separation | project workflow service | review/browser tests | Restore acceptance | IMPLEMENTED |
+| 21 | Reference-correction identity trace | existing v0.7 builders reused | reference two-candidate tests | attempt metadata | IMPLEMENTED |
+| 22 | Governance after canonical governance | review/governance service | canonical baseline/reference governance tests | Viewer recording actions | IMPLEMENTED |
+| 23 | Baseline/reference governance separation | canonical approval owners plus recorder | governance tests | CONTRACTS/WORKFLOWS | IMPLEMENTED |
+| 24 | Standalone read-only | server authoring state | Viewer/security/packed tests | `view --root` | IMPLEMENTED |
+| 25 | Authoring security | shared authoring gate | security suites | SECURITY | IMPLEMENTED |
+| 26 | PWA no-stale-evidence | PWA/service worker | isolated hard gate | SECURITY | IMPLEMENTED |
+| 27 | Packed installed v0.10 surface | package exports/dist | packed v0.10 smoke | CI/CD | IMPLEMENTED |
+| 28 | Same-candidate CI wiring | readiness workflow | Batch 8 same-tarball proof | CI/CD | IMPLEMENTED |
+| 29 | No source editing | service boundaries | browser/source immutability tests | ARCHITECTURE/SECURITY | IMPLEMENTED_BY_DESIGN_NO_PUBLIC_COMMAND |
+| 30 | No second evaluator | services call canonical owners | call-count/integration tests | ARCHITECTURE | IMPLEMENTED_BY_DESIGN_NO_PUBLIC_COMMAND |
+| 31 | No automatic approval/retry | explicit transitions | entry/review/governance tests | WORKFLOWS | IMPLEMENTED_BY_DESIGN_NO_PUBLIC_COMMAND |
+| 32 | v0.7-v0.9.1 regression preservation | unchanged owners | complete unit/browser/security/PWA suites | historical docs | IMPLEMENTED |
+
+No `MISSING_IMPLEMENTATION`, `MISSING_TEST`, `MISSING_DOCUMENTATION`, or
+`DOCUMENTATION_DRIFT` remains after this reconciliation.
+
+## 11. Milestone and roadmap acceptance
+
+`V0_10_MILESTONE_ACCEPTANCE: PASS`
+
+The applicable graphical interaction, visual scope, external edit, canonical
+evaluation, correction, human acceptance, evidence immutability, and ecosystem
+boundary criteria map to rows 1-32 and the Batch 4-8 acceptance gates.
+
+`V0_10_ROADMAP_ACCEPTANCE: PASS`
+
+Both entry modes converge on one frozen workflow; explicit activation,
+handoff, canonical check, review/correction, PASS-only acceptance, and separate
+governance are implemented and tested. Frozen exclusions remain excluded.
+
+## 12. Batch 1-8 gate audit
+
+| Batch | Frozen goal | Current source witness | Current test witness | Documentation witness | Status |
+|---:|---|---|---|---|---|
+| 1 | Workflow foundation | workflow domain/artifacts | workflow tests | CONTRACTS | PASS |
+| 2 | Project composition/check | project workflow service | project workflow tests | ARCHITECTURE/WORKFLOWS | PASS |
+| 3 | Viewer workspace | server projection/UI workspace | workspace/security tests | COMMANDS | PASS |
+| 4 | Actual entry | runtime start/promotion owners | actual-entry gate | WORKFLOWS | PASS |
+| 5 | Reference entry | approval/reference start owners | reference-entry gate | WORKFLOWS | PASS |
+| 6 | Agent handoff | handoff domain/service | handoff unit/browser tests | CONTRACTS | PASS |
+| 7 | Correction/review/governance | cycle/review services | correction/governance gates | WORKFLOWS | PASS |
+| 8 | Integrated/packed/docs wiring | integrated suite/smoke/CI | integrated and packed proofs | Batch 8 report/CI docs | PASS |
+
+Report PASS was not accepted alone; every row has current HEAD witnesses.
+
+## 13. Cross-version regression audit
+
+The final validation protects v0.1 observation, v0.2 semantic targets, v0.3
+scrolling/runtime behavior, v0.4 comparison, v0.5 contracts, v0.6 bounded
+context, v0.7 reference correction, v0.8 Viewer, v0.8.1 project workflow,
+v0.9 annotation, and v0.9.1 isolated PWA hard-gate behavior. Historical
+release documents were preserved.
+
+## 14. Document audit ledger
+
+| Document | Role | Changed | Claim/release/future result | Preservation |
+|---|---|---:|---|---|
+| README | first-use/current overview | Yes | reconciled v0.10 status; 0.9.1 remains published | preserved |
+| CHANGELOG | unreleased/release history | No | `[Unreleased]` already correct | all history preserved |
+| PROJECT_DESCRIPTION | durable intent | No | no stale status claim | complete authority preserved |
+| PROJECT_MILESTONES | capability/acceptance | No | requirements mapped and satisfied | complete authority preserved |
+| ROADMAP | version-level direction | Yes | reconciliation complete; readiness next | v0.1-v0.10 preserved; no batches |
+| PROJECT_OVERVIEW | concise orientation | Yes | stale future claim repaired | earlier version orientation preserved |
+| CURRENT_STATE | current facts | Yes | reconciliation complete; unreleased | historical sections preserved |
+| ARCHITECTURE | implemented ownership | Yes | stale v0.10 future claim repaired | earlier architecture preserved |
+| CONTRACTS | canonical contracts | No | workflow/handoff already accurate | all contract history preserved |
+| COMMANDS | implemented commands | Yes | project-aware writes corrected; no command invented | command families preserved |
+| WORKFLOWS | current procedures | No | complete loop already accurate | prior workflows preserved |
+| QUICKSTART | concise entry | Yes | source v0.10 vs published 0.9.1 clarified | simpler workflow preserved |
+| DEVELOPMENT | contributor workflow | No | no contradictory v0.10 status | retained |
+| CI_CD | CI/readiness boundary | No | four-smoke same-candidate wiring already accurate | retained |
+| RELEASE | release state/process | Yes | reconciliation complete; readiness pending | release history preserved |
+| SECURITY | safety boundary | Yes | v0.10 guarded mutations and external boundary added | v0.1-v0.9 controls preserved |
+| DOCUMENTATION_PRESERVATION_POLICY | authority rules | No | followed | unchanged |
+| v0.10 implementation plan | frozen plan/history | No | remains planning authority | unchanged |
+| Batch 1-8 reports | execution evidence | No | historically scoped claims retained | unchanged |
+
+## 15. Stale-claim repair ledger
+
+| Document | Old claim | Classification | Evidence | Correction |
+|---|---|---|---|---|
+| PROJECT_OVERVIEW | v0.10 future/unimplemented/planned | STALE_CLAIM | current source/tests and eight PASS batches | implemented, reconciled, unreleased; readiness next |
+| ARCHITECTURE | graphical workflow future/unimplemented | STALE_CLAIM | workflow/handoff/review owners | implemented/unreleased architecture |
+| CURRENT_STATE | reconciliation pending/next | STALE_CLAIM after this task | this audit and validation | reconciliation complete; readiness next |
+| ROADMAP | reconciliation remained next gate | STALE_CLAIM after this task | this audit | version-level reconciled status |
+| README | implemented but not reconciliation status | INCOMPLETE_CURRENT_FACT | this audit | concise reconciled/unreleased wording |
+| QUICKSTART | standalone Viewer phrasing implied all Viewer use was inspect-only | MISPLACED_DETAIL | project-aware routes/UI | distinguishes project-aware authoring from standalone |
+| COMMANDS and built `view --help` | only three v0.9 writes / never approves references | STALE_CLAIM | current route inventory | guarded v0.10 actions and explicit approval boundary |
+| SECURITY | v0.9 “any other POST” wording lacked current v0.10 extension | HISTORICAL_FACT_WITH_CURRENT_AMBIGUITY | route/security tests | scoped to v0.9 and added current v0.10 boundary |
+| RELEASE | reconciliation still pending implicitly | INCOMPLETE_CURRENT_FACT | this audit | reconciliation complete; readiness still pending |
+
+Matches in frozen plans and historical reports were classified as
+HISTORICAL_RELEASE_FACT or IMPLEMENTATION_PROMPT_RESIDUE and intentionally
+left unchanged.
+
+## 16. Planning and history preservation
+
+No document, roadmap version, future-version statement, product pillar,
+architecture subsystem, command family, workflow family, report, or release
+entry was removed. ROADMAP remains version-level and contains v0.1-v0.10 with
+no `Batch N` bookkeeping. CHANGELOG retains `[Unreleased]` and every historical
+release entry. The v0.10 plan and Batch 1-8 reports remain historical evidence.
+
+## 17. Documentation-check audit and hardening
+
+`DOC_CHECK_HARDENING: REQUIRED`
+
+The existing checker already protected all 17 required documents, ROADMAP
+v0.1-v0.10 retention, absence of Batch bookkeeping, package/lock version
+agreement, and `[Unreleased]`. It could not detect the exact regression found:
+current canonical documents could still describe completed v0.10 as future or
+leave reconciliation/readiness state contradictory.
+
+The existing `scripts/check-docs.mjs` owner now adds narrow semantic markers:
+no current v0.10 future/unimplemented claim, CURRENT_STATE implementation and
+reconciliation completion with readiness still next/pending, ROADMAP
+implementation-complete/documentation-reconciled status, and retention of both
+canonical v0.10 contract kind markers. It does not hardcode paragraphs or
+create a parallel preservation framework. `npm run check:docs` is the
+regression proof.
+
+## 18. Validation
+
+Final results are recorded after the complete post-edit run:
+
+- `npm run typecheck`: PASS
+- `npm run lint`: PASS
+- `npm test`: PASS
+- `npm run test:browser`: PASS
+- `npm run test:security`: PASS
+- `npm run test:pwa-hard-gate`: PASS
+- `npm run build`: PASS
+- `npm run check:docs`: PASS
+- targeted stale-claim search: PASS; remaining matches are historical
+- `git diff --check`: PASS
+- `npm pack --dry-run`: PASS; package remains 0.9.1 and contains compiled
+  v0.10/public Viewer assets without generated state
+
+This is local implementation/completeness validation, not formal multi-OS
+pre-release readiness.
+
+## 19. Changed and unchanged files
+
+Documentation changed: README, CURRENT_STATE, ROADMAP, PROJECT_OVERVIEW,
+ARCHITECTURE, COMMANDS, QUICKSTART, SECURITY, RELEASE, and this report.
+Documentation inspected but unchanged: CHANGELOG, PROJECT_DESCRIPTION,
+PROJECT_MILESTONES, CONTRACTS, WORKFLOWS, DEVELOPMENT, CI_CD, preservation
+policy, implementation plan, and Batch 1-8 reports.
+
+Tooling changed: the existing docs checker. Production behavior changed: none.
+Two user-facing documentation strings/comments in `src/cli.ts` and
+`src/viewerServer/httpServer.ts`, plus the existing CLI-help assertion, were
+updated to remove false route/security claims. No executable semantics changed.
+
+## 20. Change boundaries
+
+- Schema/protocol changes: none.
+- Package-version changes: none.
+- Dependency changes: none.
+- Product feature changes: none.
+- Release operations: none.
+- Remaining implementation gaps: none.
+- Remaining documentation ambiguities: none material.
+
+## 21. Exact next workflow
+
+Run the separate v0.10 pre-release readiness workflow: exact-candidate
+cross-platform validation, security validation, and readiness audit. Do not
+perform release preparation or publication yet.
+
+## 22. Full-file fallback accounting
+
+Canonical documentation and reports were inspected as documentation
+authorities. Source/test work used retrieval-first bounded inspection.
+
+Full source/test file reads: none.