@dailephd/my-frontend-observer 0.8.1 → 0.9.1

package/docs/reports/v0.9-batch7-integrated-acceptance.md

@@ -0,0 +1,644 @@
+# v0.9 Batch 7 Report: Integrated Acceptance, Packaging, Documentation, and Regression
+
+## 1. VERDICT
+
+PASS_V0_9_BATCH7_INTEGRATED_IMPLEMENTATION_COMPLETE
+
+v0.9 implementation is complete in the repository and validated locally. v0.9
+is not released. The package version is still `0.8.1`.
+
+## 2. Repository identity
+
+1. Repository: `C:\Users\daile\Projects\my-frontend-observer`
+2. Branch: `master`
+3. Starting HEAD: `1dccd17d0fe9dfbbc5d476ea8deaae9625e1f395`
+4. Ending HEAD before the final commit: `1dccd17d0fe9dfbbc5d476ea8deaae9625e1f395`
+5. Package: `@dailephd/my-frontend-observer`, version `0.8.1` (unchanged in
+   `package.json` and `package-lock.json`)
+6. Node `v24.20.0`, npm `11.19.0`, Windows 11 (win32 x64)
+
+## 3. Prompt 6 entry gate
+
+1. Preflight: branch `master`, HEAD `1dccd17d0fe9dfbbc5d476ea8deaae9625e1f395`,
+   package `0.8.1`, clean tracked worktree.
+2. All six prior reports exist with PASS verdicts:
+   1. `PASS_V0_9_BATCH1_VISUAL_ANNOTATION_FOUNDATION`
+   2. `PASS_V0_9_BATCH2_VIEWER_ANNOTATION_AUTHORING_BOUNDARY`
+   3. `PASS_V0_9_BATCH3_RUNTIME_SCREENSHOT_ANNOTATION_AUTHORING`
+   4. `PASS_V0_9_BATCH4_EXTERNAL_REFERENCE_ANNOTATION_AUTHORING`
+   5. `PASS_V0_9_BATCH5_RUNTIME_INTENT_CONTRACT_PROMOTION`
+   6. `PASS_V0_9_BATCH6_REFERENCE_MATERIALIZATION`
+3. Constants verified in source: viewer protocol `1.3.0`
+   (`src/viewerServer/httpServer.ts`), visual annotation schema `1.0.0`,
+   frontend contract schema `1.0.0`, external-reference schema `1.0.0`.
+4. `git ls-files -v docs/reports/v0.9-architecture-retrieval.md` printed `S` at
+   entry and before commit. The skip-worktree state was preserved. The file was
+   not restored, overwritten, deleted, or committed. No pull, rebase, reset,
+   stash, or clean was run.
+
+## 4. v0.9 implementation inventory
+
+This inventory lists implemented owners. It is not release evidence.
+
+1. Annotation domain: `src/domain/visualAnnotation.ts`.
+2. Annotation identity: `src/domain/visualAnnotationIdentity.ts`.
+3. Annotation reader and writer: `src/artifacts/visualAnnotationArtifactReader.ts`
+   and `src/artifacts/visualAnnotationArtifactWriter.ts`.
+4. Annotation persistence: `src/application/visualAnnotationPersistenceService.ts`.
+5. Viewer discovery: `visual-annotation` classification and `.tmp-*` exclusion
+   in `src/viewerServer/evidence/`, plus `evidence/annotationView.ts`.
+6. Annotation overlay media: the verified `annotation-overlay` media role.
+7. Secure authoring boundary: `src/viewerServer/authoringSecurity.ts`, the
+   shared gate in `httpServer.ts`, and the write queue in
+   `src/viewerServer/annotationAuthoring.ts`.
+8. Runtime annotation UI: `viewer/src/components/AnnotationLayer.tsx`,
+   `AnnotationToolbar.tsx`, `RuntimeAnnotationPanel.tsx`, and the runtime hooks.
+9. Reference annotation UI: `ReferenceAnnotationPanel.tsx`,
+   `CandidateRegionPreviewLayer.tsx`, and the reference hooks.
+10. Runtime intent model: `viewer/src/annotation/runtimeIntent.ts`.
+11. Runtime and reference confirmation: `viewer/src/annotation/confirmation.ts`
+    and `referenceIntent.ts`.
+12. Contract promotion: `src/application/visualAnnotationContractPromotionService.ts`
+    and `src/viewerServer/annotationContractPromotion.ts`.
+13. Reference materialization:
+    `src/application/visualAnnotationReferenceMaterializationService.ts` and
+    `src/viewerServer/annotationReferenceMaterialization.ts`.
+14. Project contract activation: `activateProjectChangeContract` in
+    `src/application/projectWorkflowService.ts`.
+
+## 5. Integrated acceptance matrix
+
+Every scenario below passed in the Pass A full runs (`npm run test:browser`:
+26 files, 235 tests; `npm test`: 84 files, 1379 tests) and in the packed smokes
+recorded in sections 15 to 17.
+
+1. Scenario 1: runtime annotation
+   1. Requirement: project-aware view, draw and note, save, reload the browser,
+      same canonical source, item ids, structured marks, and runtime CSS-pixel
+      geometry.
+   2. Test: `tests/browser/v09IntegratedAcceptance.test.ts`, "annotates a
+      runtime observation, reloads it from canonical evidence, promotes only
+      confirmed supported intent, and keeps remove, notes, and free marks
+      non-contractual". Also `tests/browser/runtimeAnnotationAuthoring.test.ts`,
+      "reloads a saved annotation from canonical evidence with the same ids,
+      marks, associations, and source", and the packed v0.9 smoke.
+   3. Result: PASS
+   4. Evidence: the persisted source matches the observation id and request id.
+      After `page.reload()` the loaded draft renders the same four item ids,
+      and the rendered rectangle `x` and `width` equal the persisted runtime
+      CSS-pixel values.
+2. Scenario 2: alias identity
+   1. Requirement: alias current to A, annotate A, alias moves to B, the
+      annotation stays bound to A.
+   2. Test: `tests/browser/runtimeAnnotationAuthoring.test.ts`, "never rebinds
+      a saved annotation when the alias moves to another observation".
+   3. Result: PASS
+   4. Evidence: after the canonical alias catalog moves `current` to B and the
+      viewer restarts, B shows no saved annotations, A still lists X, and the
+      persisted source still names A.
+3. Scenario 3: move intent to contract
+   1. Requirement: mark, explicit target association, move candidate, explicit
+      confirmation, save, selected promotion, normal `PerChangeContract`.
+   2. Test: `tests/browser/v09IntegratedAcceptance.test.ts` (runtime test
+      above). Also `tests/browser/runtimeAnnotationContractPromotion.test.ts`,
+      "promotes explicit move intents; arrow direction never decides the move
+      direction", and the packed v0.9 smoke.
+   3. Result: PASS
+   4. Evidence: the promoted contract has `contractClass: change`, schema
+      `1.0.0`, and exactly one clause `requested`
+      `property-increases header.x`.
+4. Scenario 4: preserve intent to contract
+   1. Requirement: one complete preserve path into a canonical contract.
+   2. Test: `tests/browser/runtimeAnnotationContractPromotion.test.ts`,
+      "promotes only the selected items, including expected-dependent resize
+      and preserve property/relationship intent".
+   3. Result: PASS
+   4. Evidence: a preserved `property-unchanged-within-tolerance sidebar.width`
+      (absolute-px 2) clause and a protected `relationship-unchanged` clause
+      are persisted in normal canonical `PerChangeContract` artifacts.
+5. Scenario 5: remove remains unsupported
+   1. Requirement: remove candidate, confirm, save and reload, no primitive, no
+      checkbox, forced promotion rejected, no contract.
+   2. Test: `tests/browser/v09IntegratedAcceptance.test.ts` (runtime test).
+      Also `runtimeAnnotationContractPromotion.test.ts`, "keeps remove,
+      inspect, and unconfirmed candidates out of promotion, including forced
+      API requests".
+   3. Result: PASS
+   4. Evidence: the saved remove item is confirmed with no `contractPrimitive`.
+      After reload its promotion checkbox is disabled. A forced promotion
+      returns 422, and the contracts directory holds only the move contract.
+6. Scenario 6: ambiguous or free drawing
+   1. Requirement: a free mark stays visual evidence and never becomes an
+      association, clause, or requirement.
+   2. Test: `tests/browser/v09IntegratedAcceptance.test.ts` (runtime test).
+      Also `runtimeAnnotationAuthoring.test.ts`, "never associates a mark drawn
+      over a target until the user explicitly associates it", and
+      `referenceAnnotationAuthoring.test.ts`, "never turns drawn geometry over a
+      region into a requirement, and saving never confirms".
+   3. Result: PASS
+   4. Evidence: a rectangle drawn over `header` is saved uninterpreted with no
+      association. It is not listed for promotion, and a forced promotion
+      returns 422.
+7. Scenario 7: reference annotation
+   1. Requirement: open a reference, draw, save, reload, reference-image pixels.
+   2. Test: `tests/browser/v09IntegratedAcceptance.test.ts`, "annotates an
+      approved reference in image pixels, reloads it, and materializes a
+      confirmed region and measurement requirement into a new imported
+      revision without touching sources or project acceptance". Also
+      `referenceAnnotationAuthoring.test.ts`, "reloads marks, associations, and
+      candidate/confirmed intent from canonical evidence on the exact
+      reference".
+   3. Result: PASS
+   4. Evidence: the persisted source is `reference-image-px` 400x300 for the
+      approved reference, with the imported image owner. After reload the
+      rendered rectangle equals the persisted reference-pixel mark (x 200,
+      height 100 within one pixel of pointer input).
+8. Scenario 8: region create materialization
+   1. Requirement: rectangle, candidate create, confirm, save, select,
+      materialize, new imported reference, source unchanged, explicit
+      supersession.
+   2. Test: `tests/browser/v09IntegratedAcceptance.test.ts` (reference test).
+      Also `tests/browser/referenceAnnotationMaterialization.test.ts`,
+      "materializes a confirmed created region into a new imported revision
+      without approval, config change, or switching the viewed reference", and
+      the packed v0.9 smoke.
+   3. Result: PASS
+   4. Evidence: the new artifact is `imported`, supersedes the approved source
+      id, and has regions `header`, `sidebar`, `hero-new`. Byte snapshots of
+      the approved and imported source directories are identical.
+9. Scenario 9: region refine materialization
+   1. Requirement: existing region, candidate refine, confirm, materialize,
+      revised rectangle, same id, old reference unchanged.
+   2. Test: `tests/browser/referenceAnnotationMaterialization.test.ts`,
+      "materializes a confirmed refinement from an approved source, superseding
+      the approved id and reusing the owning image bytes".
+   3. Result: PASS
+   4. Evidence: `sidebar` keeps its id with the new rectangle, `header` is
+      unchanged, and both source directories are byte-identical.
+10. Scenario 10: reference requirements
+    1. Requirement: region-property, region-relationship, and
+       region-measurement travel through canonical reference semantics, with
+       at least one going from viewer authoring to a new
+       `ExternalReferenceArtifact`.
+    2. Tests:
+       1. region-measurement, full path:
+          `tests/browser/v09IntegratedAcceptance.test.ts` (reference test).
+       2. region-property, full path:
+          `referenceAnnotationMaterialization.test.ts`, "materializes only the
+          selected subset: a created region and a requirement against it,
+          never the unselected create".
+       3. region-relationship: authoring and confirmation in
+          `referenceAnnotationAuthoring.test.ts`, "authors a
+          region-relationship requirement only from canonical relationships,
+          with no tolerance". Materialization and canonical relationship
+          derivation in `tests/unit/visualAnnotationReferenceMaterialization.test.ts`,
+          "keeps existing requirements first with recomputed identical ids,
+          then selected requirements in selection order" and "exposes normal
+          canonical relationships and adequacy for the new reference".
+    3. Result: PASS
+    4. Evidence: the materialized measurement requirement persists only
+       `category`, `requirementId`, `subject`, and `tolerance` (no measured
+       value). All requirements pass canonical validation.
+11. Scenario 11: informational intent
+    1. Requirement: inspect, note, and asset-sensitive stay informational.
+    2. Tests: `tests/browser/v09IntegratedAcceptance.test.ts` (note, runtime
+       test); `runtimeAnnotationContractPromotion.test.ts` (inspect forced
+       422); `referenceAnnotationMaterialization.test.ts`, "keeps
+       informational and candidate items unselectable, and forced API requests
+       for them are rejected without a write"; and
+       `referenceAnnotationAuthoring.test.ts`, "records informational and
+       asset-sensitive intent only through explicit actions and confirmation".
+    3. Result: PASS
+    4. Evidence: notes and inspect items are never listed for promotion, and
+       forced promotion returns 422. Informational reference items are
+       disabled with the informational reason, and forced materialization
+       returns 422 with no reference written.
+12. Scenario 12: stale revision
+    1. Requirement: B supersedes A, a second child from stale A conflicts with
+       no overwrite and no silent branch.
+    2. Test: `tests/browser/v09IntegratedAcceptance.test.ts`, "rejects a second
+       child of a stale revision without overwrite, and keeps an annotation
+       inspectable with an honestly unavailable source". Also
+       `runtimeAnnotationAuthoring.test.ts`, "keeps the draft and shows a
+       conflict when the loaded parent was already revised elsewhere, without
+       retrying".
+    3. Result: PASS
+    4. Evidence: two real pages share one viewer. The stale page receives 409
+       and a "Save conflict" alert and keeps its draft. Exactly two annotation
+       directories exist, and A and B manifests are byte-identical.
+13. Scenario 13: unrelated origin
+    1. Requirement: an unrelated browser origin cannot POST any authoring
+       write. The security suite covers all three routes.
+    2. Test: `tests/browser/v09IntegratedAcceptance.test.ts`, "never lets an
+       unrelated browser origin read the authoring capability or write through
+       any authoring POST route". Unit route suites
+       `viewerAuthoringSecurity.test.ts`, `viewerAnnotationAuthoring.test.ts`,
+       `viewerAnnotationContractPromotion.test.ts`, and
+       `viewerAnnotationReferenceMaterialization.test.ts` (all in
+       `npm run test:security`).
+    3. Result: PASS
+    4. Evidence: from a real page on another loopback origin, reading
+       `/api/authoring/session` and JSON POSTs to all three routes are blocked
+       by the browser. Simple no-cors POSTs are opaque. With the real token, a
+       request carrying the unrelated `Origin` returns 403 on all three routes.
+       No annotation, contract, or reference was written.
+14. Scenario 14: missing source
+    1. Requirement: the annotation stays loadable after its source
+       disappears, source status `unavailable`, no replacement guessed.
+    2. Test: `tests/browser/v09IntegratedAcceptance.test.ts` (stale revision
+       and missing source test). Also `tests/unit/viewerAnnotationEvidence.test.ts`,
+       "D: keeps the annotation loadable and reports the source unavailable when
+       source evidence is removed".
+    3. Result: PASS
+    4. Evidence: after the observation directory is moved outside the evidence
+       root, the annotation is still a supported evidence-list entry with a raw
+       preview. Its view route returns 200 with `source.status: unavailable`,
+       no handle, and no mention of the other observation present in the root.
+15. Scenario 15: v0.8 viewer regression
+    1. Requirement: screenshot, targets, relationships, comparison, contract
+       evaluation, reference and candidate inspection, bindings, fidelity,
+       bounded context, zoom and pan, PWA shell.
+    2. Tests (all unchanged v0.8 browser suites, run in `npm run test:browser`):
+       1. `observationSvgWorkspace.test.ts` (screenshot, targets, relationships);
+       2. `comparisonEvaluationWorkspace.test.ts` (comparison, contract
+          evaluation, safety case);
+       3. `referenceCandidateWorkspace.test.ts` (reference and candidate);
+       4. `referenceBindingFidelityWorkspace.test.ts` (bindings, zoom and pan,
+          lock, fidelity);
+       5. `boundedContextWorkspace.test.ts` (bounded context);
+       6. `viewerIntegratedAcceptance.test.ts` (v0.8 integrated scenarios);
+       7. `viewerShell.test.ts`, `viewerEvidenceShell.test.ts`, and
+          `pwaHardening.test.ts` (shell, index, PWA);
+       8. the packed viewer smoke.
+    3. Result: PASS
+    4. Evidence: every listed suite passed unchanged except `pwaHardening`,
+       which gained the materialization route in its no-cache assertion.
+16. Scenario 16: v0.8.1 project workflow regression
+    1. Requirement: `init`, `capture baseline`, `check baseline`, `view`, and
+       advanced low-level commands.
+    2. Tests: `projectCheckWorkflow.test.ts`, `projectWorkflowViewer.test.ts`,
+       `tests/unit/cliProjectWorkflow.test.ts`; low-level
+       `cliObserve.test.ts`, `cliCompare.test.ts`, and
+       `cliFrontendContracts.test.ts`; the packed observation smoke (low-level
+       installed commands) and the packed viewer smoke (installed
+       `init`/`capture`/`check`/`view` with REVIEW_REQUIRED, FAIL, and PASS).
+    3. Result: PASS
+    4. Evidence: all suites pass. Annotation is never required for ordinary
+       project use. The packed v0.9 smoke also ran `init`, `capture baseline`,
+       and `check baseline --json` (deterministic REVIEW_REQUIRED with no
+       acceptance configured).
+17. Scenario 17: clean installed package
+    1. Requirement: from the installed tarball only, project workflow,
+       project-aware authoring, runtime save and reload, promotion, contract
+       inspection, reference annotation, materialization, new reference
+       inspection, and standalone read-only safety.
+    2. Test: `scripts/ci/runPackedV09AnnotationSmoke.mjs` against the exact
+       packed tarball.
+    3. Result: PASS
+    4. Evidence: see sections 13, 14, and 17. Every summary flag was true.
+
+## 6. Runtime annotation integrated proof
+
+The runtime integrated test uses the real Node viewer server, the built React
+viewer, and real Chromium pointer input. It draws a move rectangle over
+`header`, a remove rectangle over `sidebar`, a free rectangle over `header`,
+and a note. It associates only the first two, sets and confirms intent, and
+saves. It reads the canonical manifest, reloads the page, reopens the
+observation, and loads the saved annotation. The rendered ids and marks match
+the canonical artifact exactly.
+
+## 7. Runtime intent/contract integrated proof
+
+After reload, only the confirmed move item is selectable. Promotion returns
+201 with one clause. The persisted contract is read with the canonical
+`readPerChangeContract`: `contractClass: change`, schema `1.0.0`, clause
+`requested` `property-increases header.x`. Forced promotion of the remove item,
+the free mark, and the note each returns 422, and no other contract exists.
+After another reload the contract is a normal supported evidence-list entry
+whose raw preview shows the clause.
+
+## 8. Reference annotation integrated proof
+
+The reference integrated test runs in a real initialized project whose
+configuration sets `acceptance.reference.approvedArtifact`. It opens the
+approved reference, draws a rectangle, proposes `hero-new`, confirms, then
+authors and confirms a preserved `region-measurement` requirement
+(`header` to `hero-new`, `vertical-gap`, exact). It saves, checks the persisted
+reference-image-pixel source, reloads, and reloads the saved annotation with
+matching rendered geometry.
+
+## 9. Reference materialization integrated proof
+
+Both confirmed items are selected and materialized. The response is 201 with
+`lifecycle: imported`, `approvalRequired: true`, and supersession of the
+approved id. The canonical reader shows regions `header`, `sidebar`,
+`hero-new` and the measurement requirement last. Both source directories are
+byte-identical, exactly one new reference directory exists, the project config
+bytes are unchanged, and only one approved reference exists. After reload the
+new reference opens in the normal reference workspace with `hero-new` rendered.
+
+## 10. Security integrated proof
+
+1. Real-browser unrelated origin: see scenario 13.
+2. Standalone read-only: the packed v0.9 smoke starts installed
+   `view --root <evidence-root>`. It proves `enabled: false`, 403 on all three
+   authoring routes even with a valid project token, no drawing or save
+   controls, no non-GET/HEAD page requests, and no evidence changes.
+3. `npm run test:security` still includes the four v0.9 security suites
+   (`viewerAuthoringSecurity`, `viewerAnnotationAuthoring`,
+   `viewerAnnotationContractPromotion`, `viewerAnnotationReferenceMaterialization`)
+   and `evidenceDiscoveryTempDirectories`. No suite was missing, so the script
+   was not changed.
+4. PWA: `pwaHardening.test.ts` and `viewerPwaBuild.test.ts` still prove no
+   `/api/` cache entries. The packed viewer smoke repeats this on the installed
+   package.
+
+## 11. Backward compatibility
+
+1. All pre-existing unit and browser suites pass unchanged.
+2. The only production source change in Prompt 7 is the `view --help` text in
+   `src/cli.ts` (see section 19). No command, flag, route, schema, or behavior
+   changed.
+3. Low-level commands, the v0.8 viewer, and the v0.8.1 project workflow pass in
+   source-tree tests and in the packed observation and viewer smokes.
+
+## 12. Packed candidate identity
+
+1. Package: `@dailephd/my-frontend-observer` `0.8.1`.
+2. Tarball filename: `dailephd-my-frontend-observer-0.8.1.tgz`.
+3. Candidate procedure (two-pass, as required):
+   1. Pass A: after all source, test, CI, and documentation changes and a full
+      local validation, `npm run build` then `npm pack --json` produced
+      candidate A. All three packed smokes ran against it.
+   2. This report was then updated with the Pass A results.
+   3. Pass B: `npm run check:docs`, `npm run build`, and `npm pack --json`
+      produced the final candidate from the final tracked content, including
+      this report. All three packed smokes ran again against that exact
+      tarball.
+4. Pass A candidate: 361 files, package size 958.9 kB, unpacked size
+   3.76 MB, SHA-256 `1733002bb83e92faf11eddc8a76d41badb31e6f067356d9de64c83af8b8a1749`. This SHA identifies candidate A only.
+5. The final candidate SHA-256 is not recorded in this report, because this
+   report is packaged under `docs` and embedding the hash would change the
+   tarball it describes. The final SHA-256 is printed in the Prompt 7 terminal
+   summary and kept in an untracked local validation note outside the package.
+
+## 13. Packed package contents
+
+The packed v0.9 smoke verified that the installed package contains non-empty:
+
+1. `dist/index.js` and `dist/cli.js`;
+2. `dist/domain/visualAnnotation.js` and `dist/domain/visualAnnotationIdentity.js`;
+3. `dist/artifacts/visualAnnotationArtifactReader.js` and
+   `dist/artifacts/visualAnnotationArtifactWriter.js`;
+4. `dist/application/visualAnnotationPersistenceService.js`,
+   `visualAnnotationContractPromotionService.js`, and
+   `visualAnnotationReferenceMaterializationService.js`;
+5. `dist/viewerServer/annotationAuthoring.js`,
+   `annotationContractPromotion.js`, and `annotationReferenceMaterialization.js`;
+6. `dist/viewer/index.html` and `dist/viewer/sw.js`.
+
+It also verified that `scripts/` is not packaged. Public exports resolved from
+the bare specifier `@dailephd/my-frontend-observer`:
+`VISUAL_ANNOTATION_ARTIFACT_KIND`, `VISUAL_ANNOTATION_SCHEMA_VERSION` (`1.0.0`),
+`isValidVisualAnnotationArtifact`, `buildVisualAnnotationRequestIdentity`,
+`buildVisualAnnotationInstanceIdentity`, `readVisualAnnotationArtifact`,
+`writeVisualAnnotationArtifact`, `persistVisualAnnotation`, and
+`materializeVisualAnnotationReference`. `promoteVisualAnnotationContract` is not
+exported by current `src/index.ts`, so it is not treated as public. It was not
+added, because Prompt 7 adds no new public surface.
+
+## 14. Installed-consumer purity
+
+1. The consumer is a fresh temporary directory outside the repository with its
+   own `package.json`. The exact tarball is installed with `npm install`.
+2. The installed CLI is resolved from the installed `package.json` `bin` and
+   must be inside the consumer's `node_modules`.
+3. A probe script inside the consumer resolves `@dailephd/my-frontend-observer`
+   and `playwright` with `import.meta.resolve`. Both must resolve inside the
+   consumer's `node_modules` (compared by realpath) and never into the
+   repository `src/` or `dist/`.
+4. Chromium is installed through the consumer-local Playwright CLI and launched
+   from the consumer-local Playwright module.
+5. Result: PASS for candidate A and for the final candidate.
+
+## 15. Packed observation smoke
+
+`node scripts/ci/runPackedObservationSmoke.mjs <tarball> --out <summary>`
+(unchanged script). Pass A: PASS (`pass: true`, including every v0.1 to v0.7 installed assertion, `packedNoRepoRootLeak`, and source immutability). It was rerun for the final candidate.
+
+## 16. Packed viewer smoke
+
+`node scripts/ci/runPackedViewerSmoke.mjs <tarball> --out <summary>` (unchanged
+script). Pass A: PASS (`result: PASS`, `viewerProtocolVersion: 1.3.0`, installed `check` REVIEW_REQUIRED then FAIL then PASS, alias correctness, traversal rejected, SVG overlay and reference view rendered, service worker registered, `/api/` never cached, server-down gate held). It was rerun for the final candidate. This smoke
+owns the installed project workflow (`init`/`capture`/`check` REVIEW_REQUIRED,
+FAIL, and PASS) and the project-aware viewer inspection proof, including
+`/api/` no-cache and the server-down stale-evidence gate.
+
+## 17. Packed v0.9 annotation smoke
+
+`node scripts/ci/runPackedV09AnnotationSmoke.mjs <tarball> --out <summary>`
+(new). Pass A: PASS (`result: PASS`, every summary flag true). It was rerun for the final candidate.
+
+This smoke owns the project-aware write proof and the standalone read-only
+proof for v0.9. Its summary reported `viewerProtocolVersion: 1.3.0` and true
+for `packageContentsPass`, `publicExportsPass`, `consumerPurityPass`,
+`projectWorkflowPass`, `authoringSessionEnabled`, `runtimeAnnotationPass`,
+`runtimePromotionPass`, `contractInspectionPass`, `referenceAnnotationPass`,
+`referenceMaterializationPass`, `newReferenceInspectionPass`, and
+`readOnlyBoundaryPass`. The summary contains no token, no absolute project
+paths, and no note text.
+
+Local classification:
+
+1. `LOCAL_PACKED_SMOKE`: PASS
+2. `CROSS_PLATFORM_WORKFLOW_WIRED`: PASS
+3. `CROSS_PLATFORM_WORKFLOW_EXECUTED`: NOT_RUN
+
+## 18. Cross-platform workflow wiring
+
+`.github/workflows/pre-release-readiness.yml` changes:
+
+1. New matrix step "Packed v0.9 annotation smoke (installed tarball only, real
+   Chromium)" runs
+   `node scripts/ci/runPackedV09AnnotationSmoke.mjs "${{ needs.candidate.outputs.tarball }}" --out v09-annotation-smoke-summary.json`
+   with `shell: bash`, after the two existing smokes.
+2. The smoke artifact upload now also includes
+   `v09-annotation-smoke-summary.json`. `smoke-summary.json` and
+   `viewer-smoke-summary.json` are kept.
+
+Validated by inspection (no local YAML parser or workflow validator exists in
+the repository):
+
+1. The `candidate` job is unchanged. It still builds one tarball with
+   `npm pack --json` on Linux and Node 24 and freezes its SHA-256.
+2. The matrix still downloads the same artifact and verifies the SHA before any
+   smoke.
+3. The matrix is still `windows-latest`, `ubuntu-latest`, and `macos-latest`
+   with `fail-fast: false`.
+4. The new step uses the exact candidate tarball output. Indentation matches
+   the sibling steps, and the file contains no tabs.
+
+The workflow was not run. Nothing was pushed.
+
+## 19. Documentation reconciliation
+
+Documentation now describes the implemented, unreleased v0.9 state
+consistently: published release `0.8.1`, v0.9 implementation complete and
+validated locally, not released, cross-platform readiness pending, viewer
+protocol `1.3.0`, annotation schema `1.0.0`.
+
+1. `README.md`: v0.9 visual annotation section, release status, and the
+   project-aware versus `--root` entry points.
+2. `CHANGELOG.md`: v0.9 additions under `[Unreleased]`. No `0.9.0` entry.
+3. `docs/ARCHITECTURE.md`: new "v0.9 visual annotation architecture" section
+   with ownership, coordinate domains, discovery, authoring security, the three
+   POST routes, and evaluator authority. Stale "v0.9 future" constraint
+   wording updated.
+4. `docs/COMMANDS.md`: `view` is the annotation entry point, `view --root` is
+   read-only, the added routes are listed, and the stale "accepts no write
+   methods" sentence is corrected. No annotation command was invented.
+5. `docs/CONTRACTS.md`: new "v0.9 visual annotation contract" section, and
+   stale "v0.9 still future" wording updated.
+6. `docs/CURRENT_STATE.md`: v0.9 status section (implementation complete, not
+   released), a note that the v0.8 GET/HEAD-only surface now has three POST
+   routes, updated "Not implemented" and "Next target".
+7. `docs/PROJECT_MILESTONES.md`: Milestone 9 implementation status line.
+8. `docs/PROJECT_OVERVIEW.md`: published `0.8.1` versus v0.9 implementation
+   complete, and the progression line.
+9. `docs/QUICKSTART.md`: concise visual annotation workflow.
+10. `docs/ROADMAP.md`: status wording only. "implementation has not started"
+    removed. The frozen v0.9 design and v0.10 are unchanged.
+11. `docs/SECURITY.md`: new "v0.9 local annotation write boundary" section, and
+    the stale "Read-only API" and "no evidence mutation" bullets corrected.
+12. `docs/WORKFLOWS.md`: runtime and reference visual flows, revisions, and
+    missing sources. The future-workflows heading was retitled.
+13. `docs/CI_CD.md`: v0.9 packaging section with the exact-candidate matrix
+    and the three packed smokes. It does not claim the matrix ran.
+14. `docs/DEVELOPMENT.md`: where authoring is available and where its proofs
+    live.
+15. `src/cli.ts` (`view --help` text only) and `tests/unit/cliView.test.ts`:
+    the help text said the server exposes "one minimal read-only status
+    endpoint" and "never writes to the supplied evidence root" for every mode.
+    That was stale after v0.9. It now says `--root` is read-only and the
+    project-aware session enables local annotation authoring. A regression
+    test covers the new text.
+
+Not modified: `docs/plans/v0.9-implementation-plan.md`, all prior batch reports,
+and the local skip-worktree architecture retrieval report.
+
+## 20. Version/release-state audit
+
+1. `package.json` version `0.8.1`. `package-lock.json` version and
+   `packages[""].version` `0.8.1`.
+2. No document says v0.9 is released or published, or that `0.9.0` is
+   available. `0.9.0` appears only as the future release to prepare.
+3. Viewer protocol `1.3.0`, visual annotation schema `1.0.0`, frontend contract
+   schema `1.0.0`, external-reference schema `1.0.0`. None changed in Prompt 7.
+4. No push, tag, publish, `npm version`, GitHub release, or release branch.
+
+## 21. Full regression validation
+
+Pass A, run on Windows from the repository root after all tracked changes
+except this report:
+
+1. `npm run typecheck`: PASS
+2. `npm run lint`: PASS. The first run found two `no-undef` errors for
+   `document` inside Playwright page closures in the new smoke script. They
+   were fixed with `globalThis.document`, and the rerun passed.
+3. `npm test`: PASS (84 files, 1379 tests)
+4. `npm run test:browser`: PASS (26 files, 235 tests, real Chromium)
+5. `npm run test:security`: PASS (unit: 16 files, 167 tests. Browser: 3 files,
+   77 tests)
+6. `npm run build`: PASS
+7. `npm run check:docs`: PASS (17 required files)
+8. `npm pack --dry-run`: PASS
+
+Focused runs before that: `tests/browser/v09IntegratedAcceptance.test.ts`
+PASS (4 tests), `tests/unit/cliView.test.ts` PASS (21 tests), and all three
+packed smokes PASS against a development tarball.
+
+Pass B, for the final candidate: `npm run check:docs`, `npm run build`, and
+`npm pack --json` were rerun, and all three packed smokes ran again. Pass B
+results are reported in the terminal summary and the untracked validation note.
+
+## 22. Scope audit
+
+1. New v0.9 product feature added: false
+2. v0.10 behavior implemented: false. The diff adds no source editing,
+   coding-agent invocation, HTML or CSS generation, automatic approval,
+   automatic baseline replacement, or new PASS/FAIL semantics.
+3. Annotation schema changed: false
+4. Frontend contract schema changed: false
+5. External-reference schema changed: false
+6. Viewer protocol changed: false
+7. Runtime or reference promotion semantics changed: false
+8. Security model changed: false
+9. Package version changed: false
+10. Dependency changed: false
+11. Frozen implementation plan changed: false
+12. Prior batch reports changed: false
+
+## 23. Changed files
+
+### 23.1 Added
+
+1. `tests/browser/v09IntegratedAcceptance.test.ts`
+2. `scripts/ci/runPackedV09AnnotationSmoke.mjs`
+3. `docs/reports/v0.9-batch7-integrated-acceptance.md`
+
+### 23.2 Modified
+
+1. `.github/workflows/pre-release-readiness.yml`
+2. `src/cli.ts` (`view --help` text only)
+3. `tests/unit/cliView.test.ts`
+4. `README.md`
+5. `CHANGELOG.md`
+6. `docs/ARCHITECTURE.md`
+7. `docs/CI_CD.md`
+8. `docs/COMMANDS.md`
+9. `docs/CONTRACTS.md`
+10. `docs/CURRENT_STATE.md`
+11. `docs/DEVELOPMENT.md`
+12. `docs/PROJECT_MILESTONES.md`
+13. `docs/PROJECT_OVERVIEW.md`
+14. `docs/QUICKSTART.md`
+15. `docs/ROADMAP.md`
+16. `docs/SECURITY.md`
+17. `docs/WORKFLOWS.md`
+
+### 23.3 Generated paths
+
+1. Packed consumers and projects were created under the OS temporary directory
+   by the three smoke scripts and removed by them.
+2. Test temporary directories were removed by the test resource helpers.
+3. Tarballs were written to the repository root (ignored by `*.tgz`) and
+   deleted after use.
+4. Validation logs, smoke summaries, and the untracked validation note were
+   written under the ignored repository-local workflow root
+   `.my-dev-kit-workflow/adhoc/v09-batch7/`.
+5. `npm run build` refreshed the ignored `dist/`.
+
+## 24. Remaining risks
+
+1. The cross-platform matrix has not run for this candidate. Linux and macOS
+   behavior of the new smoke (for example Playwright `--with-deps` and path
+   realpath handling) is untested until the readiness workflow runs.
+2. The workflow YAML was validated by inspection only.
+3. PWA installation proof remains limited to the v0.8 level (no OS-level
+   install).
+4. `promoteVisualAnnotationContract` is not a public export. This matches the
+   current design but may need a decision before release.
+
+## 25. Final implementation state
+
+1. v0.8.1: latest published release.
+2. v0.9: implementation complete, integrated locally, packed candidate
+   validated locally on Windows, cross-platform pre-release workflow prepared,
+   not released.
+
+## 26. Next step
+
+v0.9 pre-release readiness and controlled release preparation: push the
+implementation-complete candidate, run the exact-candidate Windows/Linux/macOS
+Pre-release readiness workflow, reconcile any cross-platform failures, then
+prepare the v0.9.0 release separately.