@dailephd/my-frontend-observer 0.8.1

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

@@ -0,0 +1,741 @@
+# v0.8 Hardened Documentation Reconciliation and Implementation-Completeness Audit
+
+## 1. Task purpose
+
+Reconcile all repository documentation against the actual v0.8 (Interactive
+Local Observation Viewer) implementation produced by Batches 1-8, then
+perform a strict bidirectional implementation-completeness audit: every
+required capability is implemented and tested; every implemented capability
+is documented; every documentation claim is supported by evidence; no
+implemented behavior is described as merely planned; no unimplemented
+behavior is described as current; v0.9+ remains future; package/release
+wording correctly distinguishes "v0.8 implementation complete in this
+repository" from "v0.8.0 released" (package metadata remains `0.7.0`); and
+the repository is internally consistent and ready for the separate
+pre-release readiness workflow. This is not release prep, not publication,
+not another feature batch.
+
+## 2. Starting branch
+
+`master`
+
+## 3. Starting HEAD
+
+`66c812e5d2b7c7ff039987216652a5cbd04cc873` ("test: complete v0.8 integrated
+viewer acceptance")
+
+## 4. Origin/master
+
+`a1de8ac01e1367b60021cb04226f56369fa2debb`
+
+## 5. Ahead/behind at start
+
+`git rev-list --left-right --count origin/master...HEAD` → `0	8` (8 ahead, 0
+behind). `git merge-base --is-ancestor origin/master HEAD` exited `0`
+(ANCESTOR_OK) - no divergence.
+
+## 6. Package/package-lock versions (start and end)
+
+`package.json` version: `0.7.0`. `package-lock.json` version: `0.7.0`.
+`package-lock.json` `packages[''].version`: `0.7.0`. Unchanged at both start
+and end of this task.
+
+## 7. Predecessor reports inspected
+
+All eight implementation reports were read in full before any documentation
+edit:
+
+1. `docs/reports/v0.8-viewer-runtime-pwa-batch1.md`
+2. `docs/reports/v0.8-evidence-index-readers-batch2.md`
+3. `docs/reports/v0.8-observation-svg-inspection-batch3.md`
+4. `docs/reports/v0.8-comparison-contract-inspection-batch4.md`
+5. `docs/reports/v0.8-reference-candidate-inspection-batch5.md`
+6. `docs/reports/v0.8-binding-fidelity-interaction-batch6.md`
+7. `docs/reports/v0.8-bounded-context-correlation-batch7.md`
+8. `docs/reports/v0.8-integrated-viewer-acceptance-batch8.md`
+
+(Batches 1-7 were read in full during their own implementation sessions
+earlier in this same continuous work; Batch 8 was authored directly in the
+immediately preceding session and its content is held in full. All eight
+were treated as implementation evidence, not overriding authority, per the
+task's source-of-truth order - actual source/tests/package state governs
+wherever a report might disagree.)
+
+## 8. Source-of-truth files inspected
+
+`package.json`, `package-lock.json`, `.gitignore`, `viewer/vite.config.ts`,
+`tsconfig.json`, `scripts/check-docs.mjs`, `scripts/clean.mjs`,
+`src/viewerServer/httpServer.ts`, `src/viewerServer/viewerService.ts`,
+`viewer/src/App.tsx`, `viewer/src/components/*.tsx` (spot-checked for
+current markup), `docs/PROJECT_MILESTONES.md` (Milestone 8, lines
+1611-1715), `docs/ROADMAP.md` (v0.8/v0.9/v0.10 sections), and every document
+listed in §16 below, each read in full or via targeted `grep`-located
+sections as appropriate to its size.
+
+## 9. my-dev-kit retrieval
+
+Index built at
+`.my-dev-kit-workflow/v0.8/documentation-completeness-audit/my-dev-kit-index`
+via `npx @dailephd/my-dev-kit@latest index --root . --src src --src viewer
+--src scripts --src tests --out <index> --call-graph --json` (121 files
+indexed, 24 components, 53 hooks). All 9 required searches ran successfully
+against it (view/CLI, viewer server, evidence readers, observation viewer,
+comparison/contracts, reference viewer, bindings/fidelity, context/
+correlation, PWA, package/build) - results consistent with source
+inspection, no discrepancy found.
+
+## 10. Actual CLI help captured
+
+`npm run build` ran first; then `node dist/cli.js --help`, `--version`, and
+`<command> --help` for all 9 commands were captured verbatim to
+`.my-dev-kit-workflow/v0.8/documentation-completeness-audit/snapshots/`.
+The `view --help` output was the authority reconciled against
+`docs/COMMANDS.md`'s `## view` section - confirmed materially consistent
+(same required/optional flags, same default port `4319`, same
+no-silent-fallback-on-port-conflict behavior, same session-only/
+never-persisted framing for `--bindings-file`/`--context-file`).
+
+## 11. Package scripts captured
+
+`prebuild`, `build`, `typecheck`, `lint`, `test`, `test:browser`,
+`test:security`, `check:docs` - exact names confirmed from `package.json`
+and used consistently across all edited documentation (no invented script
+name; `check:docs` is correct, not `docs:check`).
+
+## 12. Capability completeness matrix
+
+CAPABILITY: Viewer runtime + PWA shell
+PLAN_SOURCE: ROADMAP v0.8 §"application boundary"; Milestone 8
+IMPLEMENTATION: `src/viewerServer/`, `viewer/vite.config.ts`, `viewer/src/main.tsx`
+TESTS: `tests/unit/viewerServer.test.ts`, `tests/unit/viewerPwaBuild.test.ts`, `tests/browser/viewerShell.test.ts`, `tests/browser/pwaHardening.test.ts`
+DOCUMENTATION: `docs/COMMANDS.md#view`, `docs/ARCHITECTURE.md` "v0.8 Batch 1"/"v0.8 Batch 8", `docs/SECURITY.md`
+RESULT: PASS
+
+CAPABILITY: Metadata-first evidence indexing + on-demand loading
+PLAN_SOURCE: ROADMAP v0.8 §"loading"; Milestone 8
+IMPLEMENTATION: `src/viewerServer/evidence/discovery.ts`, `classify.ts`
+TESTS: `tests/unit/viewerEvidenceIndex.test.ts` (and related), `tests/browser/viewerEvidenceShell.test.ts`
+DOCUMENTATION: `docs/ARCHITECTURE.md` "v0.8 Batch 2", `docs/COMMANDS.md#view`
+RESULT: PASS
+
+CAPABILITY: Observation SVG inspection (geometry/semantics/visibility/overflow/scroll/relationships)
+PLAN_SOURCE: Milestone 8 "Required interface capabilities"
+IMPLEMENTATION: `viewer/src/components/ObservationWorkspace.tsx`, `TargetOverlaySvg.tsx`, `src/viewerServer/evidence/observationView.ts`
+TESTS: `tests/browser/observationSvgWorkspace.test.ts`, `tests/browser/layoutRelationships.test.ts`
+DOCUMENTATION: `docs/ARCHITECTURE.md` "v0.8 Batch 3"
+RESULT: PASS
+
+CAPABILITY: Before/after comparison + contract/change-scope inspection (incl. protected/preserved-failure case)
+PLAN_SOURCE: Milestone 8 acceptance ("contract/change-scope results identify relevant regions")
+IMPLEMENTATION: `viewer/src/components/ComparisonWorkspace.tsx`, `EvaluationWorkspace.tsx`
+TESTS: `tests/browser/comparisonEvaluationWorkspace.test.ts`, `tests/browser/observationComparison.test.ts`
+DOCUMENTATION: `docs/ARCHITECTURE.md` "v0.8 Batch 4"
+RESULT: PASS
+
+CAPABILITY: External reference/candidate inspection, applicability, compatibility
+PLAN_SOURCE: Milestone 8 "Reference/candidate inspection"
+IMPLEMENTATION: `viewer/src/components/ReferenceInspector.tsx`, `ReferenceWorkspace.tsx`
+TESTS: `tests/browser/referenceCandidateWorkspace.test.ts`
+DOCUMENTATION: `docs/ARCHITECTURE.md` "v0.8 Batch 5", `docs/CONTRACTS.md`
+RESULT: PASS
+
+CAPABILITY: Explicit binding cross-selection, zoom/pan, conditional lock, on-demand fidelity
+PLAN_SOURCE: Milestone 8 acceptance ("selecting a reference region can expose the corresponding bound runtime target")
+IMPLEMENTATION: `src/domain/externalReferenceRuntimeBinding.ts`, `viewer/src/hooks/useZoomPan.ts`, `viewer/src/components/ReferenceFidelityPanel.tsx`
+TESTS: `tests/browser/referenceBindingFidelityWorkspace.test.ts` (Cases A-J)
+DOCUMENTATION: `docs/ARCHITECTURE.md` "v0.8 Batch 6", `docs/COMMANDS.md#view`
+RESULT: PASS
+
+CAPABILITY: Many reference regions → one runtime target cross-highlight (all, not one)
+PLAN_SOURCE: Milestone 8 "Reference/candidate inspection" (implicit generality of the binding cross-selection requirement)
+IMPLEMENTATION: `viewer/src/components/ReferenceWorkspace.tsx` (`regionHighlightIds` loop)
+TESTS: `tests/browser/viewerIntegratedAcceptance.test.ts` (Scenario L)
+DOCUMENTATION: `docs/reports/v0.8-integrated-viewer-acceptance-batch8.md`, `docs/ARCHITECTURE.md` "v0.8 Batch 8"
+RESULT: PASS
+
+CAPABILITY: Fidelity FAIL + contract PASS shown independently (and the reverse)
+PLAN_SOURCE: Milestone 8 architecture constraint ("must not recompute a second fidelity model")
+IMPLEMENTATION: `viewer/src/components/ReferenceWorkspace.tsx` (independence note)
+TESTS: `tests/browser/referenceBindingFidelityWorkspace.test.ts` (Case J, PASS+FAIL), `tests/browser/viewerIntegratedAcceptance.test.ts` (Scenario M, FAIL+PASS)
+DOCUMENTATION: `docs/reports/v0.8-integrated-viewer-acceptance-batch8.md`
+RESULT: PASS
+
+CAPABILITY: Bounded agent context inspection (adequacy/omissions/truncations/correlation/raw evidence)
+PLAN_SOURCE: Milestone 8 "Required interface capabilities" (bounded agent-context references, provenance)
+IMPLEMENTATION: `viewer/src/components/ContextWorkspace.tsx`, `src/viewerServer/context.ts`
+TESTS: `tests/browser/boundedContextWorkspace.test.ts` (Cases A-J)
+DOCUMENTATION: `docs/ARCHITECTURE.md` "v0.8 Batch 7", `docs/COMMANDS.md#view`, `docs/WORKFLOWS.md`
+RESULT: PASS
+
+CAPABILITY: Multiple source observations sharing a target id → all listed
+PLAN_SOURCE: Milestone 8 (implicit generality of "source-correlation evidence displays uncertainty")
+IMPLEMENTATION: `viewer/src/components/ContextWorkspace.tsx` (`SourceObservationTargetCheck`)
+TESTS: `tests/browser/viewerIntegratedAcceptance.test.ts` (Scenario N)
+DOCUMENTATION: `docs/reports/v0.8-integrated-viewer-acceptance-batch8.md`
+RESULT: PASS
+
+CAPABILITY: Safe raw-evidence navigation (path containment, exact-identity resolution)
+PLAN_SOURCE: Milestone 8 "provenance/approval information"
+IMPLEMENTATION: `viewer/src/components/RawEvidenceViewer.tsx`, `src/viewerServer/evidence/linkedEvidence.ts`
+TESTS: `tests/unit/contextViewerServer.test.ts`, `tests/browser/boundedContextWorkspace.test.ts` (Case I: missing-source; Case J: static-candidate-safety)
+DOCUMENTATION: `docs/SECURITY.md`
+RESULT: PASS
+
+CAPABILITY: PWA stale-evidence prevention (server-down behavior)
+PLAN_SOURCE: ROADMAP v0.8 (implicit in "installable PWA" application boundary + honest-states requirement)
+IMPLEMENTATION: `viewer/vite.config.ts` (`navigateFallbackDenylist`), `viewer/src/hooks/useEvidenceIndex.ts`
+TESTS: `tests/browser/pwaHardening.test.ts` ("HARD GATE" test)
+DOCUMENTATION: `docs/SECURITY.md`, `docs/CURRENT_STATE.md`
+RESULT: PASS
+
+CAPABILITY: Packaged installed viewer (works from `dist/` alone, packed candidate)
+PLAN_SOURCE: ROADMAP v0.8 (implicit packaging continuity with v0.1-v0.7)
+IMPLEMENTATION: `package.json` `files` allowlist (includes `dist/viewer`)
+TESTS: manual/local packed-candidate proof, `docs/reports/v0.8-integrated-viewer-acceptance-batch8.md` §11 (not yet in `.github/workflows/pre-release-readiness.yml` - see §19 IMPLEMENTATION_DOCUMENTATION_DRIFT note)
+DOCUMENTATION: `docs/CI_CD.md` "v0.8 packaging implications" (new this stage)
+RESULT: PASS (implementation); formal CI coverage explicitly deferred to next stage, now documented as such
+
+CAPABILITY: Read-only evidence behavior (no mutation, no viewer-owned artifact family)
+PLAN_SOURCE: Milestone 8 architecture constraint
+IMPLEMENTATION: `src/viewerServer/httpServer.ts` (global 405 on non-GET/HEAD)
+TESTS: `docs/reports/v0.8-integrated-viewer-acceptance-batch8.md` §11 (read-only hash proof); this audit's own smoke (§32 below)
+DOCUMENTATION: `docs/SECURITY.md`
+RESULT: PASS
+
+CAPABILITY: Honest missing/malformed/unsupported states
+PLAN_SOURCE: Milestone 8 "diagnostics and evidence-state distinctions"
+IMPLEMENTATION: `viewer/src/components/EvidenceList.tsx` (`supportLabel`), `src/viewerServer/context.ts` (`unsupported-version`)
+TESTS: `tests/unit/viewerEvidenceIndex.test.ts`, `tests/unit/contextViewerServer.test.ts`
+DOCUMENTATION: `docs/COMMANDS.md#view`
+RESULT: PASS
+
+CAPABILITY: No source editing (viewer never mutates target application)
+PLAN_SOURCE: Milestone 8 architecture constraint
+IMPLEMENTATION: no filesystem-write call anywhere in `src/viewerServer/`
+TESTS: implicit in every browser test (fixtures re-hashed unmutated in Batch 8's report)
+DOCUMENTATION: `docs/SECURITY.md`
+RESULT: PASS
+
+CAPABILITY: No automatic binding (explicit declaration only)
+PLAN_SOURCE: Milestone 8 "Merely opening/importing a reference... must not silently approve"; ROADMAP v0.8 acceptance
+IMPLEMENTATION: `viewer/src/components/ReferenceWorkspace.tsx` (binding lookup only against supplied declarations)
+TESTS: `tests/browser/referenceBindingFidelityWorkspace.test.ts` Case B (no declaration, equal names never cross-select)
+DOCUMENTATION: `docs/COMMANDS.md#view`, `docs/WORKFLOWS.md`
+RESULT: PASS
+
+CAPABILITY: No second evidence engine
+PLAN_SOURCE: Milestone 8 "Architecture constraint" (explicit list of 8 forbidden second-engines)
+IMPLEMENTATION: verified via `grep -rn` across `src/viewerServer` and `viewer/src` for every forbidden canonical function
+TESTS: n/a (structural audit, re-run in this stage - §3 of `docs/reports/v0.8-integrated-viewer-acceptance-batch8.md`, re-confirmed here)
+DOCUMENTATION: `docs/ARCHITECTURE.md` (every "v0.8 Batch N" section states its call sites)
+RESULT: PASS
+
+Every required v0.8 capability listed above resolves to PASS. No
+MISSING_IMPLEMENTATION, MISSING_TEST, or MISSING_DOCUMENTATION result was
+found for any material capability; the packaged-candidate row's only
+sub-finding is a DRIFT in formal CI coverage expectations, corrected by
+documentation in this stage (§37 CI_CD.md audit below) rather than by
+code - consistent with this stage's own instruction not to perform formal
+cross-platform validation itself.
+
+## 13. Milestone 8 acceptance matrix
+
+Milestone 8 (`docs/PROJECT_MILESTONES.md` lines 1611-1715) lists 10
+acceptance bullets. Each maps to an implemented+tested+documented capability
+in §12 above:
+
+1. Inspect observations/screenshots without raw files → Batch 2/3, PASS.
+2. Inspect approved references beside candidates → Batch 5, PASS.
+3. Geometry/runtime behavior/relationships/before-after understandable → Batch 3/4, PASS.
+4. Reference/candidate fidelity + applicability understandable → Batch 5/6, PASS.
+5. Contract/change-scope results identify relevant regions → Batch 4, PASS.
+6. Reference/runtime binding ambiguity remains visible → Batch 6 (`ambiguous`/`unavailable` states), PASS.
+7. Source-correlation displays uncertainty, not false ownership → Batch 7 (`correlated`/`ambiguous`/`unavailable`, never "owner"), PASS.
+8. Evidence shown is the same canonical evidence as the coding-agent workflow → §12 "No second evidence engine" row, PASS.
+9. Selecting a reference region exposes the bound runtime target + mismatch evidence → Batch 6, plus Batch 8's many-regions-to-one-target closure, PASS.
+10. CLI/programmatic workflows remain independently functional → unchanged v0.1-v0.7 CLI, confirmed via full unit/browser suite still passing, PASS.
+
+MILESTONE8_ACCEPTANCE: PASS (all 10 criteria satisfied by current
+implementation; no rewrite of Milestone 8's durable text was needed or
+performed).
+
+## 14. ROADMAP v0.8 acceptance matrix
+
+ROADMAP v0.8's "Acceptance" paragraph and "Version-start planning decisions"
+(already resolved, per its own text) were checked against implementation:
+required capabilities list (readers, screenshot/target inspection,
+reference/region inspection, geometry/semantics/scrolling/overflow/
+visibility/relationships/before-after, reference/candidate views,
+diagnostics/honest states, change-scope classifications, contract results,
+applicability/fidelity, binding/ambiguity, correlation, raw-evidence
+navigation) - every item resolves to an implemented+tested capability in
+§12. Architectural/evidence constraints (no second engine, CLI-first,
+non-mutating) - confirmed in §12/§3-of-Batch-8-report. Exclusions
+(annotation authoring, source editing, second workflow engine, automatic
+design generation, cloud hosting, mandatory viewer) - confirmed absent: no
+annotation UI exists, no source-editing code path exists, viewer remains
+optional (every CLI command works unchanged without it).
+
+V08_ROADMAP_ACCEPTANCE: PASS.
+
+## 15. Batch 1-8 gate matrix
+
+| Batch | Gate | Report verdict | Source present at HEAD | Tests present | Status |
+|---|---|---|---|---|---|
+| 1 | Viewer runtime + PWA foundation | PASS | `src/viewerServer/`, `viewer/vite.config.ts` | `tests/unit/viewerServer.test.ts`, `tests/browser/viewerShell.test.ts` | Confirmed |
+| 2 | Evidence index + readers | PASS | `src/viewerServer/evidence/discovery.ts` | `tests/browser/viewerEvidenceShell.test.ts` | Confirmed |
+| 3 | Observation SVG inspection | PASS | `viewer/src/components/ObservationWorkspace.tsx` | `tests/browser/observationSvgWorkspace.test.ts` | Confirmed |
+| 4 | Comparison/contract inspection | PASS | `viewer/src/components/ComparisonWorkspace.tsx` | `tests/browser/comparisonEvaluationWorkspace.test.ts` | Confirmed |
+| 5 | Reference/candidate inspection | PASS | `viewer/src/components/ReferenceWorkspace.tsx` | `tests/browser/referenceCandidateWorkspace.test.ts` | Confirmed |
+| 6 | Binding/fidelity interaction | PASS | `viewer/src/hooks/useZoomPan.ts` | `tests/browser/referenceBindingFidelityWorkspace.test.ts` | Confirmed |
+| 7 | Bounded context/correlation | PASS | `viewer/src/components/ContextWorkspace.tsx` | `tests/browser/boundedContextWorkspace.test.ts` | Confirmed |
+| 8 | Integrated acceptance/PWA hardening/packaging | PASS | (accessibility fix + PWA/packaging proof, no new component) | `tests/browser/viewerIntegratedAcceptance.test.ts`, `tests/browser/pwaHardening.test.ts` | Confirmed |
+
+BATCH1_TO_BATCH8_GATE_AUDIT: PASS - every batch's claimed implementation
+still exists at current HEAD and is still covered by passing tests (full
+suite re-run in §26/§27 below).
+
+## 16. Document audit ledger
+
+DOCUMENT: README.md
+ROLE: user-facing introduction and normal usage
+AUDITED: YES
+CHANGED: YES
+IMPLEMENTATION_CLAIMS: PASS
+COMMAND_CLAIMS: PASS
+RELEASE_STATE: PASS
+FUTURE_SCOPE: NOT_APPLICABLE
+PRESERVATION: PASS
+NOTES: added an "Interactive local viewer" section (implemented, unreleased) and fixed the ROADMAP-link line that falsely said "v0.8+ remain future".
+
+DOCUMENT: CHANGELOG.md
+ROLE: chronological released history plus unreleased changes
+AUDITED: YES
+CHANGED: YES
+IMPLEMENTATION_CLAIMS: PASS
+COMMAND_CLAIMS: NOT_APPLICABLE
+RELEASE_STATE: PASS
+FUTURE_SCOPE: NOT_APPLICABLE
+PRESERVATION: PASS
+NOTES: added a new `[Unreleased]` section (no such convention existed before) summarizing v0.8 user-visible capability; every existing dated release entry (`0.1.0`-`0.7.0`) left byte-unchanged.
+
+DOCUMENT: docs/PROJECT_DESCRIPTION.md
+ROLE: durable product intent and responsibility boundaries
+AUDITED: YES
+CHANGED: NO
+IMPLEMENTATION_CLAIMS: PASS
+COMMAND_CLAIMS: NOT_APPLICABLE
+RELEASE_STATE: NOT_APPLICABLE
+FUTURE_SCOPE: PASS
+PRESERVATION: PASS
+NOTES: NO CHANGE REQUIRED - every viewer mention is a durable forward-looking constraint ("the viewer must consume...", "must not create...") that remains true post-implementation, not a false current-state claim.
+
+DOCUMENT: docs/PROJECT_MILESTONES.md
+ROLE: ordered capability design and milestone acceptance
+AUDITED: YES
+CHANGED: NO
+IMPLEMENTATION_CLAIMS: PASS
+COMMAND_CLAIMS: NOT_APPLICABLE
+RELEASE_STATE: NOT_APPLICABLE
+FUTURE_SCOPE: PASS
+PRESERVATION: PASS
+NOTES: NO CHANGE REQUIRED - Milestone 8's acceptance criteria are durable capability history, all satisfied per §13; not rewritten as batch history.
+
+DOCUMENT: docs/PROJECT_OVERVIEW.md
+ROLE: concise navigation/current orientation
+AUDITED: YES
+CHANGED: YES
+IMPLEMENTATION_CLAIMS: PASS
+COMMAND_CLAIMS: NOT_APPLICABLE
+RELEASE_STATE: PASS
+FUTURE_SCOPE: PASS
+PRESERVATION: PASS
+NOTES: fixed a false claim ("Interactive viewer support... not implemented... v0.8-v0.10... remain future and unimplemented") and the workflow-arrow diagram to correctly separate implemented-unreleased v0.8 from future v0.9-v0.10.
+
+DOCUMENT: docs/ROADMAP.md
+ROLE: version-level goals/constraints/acceptance/status
+AUDITED: YES
+CHANGED: YES
+IMPLEMENTATION_CLAIMS: PASS
+COMMAND_CLAIMS: NOT_APPLICABLE
+RELEASE_STATE: PASS
+FUTURE_SCOPE: PASS
+PRESERVATION: PASS
+NOTES: added a "Current status" line to the v0.8 section (mirroring the existing v0.7 pattern); no batch content copied in (`check:docs`'s own "no Batch N in ROADMAP" rule still passes); v0.9/v0.10 sections left unchanged (their "depends on v0.8 viewer" wording was already accurate as a design dependency, not a release-state claim).
+
+DOCUMENT: docs/CURRENT_STATE.md
+ROLE: actual current implementation/repository/release state
+AUDITED: YES
+CHANGED: YES
+IMPLEMENTATION_CLAIMS: PASS
+COMMAND_CLAIMS: NOT_APPLICABLE
+RELEASE_STATE: PASS
+FUTURE_SCOPE: PASS
+PRESERVATION: PASS
+NOTES: the single largest drift found - the file ended at "v0.8+ remain future" with no v0.8 section at all. Added a full "v0.8 status" section (batch-by-batch summary, architectural invariants, validation, explicit "not yet performed" list) and fixed the header and "Next target" section; every v0.1-v0.7 Prompt-by-Prompt historical section left untouched.
+
+DOCUMENT: docs/ARCHITECTURE.md
+ROLE: actual architecture plus labeled future constraints
+AUDITED: YES
+CHANGED: YES
+IMPLEMENTATION_CLAIMS: PASS
+COMMAND_CLAIMS: NOT_APPLICABLE
+RELEASE_STATE: PASS
+FUTURE_SCOPE: PASS
+PRESERVATION: PASS
+NOTES: added a "v0.8 Batch 8" section (previously missing - Batches 1-7 each had one, Batch 8 did not); fixed two stale "planned v0.8"/"still-future v0.8-v0.10" section headers/sentences to correctly reflect v0.8 as implemented; every Batch 1-7 historical section left untouched.
+
+DOCUMENT: docs/COMMANDS.md
+ROLE: actual current command reference
+AUDITED: YES
+CHANGED: YES
+IMPLEMENTATION_CLAIMS: PASS
+COMMAND_CLAIMS: PASS
+RELEASE_STATE: PASS
+FUTURE_SCOPE: NOT_APPLICABLE
+PRESERVATION: PASS
+NOTES: `view` command's flags/behavior were already accurately documented (reconciled against actual `node dist/cli.js view --help` output, no drift found); only its stale "Current status: v0.8 Batch 7" status label was updated to reflect Batch 8 completion.
+
+DOCUMENT: docs/WORKFLOWS.md
+ROLE: actual current workflows
+AUDITED: YES
+CHANGED: YES
+IMPLEMENTATION_CLAIMS: PASS
+COMMAND_CLAIMS: PASS
+RELEASE_STATE: PASS
+FUTURE_SCOPE: PASS
+PRESERVATION: PASS
+NOTES: the entire viewer workflow was previously filed only under "Future workflows (v0.8-v0.10)". Split into a new "Current interactive viewer workflow (v0.8...)" section (documenting `view`/`--bindings-file`/`--context-file` flow per task §33) and a retitled "Future workflows (v0.9-v0.10)" section; fixed the closing "v0.8 must consume" sentence to present tense.
+
+DOCUMENT: docs/CONTRACTS.md
+ROLE: actual contract/schema/evidence boundaries
+AUDITED: YES
+CHANGED: YES
+IMPLEMENTATION_CLAIMS: PASS
+COMMAND_CLAIMS: NOT_APPLICABLE
+RELEASE_STATE: PASS
+FUTURE_SCOPE: PASS
+PRESERVATION: PASS
+NOTES: 4 narrow tense fixes (section header, "must continue to preserve" → "has preserved", "planned v0.8 viewer must consume" → "consumes... exactly as required", "follows in v0.8" → "is implemented in v0.8"); the durable design-constraint prose itself (identity/provenance/tolerance/etc. rules) was left completely unchanged, per instruction not to invent a new persisted viewer contract.
+
+DOCUMENT: docs/SECURITY.md
+ROLE: actual security boundaries and safety behavior
+AUDITED: YES
+CHANGED: YES
+IMPLEMENTATION_CLAIMS: PASS
+COMMAND_CLAIMS: NOT_APPLICABLE
+RELEASE_STATE: PASS
+FUTURE_SCOPE: PASS
+PRESERVATION: PASS
+NOTES: added a full "Interactive local viewer (v0.8...)" section (loopback-only origin, path containment, read-only API, binding/context-file explicit-input boundary, PWA cache scope, server-down protection) - previously entirely absent, the viewer's security properties were described only as "future, unimplemented concerns". Fixed "Not yet addressed" to distinguish implemented-and-locally-verified from the still-pending formal pre-release security stage, and recorded the symlink/junction residual-risk finding from the Batch 8 report.
+
+DOCUMENT: docs/DEVELOPMENT.md
+ROLE: actual development/build/test workflow
+AUDITED: YES
+CHANGED: YES
+IMPLEMENTATION_CLAIMS: PASS
+COMMAND_CLAIMS: PASS
+RELEASE_STATE: NOT_APPLICABLE
+FUTURE_SCOPE: NOT_APPLICABLE
+PRESERVATION: PASS
+NOTES: fixed stale test counts (627/32 files, 120 tests → 1156/63 files, 178/19 files, with an added caveat that exact counts drift and the commands are authoritative); fixed the viewer-smoke paragraph's "never reads... in this batch" phrasing (now accurately describes the final v0.8 behavior: reads `--root` for bounded discovery, never writes to it) and added `--bindings-file`/`--context-file` to the smoke example.
+
+DOCUMENT: docs/CI_CD.md
+ROLE: actual CI/package/release-validation process
+AUDITED: YES
+CHANGED: YES
+IMPLEMENTATION_CLAIMS: PASS
+COMMAND_CLAIMS: NOT_APPLICABLE
+RELEASE_STATE: PASS
+FUTURE_SCOPE: NOT_APPLICABLE
+PRESERVATION: PASS
+NOTES: added a new "v0.8 packaging implications" section documenting the real build/package facts (viewer assets built into `dist/viewer`, already inside the `files` allowlist) and explicitly stating that `.github/workflows/pre-release-readiness.yml` has NOT been extended to cover v0.8, and that Batch 8's local packed-candidate proof is genuine evidence but not a substitute for that formal matrix - this was previously entirely undocumented (silent gap, not a false claim).
+
+DOCUMENT: docs/QUICKSTART.md
+ROLE: user-facing quickstart
+AUDITED: YES
+CHANGED: YES
+IMPLEMENTATION_CLAIMS: PASS
+COMMAND_CLAIMS: PASS
+RELEASE_STATE: PASS
+FUTURE_SCOPE: NOT_APPLICABLE
+PRESERVATION: PASS
+NOTES: added one short paragraph pointing to `view` (previously not mentioned at all).
+
+DOCUMENT: docs/plans/v0.8-implementation-plan.md
+ROLE: frozen concrete implementation plan
+AUDITED: YES
+CHANGED: NO
+IMPLEMENTATION_CLAIMS: PASS
+COMMAND_CLAIMS: NOT_APPLICABLE
+RELEASE_STATE: PASS
+FUTURE_SCOPE: NOT_APPLICABLE
+PRESERVATION: PASS
+NOTES: NO CHANGE REQUIRED - it already correctly self-describes as "planning authority only... does not prove that any v0.8 batch has been implemented" and already correctly states the exact post-Batch-8 workflow this audit stage is performing; nothing to repair.
+
+DOCUMENT: docs/DOCUMENTATION_PRESERVATION_POLICY.md
+ROLE: meta-policy for documentation responsibility
+AUDITED: YES
+CHANGED: NO
+IMPLEMENTATION_CLAIMS: NOT_APPLICABLE
+COMMAND_CLAIMS: NOT_APPLICABLE
+RELEASE_STATE: NOT_APPLICABLE
+FUTURE_SCOPE: NOT_APPLICABLE
+PRESERVATION: PASS
+NOTES: NO CHANGE REQUIRED - durable meta-policy, no v0.8-specific claims.
+
+DOCUMENT: docs/RELEASE.md
+ROLE: release-history/readiness record
+AUDITED: YES
+CHANGED: NO
+IMPLEMENTATION_CLAIMS: NOT_APPLICABLE
+COMMAND_CLAIMS: NOT_APPLICABLE
+RELEASE_STATE: PASS
+FUTURE_SCOPE: NOT_APPLICABLE
+PRESERVATION: PASS
+NOTES: NO CHANGE REQUIRED - accurately records the `0.7.0` release and prior releases; makes no claim about v0.8 (correctly silent, since v0.8 has not been released) - the record it exists to keep is release history, not in-repository-implementation status, which is `CURRENT_STATE.md`'s role.
+
+## 17. Command consistency audit
+
+Built a command/flag matrix from actual `node dist/cli.js <command> --help`
+output (§10) and compared it against `README.md`, `docs/COMMANDS.md`,
+`docs/WORKFLOWS.md`, `docs/DEVELOPMENT.md`, `docs/QUICKSTART.md`. No flag,
+default value, or exit-code-behavior mismatch was found for any of the 9
+commands. `view`'s documented syntax
+(`--root`/`--bindings-file`/`--context-file`/`--port`/`--no-open`) matches
+the captured help output exactly. COMMAND_SURFACE_AUDIT: PASS.
+
+## 18. Schema/version consistency audit
+
+Compared documentation against actual constants: observation schema `1.2.0`
+(`src/domain/schema.ts`), comparison schema `1.0.0`, frontend contract
+schema `1.0.0`, evaluation artifact schema `1.0.0`, bounded-agent-context
+schema `1.0.0`, external-reference schema `1.0.0` - no v0.8 batch bumped any
+schema version, and no documentation claims otherwise (`docs/CURRENT_STATE.md`
+still correctly cites all six versions at the top). Package version `0.7.0`
+confirmed consistent everywhere it is cited. SCHEMA_VERSION_AUDIT: PASS.
+
+## 19. Release-state consistency audit
+
+Searched every edited document plus README/CHANGELOG for
+"0.8.0 released"/"0.8.0 published"/"current version 0.8.0"/"latest package
+0.8.0"/"release-ready"/"publish-ready"/"cross-platform ready" (case
+insensitive) - zero matches. Searched broadly for any remaining "v0.8...
+future/unimplemented/not yet/planned" phrasing and found two genuine
+remaining drifts in `docs/ARCHITECTURE.md` (a stale section header calling
+v0.8 "planned" and a stale "still-future v0.8-v0.10" sentence), both
+corrected (§16 above). PACKAGE_RELEASE_STATE_AUDIT: PASS.
+
+## 20. Future-scope audit
+
+Searched for `v0.9`/`annotation`/`draw`/`resize`/`move`/`remove`/`visual
+intent`/`source edit`/`automatic correction`/`image-to-code` across the
+repository. No v0.9+ feature (structured annotation, region drawing/resize/
+move, requirement editing, automatic source correction, image-to-code
+generation) is implemented anywhere in `src/` or `viewer/src/`, and no
+documentation describes any of them as current. All such mentions remain
+correctly scoped to "future"/"v0.9"/"v0.10" sections. FUTURE_V09_SCOPE_PRESERVED: PASS.
+
+## 21. Architecture drift audit
+
+See §16 (docs/ARCHITECTURE.md entry) and §3/§12 above (no-second-engine
+re-audit). ARCHITECTURE drift found and corrected: missing Batch 8 section,
+two stale "planned"/"still-future" sentences. No drift found in the
+per-batch 1-7 sections (each remains an accurate historical record of what
+that batch actually implemented, still true at current HEAD).
+
+## 22. Workflow drift audit
+
+See §16 (docs/WORKFLOWS.md entry). The entire viewer workflow was
+undocumented as "current" (filed only under "Future workflows") - corrected
+with a genuine new current-workflow section per task §33's exact required
+content (view → server → discovery → readers → on-demand loading → modes;
+`--bindings-file` → binding evaluation → cross-selection → on-demand
+fidelity; `--context-file` → context inspection → provenance → raw-evidence
+navigation; viewer-is-optional/non-mutating/no-my-dev-kit/no-context-rebuild
+invariants).
+
+## 23. Security-documentation audit
+
+See §16 (docs/SECURITY.md entry) and §35 task requirement. All required
+boundary facts (loopback-only, fixed origin, explicit evidence root, path
+containment, traversal rejection, read-only API, no target/evidence
+mutation, binding/context-file explicit-session-input framing, PWA cache
+scope, server-down protection) are now documented, each citing the actual
+mechanism (`127.0.0.1` bind, single top-of-handler 405 check,
+`navigateFallbackDenylist`, etc.) rather than generic prose. Symlink/
+junction-escape handling is explicitly recorded as a residual risk, not
+claimed as covered. No claim that a formal pre-release security audit has
+already passed for v0.8 - explicitly the opposite.
+
+## 24. PWA-documentation accuracy audit
+
+Every PWA claim added to `docs/SECURITY.md`/`docs/CURRENT_STATE.md`/
+`docs/ARCHITECTURE.md`/README this stage is scoped to what Batch 8 actually
+proved: live service-worker registration, manifest fetch, zero `/api/`
+cache-storage entries, and the server-down hard gate holding - all real
+Chromium proof, not static-file inspection alone. No document claims
+"actual OS PWA installation verified" - Batch 8's own honest finding
+(`ACTUAL_OS_PWA_INSTALLATION_VERIFIED: NO`, CDP display-mode emulation
+accepted but not observed to take effect) is preserved as-is in the Batch 8
+report and not overstated anywhere in the reconciled documentation.
+
+## 25. Binding/fidelity/context terminology audit
+
+Spot-checked every edited document for the terminology rules in the task
+(§53-57): "reference region" vs "runtime target" kept distinct everywhere;
+"binding exists only through explicit declaration" preserved (`docs/WORKFLOWS.md`
+new section explicitly states cross-selection only fires for a declared,
+resolved `bound` result); "compatibility ≠ fidelity", "fidelity PASS ≠
+contract PASS", "adequacy ≠ fidelity PASS" all preserved in
+`docs/CONTRACTS.md`/`docs/COMMANDS.md` unchanged prose; "correlated
+candidate"/"ambiguous candidates" used, never "owner"/"owned by" (confirmed
+via `grep -i "owner\|owned by"` across edited docs - no hits introduced by
+this stage's edits); "`--context-file` supplied to viewer" kept distinct
+from "persisted viewer artifact" everywhere it was added or touched.
+
+## 26. Historical preservation audit
+
+No historical implementation report was modified. No CHANGELOG entry for
+`0.1.0`-`0.7.0` was altered, reordered, or deleted (only a new
+`[Unreleased]` section was prepended). No ROADMAP version section was
+deleted, merged, or compressed - v0.1 through v0.10 all still present
+(`check:docs`'s own loop confirms this programmatically). No Milestone was
+deleted or compressed (`docs/PROJECT_MILESTONES.md` untouched). No
+per-batch "v0.8 Batch N" or "v0.7 Prompt N" historical section in
+`docs/ARCHITECTURE.md`/`docs/CURRENT_STATE.md` was rewritten - only new
+sections were appended and a small number of forward-looking-tense
+sentences outside those historical sections were corrected to present tense.
+
+## 27. Documentation changes made
+
+Summarized in full in §16 above (per-document ledger). In one sentence: 13
+documentation files plus `scripts/check-docs.mjs` were changed, all
+additive or narrow-tense-correcting; zero product source files were
+touched; zero historical content was deleted or rewritten.
+
+## 28. Documents audited but unchanged
+
+`docs/PROJECT_DESCRIPTION.md`, `docs/PROJECT_MILESTONES.md`,
+`docs/plans/v0.8-implementation-plan.md`,
+`docs/DOCUMENTATION_PRESERVATION_POLICY.md`, `docs/RELEASE.md` - see §16 for
+the explicit "NO CHANGE REQUIRED" reasoning recorded for each.
+
+## 29. Documentation-check changes
+
+`scripts/check-docs.mjs` gained two narrow assertions, both targeting a
+demonstrated recurring drift class from this exact audit and from the
+task's own explicit warning (§79): (1) `package.json` and
+`package-lock.json` versions (including `packages[''].version`) must match
+each other - guards against exactly the "documentation-stage accidentally
+changed the version" mistake the task explicitly names; (2) `CHANGELOG.md`
+must contain the literal string `[Unreleased]` - guards against the
+just-introduced unreleased-work convention silently disappearing in a
+future edit. Both are cheap, structural, and low-false-positive-risk. No
+dedicated unit test file was added for `scripts/check-docs.mjs` - no such
+test convention exists for any script under `scripts/` in this repository
+(including the pre-existing `scripts/clean.mjs`), and the change is
+directly exercised by `npm run check:docs` itself, which is part of the
+full validation chain re-run in §31 below.
+
+## 30. Pre-edit validation results
+
+Before any documentation edit: `git status --short` clean, HEAD confirmed
+at `66c812e`, ancestry confirmed, package/package-lock versions confirmed
+`0.7.0`/`0.7.0`/`0.7.0`. (The full validation chain was not separately
+re-run pre-edit beyond this, since Batch 8's own immediately-preceding
+session had already run and recorded a fully passing chain at this exact
+HEAD - see `docs/reports/v0.8-integrated-viewer-acceptance-batch8.md` §10 -
+and no product code was touched between that run and this audit's start.)
+
+## 31. Post-edit validation results
+
+| Command | Result |
+|---|---|
+| `npx tsc --noEmit -p tsconfig.json` | clean |
+| `npm run typecheck` (both `tsconfig.json` and `viewer/tsconfig.json`) | clean |
+| `npm run lint` | clean |
+| `npm test` | 1156/1156 passed, 63 files |
+| `npm run build` | clean (tsc + vite build + PWA precache generation) |
+| `npm run check:docs` | passed (17 required files; both new hardened checks passed) |
+| `npm run test:browser` | 178/178 passed, 19 files |
+| `git diff --check` | clean |
+
+## 32. Viewer smoke result
+
+Built a fresh evidence root (`writeBoundedContextEvidenceFixture`, real
+canonical writers) plus a `bindings.json` and `context.json` matching the
+exact documented shapes, under
+`.my-dev-kit-workflow/v0.8/documentation-completeness-audit/smoke/`. Ran
+`node dist/cli.js view --root <fixture-root> --bindings-file
+<bindings.json> --context-file <context.json> --port 4319 --no-open`
+verbatim as documented:
+
+- Command started and printed `Viewer: http://127.0.0.1:4319` /
+  `Root: <path>` / `Press Ctrl+C to stop.`, matching `docs/COMMANDS.md`
+  exactly.
+- `netstat` confirmed the listener bound only to `127.0.0.1:4319`.
+- `GET /api/index` returned real evidence records; `GET /api/context`
+  returned `status: "valid"` with the supplied artifact; `POST /api/index`
+  returned `405`, live-confirming the write-method-rejection claim in
+  `docs/SECURITY.md`.
+- A first attempt on a port already held by a stray leftover process from
+  an earlier session correctly failed with the exact documented
+  "port already in use... never silently substituted" diagnostic - this
+  incidentally re-confirmed that exact documented behavior live, before the
+  stray process was killed and a clean run performed.
+- Server stopped cleanly; SHA-256 of every file in the evidence root was
+  identical before and after the whole session (15 files, byte-for-byte
+  unchanged).
+
+VIEWER_HELP_SMOKE: PASS. VIEWER_START_SMOKE: PASS. DOCUMENTED_EXAMPLE_EXECUTION: PASS.
+
+## 33. Generated path inventory
+
+Everything generated by this stage lives under
+`.my-dev-kit-workflow/v0.8/documentation-completeness-audit/`:
+`tmp/`, `cache/`, `logs/` (unused - no log files were needed this stage),
+`smoke/` (the fixture/bindings/context files and hash snapshots above,
+proof artifacts, not committed), `my-dev-kit-index/` (the retrieval index),
+`audit/` (unused - findings were written directly into this report rather
+than staged in scratch files), `snapshots/` (captured CLI help output).
+Plus the normal `node_modules/` and `dist/` (rebuilt by `npm run build`,
+neither committed). Nothing was written to `C:`, Downloads, a prior
+implementation-batch workflow root, or the repository root.
+
+## 34. Repository hygiene
+
+`git status --short` before staging showed exactly: 13 modified
+documentation files plus `scripts/check-docs.mjs` - no untracked file, no
+deletion, no tarball, no consumer install, no PWA profile, nothing outside
+`.my-dev-kit-workflow/`. `git diff --stat`: 14 files changed, 563
+insertions, 56 deletions - entirely additive/corrective, no bulk rewrite.
+REPOSITORY_POLLUTION_CHECK: PASS.
+
+## 35. Remaining risks
+
+- Formal Windows/Linux/macOS cross-platform pre-release readiness for the
+  v0.8 viewer/PWA surface has not been performed (explicitly the next
+  workflow stage's job, now clearly documented as pending in
+  `docs/CI_CD.md` rather than silently absent).
+- Formal pre-release security review of the v0.8 viewer surface has not
+  been performed (Batch 8's audit was local/manual; now clearly documented
+  as such in `docs/SECURITY.md`).
+- Symlink/junction filesystem-escape handling for the viewer's raw-evidence
+  routes remains untested by a dedicated test (carried forward from Batch
+  8's own report, now also reflected in `docs/SECURITY.md`).
+- Standalone/installed-PWA behavioral proof did not exceed CDP
+  command-acceptance in Batch 8 (matchMedia did not reflect the emulated
+  display-mode feature) - a genuine open question worth follow-up
+  investigation, not resolved or claimed resolved by this stage.
+- `.github/workflows/pre-release-readiness.yml` has not been extended to
+  cover the v0.8 viewer/PWA surface - explicitly deferred to the next
+  stage, not performed here.
+
+## 36. Next-stage decision
+
+READY_FOR_V08_PRERELEASE_READINESS.
+
+## 37. Final verdict
+
+PASS_V08_HARDENED_DOCUMENTATION_AND_IMPLEMENTATION_COMPLETENESS_AUDIT