yam-flow 2.5.1 → 2.7.0

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 All notable changes to yam-flow are documented here.
 
+## v2.7.0 - 2026-08-24
+
+### Added
+
+- Added immutable final-scope verification closure receipts that bind declared work to the current Git dirty, staged, and untracked path set, promote release-sensitive changes, and separate selected checks from operator-declared execution evidence.
+- Added optional demand-gated media provider receipts with exact call/execution/dry-run/submit state plus confined, identity-bound local asset provenance.
+
+### Improved
+
+- Skill installation and removal now use no-follow regular-file access where available, verify descriptor and path identity, and revalidate parent-directory identity around read, copy, move, rollback, and mutation boundaries.
+- Verification closure and media receipt reads and immutable writes apply confined path, non-symlink parent, descriptor identity, size, and digest checks; media asset hashing is sequential and bounded.
+
+### Security
+
+- Symlinked install source/destination segments, raced path identities, rollback or cleanup targets whose recorded type/device/inode no longer match, unplanned final Git paths, unavailable Git scope, receipt path escapes, local asset symlinks, and incoherent provider-execution claims fail closed.
+- Node does not expose descriptor-relative `openat` traversal, and arbitrary Windows reparse-point coverage remains unverified; these limits are documented instead of overstated.
+
+### Verification
+
+- Focused install-transaction and phase-adoption smokes cover source/destination race handling, rollback preservation, Git-scope drift, immutable/tampered receipts, bounded media assets, and packaged CLI compatibility.
+- Release checks include typecheck, clean build/self-verification, distribution freshness, package boundary/secrets, registry version availability, and CLI smoke.
+
+## v2.6.0 - 2026-08-07
+
+### Added
+
+- Added effective executable identity validation for global yam install and rollback, including npm global root, package/bin mapping, PATH target, canonical realpaths, and observed version.
+- Added bounded paired-sample promotion receipts with explicit thresholds, deterministic evidence digests, operator-asserted measurement truth, and strict keep/revert gates.
+- Added a capability matrix to `yam tools doctor --json` that separates maturity from observed runtime readiness.
+- Added digest-bound strict gate results at release, external-update, Mission-completion, and benchmark-promotion boundaries.
+- Added the opt-in Demand-Gated Design Production Phase: pre-recorded operator demand, local static Plan Review Canvas Lite, at most two chronologically finding-backed revisions, final gallery manifest, and digest-verifiable immutable phase receipt.
+
+### Improved
+
+- External update receipts preserve the deepest actionable Doctor or rollback failure as the primary blocker while keeping receipt persistence failures as secondary evidence.
+- Ueye design-production artifacts bind one canonical revision state to its closed Canvas, enforce Canvas-comment and archive chronology at record time, and revalidate source, exact anchors, protected-asset editability, final-round gallery linkage, upstream digests, nested receipt semantics, session state, and aggregate state without upgrading those checks into visual, license, or implementation proof.
+
+### Security
+
+- Same-version PATH shadows, malformed global package/bin identities, path/symlink escapes, protected-asset replacement attempts, and inconsistent gate contracts fail closed.
+- Canvas rendering is local static HTML with a no-script/no-network CSP and escaped reviewer content; it starts no server or background process.
+
+### Verification
+
+- Focused external-update identity, strict-gate/promotion/capability/Mission, and design-production smokes.
+- TypeScript typecheck, clean build, self-verification, packaged CLI, package-boundary/secret, and bounded Deep checks.
+
 ## v2.5.1 - 2026-07-31
 
 ### Added

package/COMMANDS.md

@@ -154,7 +154,63 @@ yam update apply --component yam --json
 yam update apply --all --json
 ```
 
-`yam update check` is read-only. Every `apply` needs explicit authorization, uses a concurrent-run lock, records a component receipt, and stops on failed/manual results. `--all` runs yam last. Insane Search is never remove-first and `.codex/plugins/cache` is never edited directly.
+`yam update check` is read-only. Every `apply` needs explicit authorization, uses a concurrent-run lock, records a component receipt, and stops on failed/manual results. `--all` runs yam last. A yam install verifies the effective executable identity before any yam-side install command and repeats that check during rollback. This identity contract currently supports POSIX symlink layouts; Windows npm `.cmd` shims fail closed as unverified. Insane Search is never remove-first and `.codex/plugins/cache` is never edited directly.
+
+## Demand-Gated Design Production
+
+Use only after repeated plan-review or large multi-asset coordination demand is real. A one-off review remains on the ordinary Ueye/Mission path.
+
+```bash
+yam ueye production canvas create --session-id campaign --title "Campaign review" --demand-kind multi_asset_production --demand-evidence "Five coordinated assets require one review package" --artifact-spec ./canvas-artifact.json --json
+yam ueye production canvas comment --session-path .yam/ueye/design-production/campaign/plan-review.json --render-path .yam/ueye/design-production/campaign/canvas.html --comment-id finding-1 --artifact-id campaign-plan --anchor-kind line --locator L12 --finding "CTA hierarchy is ambiguous" --requested-change "Make the primary CTA explicit" --json
+yam ueye production canvas close --session-path .yam/ueye/design-production/campaign/plan-review.json --render-path .yam/ueye/design-production/campaign/canvas.html --verdict request_changes --json
+yam ueye production revision init --session-id campaign --json
+yam ueye production revision record --state-path .yam/ueye/design-production/campaign/revision-state.json --finding-id round-1 --source-comment-id finding-1 --finding-summary "CTA hierarchy is ambiguous" --finding-evidence "Canvas line L12" --planned-change "Clarify the primary CTA" --outcome accepted --revision-ref ./ueye-revision-ref.json --json
+yam ueye production gallery write --manifest-path .yam/ueye/design-production/campaign/gallery.json --session-id campaign --completion-state packaged --artifact-spec ./gallery-artifact.json --json
+yam ueye production gallery verify --manifest-path .yam/ueye/design-production/campaign/gallery.json --json
+yam ueye production finalize --demand-kind multi_asset_production --demand-evidence "Five coordinated assets require one review package" --canvas-session-path .yam/ueye/design-production/campaign/plan-review.json --revision-state-path .yam/ueye/design-production/campaign/revision-state.json --gallery-manifest-path .yam/ueye/design-production/campaign/gallery.json --receipt-path .yam/ueye/design-production/campaign/phase-receipt.json --json
+yam ueye production phase verify --receipt-path .yam/ueye/design-production/campaign/phase-receipt.json --json
+```
+
+Canvas artifact specs use `{ "id", "role", "file_path" }`; gallery specs include `{ "id", "role", "provenance", "revision_ref", "dimensions", "sha256", "completion_state", "final_path" }`. A revision reference also carries the archive receipt's exact `archived_at`, which must match its Ueye manifest entry. All project paths are relative and confined; Canvas session/render paths and the single revision state are fixed under the session-specific `.yam/ueye/design-production/` directory. Revision init binds that state to the closed `request_changes` Canvas path and digest; record/show/finalize reject alternate state files, and record immediately checks the source Canvas comment plus the current archive-time boundary. Demand is operator-asserted but must be recorded before Canvas creation and match at finalize. Canvas source hashes and exact anchors are rechecked before comment/close/finalize. Every phase round names its source Canvas comment and supplies at least one newly archived Ueye revision created within that round's review window; gallery artifacts bind to the final round. Ueye asset/revision hashes are rechecked, a protected `do_not_replace` asset requires `intent: "preserve"`, and `edit_copy` requires `allowed_for_edit: true`. The phase receipt stores upstream and canonical receipt digests, and `phase verify` re-reads their semantics as well as detecting later byte changes. Overall phase truth remains `partial`, and gallery visual, license, and implementation claims always remain `not_verified`.
+
+## Verification Closure And Media Provider Receipts
+
+These are explicit, immutable artifacts. They do not run verification commands or contact media providers.
+
+Prepare one JSON file per selected/executed/skipped/truncated command record, then repeat the corresponding flag:
+
+```json
+{"id":"typecheck","command":"npm run typecheck","scope":"affected","required":true}
+```
+
+```json
+{"id":"typecheck","command":"npm run typecheck","exit_code":0,"evidence":"exit 0 observed in the final worktree"}
+```
+
+```bash
+yam verification closure create --root /path/to/project --receipt-path .yam/verification/final.json --planned-scope affected --changed-file src/example.ts --selected-spec ./selected.json --executed-spec ./executed.json --json
+yam verification closure verify --root /path/to/project --receipt-path .yam/verification/final.json --json
+```
+
+`create` snapshots the Git top-level dirty, staged, and untracked path set. Every observed path must be declared; unplanned paths, missing declared paths, unavailable Git scope, missing required execution, and release-sensitive paths without a required release-scope check fail closed. `verify` re-reads the current Git path set as well as the receipt digest. A later path-set change returns `current_git_scope_drift`; rerun checks against the final state and create a new receipt path because receipts are non-overwriting. Content-only changes to an already-dirty path do not alter the Git path set, and command results remain operator-asserted `partial` evidence.
+
+Media provider receipts are optional and should be used only after real execution-tracking demand exists. Each asset spec contains `{ "id", "role", "file_path", "provenance": { "kind", "source_ref", "recorded_at" } }`.
+
+```bash
+yam media provider create --root /path/to/project --receipt-path .yam/media/dry-run.json --demand-kind media_generation --demand-evidence "coordinated asset work needs an execution boundary" --provider example --model example-v1 --provider-calls 0 --dry-run --asset-spec ./input-asset.json --json
+yam media provider verify --root /path/to/project --receipt-path .yam/media/dry-run.json --json
+```
+
+A dry run requires zero calls, no execution, and no submit. Explicit execution requires `--provider-execution --submit`, at least one call, and a provider-provenance output asset. Local asset and receipt integrity is verified, but provider execution, visual quality, and implementation correctness are not independently proven.
+
+## Bounded Promotion
+
+```bash
+yam benchmark report --label "scout strategy" --candidate-digest <sha256> --baseline-digest <sha256> --sample seed-1:0.82:0.71 --sample seed-2:0.79:0.70 --unit score --evidence-source "fixed local fixture" --target higher --min-samples 2 --min-mean-delta 0.05 --min-win-rate 0.5 --json
+```
+
+This command records paired arithmetic; it does not run the benchmark. A `keep` decision still has `measurement_truth: operator_asserted` and overall `truth_status: partial`.
 
 ## Tool Doctor / Proof / Safety
 

package/README.md

@@ -112,7 +112,9 @@ cd ~/Documents/Codex/tools/yam
 yam install
 ```
 
-`yam install` first checks ownership of every existing active skill. A skill is replaced automatically only when the previous yam receipt names it and its complete regular-file inventory and content hashes still match the receipt. The installer then stages every managed skill plus the shared `references/` directory, verifies the complete staged file manifest with SHA-256, and replaces the verified active set in `~/.agents/skills/`. If any commit or post-install verification step fails, yam restores the previous managed skill set and receipt.
+`yam install` first checks ownership of every existing active skill. A skill is replaced automatically only when the previous yam receipt names it and its complete regular-file inventory and content hashes still match the receipt. The installer then stages every managed skill plus the shared `references/` directory, verifies the complete staged file manifest with SHA-256, and replaces the verified active set in `~/.agents/skills/`. If any commit or post-install verification step fails, yam restores the previous managed skill set and receipt. Rollback and cleanup remove newly installed skills, receipts, locks, and transaction roots only while their recorded type and device/inode identity still match; an identity-swapped path is preserved and reported instead of being treated as yam-owned.
+
+Install source, destination, receipt, and managed-tree paths must use canonical physical directories. A symlink alias used as the package source or `YAM_SKILLS_HOME`, or a symlinked parent segment inside either boundary, fails closed; resolve the alias to its real path before retrying. Regular-file reads use descriptor identity checks and `O_NOFOLLOW` where the platform exposes it, while mutation boundaries revalidate parent directory identities. This narrows symlink-swap risk but is not `openat`-grade proof because Node does not expose descriptor-relative traversal here. Arbitrary Windows reparse-point handling is also unverified, so Windows receives the portable identity checks without a claim of complete reparse coverage.
 
 If an existing active directory is user-owned, locally modified, or cannot be proven yam-owned, installation stops before staging and preserves it. After reviewing the files, replace only the intended conflicting name explicitly:
 
@@ -150,7 +152,11 @@ yam update apply --component yam
 yam update apply --all --json
 ```
 
-`--all` processes Scrapling, then Insane Search, then yam so the running updater replaces itself last. It stops at the first failed or manual-only component. A yam update is successful only after the installed version and status checks plus a final read-only `yam doctor --json` return the expected healthy contract. Doctor failure triggers the existing rollback path, and rollback is considered automatic only when its own version, status, and Doctor checks pass. Each attempt writes a component receipt under `~/.local/state/yam/update-receipts/` with the old/new version, source revision, checks, side effects, outcome, and rollback guidance. A lock prevents concurrent apply runs.
+`--all` processes Scrapling, then Insane Search, then yam so the running updater replaces itself last. It stops at the first failed or manual-only component. After the global npm install, yam resolves `npm root -g`, the installed package manifest and bin mapping, the first `yam` on `PATH`, canonical realpaths, and the observed version before any `yam install` mutation. A same-version PATH shadow, malformed package, or identity mismatch fails closed; legitimate multi-hop symlinks remain valid. Rollback repeats the same identity check before rollback-side yam commands.
+
+A yam update is successful only after the installed version and status checks plus a final read-only `yam doctor --json` return the expected healthy contract. Doctor failure triggers the existing rollback path, and rollback is considered automatic only when its own identity, version, status, and Doctor checks pass. The deepest actionable rollback or Doctor cause remains primary even if receipt persistence also fails. Each attempt writes a bounded, redacted component receipt under `~/.local/state/yam/update-receipts/` with the old/new version, source revision, executable identity, checks, side effects, outcome, and rollback guidance. The aggregate apply response emits and verifies the strict `yam.gate-result.v1`; an already-held lock also returns a blocked gate without mutating components. A lock prevents concurrent apply runs.
+
+Effective yam identity currently verifies POSIX-style executable/symlink layouts through `which` and canonical realpaths. Windows npm `.cmd` shim identity is intentionally unverified and fails closed until a dedicated shim parser and fixture exist.
 
 Scrapling updates install an exact stable PyPI version into a new versioned virtual environment. `pip check`, ordinary HTTP extraction, and headless browser extraction must pass before the executable symlink changes atomically; the previous environment is retained. An existing environment must have a matching `.yam-scrapling-install.json` ownership marker before yam will replace its link. Insane Search uses only the official `codex plugin` commands. yam never edits `.codex/plugins/cache`, never removes the plugin first, and returns `manual_plugin_update_required` when the installed Codex CLI cannot update it safely in place.
 
@@ -216,6 +222,13 @@ yam ueye asset add --manifest .yam/ueye/assets.json --id official-logo --file ./
 yam ueye asset verify --manifest .yam/ueye/assets.json --json
 yam ueye revision archive --file .yam/screens/home.png --round 1 --artifact-id home --root .yam/ueye/revisions --json
 yam ueye revision verify --manifest .yam/ueye/revisions/manifest.json --json
+yam ueye production canvas create --session-id campaign --title "Campaign plan review" --demand-kind multi_asset_production --demand-evidence "Five coordinated campaign assets require one bounded review package" --artifact-spec ./canvas-artifact.json --json
+yam ueye production canvas comment --session-path .yam/ueye/design-production/campaign/plan-review.json --render-path .yam/ueye/design-production/campaign/canvas.html --comment-id finding-1 --artifact-id campaign-plan --anchor-kind line --locator L12 --finding "CTA hierarchy is ambiguous" --requested-change "Make the primary CTA explicit" --json
+yam ueye production canvas close --session-path .yam/ueye/design-production/campaign/plan-review.json --render-path .yam/ueye/design-production/campaign/canvas.html --verdict request_changes --json
+yam ueye production revision init --session-id campaign --json
+yam ueye production gallery verify --manifest-path .yam/ueye/design-production/campaign/gallery.json --json
+yam ueye production finalize --demand-kind multi_asset_production --demand-evidence "Five coordinated campaign assets require one bounded review package" --canvas-session-path .yam/ueye/design-production/campaign/plan-review.json --revision-state-path .yam/ueye/design-production/campaign/revision-state.json --gallery-manifest-path .yam/ueye/design-production/campaign/gallery.json --receipt-path .yam/ueye/design-production/campaign/phase-receipt.json --json
+yam ueye production phase verify --receipt-path .yam/ueye/design-production/campaign/phase-receipt.json --json
 yam proof --route ueye --truth verified --visual "implementation screenshot evidence recorded" --design-completion '{"completion_claim":"done","has_implementation_screenshot":true,"design_quality":"pass","states_checked":true,"mobile_checked":true,"contrast_checked":true,"cta_checked":true,"direction_locked":true,"truth_status":"verified"}'
 yam media proof --requested --attempted --output ./generated.png --wait-loop --json
 yam proof --route mission --mission-envelope '{"agent_id":"implementer","assigned_scope":"target component","changed_files":["src/file.ts"],"verification_hint":"npm run typecheck","truth_status":"partial"}'
@@ -320,6 +333,12 @@ These shapes keep reports machine-readable without turning normal work into a he
 - Ueye design brief and anti-slop review: `$ueye` reports can record operator-provided brief dimensions, constraints, invented metrics, placeholder copy, generic visuals, and custom anti-slop blockers. P0 anti-slop findings block `done` claims.
 - Ueye deep visual review: `$ueye` can record acceptance criteria, touched/read/verified files, skipped checks, residual risks, stop condition, resume hint, design-system evidence, implementation evidence, and a state matrix so serious UI work can carry Deep-grade verification without leaving the Ueye route.
 - Ueye asset/revision integrity: `$ueye` can record license/provenance and protected/editable flags for local references, then preserve pre-edit artifacts in hash-verified numbered rounds.
+- Demand-gated design production: when repeated Plan Review or large multi-asset work creates real coordination demand, Ueye can add a local static Canvas-lite review, at most two finding-backed revision rounds, a final gallery manifest, and one phase receipt. One-off review and single-asset work stay on the ordinary Ueye/Mission path. Integrity evidence never becomes proof of visual quality, licensing, or implementation correctness.
+- Bounded promotion receipt: `yam benchmark report` can compare paired candidate/baseline measurements under explicit sample, mean-delta, and win-rate thresholds. Arithmetic is verified, while measurement provenance remains `operator_asserted` and overall truth stays `partial`.
+- Honest capability matrix: `yam tools doctor --json` reports feature maturity separately from observed runtime readiness; instruction-only or unprobed capabilities are not reported as executed.
+- Strict gate result: release, update, benchmark-promotion, and Mission completion boundaries emit a digest-bound `yam.gate-result.v1` and fail closed on missing or inconsistent required evidence.
+- Final-scope verification closure: `yam verification closure create|verify` binds the planned boundary, current Git dirty/staged/untracked paths, release-sensitive escalation, selected versus operator-declared executed commands, skipped/truncated reasons, and an immutable digest. Missing required execution, unknown results, unplanned files, unavailable Git scope, and later receipt tampering fail closed; yam does not execute the recorded commands or upgrade their truth beyond `partial`.
+- Optional media provider receipt: `yam media provider create|verify` records an explicit demand trigger, exact `provider_calls`/`provider_execution`/`dry_run`/`submit` state, and identity-bound local asset provenance. It never calls a provider, and integrity verification never proves visual or implementation correctness.
 
 ## Ueye Capture And Compare
 
@@ -331,6 +350,7 @@ yam ueye compare --reference ./reference.png --actual .yam/screens/home.png --js
 yam ueye preflight . --json
 yam ueye asset verify --manifest .yam/ueye/assets.json --json
 yam ueye revision verify --manifest .yam/ueye/revisions/manifest.json --json
+yam ueye production --help
 yam ueye report --reference ./reference.png --actual .yam/screens/home.png --brief-dimension "primary CTA clarity" --constraint "mobile first" --anti-slop "placeholder copy remains" --acceptance-criterion "pricing card CTA remains visible on mobile" --design-system-evidence "uses existing button token" --implementation-evidence "browser screenshot reviewed" --state-check default:pass --state-check mobile:partial --skipped-check "hover state not checked on touch viewport" --residual-risk "tablet breakpoint still needs visual pass" --stop-condition "stop after primary states are checked and residual risk is recorded" --resume-hint "capture tablet screenshot next" --completion-claim done --design-quality pass --direction-locked --reference-read --states-checked --mobile-checked --contrast-checked --cta-checked --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --preserved-state --json
 ```
 
@@ -342,10 +362,16 @@ yam ueye report --reference ./reference.png --actual .yam/screens/home.png --bri
 
 `preflight` does not claim visual verification. It is a pre-work checklist for reference source, target states, mobile/responsive needs, CTA/contrast/accessibility risk, screenshot availability, and likely P0/P1 candidates.
 
+The design production phase is deliberately dormant by default. Use it only when repeated plan annotation or a large coordinated asset set makes prose/file-by-file review costly. The operator-asserted demand trigger is recorded before Canvas creation and must match at finalize. Canvas is static local HTML with no server; its closed `request_changes` session binds one canonical `revision-state.json`, so init/record/show/finalize cannot select an alternate state to reset the two-round budget. Each recorded round must link a current Canvas comment and a newly archived Ueye revision created within that review boundary; the final gallery verifies path/hash/dimension/final-round linkage only and must be created no earlier than Canvas close or the final revision record. `finalize` binds SHA-256 digests for Canvas, revision state, and gallery into an immutable receipt, while `phase verify` re-reads nested upstream semantics and detects later evidence changes. Overall truth remains `partial`, correctness claims remain false, and a two-round unresolved stop remains draft.
+
 Generated media can guide visual direction, but it cannot prove the implemented UI by itself:
 
 ```bash
 yam media proof --requested --attempted --output ./generated.png --wait-loop --json
 ```
 
+When real repeated media work needs an execution boundary, prepare bounded JSON asset specs and opt in explicitly. Dry-run receipts require zero calls/no submit; execution receipts require a submitted call plus a provider-provenance output. Both the receipt and local asset paths are confined below the project root and can be re-read with `yam media provider verify`. The existing `yam media proof` command remains the lightweight default.
+
+For completion evidence, `yam verification closure create` consumes small selected/executed/skipped/truncated JSON specs. It snapshots actual Git status before writing under `.yam/verification/`; declare every expected changed path with repeated `--changed-file`, then use `verify` to detect semantic, digest, or current Git path-set drift. `current_git_scope_drift` means checks must be rerun against the final state and a new immutable receipt must be created. This remains an explicit artifact, not an always-on hook or command runner.
+
 For agent-driven visual QA, prefer the Codex in-app Browser plugin. Use the user's Chrome browser only when explicitly requested or when Chrome-only session/profile state is required.

package/ROADMAP.md

@@ -53,6 +53,7 @@ Tasks:
 - Detect common commands: typecheck, lint, test, build. Done.
 - Map changed files to likely checks. Done: dirty, staged, and untracked paths now map to focused rules with confidence, reason, fallback, and available commands.
 - Keep this advisory, not mandatory. Done.
+- Add an explicit final-scope closure artifact without turning the detector into an auto-runner. Done: immutable receipts bind current Git scope, release escalation, selected/executed command separation, skipped/truncated reasons, and partial operator-asserted truth.
 
 ### 4. Token Budget Reporter
 
@@ -76,6 +77,7 @@ Tasks:
 - Add local reference asset provenance/protection manifest and non-overwriting revision history. Done.
 - Add optional browser/screenshot capture notes.
 - Keep image generation optional, never a gate.
+- Add an optional provider-execution boundary only when real media demand exists. Done: exact fail-closed execution fields, confined hash-bound local assets/provenance, and verify/tamper detection without provider calls or correctness claims.
 
 ### 6. Deep Runtime Workflow
 
@@ -94,7 +96,7 @@ Goal: make install/update simpler.
 
 Tasks:
 
-- Add symlink-friendly local install.
+- Reconsider symlink-friendly local install only if Node exposes a safe descriptor-relative traversal boundary or an equivalent proven design. Deferred: current package source, `YAM_SKILLS_HOME`, and managed-tree paths intentionally reject symlink aliases and symlinked parent segments.
 - Add version command. Done.
 - Add staged transactional install, rollback, receipt, and drift-aware status. Done.
 - Add checked component updates for yam, Scrapling, and Insane Search with explicit authorization, receipts, and rollback guidance. Done.
@@ -435,7 +437,7 @@ Keep out for now:
 
 #### Plan Review Canvas Lite
 
-Status: deferred until repeated real-use demand.
+Status: available only inside the opt-in Demand-Gated Design Production Phase.
 
 Trigger:
 
@@ -443,15 +445,47 @@ Trigger:
 - Terminal-only approval causes revision ambiguity or costly re-reading.
 - A local browser review surface would materially shorten an approved Mission or Ueye feedback loop.
 
-First shape:
+Implemented shape:
 
-- local-only artifact review.
-- anchored comments and approve/request-changes verdict.
-- explicit session end and bounded idle shutdown.
-- Host/Origin checks, path confinement, and sandboxed artifact rendering.
+- local-only, path-confined static HTML artifact review with no server or background process.
+- exact line/text anchors and bounded operator-asserted image regions.
+- source hash and exact-anchor revalidation before comments, close, and finalize.
+- anchored findings plus explicit approve/request-changes verdict and session end.
 
 Keep out for now:
 
 - default local server.
 - remote sharing or hosting.
 - automatic implementation start without an explicit approval verdict.
+
+#### Demand-Gated Design Production Phase
+
+Status: implemented as an opt-in phase; remain dormant until repeated plan review or large multi-asset design production creates real coordination cost.
+
+Trigger:
+
+- Plan review repeatedly needs exact-element annotations that prose feedback cannot express efficiently.
+- A Ueye task produces several related visual assets that must preserve cross-asset consistency and provenance.
+- Reviewers need bounded before/after comparison or a packaged overview instead of inspecting files one by one.
+
+Phases:
+
+1. Record the operator-asserted demand kind and concrete evidence before Canvas creation, then require an exact match at finalize.
+2. Run Plan Review Canvas Lite as a local-only, explicitly closed review session.
+3. Bind one canonical revision state to the closed Canvas path/digest, then run at most two Canvas-comment-linked revision rounds, requiring at least one new hash-verified Ueye archive in the current review boundary per round.
+4. Write and verify a final gallery manifest with artifact ids, roles, provenance, final-round revision references, dimensions, hashes, completion state, and final paths.
+5. Finalize one immutable phase receipt with Canvas/revision/gallery and canonical receipt digests only when the demand trigger, closed Canvas, archive chronology, terminal revision state when required, matching session ids, and gallery integrity agree; re-verify it to detect later evidence changes.
+
+Entry and stop rules:
+
+- Enter only after the trigger appears in real work; a one-off plan, screenshot review, or single-asset edit stays on the existing Ueye/Mission path.
+- Each round requires a concrete finding from the bound Canvas; alternate state paths fail closed, and the phase ends after acceptance, two rounds, or a blocked integrity gate, whichever comes first.
+- The gallery is an inspection and packaging artifact, not proof that visual quality, licensing, or implementation correctness passed.
+- A two-round-limit stop may finalize only a draft gallery; it cannot be upgraded into a packaged or complete result.
+
+Keep out for now:
+
+- automatic creation of a design runtime or typed JSONL message bus.
+- unbounded revision loops or autonomous approval.
+- remote gallery hosting, public sharing, or background review services.
+- replacing protected source assets or weakening existing provenance and `do_not_replace` checks.