@dailephd/my-frontend-observer 0.8.1 → 0.9.1

package/docs/CURRENT_STATE.md

@@ -1,15 +1,93 @@
 # Current State
 
-v0.8.1 is released and published as `@dailephd/my-frontend-observer@0.8.1`.
-Project aliases, `init`, `capture`, project-aware `view`, and `check`
-orchestration are implemented and MIT licensed.
-
-The project is published at package version `0.8.1` (roadmap v0.8.1,
-Interactive Local Observation Viewer; observation schema `1.2.0`; 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 schema version changed for v0.8) - see "v0.8 status" below for
-the final, complete v0.8 state.
+v0.9.1 is released and published as `@dailephd/my-frontend-observer@0.9.1`.
+v0.9 (Human Visual Annotation and Design-Intent Capture) adds structured visual
+annotation to the project-aware viewer. It passed integrated real-Chromium
+acceptance and final exact-candidate pre-release readiness on Windows, Linux
+and macOS, including all four tutorials. The viewer protocol is `1.3.0` and the
+visual annotation schema is `1.0.0`. Project aliases, `init`, `capture`,
+project-aware `view`, and `check` orchestration from v0.8.1 remain implemented,
+and the package is MIT licensed. The
+repository also holds a deterministic demo and four tutorial scenarios for
+v0.9, recorded by the external `@dailephd/my-dev-kit-lab@0.4.9` tool. See
+"v0.9 status" below.
+
+The project is published at package version `0.9.1` (roadmap v0.9.1, PWA
+Hard-Gate Isolation and Reproducible Security Acceptance; the preceding v0.9
+release was Human Visual Annotation and Design-Intent Capture; observation
+schema `1.2.0`;
+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`; visual annotation schema `1.0.0`). v0.9.0
+added the visual annotation schema and did not change any other canonical
+evidence schema version. v0.8.1 did not change any canonical evidence schema
+version either; see "v0.8 status" below for the final, complete v0.8 viewer
+state.
+
+## v0.9.1 maintenance status
+
+Status: released and published as `@dailephd/my-frontend-observer@0.9.1`.
+No production code changed.
+
+Result of the implementation:
+
+1. The original failure was reproduced. Selected alone, the hard gate failed at
+   the offline reload with `net::ERR_CONNECTION_REFUSED`.
+2. Root cause, part one: the old readiness check was
+   `registration?.active !== undefined`. While the worker was still installing,
+   `active` was `null` and the page had no controller. Because
+   `null !== undefined` is true, the check passed and the server was closed
+   before the worker controlled the page or finished precaching.
+3. Root cause, part two: the gate shared a server, evidence root, and a fixed
+   persistent Chromium profile with earlier tests. In normal file order those
+   tests had already activated a controlling worker, which hid the defect.
+4. The hard gate now owns a fresh evidence root, viewer server, temporary
+   persistent profile, and BrowserContext. No PWA test uses the fixed
+   `.my-dev-kit-workflow` profile any more.
+5. The gate proves service-worker activation (`registration.active !== null`)
+   and current-page control (`navigator.serviceWorker.controller !== null`)
+   as separate facts.
+6. It proves the app shell is in the Workbox precache and that no `/api/`
+   request is in Cache Storage.
+7. It proves the server is down with a direct Node-side request before the
+   offline reload.
+8. After the reload, the shell renders, the evidence list shows its explicit
+   unavailable state, and the previously visible evidence identity is absent.
+9. `npm run test:pwa-hard-gate` runs the gate alone. `npm run test:security`
+   now ends with it. It passes repeatedly, and the full PWA file, browser suite,
+   and security suite pass.
+10. Production PWA behavior is unchanged.
+
+Evidence: `docs/reports/v0.9.1-batch1-pwa-hard-gate-isolation.md` and
+`docs/reports/v0.9.1-batch2-hard-gate-validation-integration.md`.
+
+The historical planning background follows.
+
+A post-release test-isolation defect has been identified in
+`tests/browser/pwaHardening.test.ts`. The PWA server-down test labeled
+`HARD GATE` passes in the normal full-file/full-suite execution but fails
+when selected independently with Vitest `-t`. The current test shares a
+persistent Chromium context/profile with earlier tests, and its own setup proves
+that a service-worker registration is active without independently proving all
+of the state the server-down experiment needs: that the current page is
+controlled, that the application shell is actually precached, and that no
+historical profile/cache state was inherited.
+
+This is currently classified as a test-isolation defect, not a demonstrated
+production PWA regression. The released safety contract remains unchanged:
+application-shell caching may keep the viewer shell available while evidence
+and media remain server-backed, and stale evidence must never be presented as
+current after the server is unavailable. No production PWA code change is
+authorized unless a corrected fresh-state hard-gate experiment first
+demonstrates a real runtime failure.
+
+The completed v0.9.1 maintenance patch was governed by the frozen implementation
+plan `docs/plans/v0.9.1-implementation-plan.md`. It made the hard gate own fresh
+disposable evidence/server/browser-profile state, explicitly prove service-worker
+control and shell/API cache preconditions, explicitly prove the server is
+unavailable before the offline reload, and add an isolated execution gate so the
+same test passes by itself as well as inside the full browser and security
+suites.
 
 v0.8 (Interactive Local Observation Viewer) is fully implemented, tested,
 formally cross-platform/security validated, and released. All eight v0.8
@@ -38,13 +116,14 @@ The retained repository contains:
   and standardized documentation.
 
 The package bin (`src/cli.ts`) now exposes the real current public CLI
-surface described below - the five commands released through `0.6.0`
+surface described below: the five low-level commands released through `0.6.0`
 (`observe`, `compare`, `approve-baseline`, `save-change-contract`,
-`evaluate-contract`) plus three additional commands released as part of
-`0.7.0` (`import-reference`, `approve-reference`,
-`evaluate-reference-fidelity` - see "v0.7 Prompt 1/6 status" below) - while
-remaining a thin parsing/dispatch/presentation boundary; it is no longer the
-not-implemented placeholder.
+`evaluate-contract`); three reference commands released in `0.7.0`
+(`import-reference`, `approve-reference`, `evaluate-reference-fidelity`);
+`view`, released in `0.8.0`; and the v0.8.1 high-level `init`, `capture`, and
+`check` commands. v0.8.1 also makes `view` project-aware while preserving its
+standalone `--root` form. `src/cli.ts` remains a thin parsing/dispatch/
+presentation boundary; it is no longer the not-implemented placeholder.
 
 ## v0.1 progress (Batch 1–6; implemented and released as 0.1.0)
 
@@ -546,13 +625,11 @@ binding, or fidelity evaluation yet.
   extends outside the owning image's bounds.
 - **Domain** (`src/domain/externalReferenceRegionRelationships.ts`): reuses
   the exact pure geometry predicates `deriveLayoutRelationships` uses for
-  runtime targets (now exported additively from `relationships.ts`, formulas
-  unchanged) to derive the six geometry-only relationship families
-  (horizontal order, vertical order, area overlap, relative width, geometric
-  fit, vertical sequencing) between reference regions. Not persisted -
-  `deriveReferenceRegionRelationships()` is a pure function callers invoke
-  on demand against an artifact's own `regions`, bounded at
-  `MAX_REFERENCE_REGION_RELATIONSHIP_RECORDS`.
+  runtime targets (now exported additively) from `relationships.ts` rather
+  than reimplemented, so reference-region geometry and runtime-target
+  geometry can never diverge on the same underlying formula; only the
+  geometry-only relationship families apply, since a static image exposes
+  no DOM, scroll, or viewport evidence.
 - **Schema**: `ExternalReferenceArtifact` gained one additive, optional
   `regions?: ReferenceRegion[]` field. No schema version bump
   (`EXTERNAL_REFERENCE_SCHEMA_VERSION` remains `'1.0.0'`) - every Prompt 1
@@ -980,7 +1057,9 @@ most one designated server-side call site, and several (`compareObservations`,
 never called by the viewer at all. The viewer never runs
 `@dailephd/my-dev-kit`, never mutates target source or any Observer
 artifact, never persists a new viewer-owned evidence family, and every route
-rejects non-`GET`/`HEAD` methods.
+rejects non-`GET`/`HEAD` methods. (That was the complete v0.8 surface. v0.9
+later adds exactly three project-aware authoring `POST` routes. See "v0.9
+status" below.)
 
 **Validated on the canonical worktree**: `npm run typecheck`, `npm run
 lint`, `npm test`, `npm run build`, `npm run check:docs`, `npm run
@@ -998,25 +1077,132 @@ viewer surface both passed - see the readiness report above, including the
 one security finding it found and fixed (a symlinked-media evidence-root
 escape in the viewer's media route).
 
+## v0.9 status (Human Visual Annotation and Design-Intent Capture) - released as 0.9.0
+
+v0.9 is implemented against the frozen plan
+`docs/plans/v0.9-implementation-plan.md` and released as
+`@dailephd/my-frontend-observer@0.9.0`.
+
+- **Prompt 1** (`docs/reports/v0.9-batch1-visual-annotation-foundation.md`)
+  added the `VisualAnnotationArtifact` domain (schema `1.0.0`), structured
+  point/rectangle/line/arrow/note marks, runtime and reference coordinate
+  spaces, explicit associations, candidate/confirmed interpretation,
+  deterministic identity, the atomic writer, the canonical reader, the
+  persistence service, and the derived overlay SVG.
+- **Prompt 2**
+  (`docs/reports/v0.9-batch2-viewer-annotation-authoring-boundary.md`) added
+  viewer discovery of annotations, the source-resolving annotation view
+  route, the verified overlay media role, and the project-aware authoring
+  boundary with `POST /api/annotations`. `view --root` stays read-only.
+- **Prompt 3**
+  (`docs/reports/v0.9-batch3-runtime-screenshot-annotation-authoring.md`)
+  added runtime screenshot annotation in runtime CSS pixels with zoom, pan,
+  keyboard selection, save, reload, revisions, and stale-parent conflicts.
+- **Prompt 4**
+  (`docs/reports/v0.9-batch4-external-reference-annotation-authoring.md`)
+  added external-reference annotation in reference-image pixels, candidate
+  region create and refine proposals, candidate reference requirements, and
+  informational and asset-sensitive intent.
+- **Prompt 5**
+  (`docs/reports/v0.9-batch5-runtime-intent-contract-promotion.md`) added
+  runtime intent, explicit confirmation, promotion of selected confirmed
+  `move`/`resize`/`preserve` intent into a canonical per-change contract
+  (`POST /api/annotations/:handle/promote-contract`), optional explicit
+  project contract activation, and `.tmp-*` discovery exclusion. Confirmed
+  `remove` intent is honestly non-promotable.
+- **Prompt 6** (`docs/reports/v0.9-batch6-reference-materialization.md`)
+  added materialization of selected confirmed reference regions and
+  requirements into a new imported external-reference revision
+  (`POST /api/annotations/:handle/materialize-reference`). The source is never
+  changed and nothing is approved automatically.
+- **Prompt 7** (`docs/reports/v0.9-batch7-integrated-acceptance.md`) added the
+  integrated real-Chromium acceptance suite
+  (`tests/browser/v09IntegratedAcceptance.test.ts`), the packed installed
+  annotation smoke (`scripts/ci/runPackedV09AnnotationSmoke.mjs`), its step in
+  the pre-release readiness matrix, and this documentation reconciliation.
+
+Current versions: package `0.9.0`, viewer protocol `1.3.0`, visual annotation
+schema `1.0.0`, frontend contract schema `1.0.0`, external-reference schema
+`1.0.0`. No other schema changed.
+
+Invariants: annotations are evidence, not contracts. Only selected confirmed
+supported intent is promoted or materialized, always through the existing
+canonical contract and external-reference services. The existing contract,
+reference relationship, adequacy, and fidelity evaluators remain the only
+source of verdicts. Observer never edits target source, never approves a
+baseline or reference automatically, and never updates project reference
+acceptance.
+
+Validation state: the full local validation suite, the integrated acceptance
+suite, and all three packed installed-candidate smokes passed locally on
+Windows. See the Prompt 7 report for exact results. A cross-platform
+pre-release readiness run passed on Windows, Linux, and macOS for the Prompt 7
+commit `a78a058` (`docs/reports/v0.9-pre-release-readiness.md`). That run is
+historical evidence only. It did not contain the demo and tutorial commits
+described below, so it is not readiness evidence for the final candidate.
+
+### v0.9 demo and tutorials (release support, not product behavior)
+
+- **Demo foundation** (commit `59ae009`,
+  `docs/reports/v0.9-demo-foundation.md`): a deterministic demo application
+  in `examples/v09-demo/` with ten stable region names, nine frozen states, a
+  loopback-only demo server, a disposable-target materializer, and a fixed
+  1440x900 reference PNG.
+- **Tutorial integration** (commit `6895b30`,
+  `docs/reports/v0.9-tutorial-integration.md`): four `TutorialScenarioV1`
+  scenarios in `examples/v09-demo/tutorials/`, a per-run target-contract
+  generator, and a prepare command that builds each disposable target through
+  the canonical `init`, `capture`, contract, and reference commands. The only
+  product change was two optional `data-testid` attributes on the viewer
+  drawing surfaces.
+- **End-to-end acceptance**
+  (`docs/reports/v0.9-tutorial-end-to-end-acceptance.md`): all four tutorials
+  regenerated from clean targets with `@dailephd/my-dev-kit-lab@0.4.9`,
+  structural and content acceptance, canonical evidence checks, and a full
+  local regression. Scenario narration, reading pauses, and screenshot
+  requests were corrected in this stage. Human visual review of the videos
+  was completed and approved before release.
+- **Final pre-release readiness**
+  (`docs/reports/v0.9-final-pre-release-readiness.md`, with corrections in
+  `docs/reports/v0.9-final-readiness-corrections.md`): one exact candidate
+  package passed the packed observation, viewer and v0.9 annotation smokes and
+  all four tutorials on Windows, Linux and macOS, using
+  `@dailephd/my-dev-kit-lab@0.4.9` semantic `select-option` for native
+  selects.
+
+The four scenarios are annotation basics, runtime intent to an active change
+contract, reference authoring, and reference materialization. After each run
+the canonical evidence is read directly from the disposable target. The checks
+prove, for example, that only the two selected clauses were promoted, that
+`remove` and `inspect` never became clauses, and that a materialized reference
+revision is `imported`, supersedes its approved source, and reuses the source
+image bytes unchanged.
+
+`my-dev-kit-lab` is an external tool invoked through `npx`. It is not an
+Observer dependency, and Observer has no tutorial command, recorder, subtitle
+writer, or tutorial manifest schema. `examples/v09-demo/` is excluded from the
+npm package.
+
 ## Not implemented
 
 - v0.5 baseline-selection/discovery policy (the caller must supply which
   baseline to approve/evaluate against; there is no "find the current
-  baseline" command), source ownership, orchestrator/lab product
-  integration, and annotation all remain unimplemented in this repository.
+  baseline" command), source ownership, and orchestrator/lab product
+  integration all remain unimplemented in this repository.
   (v0.6's bounded runtime projection and runtime/static correlation, the
   complete v0.7 external-reference correction workflow described above, and
   the v0.8 interactive viewer described in "v0.8 status" above, *are* now
   implemented.) A CLI surface for Prompt 8's correction workflow specifically
   remains unimplemented by design (programmatic-only, library-level use is
   the current supported entry point) - see "v0.7 Prompt 8 status" above.
-  Structured visual annotation (v0.9) and the full graphical human-LLM
-  workflow (v0.10) remain future and unimplemented.
+  The full graphical human-LLM workflow (v0.10) remains future and
+  unimplemented. Structured visual annotation (v0.9) is implemented and
+  released as `0.9.0` - see "v0.9 status" above.
 
 ## Next target
 
-v0.1-v0.8 are implemented, validated, and released (`0.1.0`, `0.2.0`,
-`0.3.0`, `0.4.0`, `0.5.0`, `0.6.0`, `0.7.0`, `0.8.0`). v0.7 (End-to-End
+v0.1-v0.9 are implemented, validated, and released (`0.1.0`, `0.2.0`,
+`0.3.0`, `0.4.0`, `0.5.0`, `0.6.0`, `0.7.0`, `0.8.0`, `0.8.1`, `0.9.0`). v0.7 (End-to-End
 Coding-Agent Frontend Change Review) is fully implemented and released: the
 external-reference artifact foundation, explicit reference
 regions/relationships, selected design requirements/tolerance
@@ -1035,8 +1221,8 @@ for the completeness audit, and
 readiness validation that preceded this release.
 
 v0.8 (Interactive Local Observation Viewer) is fully implemented, tested,
-and released - see "v0.8 status" above. v0.8.1 is the current package
-release: `@dailephd/my-frontend-observer@0.8.1`. All
+and released - see "v0.8 status" above. v0.8.1 was released as
+`@dailephd/my-frontend-observer@0.8.1`. All
 eight implementation batches, the hardened documentation/implementation-
 completeness audit, and formal pre-release readiness (cross-platform and
 security validation) have passed - see `docs/ROADMAP.md` for v0.8's full
@@ -1044,6 +1230,9 @@ scope,
 `docs/reports/v0.8-implementation-completeness-documentation-reconciliation.md`
 for the completeness audit, and
 `docs/reports/v0.8-prerelease-readiness-cross-platform-security-code-rot.md`
-for the cross-platform readiness validation that preceded this release. v0.9
-(structured visual annotation) and v0.10 (full graphical human-LLM workflow)
-remain future - see `docs/ROADMAP.md`.
+for the cross-platform readiness validation that preceded this release.
+
+v0.9 (structured visual annotation) is released as
+`@dailephd/my-frontend-observer@0.9.0` - see "v0.9 status" above. The next
+target is v0.10 (full graphical human-LLM workflow), which remains future and
+unimplemented - see `docs/ROADMAP.md`.

package/docs/DEVELOPMENT.md

@@ -1,7 +1,8 @@
 # Development
 
-The released v0.8.1 workflow is published as
-`@dailephd/my-frontend-observer@0.8.1` (CLI `my-frontend-observer`).
+The released v0.9.1 package is published as
+`@dailephd/my-frontend-observer@0.9.1` (CLI `my-frontend-observer`). It keeps
+the v0.8.1 project workflow and adds structured visual annotation.
 
 The v0.8.1 workflow is exercised through unit and real-Chromium tests. Project fixtures use `init`, `capture baseline`, and `check`; coding-agent consumers use bounded `check --json`. `tests/browser/projectCheckWorkflow.test.ts` covers REVIEW_REQUIRED, contract FAIL-to-PASS, reference FAIL/PASS/BLOCKED, incomparable BLOCKED, current history, and contained acceptance paths. `scripts/ci/runPackedViewerSmoke.mjs` is the single installed-package viewer/project-workflow smoke owner: it repeats REVIEW_REQUIRED and unchanged-contract FAIL-to-PASS before alias-aware viewer proof. Run the full unit, browser, security, build, documentation, and packed-consumer validations before release readiness.
 
@@ -37,6 +38,36 @@ first; it is kept out of `npm test` because it launches a real browser and
 is slower. Exact counts drift as the suite grows - run the commands above
 for the current numbers rather than trusting this document.
 
+## Hard/security/acceptance gate isolation
+
+Tests explicitly designated `HARD GATE`, `SECURITY GATE`, or
+`ACCEPTANCE GATE` must be independently reproducible. A passing full suite is
+not sufficient evidence if the gate itself only succeeds because another test
+ran first or because a prior run left browser/cache/filesystem state behind.
+
+For browser-based gates, the gate must own or explicitly establish every
+precondition material to its claim. That includes disposable evidence state,
+servers, browser profiles/contexts, service-worker control, relevant cache
+state, and cleanup. Fixed persistent profiles must not be used as hidden
+fixtures for a hard acceptance claim.
+
+v0.9.1 applies this rule to the PWA server-down safety proof in
+`tests/browser/pwaHardening.test.ts`. The hard gate owns its evidence root,
+viewer server, temporary Chromium profile, and context. It must pass when
+selected alone and must also continue to pass in the complete browser and
+security suites.
+
+Run the gate by itself with:
+
+```powershell
+npm run test:pwa-hard-gate
+```
+
+Run this command when working on PWA, service-worker, viewer-server, or
+security behavior. It must pass on its own, not only after other tests have
+run. `npm run test:security` also runs it after the rest of the security
+suite. See `docs/plans/v0.9.1-implementation-plan.md`.
+
 ROADMAP v0.1 and Project Milestone 1 require browser-level validation once the
 observation capability is planned and implemented. Static checks must not later
 be substituted for that required browser evidence. `npm run test:browser` is
@@ -187,7 +218,11 @@ This starts a real, loopback-only server serving the actual built PWA. As of
 v0.8 (all eight implementation batches), it reads `--root` only for bounded,
 read-only evidence discovery through the existing canonical
 readers/classifiers - it never writes to `--root` or modifies any artifact
-under it.
+under it. The v0.9 annotation authoring surface (implemented, not yet
+released) is available only from the project-aware `node dist/cli.js view`
+inside an initialized project, never from `--root`. Its end-to-end browser
+proof is `tests/browser/v09IntegratedAcceptance.test.ts`, and its packed
+installed proof is `scripts/ci/runPackedV09AnnotationSmoke.mjs`.
 
 Unlike `scripts/ci/runPackedObservationSmoke.mjs`, none of these five dev
 smokes is wired into any CI workflow or is a release gate - they are

package/docs/PROJECT_DESCRIPTION.md

@@ -1357,7 +1357,10 @@ The viewer must consume the reusable observation, reference, comparison, contrac
 
 It must not contain a second browser-observation implementation, a second reference model, a second binding engine, a second reference-evaluation implementation, a second contract engine, or a second bounded-context builder.
 
-## Future capability — Human visual annotation
+## Implemented capability (v0.9) — Human visual annotation
+
+Status: implemented and released as `0.9.0`. The intent below is unchanged and
+remains the capability authority.
 
 A later phase should allow the user to communicate visual intent directly on top of either an observed frontend or an approved external reference.
 

package/docs/PROJECT_MILESTONES.md

@@ -1715,6 +1715,38 @@ Milestone 8 is complete when:
 
 ## Milestone 9 — Human Visual Annotation and Design-Intent Capture
 
+Implementation status: implemented and released as `0.9.0`. The milestone
+design below is unchanged and remains the capability authority. Milestone 10
+remains future.
+
+### v0.9.1 maintenance acceptance note
+
+v0.9.1 is a bounded maintenance patch over Milestone 9 rather than a new
+capability milestone. A post-release PWA hard-gate test-isolation defect was
+found: the server-down safety test can pass only after earlier tests have
+prepared persistent service-worker/cache state. No production PWA regression has
+been demonstrated.
+
+The durable acceptance rule added by this maintenance patch is broader than the
+single PWA test: any test explicitly designated `HARD GATE`, `SECURITY GATE`,
+or `ACCEPTANCE GATE` must be able to establish its own prerequisites and pass
+when selected independently from fresh state. Such a gate must not rely on
+another test running first, a fixed browser profile, historical cache state, or
+test ordering. For browser gates, owned servers, evidence roots, browser
+profiles, contexts, and other state must be scoped and cleaned up explicitly.
+
+The v0.9.1 correction is test/validation work unless the corrected isolated
+experiment demonstrates a genuine product failure. In that case the work must
+stop and be reclassified before production semantics change. The concrete
+implementation details live in
+`docs/plans/v0.9.1-implementation-plan.md`; the Milestone 9 product capability
+design below remains unchanged.
+
+Status: the maintenance invariant is implemented and released in v0.9.1 for the PWA hard gate, which
+now passes alone through `npm run test:pwa-hard-gate` and inside the full
+browser and security suites. No genuine product failure was found. Release of
+v0.9.1 is released and published.
+
 ### Objective
 
 Add visual human intent to the already working Milestone 7 coding-agent/reference workflow through the Milestone 8 viewer.

package/docs/PROJECT_OVERVIEW.md

@@ -1,8 +1,10 @@
 # Project Overview
 
-The repository contains the complete v0.8.1 source workflow (`init`, `capture`,
-`check`, project-aware `view`), released as
-`@dailephd/my-frontend-observer@0.8.1` under the MIT license.
+The repository contains the complete v0.9.1 release, published as
+`@dailephd/my-frontend-observer@0.9.1` under the MIT license. It hardens
+independent PWA security acceptance while preserving the structured visual
+annotation added to the v0.8.1 project workflow (`init`,
+`capture`, `check`, project-aware `view`).
 
 `my-frontend-observer` is the rendered browser/runtime evidence producer in
 the my-dev-kit ecosystem. It addresses the gap between source-level evidence
@@ -28,13 +30,16 @@ Region Identity; v0.3, Runtime Scrolling, Overflow, and Visibility Behavior;
 v0.4, Layout Relationships, Dependency Evidence, and Before/After
 Comparison; v0.5, Executable Frontend Contracts and Explicit Change Scope;
 v0.6, Bounded Agent Context and Native my-dev-kit Ecosystem Integration;
-v0.7, End-to-End Coding-Agent Frontend Change Review; and v0.8, Interactive
-Local Observation Viewer, are released and published to npm. The current
-package version is `0.8.1` as `@dailephd/my-frontend-observer` (observation schema `1.2.0`, comparison schema
+v0.7, End-to-End Coding-Agent Frontend Change Review; v0.8, Interactive
+Local Observation Viewer; v0.8.1, Project Workflow CLI and Human-Readable
+Evidence Aliases; and v0.9, Human Visual Annotation and Design-Intent Capture,
+are released and published to npm. The current package version is `0.9.1` as
+`@dailephd/my-frontend-observer` (observation schema `1.2.0`, 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`). The
-released package was validated as a packed npm tarball in a clean consumer
-environment across Windows, Linux, and macOS.
+bounded-agent-context schema `1.0.0`, external-reference schema `1.0.0`,
+visual annotation schema `1.0.0`). The released package was validated as a
+packed npm tarball in a clean consumer environment across Windows, Linux, and
+macOS.
 
 The released low-level command surface remains artifact-oriented: a real
 `observe` command launches Chromium, enforces loopback-only safety, captures
@@ -81,8 +86,8 @@ engines used by the CLI, never a second implementation of them. See
 and `docs/reports/v0.8-prerelease-readiness-cross-platform-security-code-rot.md`
 for the implementation and release evidence.
 
-The repository implementation now includes released v0.8.1, a project-workflow
-CLI usability patch published as `@dailephd/my-frontend-observer@0.8.1`. It does
+v0.8.1 was a project-workflow CLI usability patch published as
+`@dailephd/my-frontend-observer@0.8.1`. It does
 not introduce a new evidence model. It adds project configuration,
 human-readable aliases, managed project-local Observer state, and a small
 high-level `init` / `capture` / `check` / project-aware `view` workflow above
@@ -92,10 +97,33 @@ artifact identifiers during ordinary use. Existing low-level commands remain
 supported. The frozen plan is
 `docs/plans/v0.8.1-cli-usability-patch-plan.md`.
 
-v0.9 and v0.10 remain future and unimplemented. v0.9 adds structured visual
-annotation through the existing viewer. v0.10 completes the visual human-LLM
-workflow and should consume the v0.8.1 high-level acceptance surface rather than
-introduce another Observer command architecture.
+The latest published release is v0.9.1. v0.9 added structured
+visual annotation to the project-aware viewer for both runtime observations and
+external references. People draw marks, explicitly associate them, and confirm
+structured intent. Selected confirmed runtime intent can become a normal
+per-change contract, and selected confirmed reference intent can become a new
+imported external-reference revision. The existing contract and reference
+evaluators stay authoritative. It followed the frozen plan in
+`docs/plans/v0.9-implementation-plan.md`, grounded by
+`docs/reports/v0.9-architecture-retrieval.md`.
+The repository-owned deterministic demo and its four tutorial scenarios
+(`examples/v09-demo/`, recorded by the external
+`@dailephd/my-dev-kit-lab@0.4.9` tool) passed final cross-platform readiness
+with the release. They are release support and documentation, not product
+behavior, and they are not shipped in the npm package.
+
+The v0.9.1 maintenance release hardens the
+PWA server-down hard acceptance test so the gate is reproducible from a fresh
+browser profile and fresh test-owned state. PWA hard/security acceptance no
+longer depends on prior test order or persistent browser state, and
+`npm run test:security` now also runs the gate by itself through
+`npm run test:pwa-hard-gate`. This was a test-isolation correction, not a
+production PWA defect. No production behavior changed. The frozen concrete plan
+is `docs/plans/v0.9.1-implementation-plan.md`.
+
+v0.10 remains future and unimplemented and completes the visual human-LLM
+workflow on top of the v0.9 annotation model and v0.8.1 high-level acceptance
+surface.
 
 The revised dependency path reaches practical coding-agent use before graphical
 interaction and keeps later visual work on the same canonical evidence system:
@@ -109,9 +137,9 @@ runtime observation and stable identity
   + reference-vs-candidate structured fidelity evaluation
   + controlled end-to-end correction workflow (released as 0.7.0)
 → interactive viewer with reference/candidate inspection (released as 0.8.0)
-→ project workflow CLI + human-readable evidence aliases (implemented in source; not published)
+→ project workflow CLI + human-readable evidence aliases (released as 0.8.1)
 → structured visual annotation on runtime screenshots and external references
-  (planned v0.9)
+  (released as 0.9.0)
 → full visual human-LLM workflow with actual-frontend-driven and
   reference-driven entry modes (planned v0.10)
 ```
@@ -145,6 +173,19 @@ Repository-local authorities and navigation:
   release state.
 - [plans/v0.8.1-cli-usability-patch-plan.md](plans/v0.8.1-cli-usability-patch-plan.md)
   freezes the concrete implementation plan for the v0.8.1 patch.
+- [plans/v0.9-implementation-plan.md](plans/v0.9-implementation-plan.md)
+  freezes the concrete implementation architecture, seven ordered batches,
+  gates, and validation expectations for v0.9. It is planning authority only;
+  the v0.9 implementation state is recorded in CURRENT_STATE.md and the
+  `reports/v0.9-*.md` reports.
+- [plans/v0.9.1-implementation-plan.md](plans/v0.9.1-implementation-plan.md)
+  freezes the bounded maintenance plan for independent PWA hard-gate
+  reproduction, fresh browser-profile ownership, explicit service-worker/cache
+  precondition proof, and isolated-gate validation. It does not authorize a
+  production PWA change unless the corrected experiment demonstrates a real
+  product defect.
+- [reports/v0.9-architecture-retrieval.md](reports/v0.9-architecture-retrieval.md)
+  preserves the bounded current-source retrieval that grounded the v0.9 plan.
 
 Historical greenfield artifacts and reports are retained as evidence that an
 earlier run overreached into v0.1; they are not current-state authority.