@dailephd/my-frontend-observer 0.9.1 → 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,17 @@
 # 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.1`; 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
 

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:
@@ -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.1 is released and published as `@dailephd/my-frontend-observer@0.9.1`.
+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
@@ -1195,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
@@ -1233,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/PROJECT_OVERVIEW.md

@@ -1,10 +1,8 @@
 # Project Overview
 
-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`).
+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
@@ -32,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.1` 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
@@ -97,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.1. v0.9 added 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
@@ -112,7 +111,7 @@ The repository-owned deterministic demo and its four tutorial scenarios
 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
+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
@@ -121,9 +120,11 @@ longer depends on prior test order or persistent browser state, and
 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.
+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:
@@ -141,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
@@ -184,6 +186,9 @@ Repository-local authorities and navigation:
   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,26 +1,29 @@
 # Release
 
-`v0.9.1` (PWA Hard-Gate Isolation and Reproducible Security Acceptance) is
-released and published to npm as `@dailephd/my-frontend-observer`. This
-maintenance 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.1`; 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

package/docs/ROADMAP.md

@@ -1,10 +1,7 @@
 # Roadmap
 
-v0.9.1 status: released and published to npm as
-`@dailephd/my-frontend-observer@0.9.1`. It is a bounded maintenance patch that
-corrects the PWA hard-gate test-isolation defect discovered after the v0.9.0
-release. No production PWA regression has been demonstrated. v0.10 remains
-future work.
+Current release: v0.10.0, Full Visual Human–LLM Frontend Change Workflow.
+The v0.9.1 PWA hard-gate isolation maintenance release is preserved in history.
 
 This is a version-level specification, not an implementation checklist.
 Concrete steps and sequencing are designed only when a version begins, after
@@ -944,6 +941,10 @@ product/package behavior while proving the stronger test-isolation invariant.
 
 ## v0.10 — Full Visual Human–LLM Frontend Change Workflow
 
+Current status: released as `0.10.0`. The frozen implementation authority
+remains
+`docs/plans/v0.10-implementation-plan.md`.
+
 Objective/problem: complete the visual communication branch by combining the
 already operational coding-agent loop with graphical inspection, external design
 references, structured annotation, and the v0.8.1 project-level acceptance

package/docs/SECURITY.md

@@ -219,10 +219,12 @@ protect against other software already running as the same user.
   `content-type: application/json`, identity `content-encoding` only, a
   256 KiB (`262144` byte) body limit, valid JSON, and a closed request shape
   with unknown fields rejected.
-- **Exactly three `POST` routes**: `POST /api/annotations`,
+- **Exactly three v0.9 `POST` routes**: v0.9 introduced
+  `POST /api/annotations`,
   `POST /api/annotations/:handle/promote-contract`, and
   `POST /api/annotations/:handle/materialize-reference`. `PUT`, `PATCH`, and
-  `DELETE` stay unsupported everywhere. Any other `POST` returns `405`.
+  `DELETE` stay unsupported everywhere. The implemented, unreleased v0.10
+  routes extend this same gate as described below.
 - **No permissive CORS**: no `Access-Control-Allow-*` headers are sent, so a
   page from any other origin cannot read the capability or send a JSON
   authoring request. A real-Chromium test proves this for all three routes.
@@ -249,12 +251,32 @@ protect against other software already running as the same user.
   `.tmp-*` directories, so a partially written artifact is never presented as
   evidence.
 
+## v0.10 Visual Change authoring boundary
+
+v0.10 extends only the project-aware guarded `POST` surface. It adds explicit
+reference approval and actual/reference workflow creation, plus workflow
+activation, canonical check, restore, handoff preparation, human review, and
+recording of already-existing governance results. Every route reuses the same
+exact Host, Origin, memory-only capability token, JSON content type,
+compression rejection, body limit, closed request-shape, serialized-write,
+path-containment, and `no-store` controls. Standalone `view --root` remains
+read-only, and the service worker continues to cache no `/api/` response.
+
+The additional surface does not grant source-edit or external-process
+authority. Observer never edits target source, executes a coding agent, invokes
+my-dev-kit, or contacts/controls an orchestrator. Optional orchestrator fields
+are bounded traceability metadata only. Handoffs are generated in memory and
+are not a persisted evidence family. Review acceptance requires the latest
+canonical Observer check to be PASS; it cannot approve a baseline/reference or
+restore project acceptance. Governance recording can reference only a
+separately persisted canonical approval and does not perform that approval.
+
 ## Not yet addressed
 
 Certificate-failure-specific handling, permission-prompt-specific handling
 (Chromium's default deny-all applies; no permission is ever explicitly
 granted), and any non-loopback/remote browsing mode remain unimplemented and
-out of scope. `@dailephd/my-frontend-observer@0.9.0` is published to npm, and a
+out of scope. `@dailephd/my-frontend-observer@0.10.0` is the current release. A
 pre-release readiness CI workflow (Windows/Linux/macOS packed-candidate
 validation, now covering the v0.8 viewer alongside every earlier version's
 packed behavior) exists (see `docs/CI_CD.md`). The v0.7 external-reference/

package/docs/WORKFLOWS.md

@@ -685,11 +685,37 @@ repository. The run result's `status` must be `passed` and its
 `cleanupErrors` must be empty. The demo and scenarios are not in the npm
 package. See `examples/v09-demo/README.md` for details and maintenance notes.
 
-## Visual workflow progression (v0.9 implemented, v0.10 future)
+## Complete v0.10 visual-change workflow (implemented, unreleased)
 
 The sequence on top of the v0.7/v0.8 foundation above preserves the current
 engines and lets graphical interfaces consume rather than invent the reference
-model. v0.9 is released as `0.9.0`. v0.10 is still future:
+model. v0.9 is released as `0.9.0`; v0.10 is implemented in the repository
+and remains unreleased.
+
+Actual-frontend entry starts in project-aware `view`: open a runtime
+observation, draw and explicitly associate a mark, author and confirm runtime
+intent, save it, select confirmed intent, and create an inactive visual-change
+workflow. Reference entry opens one exact approved reference, saves confirmed
+reference intent against that instance, selects an exact baseline observation,
+authors explicit region-to-runtime bindings, and creates an inactive reference
+workflow.
+
+Both modes then share the same human-controlled loop:
+
+```text
+explicit Activate
+-> Prepare handoff
+-> external actor edits source outside Observer
+-> Run check (the canonical check <baseline> --json operation)
+-> immutable pending attempt
+-> Request correction, Accept latest PASS, or Abandon
+-> optional governance recording only after a separate canonical approval
+-> optional explicit Restore acceptance
+```
+
+The controlling invariants are `DRAW != DECIDE`, `CONFIRM !=
+PROMOTE/MATERIALIZE`, `PROMOTE/MATERIALIZE != ACTIVATE`, `PASS != ACCEPT`, and
+`ACCEPT != GOVERNANCE`.
 
 ```text
 stable targets and bounded runtime behavior