@dailephd/my-frontend-observer 0.9.0 → 0.10.0

package/docs/ARCHITECTURE.md

@@ -1,5 +1,17 @@
 # Architecture
 
+## v0.10 visual workflow boundaries
+
+`VisualChangeWorkflowArtifact` (`1.0.0`) is the only new persisted v0.10
+family. It owns frozen scope, explicit activation/restoration, immutable
+attempt and review revisions, and optional references to governance results.
+The Viewer is the human workflow entry; `checkProject` remains the canonical
+evaluator. `VisualChangeAgentHandoff` (`1.0.0`) is a generated, non-persisted
+transfer contract. An external human or coding agent edits source. Optional
+orchestrator metadata is traceability only and Observer never imports or runs
+the orchestrator. Human acceptance is separate from baseline/reference
+governance and never rewrites prior workflow evidence.
+
 ## v0.8.1 project workflow
 
 Versioned project configuration (`1.0.0` compatibility plus current `1.1.0`
@@ -21,7 +33,7 @@ the workflow result remain in memory/presentation.
 ## Current package architecture
 
 The current repository is one published TypeScript ESM package
-(`@dailephd/my-frontend-observer@0.9.0`). The CLI remains
+(`@dailephd/my-frontend-observer@0.9.1`). The CLI remains
 `my-frontend-observer`; the npm scope does not rename the product or artifact
 identities.
 
@@ -369,7 +381,7 @@ lab code in this repository - those remain separate sibling-repository
 responsibilities per the Milestone 6 ownership split in
 `docs/PROJECT_MILESTONES.md`.
 
-## v0.7 (released as `0.7.0`), v0.8 (released as `0.8.0`), and planned v0.9–v0.10 reference-evidence architecture constraints
+## v0.7-v0.10 reference-evidence architecture constraints
 
 The external visual-reference capability (v0.7) is released as package
 version `0.7.0` - see "v0.7 Prompt 1" through "v0.7 Prompt 8" below for the
@@ -378,9 +390,9 @@ extends the existing v0.1-v0.6 evidence architecture rather than becoming a
 UI-only feature or a parallel visual-comparison stack. v0.8 (interactive
 viewer) is released as package version `0.8.0`. v0.9 (structured visual
 annotation) is released as package version `0.9.0` - see "v0.9 visual
-annotation architecture" below. v0.10 (full graphical human-LLM
-workflow) remains future and unimplemented. The constraints below applied to
-v0.9 and still apply to v0.10.
+annotation architecture" below. v0.10 (full graphical human-LLM workflow) is
+implemented and documentation-reconciled but remains unreleased. The
+constraints below apply to both v0.9 and v0.10.
 
 The evidence domains remain distinct:
 

package/docs/CI_CD.md

@@ -1,6 +1,38 @@
 # CI/CD
 
-CI interprets `check` as PASS `0`, FAIL `1`, REVIEW_REQUIRED `2`, or BLOCKED `3`. The released package is `@dailephd/my-frontend-observer@0.9.0`; its CLI remains `my-frontend-observer`. Packed readiness installs one exact tarball and runs `runPackedViewerSmoke.mjs` as the single project/viewer smoke owner for `init`, `capture`, bounded `check --json` REVIEW_REQUIRED and unchanged-contract FAIL-to-PASS, alias-aware project `view`, and viewer security. `runPackedObservationSmoke.mjs` remains the lower-level legacy observation smoke.
+CI interprets `check` as PASS `0`, FAIL `1`, REVIEW_REQUIRED `2`, or BLOCKED `3`. The current package is `@dailephd/my-frontend-observer@0.10.0`; its CLI remains `my-frontend-observer`. Packed readiness installs one exact tarball and runs `runPackedViewerSmoke.mjs` as the single project/viewer smoke owner for `init`, `capture`, bounded `check --json` REVIEW_REQUIRED and unchanged-contract FAIL-to-PASS, alias-aware project `view`, and viewer security. `runPackedObservationSmoke.mjs` remains the lower-level legacy observation smoke.
+
+The same matrix now also runs `runPackedV010WorkflowSmoke.mjs`. It installs the
+same SHA-verified candidate into a clean consumer and exercises installed
+actual/reference workflow creation, activation, handoff, immutable correction
+attempts, PASS-only acceptance, project-aware Viewer discovery, and standalone
+read-only behavior. Its bounded summary is uploaded with the existing matrix
+summary artifact. The candidate job still owns exactly one `npm pack`; no
+second v0.10 candidate or matrix exists. Formal v0.10 exact-candidate readiness
+passed on Windows, Linux, and macOS.
+All four packed smokes, security checks, and PWA gates passed against the same
+candidate. Run 35789033295 records that readiness result.
+
+## Gate isolation invariant
+
+Cross-platform/full-suite success does not by itself prove that a security or
+acceptance gate is independent. Any test explicitly labeled `HARD GATE`,
+`SECURITY GATE`, or `ACCEPTANCE GATE` must also be able to run from fresh
+state without relying on earlier test order, a previously warmed service-worker
+cache, a persistent browser profile from an earlier run, or another test's
+server/evidence setup.
+
+v0.9.1 applies this rule to the PWA server-down
+hard gate. `npm run test:pwa-hard-gate` runs that gate by itself. It is a
+separate required proof in addition to the normal full-file execution in
+`npm run test:browser` and `npm run test:security`.
+
+`npm run test:security` now ends with `npm run test:pwa-hard-gate`. The
+`candidate` job in `.github/workflows/pre-release-readiness.yml` already runs
+`npm run test:security`, so release-readiness candidate validation receives
+the isolated gate automatically. The workflow YAML did not need to change. The
+released v0.9.1 suite contains the corrected isolated gate. No production PWA
+regression was found.
 
 A GitHub Actions pre-release readiness workflow exists at
 `.github/workflows/pre-release-readiness.yml` (triggered manually via

package/docs/COMMANDS.md

@@ -1,5 +1,18 @@
 # Commands
 
+## v0.10 visual workflow operations
+
+v0.10 adds no CLI command. Project-aware `view` exposes the Visual changes
+workspace for actual/reference entry, explicit activation, bounded handoff,
+Run check, correction/review, acceptance, governance-result recording, and
+explicit restore. These are guarded local HTTP/UI actions backed by canonical
+application owners, not new command-line subcommands. Standalone `view --root`
+remains inspection-only.
+
+Every handoff names `check <baseline> --json` as the exact post-edit machine
+operation. It captures a fresh candidate and runs the existing canonical
+comparison, contract, and configured reference-fidelity owners.
+
 ## v0.8.1 common workflow
 
 `init --url <loopback-url> [--viewport WIDTHxHEIGHT] [--target id=selector ... | --targets-file file] [--default-baseline alias] [--replace]` creates schema-`1.1.0` project configuration; schema `1.0.0` remains readable and forbids `acceptance`. Schema `1.1.0` may add exactly:
@@ -783,7 +796,7 @@ the annotation workflow. The rest of this section describes the inspection
 surface, which is unchanged.
 
 **Current status: viewer behavior is released as package
-`@dailephd/my-frontend-observer@0.9.0`.** Starts one
+`@dailephd/my-frontend-observer@0.9.1`.** Starts one
 loopback-only Node viewer server and serves the same React + TypeScript +
 Vite application to a normal browser or an installed Progressive Web App.
 `--root` is used as a bounded, read-only evidence-discovery root: the server
@@ -948,12 +961,13 @@ Options:
 - `--help` — show `view` usage.
 
 The server binds only to `127.0.0.1` (never `0.0.0.0`), serves only the
-built viewer application assets plus the bounded, read-only `/api/*`
+built viewer application assets plus bounded `/api/*`
 endpoints described above, and never exposes the supplied evidence root as a
 generic static directory or arbitrary filesystem path. With `--root` it
-accepts no write methods and writes nothing. Without `--root`, the only
-writes are the three v0.9 authoring routes above, which create new immutable
-artifacts and never modify existing ones. On success,
+accepts no write methods and writes nothing. Without `--root`, the guarded
+project-aware authoring routes create only new immutable artifacts and workflow
+revisions through canonical owners; they never edit target source or rewrite
+existing evidence. On success,
 prints the viewer URL and keeps running (serving the viewer) until
 interrupted. On invalid syntax, a missing/non-directory `--root`, an
 invalid `--port`, an invalid `--bindings-file`, an invalid `--context-file`

package/docs/CONTRACTS.md

@@ -1,5 +1,40 @@
 # Contracts
 
+## Visual-change workflow artifact (`1.0.0`, v0.10 Batch 1)
+
+`my-frontend-observer/visual-change-workflow` is the immutable Observer-owned history envelope for one frozen visual-change request. It records a deterministic `visualChangeRequestId`, a fresh `visualChangeWorkflowId`, optional forward-only `supersedesVisualChangeWorkflowId`, exact references to existing canonical evidence, zero to twenty bounded attempt records, optional activation/governance result references, producer metadata, and creation provenance.
+
+The two entry modes are exactly `actual-frontend` and `reference`. Reference mode stores validated explicit runtime binding declarations in canonical `bindings.json`; the manifest pins its SHA-256 and declaration count. Actual mode never writes that file. Project-relative evidence references must remain contained portable paths; source artifacts and media are referenced rather than copied.
+
+Request identity hashes semantic scope only. It excludes timestamps and operational storage locations. Workflow instance identity is fresh for every explicit persistence. Attempt identity is deterministic over the visual-change request ID and candidate observation ID. Human review state is exactly `pending`, `correction-requested`, `accepted`, or `abandoned`; this foundation validates structure but does not implement the later acceptance rule or execute checks.
+
+The v0.10 Batch 2 application composition explicitly activates either the frozen per-change contract or the frozen approved reference and workflow-owned bindings in project acceptance. Activation and restoration preserve unrelated configuration, use compensating atomic writes across mutable project configuration and immutable workflow revisions, and refuse acceptance drift. A workflow check resolves an alias only when its catalog identity and artifact location exactly match the frozen baseline, then invokes the existing `checkProject` owner once. Only a canonical result containing both baseline and candidate summaries can append a pending attempt revision; the snapshot is a bounded direct projection of that result and does not repeat evaluation.
+
+The v0.10 Batch 3 Viewer exposes bounded workflow inspection at `GET /api/visual-changes/:handle/view` in both standalone and project-aware sessions. Create, activate, check, and restore POST operations are project-aware only, reuse the existing in-memory authoring capability and request guards, accept no filesystem paths, and delegate to the Batch 2 application service. Every new response is `no-store`. Successful immutable mutations return the exact new workflow ID so the Viewer can refresh and reselect that revision without guessing. The Viewer protocol remains `1.3.0`.
+
+The v0.10 Batch 4 actual-frontend entry route promotes only explicitly selected, saved, confirmed, canonically promotable runtime intent without activating project acceptance. It freezes the exact resulting contract instance with the saved annotation, source observation, and configured persistent baseline contract through the Batch 2 workflow-creation owner. Repeated equivalent starts share `contractRequestId` while receiving fresh contract, visual-change request, and workflow instance identities. Activation remains a later explicit workflow action.
+
+Reference entry freezes only an exact approved reference, an annotation authored
+against that exact instance, an exact baseline observation, and explicitly
+authored valid bindings. Adequacy, compatibility, complete required-region
+coverage, and canonical binding evaluation fail closed. Imported references,
+inferred bindings, and session bindings are not executable workflow scope.
+
+`VisualChangeAgentHandoff` uses handoff kind
+`my-frontend-observer/visual-change-agent-handoff` and version `1.0.0`. It is a
+bounded non-artifact transfer contract and is never discovered or persisted as
+Observer evidence. It includes confirmed scope, Observer-owned bounded context,
+optional unchanged supplemental context, the exact post-edit check instruction,
+and optional non-authoritative orchestrator correlation.
+
+The current cycle is derived from the latest attempt. A pending attempt blocks
+another check or handoff until explicit correction, acceptance, or abandonment.
+Only the latest canonical PASS may be accepted. Review changes only the latest
+attempt's review object in a fresh workflow revision. Governance references may
+be recorded only after acceptance and only for already-persisted canonical
+approval results; they do not perform approval or change project configuration.
+No existing evidence schema changed for v0.10.
+
 ## Current contracts
 
 The observation artifact contract is published in the current
@@ -490,7 +525,7 @@ blockers; on the canonical worktree, `npm run typecheck`, `npm run lint`,
 `npm test` (627 tests), `npm run test:browser` (120 tests), `npm run
 test:security`, `npm run build`, and `npm run check:docs` all pass.
 
-## v0.7 external visual-reference contract direction (released as `0.7.0`; v0.8 viewer released as `0.8.0`; v0.9 released as `0.9.0`; v0.10 still future)
+## v0.7 external visual-reference contract direction (preserved through implemented, unreleased v0.10)
 
 External visual-reference support is released as package version `0.7.0`
 (see "v0.7 Prompt 1" through "v0.7 Prompt 8" below for the exact contract).
@@ -498,9 +533,8 @@ The exact public type names, artifact kinds, schema versions, persistence
 layout, and command/programmatic entry points were designed during v0.7
 implementation from current repository precedent, following the constraints
 below. v0.8 (released as package version `0.8.0` - see
-`docs/CURRENT_STATE.md`) has preserved them. v0.9 (implemented, not yet
-released) preserves them too. v0.10 remains future and must continue to
-preserve them.
+`docs/CURRENT_STATE.md`) has preserved them. v0.9 is released and preserves
+them. The implemented, unreleased v0.10 workflow preserves them too.
 
 **Distinct evidence domain**: an external reference is desired-design evidence,
 not an `ObservationArtifact` and not the "before" side of a v0.4

package/docs/CURRENT_STATE.md

@@ -1,6 +1,18 @@
 # Current State
 
-v0.9.0 is released and published as `@dailephd/my-frontend-observer@0.9.0`.
+v0.10.0 is the current release of `@dailephd/my-frontend-observer`.
+Formal Windows, Linux, and macOS exact-candidate readiness, security checks,
+and PWA gates passed before release. The package version is `0.10.0`.
+
+The full Visual Change workflow supports actual-frontend and approved-reference
+entry, structured intent, explicit activation, bounded coding-agent handoff,
+immutable check attempts and correction, PASS-only human acceptance, and
+separate governance. The Viewer discovers installed-package workflow evidence.
+Observer never edits source or performs automatic approval. Schemas remain
+independently versioned: observation `1.2.0`, comparison `1.0.0`, frontend
+contract `1.0.0`, evaluation `1.0.0`, bounded-agent-context `1.0.0`,
+external-reference `1.0.0`, visual annotation `1.0.0`, visual-change workflow
+`1.0.0`, handoff `1.0.0`; Viewer protocol remains `1.3.0`.
 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
@@ -12,8 +24,10 @@ 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.0` (roadmap v0.9, Human
-Visual Annotation and Design-Intent Capture; observation schema `1.2.0`;
+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
@@ -22,6 +36,71 @@ 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
 implementation batches, the hardened documentation/implementation-
@@ -1128,14 +1207,15 @@ npm package.
   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.
-  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.
+  The full graphical human-LLM workflow is released as `0.10.0`. Structured
+  visual annotation (v0.9) is
+  implemented and released as `0.9.0` - see "v0.9 status" above.
 
 ## Next target
 
-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
+v0.1-v0.10 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`,
+`0.9.1`, `0.10.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
@@ -1166,6 +1246,7 @@ for the completeness audit, and
 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`.
+`@dailephd/my-frontend-observer@0.9.0` - see "v0.9 status" above. v0.10.0 is
+the current release. Its formal exact-candidate readiness passed on Windows,
+Linux, and macOS, including installed-package, security, and PWA gates. See
+`docs/reports/v0.10-release-preparation.md` for release-preparation evidence.

package/docs/DEVELOPMENT.md

@@ -1,7 +1,7 @@
 # Development
 
-The released v0.9.0 package is published as
-`@dailephd/my-frontend-observer@0.9.0` (CLI `my-frontend-observer`). It keeps
+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.
@@ -38,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

package/docs/PROJECT_MILESTONES.md

@@ -1719,6 +1719,34 @@ 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,9 +1,8 @@
 # Project Overview
 
-The repository contains the complete v0.9.0 release, published as
-`@dailephd/my-frontend-observer@0.9.0` under the MIT license. It adds
-structured visual annotation to the v0.8.1 project workflow (`init`,
-`capture`, `check`, project-aware `view`).
+The repository contains the v0.10.0 release of
+`@dailephd/my-frontend-observer` under the MIT license. It completes the Visual
+Change workflow on the project workflow (`init`, `capture`, `check`, Viewer).
 
 `my-frontend-observer` is the rendered browser/runtime evidence producer in
 the my-dev-kit ecosystem. It addresses the gap between source-level evidence
@@ -31,14 +30,15 @@ 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; 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.0` as
+Evidence Aliases; v0.9, Human Visual Annotation and Design-Intent Capture; and
+v0.10.0, Full Visual Human–LLM Frontend Change Workflow, are released and
+published to npm. The current package version is `0.10.0` 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`,
-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.
+visual annotation schema `1.0.0`, visual-change workflow schema `1.0.0`,
+handoff `1.0.0`; Viewer protocol `1.3.0`). Exact-candidate readiness passed
+on Windows, Linux, and macOS.
 
 The released low-level command surface remains artifact-oriented: a real
 `observe` command launches Chromium, enforces loopback-only safety, captures
@@ -96,7 +96,7 @@ 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`.
 
-The latest published release is v0.9.0. v0.9 adds structured
+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
@@ -110,9 +110,21 @@ The repository-owned deterministic demo and its four tutorial scenarios
 `@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.
-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 v0.9.1 maintenance release hardened 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.0 completes the Visual Change workflow on top of the v0.9 annotation
+model and v0.8.1 high-level acceptance surface. It supports actual-frontend
+and approved-reference entry, explicit activation, bounded coding-agent
+handoff, immutable correction history, PASS-only human acceptance, and
+separate governance. Installed-package and Viewer support are included.
 
 The revised dependency path reaches practical coding-agent use before graphical
 interaction and keeps later visual work on the same canonical evidence system:
@@ -130,7 +142,8 @@ runtime observation and stable identity
 → structured visual annotation on runtime screenshots and external references
   (released as 0.9.0)
 → full visual human-LLM workflow with actual-frontend-driven and
-  reference-driven entry modes (planned v0.10)
+  reference-driven entry modes (implemented, documentation-reconciled,
+  unreleased v0.10)
 ```
 
 The implemented reference model is not a second observer or a
@@ -167,6 +180,15 @@ Repository-local authorities and navigation:
   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.
+- [plans/v0.10-implementation-plan.md](plans/v0.10-implementation-plan.md)
+  is the frozen planning authority for the completed v0.10 implementation;
+  current evidence and reconciliation are recorded in the v0.10 reports.
 - [reports/v0.9-architecture-retrieval.md](reports/v0.9-architecture-retrieval.md)
   preserves the bounded current-source retrieval that grounded the v0.9 plan.
 

package/docs/QUICKSTART.md

@@ -80,9 +80,13 @@ approve a reference or prove every aesthetic requirement. See
 [CONTRACTS.md](CONTRACTS.md) and [WORKFLOWS.md](WORKFLOWS.md).
 
 `my-frontend-observer view --no-open` starts the loopback-only viewer over managed
-project evidence. Use `view --root observations --no-open` for standalone roots.
-The viewer is inspect-only. Its `--bindings-file` and `--context-file` inputs do
-not create a second evaluator or automatic source-owner mapping.
+project evidence. The v0.10.0 project-aware Viewer also owns the explicit
+Visual Change workflow: visual entry, activation, handoff, check,
+review/correction, acceptance, and separate
+governance-result recording. Use `view --root observations --no-open` for
+standalone roots; that mode remains inspect-only. The `--bindings-file` and
+`--context-file` inputs do not create a second evaluator or automatic
+source-owner mapping. The installed package includes the Visual Change surface.
 
 To validate this repository itself, rather than the target application:
 

package/docs/RELEASE.md

@@ -1,25 +1,29 @@
 # Release
 
-`v0.9.0` (Human Visual Annotation and Design-Intent Capture) is released and
-published to npm as `@dailephd/my-frontend-observer`. The release adds
-structured visual annotation of runtime observations and external references
-to the project-aware viewer, selected promotion of confirmed runtime intent
-into canonical change contracts, and selected materialization of confirmed
-reference intent into new imported reference revisions, with final
-Windows/Linux/macOS readiness and the MIT license.
+`v0.10.0` (Full Visual Human–LLM Frontend Change Workflow) is the current
+release state. Formal exact-candidate readiness passed on Windows, Linux, and
+macOS, including installed-package workflow smokes and security/PWA gates.
+
+`v0.9.1` (PWA Hard-Gate Isolation and Reproducible Security Acceptance) is the
+previous maintenance release, published to npm as
+`@dailephd/my-frontend-observer`. It hardened isolated PWA security acceptance
+without changing production behavior.
 
 The CLI remains `my-frontend-observer`; package identity and product identity
 are intentionally distinct. Canonical artifact schemas remain versioned
 independently from the npm package version.
 
 Observation, comparison, frontend contract, evaluation artifact,
-bounded-agent-context, external-reference, visual annotation, and package
-version all remain separate: package version is `0.9.0`; observation schema is
+bounded-agent-context, external-reference, visual annotation,
+visual-change-workflow, handoff, Viewer protocol, and package version all
+remain separate: package version is `0.10.0`; observation schema is
 `1.2.0`, comparison schema is `1.0.0`, frontend contract schema is `1.0.0`,
 evaluation artifact schema is `1.0.0`, bounded-agent-context schema is
 `1.0.0`, external-reference schema is `1.0.0`, and visual annotation schema is
-`1.0.0` - none of which changes automatically with the package version. v0.9
-introduced the visual annotation schema and bumped no existing schema.
+`1.0.0`, visual-change-workflow schema is `1.0.0`, handoff version is `1.0.0`,
+and Viewer protocol is `1.3.0` - none changes automatically with the package
+version. v0.9 introduced the visual annotation schema and bumped no existing
+schema.
 
 Prior releases: `v0.8.1` (Project Workflow CLI and Human-Readable Evidence
 Aliases), `v0.8.0` (Interactive Local Observation Viewer), `v0.7.0` (End-to-End