@dailephd/my-frontend-observer 0.10.0 → 0.10.1

package/docs/reports/v0.10-batch1-visual-change-workflow-foundation.md

@@ -1,102 +1,102 @@
-# v0.10 Batch 1 Visual-Change Workflow Foundation
-
-## 1. Verdict
-
-PASS after the validation recorded below.
-
-## 2. Repository and Git state
-
-- Repository: `C:\Users\daile\Projects\my-frontend-observer`
-- Starting commit: `0ca6a686ee16447052845227a86f685b91aa54c1`
-- Branch: `feature/v0.10-full-visual-workflow`
-- Intended commit: `feat: add v0.10 visual change workflow foundation`
-
-## 3. Retrieval and index
-
-- Published my-dev-kit version: `1.12.3`
-- Index: `.my-dev-kit-context/indexes/my-frontend-observer-v0.9.1-20260922T070928-v010-batch1`
-- Command: `my-dev-kit index --root C:\Users\daile\Projects\my-frontend-observer --src src --src viewer/src --src tests --src scripts --out <index> --call-graph --json`
-- Roots: `src`, `viewer/src`, `tests`, `scripts`
-- Summary: 162 files, 1,606 symbols, 3,471 edges, zero index-level warnings/errors.
-- Partial analyzers: data-model (758 warnings) and classification (1,568 warnings). Syntax, call graph, frontend semantic, and frontend reachability completed.
-
-Canonical precedents confirmed:
-
-- `src/domain/visualAnnotation.ts` and `visualAnnotationIdentity.ts`: closed validation, sorted-key canonical JSON, SHA-256 request identity, nonce-backed instance identity, producer/provenance, and forward supersession.
-- `src/domain/externalReference.ts`, `externalReferenceIdentity.ts`, and `frontendContractIdentity.ts`: exact request/instance and immutable supersession conventions.
-- `src/domain/externalReferenceRuntimeBinding.ts`: the exact reusable explicit binding declaration type and its identifier, bound, and duplicate semantics.
-- `src/artifacts/visualAnnotationArtifactWriter.ts` and reader: sibling temporary directory, overwrite refusal, cleanup, manifest/media digest validation, and atomic rename.
-- `src/projectWorkflow/projectPaths.ts`: the project evidence-root/path owner.
-- `src/viewerServer/evidence/classify.ts`, `index.ts`, `projection.ts`, `handles.ts`, and `annotationView.ts`: the existing support-state classifier, metadata-first index, safe handles, bounded exact identity lookup, and honest unavailable projection.
-- Existing `EvidenceReference` is structured evaluation provenance and explicitly is not a filesystem reference. Therefore a small workflow-owned project-relative artifact reference was required; no generalized cross-project framework was added.
-
-Full source/test file reads: none.
-
-## 4. Production implementation
-
-Created:
-
-- `src/domain/visualChangeWorkflow.ts`
-- `src/domain/visualChangeWorkflowIdentity.ts`
-- `src/artifacts/visualChangeWorkflowArtifactWriter.ts`
-- `src/artifacts/visualChangeWorkflowArtifactReader.ts`
-- `src/application/visualChangeWorkflowPersistenceService.ts`
-- `src/viewerServer/evidence/visualChangeWorkflowView.ts`
-
-Modified:
-
-- `src/projectWorkflow/projectPaths.ts`
-- `src/viewerServer/evidence/classify.ts`
-- `src/viewerServer/evidence/handles.ts`
-- `src/viewerServer/evidence/projection.ts`
-- `src/index.ts`
-- `docs/CONTRACTS.md`
-
-The artifact kind is exactly `my-frontend-observer/visual-change-workflow`; schema is exactly `1.0.0`; attempts are bounded at 20. The closed domain union contains the two frozen entry modes, exact evidence references, check snapshots, coordination metadata, review state, activation, and governance-result references.
-
-Request identity is deterministic over semantic evidence identities and binding content. Storage paths, timestamps, output roots, temp roots, Viewer handles/ports, and coordination filesystem details are excluded. Workflow instance IDs are fresh. Attempt IDs hash request ID plus candidate observation ID. Revisions use `supersedesVisualChangeWorkflowId`; parents are never rewritten.
-
-The writer validates, refuses existing final output, uses `.tmp-<workflowId>`, writes canonical bindings when required, verifies its digest, writes the manifest, and atomically renames. The reader checks kind/version/domain validity, exact `bindings.json` path, regular-file status, SHA-256, canonical bytes, declaration equality, and count. No referenced artifact or media is copied.
-
-Discovery classifies the new family through the existing support-state machinery. Metadata includes workflow/request identity, mode, baseline, annotation, selected reference, attempt count, latest check/review state, and supersession without embedding attempts. The read projection resolves exact identities using canonical classification and returns explicit unavailable state for missing or ambiguous links.
-
-## 5. Tests
-
-Created `tests/unit/visualChangeWorkflow.test.ts`. Its ten focused cases protect:
-
-1. minimal actual/reference validation, closed shapes, wrong kind, and unsupported schema;
-2. request identity determinism and semantic-scope changes, including operational path exclusion;
-3. fresh workflow identity and deterministic attempt identity invariants;
-4. attempt bounds, revision lineage, path safety, and review vocabulary;
-5. actual-mode round trip, absent bindings file, and overwrite refusal;
-6. deterministic bindings bytes, digest/count round trip, and tamper rejection;
-7. temporary-output cleanup on injected failure;
-8. same-request/different-instance persistence and byte-immutable parent revision;
-9. supported classification and bounded index metadata;
-10. exact linked-evidence resolution and honest missing evidence.
-
-Existing focused annotation, external-reference, contract, and discovery suites remained unchanged and passed.
-
-## 6. Validation
-
-- `npm run typecheck`: PASS.
-- `npm run lint`: PASS after removal of one unused import.
-- Focused five-file Vitest run: PASS, 51 tests.
-- `npm test`: PASS.
-- `npm run build`: PASS.
-- `npm run check:docs`: PASS.
-- `git diff --check`: PASS.
-
-Existing constants remain 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`, and Viewer protocol `1.3.0`.
-
-## 7. Exclusions and risk
-
-No project activation/restoration, live `checkProject` mapping, Viewer UI/POST routes, entry-mode UI, handoff, orchestrator execution, rerender/correction loop, acceptance action, governance operation, tutorial, version bump, or release work was implemented.
-
-Remaining risk is limited to later-batch composition: Batch 2 must map canonical `CheckWorkflowResult` into the frozen snapshot, activate/restore project acceptance explicitly, and record attempts without scope drift. Batch 1 deliberately does not enforce accepted-requires-PASS.
-
-## 8. Batch 2 handoff
-
-Start from this Batch 1 commit. Reuse `persistVisualChangeWorkflow`, `readVisualChangeWorkflowArtifact`, `buildVisualChangeAttemptIdentity`, `visualChangeOutputLocation`, and the existing `checkProject` owner. Implement only explicit acceptance activation/restore and canonical check-to-snapshot attempt recording, preserving all Batch 1 identities and schema `1.0.0`.
-
-Generated state is confined to `.my-dev-kit-workflow/` and `.my-dev-kit-context/`; neither path is staged.
+# v0.10 Batch 1 Visual-Change Workflow Foundation
+
+## 1. Verdict
+
+PASS after the validation recorded below.
+
+## 2. Repository and Git state
+
+- Repository: `C:\Users\daile\Projects\my-frontend-observer`
+- Starting commit: `0ca6a686ee16447052845227a86f685b91aa54c1`
+- Branch: `feature/v0.10-full-visual-workflow`
+- Intended commit: `feat: add v0.10 visual change workflow foundation`
+
+## 3. Retrieval and index
+
+- Published my-dev-kit version: `1.12.3`
+- Index: `.my-dev-kit-context/indexes/my-frontend-observer-v0.9.1-20260922T070928-v010-batch1`
+- Command: `my-dev-kit index --root C:\Users\daile\Projects\my-frontend-observer --src src --src viewer/src --src tests --src scripts --out <index> --call-graph --json`
+- Roots: `src`, `viewer/src`, `tests`, `scripts`
+- Summary: 162 files, 1,606 symbols, 3,471 edges, zero index-level warnings/errors.
+- Partial analyzers: data-model (758 warnings) and classification (1,568 warnings). Syntax, call graph, frontend semantic, and frontend reachability completed.
+
+Canonical precedents confirmed:
+
+- `src/domain/visualAnnotation.ts` and `visualAnnotationIdentity.ts`: closed validation, sorted-key canonical JSON, SHA-256 request identity, nonce-backed instance identity, producer/provenance, and forward supersession.
+- `src/domain/externalReference.ts`, `externalReferenceIdentity.ts`, and `frontendContractIdentity.ts`: exact request/instance and immutable supersession conventions.
+- `src/domain/externalReferenceRuntimeBinding.ts`: the exact reusable explicit binding declaration type and its identifier, bound, and duplicate semantics.
+- `src/artifacts/visualAnnotationArtifactWriter.ts` and reader: sibling temporary directory, overwrite refusal, cleanup, manifest/media digest validation, and atomic rename.
+- `src/projectWorkflow/projectPaths.ts`: the project evidence-root/path owner.
+- `src/viewerServer/evidence/classify.ts`, `index.ts`, `projection.ts`, `handles.ts`, and `annotationView.ts`: the existing support-state classifier, metadata-first index, safe handles, bounded exact identity lookup, and honest unavailable projection.
+- Existing `EvidenceReference` is structured evaluation provenance and explicitly is not a filesystem reference. Therefore a small workflow-owned project-relative artifact reference was required; no generalized cross-project framework was added.
+
+Full source/test file reads: none.
+
+## 4. Production implementation
+
+Created:
+
+- `src/domain/visualChangeWorkflow.ts`
+- `src/domain/visualChangeWorkflowIdentity.ts`
+- `src/artifacts/visualChangeWorkflowArtifactWriter.ts`
+- `src/artifacts/visualChangeWorkflowArtifactReader.ts`
+- `src/application/visualChangeWorkflowPersistenceService.ts`
+- `src/viewerServer/evidence/visualChangeWorkflowView.ts`
+
+Modified:
+
+- `src/projectWorkflow/projectPaths.ts`
+- `src/viewerServer/evidence/classify.ts`
+- `src/viewerServer/evidence/handles.ts`
+- `src/viewerServer/evidence/projection.ts`
+- `src/index.ts`
+- `docs/CONTRACTS.md`
+
+The artifact kind is exactly `my-frontend-observer/visual-change-workflow`; schema is exactly `1.0.0`; attempts are bounded at 20. The closed domain union contains the two frozen entry modes, exact evidence references, check snapshots, coordination metadata, review state, activation, and governance-result references.
+
+Request identity is deterministic over semantic evidence identities and binding content. Storage paths, timestamps, output roots, temp roots, Viewer handles/ports, and coordination filesystem details are excluded. Workflow instance IDs are fresh. Attempt IDs hash request ID plus candidate observation ID. Revisions use `supersedesVisualChangeWorkflowId`; parents are never rewritten.
+
+The writer validates, refuses existing final output, uses `.tmp-<workflowId>`, writes canonical bindings when required, verifies its digest, writes the manifest, and atomically renames. The reader checks kind/version/domain validity, exact `bindings.json` path, regular-file status, SHA-256, canonical bytes, declaration equality, and count. No referenced artifact or media is copied.
+
+Discovery classifies the new family through the existing support-state machinery. Metadata includes workflow/request identity, mode, baseline, annotation, selected reference, attempt count, latest check/review state, and supersession without embedding attempts. The read projection resolves exact identities using canonical classification and returns explicit unavailable state for missing or ambiguous links.
+
+## 5. Tests
+
+Created `tests/unit/visualChangeWorkflow.test.ts`. Its ten focused cases protect:
+
+1. minimal actual/reference validation, closed shapes, wrong kind, and unsupported schema;
+2. request identity determinism and semantic-scope changes, including operational path exclusion;
+3. fresh workflow identity and deterministic attempt identity invariants;
+4. attempt bounds, revision lineage, path safety, and review vocabulary;
+5. actual-mode round trip, absent bindings file, and overwrite refusal;
+6. deterministic bindings bytes, digest/count round trip, and tamper rejection;
+7. temporary-output cleanup on injected failure;
+8. same-request/different-instance persistence and byte-immutable parent revision;
+9. supported classification and bounded index metadata;
+10. exact linked-evidence resolution and honest missing evidence.
+
+Existing focused annotation, external-reference, contract, and discovery suites remained unchanged and passed.
+
+## 6. Validation
+
+- `npm run typecheck`: PASS.
+- `npm run lint`: PASS after removal of one unused import.
+- Focused five-file Vitest run: PASS, 51 tests.
+- `npm test`: PASS.
+- `npm run build`: PASS.
+- `npm run check:docs`: PASS.
+- `git diff --check`: PASS.
+
+Existing constants remain 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`, and Viewer protocol `1.3.0`.
+
+## 7. Exclusions and risk
+
+No project activation/restoration, live `checkProject` mapping, Viewer UI/POST routes, entry-mode UI, handoff, orchestrator execution, rerender/correction loop, acceptance action, governance operation, tutorial, version bump, or release work was implemented.
+
+Remaining risk is limited to later-batch composition: Batch 2 must map canonical `CheckWorkflowResult` into the frozen snapshot, activate/restore project acceptance explicitly, and record attempts without scope drift. Batch 1 deliberately does not enforce accepted-requires-PASS.
+
+## 8. Batch 2 handoff
+
+Start from this Batch 1 commit. Reuse `persistVisualChangeWorkflow`, `readVisualChangeWorkflowArtifact`, `buildVisualChangeAttemptIdentity`, `visualChangeOutputLocation`, and the existing `checkProject` owner. Implement only explicit acceptance activation/restore and canonical check-to-snapshot attempt recording, preserving all Batch 1 identities and schema `1.0.0`.
+
+Generated state is confined to `.my-dev-kit-workflow/` and `.my-dev-kit-context/`; neither path is staged.

package/docs/reports/v0.10-batch2-project-composition-check-recording.md

@@ -1,103 +1,103 @@
-# v0.10 Batch 2 Project Composition and Check Recording
-
-## 1. Verdict
-
-PASS. Batch 2 project composition, explicit activation and restoration, drift gates, canonical project-check reuse, and immutable attempt recording are implemented.
-
-## 2. Repository and Git state
-
-- Repository: `C:\Users\daile\Projects\my-frontend-observer`
-- Starting commit: `62c4df47dd278c1fbd431824ca6e773366f1d1fb`
-- Branch: `feature/v0.10-full-visual-workflow`
-- Commit message: `feat: add v0.10 project visual change composition`
-
-The preflight worktree was clean. Local and remote shared branches both pointed to the authoritative Batch 1 commit.
-
-## 3. my-dev-kit retrieval
-
-- Resolved published version: `1.12.3`
-- Install: `.my-dev-kit-workflow/tools/v0.10-batch2/`
-- CLI version: `1.12.3`
-- Verified commands: `index`, `search`, `lookup`, `slice`, `source`, `graph-diff`, and `context`
-- Fresh index: `.my-dev-kit-context/indexes/my-frontend-observer-v0.10-batch2-20260922`
-- Exact index command: `node .my-dev-kit-workflow/tools/v0.10-batch2/node_modules/@dailephd/my-dev-kit/dist/cli.js index --root C:\Users\daile\Projects\my-frontend-observer --src src --src viewer/src --src tests --src scripts --out C:\Users\daile\Projects\my-frontend-observer\.my-dev-kit-context\indexes\my-frontend-observer-v0.10-batch2-20260922 --call-graph --json`
-- Index summary: 168 files, 1,669 symbols, 3,581 edges, zero index-level warnings or errors.
-- Complete analyzers: syntax, call graph, frontend semantic, frontend reachability.
-- Partial analyzers: data model with 790 warnings; classification with 1,621 warnings.
-- Skipped/not-run analyzers were Android-specific and model-view lineage.
-
-Retrieval used search, lookup, slice, exact symbol source, local dependency expansion, bounded file ranges, and continuation markers. It verified `activateProjectChangeContract`, `FrontendObserverAcceptanceConfig`, `checkProject`, `CheckWorkflowResult`, the alias catalog, canonical observation/contract/reference readers, `persistVisualChangeWorkflow`, `readVisualChangeWorkflowArtifact`, and `buildVisualChangeAttemptIdentity`.
-
-## 4. Reused owners
-
-- `src/application/projectWorkflowService.ts`: existing atomic activation precedent; unchanged behavior.
-- `src/projectWorkflow/projectConfig.ts`: unchanged project schema and validation.
-- `src/projectWorkflow/aliasCatalog.ts`: exact baseline alias identity and location.
-- `src/application/projectCheckService.ts`: sole capture, comparison, contract, reference, blocker, and final-status owner.
-- `src/projectWorkflow/checkResult.ts`: canonical bounded result fields and truncation.
-- Canonical artifact readers for observations, annotations, baseline/change contracts, external references, and visual-change workflows.
-- `src/application/visualChangeWorkflowPersistenceService.ts`: all new immutable workflow revisions.
-- `src/domain/visualChangeWorkflowIdentity.ts`: existing attempt identity helper.
-
-## 5. Application service
-
-Created `src/application/visualChangeProjectWorkflowService.ts`. It exports project-aware create/freeze, activation, restoration, canonical check recording, and the pure snapshot mapper. `src/index.ts` exposes the application surface through the established public convention.
-
-Create/freeze validates the project configuration and every referenced project-contained artifact. It checks baseline observation ID, request ID, and path, annotation identity, optional baseline-contract identity, actual-mode change-contract identity/request identity, and reference identity/request identity. It persists through the Batch 1 owner without activation, attempts, or project-config mutation.
-
-## 6. Activation and rollback
-
-Actual activation requires an existing contract block, exact frozen baseline-contract path and identity, and exact change-contract evidence. It changes only `acceptance.contract.changeArtifact`.
-
-Reference activation requires an existing reference block, the exact frozen approved reference, reader-verified workflow bindings, and contract/baseline consistency. It changes only the approved reference artifact and the source workflow's project-relative `bindings.json`.
-
-Both modes snapshot all represented mutable acceptance selection fields. They atomically write a validated updated configuration and then persist a new workflow revision with the same request ID, unchanged attempts/governance data, activation before/after/activatedAt, and forward supersession. A persistence failure restores the exact original config bytes. A failed compensation returns distinct `partial-state-failure` language stating manual repair may be required.
-
-## 7. Restore
-
-Restore requires a live activation and exact equality with `activation.after`. Drift is non-mutating. Actual restore changes only the prior change-contract selection. Reference restore restores the prior reference and exact optional bindings presence/value. The successful immutable revision adds only `restoredAt` and forward supersession. Persistence failure compensates back to the exact activated configuration.
-
-## 8. Baseline and drift rules
-
-Baseline resolution first prefers `defaultBaseline` only when observation ID, request ID, and exact project-relative artifact location all match. Otherwise it chooses the lexicographically first exact matching alias. No exact alias returns `baseline-drift` before `checkProject`.
-
-The pre-check gate requires a valid active non-restored workflow, exact acceptance selection, exact baseline, exact baseline/change contract identities where active, exact approved reference identity, exact bindings selection, and reader-verified frozen bindings bytes. Represented changes return `acceptance-drift` or `baseline-drift` without evaluation.
-
-## 9. Canonical check and snapshot
-
-The service calls only `checkProject(projectRoot, resolvedAlias)`. The pure mapper directly projects status, baseline/candidate IDs, complete comparison/evaluation references, verified active contract IDs, canonical reference ID/fidelity state, ordered failed/unavailable clause and requirement IDs, bounded unexpected-change count, and blockers. Blockers are capped at 50. Snapshot truncation combines canonical overall, contract, reference, and blocker projection truncation.
-
-A result without both baseline and candidate is returned as `candidate-not-produced` and is not recorded. Post-check baseline or reference mismatch returns `check-scope-mismatch`.
-
-## 10. Attempt persistence
-
-Candidate identity/path comes only from the canonical result and is containment checked. Attempt identity uses `buildVisualChangeAttemptIdentity`. New attempts are pending, timestamped, and link to the immediately prior attempt. Duplicate IDs and a twenty-first attempt are rejected without truncation. Persistence produces a new revision with identical scope/request identity and immutable parent bytes. Persistence failure retains canonical check evidence and reports that history was not updated.
-
-## 11. Tests and validation
-
-Created `tests/unit/visualChangeProjectWorkflowService.test.ts`. It covers direct PASS/FAIL/BLOCKED/REVIEW_REQUIRED projection, comparison/evaluation references, clause and reference-requirement ordering, bounded unexpected changes, blocker bounds, canonical truncation, create-without-activation, immutable activation and restore revisions, rollback after persistence failure, and one-call canonical check recording of a pending candidate attempt. Real application tests use canonical artifact writers/readers.
-
-Focused validation: 3 files, 25 tests, PASS. This includes the new service, existing Batch 1 visual-change workflow, and existing project check tests.
-
-Full validation:
-
-- `npm run typecheck`: PASS.
-- `npm run lint`: PASS.
-- `npm test`: PASS, 91 files and 1,477 tests.
-- `npm run build`: PASS.
-- `npm run check:docs`: PASS.
-- `git diff --check`: PASS.
-
-Existing `activateProjectChangeContract`, `checkProject`, Batch 1 workflow behavior, schema constants, and Viewer protocol remain unchanged and pass the full suite.
-
-## 12. Full-file read accounting
-
-Full source/test file reads: none. my-dev-kit bounded retrieval supplied every required implementation shape. Its symbol index lacks reliable symbol end lines for some declarations, so continuation markers and bounded explicit file ranges were used instead of whole-file reads. Canonical documentation reads are excluded by task rule.
-
-## 13. Exclusions and handoff
-
-No Viewer workspace, POST route, annotation UI composition, coding-agent handoff, orchestrator integration, automatic retry, correction action, human acceptance, governance approval, version bump, release, tag, publication, or PR work was implemented.
-
-Batch 3 should start from this commit and add only the secure project-aware Viewer workspace/API specified by the frozen plan. It can call this application service without reconstructing activation, drift, check, snapshot, or attempt semantics.
-
-Generated state is confined to `.my-dev-kit-workflow/` and `.my-dev-kit-context/`. Neither path is staged.
+# v0.10 Batch 2 Project Composition and Check Recording
+
+## 1. Verdict
+
+PASS. Batch 2 project composition, explicit activation and restoration, drift gates, canonical project-check reuse, and immutable attempt recording are implemented.
+
+## 2. Repository and Git state
+
+- Repository: `C:\Users\daile\Projects\my-frontend-observer`
+- Starting commit: `62c4df47dd278c1fbd431824ca6e773366f1d1fb`
+- Branch: `feature/v0.10-full-visual-workflow`
+- Commit message: `feat: add v0.10 project visual change composition`
+
+The preflight worktree was clean. Local and remote shared branches both pointed to the authoritative Batch 1 commit.
+
+## 3. my-dev-kit retrieval
+
+- Resolved published version: `1.12.3`
+- Install: `.my-dev-kit-workflow/tools/v0.10-batch2/`
+- CLI version: `1.12.3`
+- Verified commands: `index`, `search`, `lookup`, `slice`, `source`, `graph-diff`, and `context`
+- Fresh index: `.my-dev-kit-context/indexes/my-frontend-observer-v0.10-batch2-20260922`
+- Exact index command: `node .my-dev-kit-workflow/tools/v0.10-batch2/node_modules/@dailephd/my-dev-kit/dist/cli.js index --root C:\Users\daile\Projects\my-frontend-observer --src src --src viewer/src --src tests --src scripts --out C:\Users\daile\Projects\my-frontend-observer\.my-dev-kit-context\indexes\my-frontend-observer-v0.10-batch2-20260922 --call-graph --json`
+- Index summary: 168 files, 1,669 symbols, 3,581 edges, zero index-level warnings or errors.
+- Complete analyzers: syntax, call graph, frontend semantic, frontend reachability.
+- Partial analyzers: data model with 790 warnings; classification with 1,621 warnings.
+- Skipped/not-run analyzers were Android-specific and model-view lineage.
+
+Retrieval used search, lookup, slice, exact symbol source, local dependency expansion, bounded file ranges, and continuation markers. It verified `activateProjectChangeContract`, `FrontendObserverAcceptanceConfig`, `checkProject`, `CheckWorkflowResult`, the alias catalog, canonical observation/contract/reference readers, `persistVisualChangeWorkflow`, `readVisualChangeWorkflowArtifact`, and `buildVisualChangeAttemptIdentity`.
+
+## 4. Reused owners
+
+- `src/application/projectWorkflowService.ts`: existing atomic activation precedent; unchanged behavior.
+- `src/projectWorkflow/projectConfig.ts`: unchanged project schema and validation.
+- `src/projectWorkflow/aliasCatalog.ts`: exact baseline alias identity and location.
+- `src/application/projectCheckService.ts`: sole capture, comparison, contract, reference, blocker, and final-status owner.
+- `src/projectWorkflow/checkResult.ts`: canonical bounded result fields and truncation.
+- Canonical artifact readers for observations, annotations, baseline/change contracts, external references, and visual-change workflows.
+- `src/application/visualChangeWorkflowPersistenceService.ts`: all new immutable workflow revisions.
+- `src/domain/visualChangeWorkflowIdentity.ts`: existing attempt identity helper.
+
+## 5. Application service
+
+Created `src/application/visualChangeProjectWorkflowService.ts`. It exports project-aware create/freeze, activation, restoration, canonical check recording, and the pure snapshot mapper. `src/index.ts` exposes the application surface through the established public convention.
+
+Create/freeze validates the project configuration and every referenced project-contained artifact. It checks baseline observation ID, request ID, and path, annotation identity, optional baseline-contract identity, actual-mode change-contract identity/request identity, and reference identity/request identity. It persists through the Batch 1 owner without activation, attempts, or project-config mutation.
+
+## 6. Activation and rollback
+
+Actual activation requires an existing contract block, exact frozen baseline-contract path and identity, and exact change-contract evidence. It changes only `acceptance.contract.changeArtifact`.
+
+Reference activation requires an existing reference block, the exact frozen approved reference, reader-verified workflow bindings, and contract/baseline consistency. It changes only the approved reference artifact and the source workflow's project-relative `bindings.json`.
+
+Both modes snapshot all represented mutable acceptance selection fields. They atomically write a validated updated configuration and then persist a new workflow revision with the same request ID, unchanged attempts/governance data, activation before/after/activatedAt, and forward supersession. A persistence failure restores the exact original config bytes. A failed compensation returns distinct `partial-state-failure` language stating manual repair may be required.
+
+## 7. Restore
+
+Restore requires a live activation and exact equality with `activation.after`. Drift is non-mutating. Actual restore changes only the prior change-contract selection. Reference restore restores the prior reference and exact optional bindings presence/value. The successful immutable revision adds only `restoredAt` and forward supersession. Persistence failure compensates back to the exact activated configuration.
+
+## 8. Baseline and drift rules
+
+Baseline resolution first prefers `defaultBaseline` only when observation ID, request ID, and exact project-relative artifact location all match. Otherwise it chooses the lexicographically first exact matching alias. No exact alias returns `baseline-drift` before `checkProject`.
+
+The pre-check gate requires a valid active non-restored workflow, exact acceptance selection, exact baseline, exact baseline/change contract identities where active, exact approved reference identity, exact bindings selection, and reader-verified frozen bindings bytes. Represented changes return `acceptance-drift` or `baseline-drift` without evaluation.
+
+## 9. Canonical check and snapshot
+
+The service calls only `checkProject(projectRoot, resolvedAlias)`. The pure mapper directly projects status, baseline/candidate IDs, complete comparison/evaluation references, verified active contract IDs, canonical reference ID/fidelity state, ordered failed/unavailable clause and requirement IDs, bounded unexpected-change count, and blockers. Blockers are capped at 50. Snapshot truncation combines canonical overall, contract, reference, and blocker projection truncation.
+
+A result without both baseline and candidate is returned as `candidate-not-produced` and is not recorded. Post-check baseline or reference mismatch returns `check-scope-mismatch`.
+
+## 10. Attempt persistence
+
+Candidate identity/path comes only from the canonical result and is containment checked. Attempt identity uses `buildVisualChangeAttemptIdentity`. New attempts are pending, timestamped, and link to the immediately prior attempt. Duplicate IDs and a twenty-first attempt are rejected without truncation. Persistence produces a new revision with identical scope/request identity and immutable parent bytes. Persistence failure retains canonical check evidence and reports that history was not updated.
+
+## 11. Tests and validation
+
+Created `tests/unit/visualChangeProjectWorkflowService.test.ts`. It covers direct PASS/FAIL/BLOCKED/REVIEW_REQUIRED projection, comparison/evaluation references, clause and reference-requirement ordering, bounded unexpected changes, blocker bounds, canonical truncation, create-without-activation, immutable activation and restore revisions, rollback after persistence failure, and one-call canonical check recording of a pending candidate attempt. Real application tests use canonical artifact writers/readers.
+
+Focused validation: 3 files, 25 tests, PASS. This includes the new service, existing Batch 1 visual-change workflow, and existing project check tests.
+
+Full validation:
+
+- `npm run typecheck`: PASS.
+- `npm run lint`: PASS.
+- `npm test`: PASS, 91 files and 1,477 tests.
+- `npm run build`: PASS.
+- `npm run check:docs`: PASS.
+- `git diff --check`: PASS.
+
+Existing `activateProjectChangeContract`, `checkProject`, Batch 1 workflow behavior, schema constants, and Viewer protocol remain unchanged and pass the full suite.
+
+## 12. Full-file read accounting
+
+Full source/test file reads: none. my-dev-kit bounded retrieval supplied every required implementation shape. Its symbol index lacks reliable symbol end lines for some declarations, so continuation markers and bounded explicit file ranges were used instead of whole-file reads. Canonical documentation reads are excluded by task rule.
+
+## 13. Exclusions and handoff
+
+No Viewer workspace, POST route, annotation UI composition, coding-agent handoff, orchestrator integration, automatic retry, correction action, human acceptance, governance approval, version bump, release, tag, publication, or PR work was implemented.
+
+Batch 3 should start from this commit and add only the secure project-aware Viewer workspace/API specified by the frozen plan. It can call this application service without reconstructing activation, drift, check, snapshot, or attempt semantics.
+
+Generated state is confined to `.my-dev-kit-workflow/` and `.my-dev-kit-context/`. Neither path is staged.

package/docs/reports/v0.10-batch3-viewer-visual-change-workspace.md

@@ -1,93 +1,93 @@
-# v0.10 Batch 3 Viewer Visual-Change Workspace
-
-## 1. Verdict and repository
-
-PASS.
-
-- Repository: `C:\Users\daile\Projects\my-frontend-observer`
-- Starting commit: `a7613d7520ca77523514daae3632dbe579e68cf7`
-- Branch: `feature/v0.10-full-visual-workflow`
-- Commit message: `feat: add v0.10 visual change viewer workspace`
-
-## 2. Retrieval and tooling
-
-- Latest published my-dev-kit: `1.12.3`
-- Local install: `.my-dev-kit-workflow/tools/v0.10-batch3/`
-- Fresh index: `.my-dev-kit-context/indexes/my-frontend-observer-v0.10-batch3-20260922`
-- Command: `node C:\Users\daile\Projects\my-frontend-observer\.my-dev-kit-workflow\tools\v0.10-batch3\node_modules\@dailephd\my-dev-kit\dist\cli.js index --root C:\Users\daile\Projects\my-frontend-observer --src src --src viewer/src --src tests --src scripts --out C:\Users\daile\Projects\my-frontend-observer\.my-dev-kit-context\indexes\my-frontend-observer-v0.10-batch3-20260922 --call-graph --json`
-- Summary: 169 files, 1,700 symbols, 3,639 edges, zero index warnings/errors.
-- Complete: syntax, call graph, frontend semantic, frontend reachability.
-- Partial: data model, 802 warnings; classification, 1,647 warnings.
-
-Bounded search, lookup, slice, exact symbol source, dependency expansion, continuation, and line ranges verified the one HTTP dispatcher, shared authoring gate, project-aware startup, annotation adapter precedent, memory-only authoring hook, explicit mutation hooks, top-level shell, workflow projection, index metadata, and Batch 2 application owner.
-
-## 3. Server surface
-
-Created `src/viewerServer/visualChangeAuthoring.ts` and extended the existing `httpServer.ts` dispatcher with exactly:
-
-- `GET /api/visual-changes/:handle/view`
-- `POST /api/visual-changes`
-- `POST /api/visual-changes/:handle/activate`
-- `POST /api/visual-changes/:handle/check`
-- `POST /api/visual-changes/:handle/restore-acceptance`
-
-No handoff or review route exists. GET uses `getVisualChangeWorkflowView`. Handle mutations resolve one supported workflow through the existing safe handle boundary and never accept paths. Create accepts exactly `{scope}`; mutation bodies accept exactly `{}`.
-
-The frozen failure mapping is 409 for activation/state/drift/scope/candidate/duplicate/limit/config conflicts, 422 for invalid workflows/references, and 500 for write/persistence/partial-state failures. Candidate-not-produced retains the canonical check body. Partial-state wording comes unchanged from the application service.
-
-Every POST passes through `readAuthoringJsonRequest`, which reuses exact Host, Origin, in-memory token, JSON content type, no-compression, and 256 KiB body guards. Standalone state has no authoring session and fails closed before application calls. All responses use `Cache-Control: no-store`.
-
-## 4. Viewer workspace
-
-The existing shell now has Evidence, Bounded context, and Visual changes modes using native `aria-pressed` buttons. `VisualChangeWorkspace` filters `/api/index` metadata to workflow records, loads only the exact selected handle, and shows bounded summary fields, all stored attempts in order, and honest linked-evidence availability. Available linked evidence navigates through its exact supported handle.
-
-Project-aware sessions expose only Activate, Run check, and Restore acceptance with server-authoritative eligibility. Check has a disabled `Running check…` pending state. There is no retry, automatic restore, review, handoff, approval, or coding-agent control. Standalone and capability-error sessions retain inspection and omit mutations.
-
-The action hook keeps the token only as an argument from the existing memory-only session hook. Mutation success explicitly refreshes `/api/index`, finds the exact returned workflow ID, and selects only that supported revision. Missing exact revisions produce a warning rather than fuzzy selection.
-
-The workspace uses keyboard-operable native controls, semantic lists and definition lists, textual status, `aria-live` mutation feedback, disabled states, and no focus trap.
-
-## 5. Leakage and protocol audit
-
-New success responses contain workflow/request IDs and bounded canonical evidence only. They expose no project root, absolute manifest/bindings/temp path, token, stack trace, or orchestrator path. Tests verify error output does not contain the project root and browser storage/visible text do not contain the token mechanism.
-
-`VIEWER_PROTOCOL_VERSION` remains exactly `1.3.0`; `/api/status` behavior is unchanged. The service worker continues to exclude `/api/` responses.
-
-## 6. Tests and validation
-
-Created:
-
-- `tests/unit/visualChangeAuthoring.test.ts`
-- `tests/unit/viewerVisualChangeAuthoring.test.ts`
-- `tests/browser/visualChangeWorkspace.test.ts`
-
-These cover closed parsers, frozen failure mapping, supported/unknown/wrong-family GET handling, standalone GET/read-only behavior, project-only POSTs, Host/Origin/token/content-type/compression/body bounds, no-store, path leakage, the third navigation mode, aria-pressed and keyboard operation, common actual-mode identities, honest unavailable links, read-only versus project-aware actions, prohibited later-batch actions, and browser storage/token visibility.
-
-Validation:
-
-- Focused unit/application tests: PASS.
-- `npm run typecheck`: PASS.
-- `npm run lint`: PASS.
-- `npm test`: PASS.
-- `npm run test:browser`: PASS.
-- `npm run test:security`: PASS.
-- `npm run test:pwa-hard-gate`: PASS.
-- `npm run build`: PASS.
-- `npm run check:docs`: PASS.
-- `git diff --check`: PASS.
-
-The initial browser command failed before meaningful assertions because the isolated project-local Playwright directory had no Chromium. Playwright Chromium 151.0.7922.34 was installed under `.my-dev-kit-workflow/playwright-browsers`, after which the complete browser gate passed.
-
-Existing annotation save, contract promotion, reference materialization, authoring security, standalone read-only mode, Evidence, Bounded context, Batch 1, and Batch 2 suites remain passing.
-
-## 7. Full-file read accounting
-
-Full source/test file reads: none. Bounded my-dev-kit retrieval provided the necessary route, security, startup, projection, hook, component, and test precedent. Where symbol end lines were unavailable, explicit bounded ranges and continuation markers supplied the missing local context.
-
-## 8. Exclusions and Batch 4 handoff
-
-No actual/reference entry composition, annotation-to-workflow creation UI, reference selection, binding authoring, handoff, orchestrator integration, retry loop, review/correction/acceptance, baseline/reference governance, version bump, release, PR, or publication was implemented.
-
-Batch 4 can add the actual-frontend entry workflow inside the existing Visual changes shell and call the already-secured create/activate boundaries. It must not replace the Batch 2 application service or Batch 3 security/reselection mechanisms.
-
-Generated tool, index, browser, cache, and temporary state remains beneath `.my-dev-kit-workflow/` and `.my-dev-kit-context/` and is not staged.
+# v0.10 Batch 3 Viewer Visual-Change Workspace
+
+## 1. Verdict and repository
+
+PASS.
+
+- Repository: `C:\Users\daile\Projects\my-frontend-observer`
+- Starting commit: `a7613d7520ca77523514daae3632dbe579e68cf7`
+- Branch: `feature/v0.10-full-visual-workflow`
+- Commit message: `feat: add v0.10 visual change viewer workspace`
+
+## 2. Retrieval and tooling
+
+- Latest published my-dev-kit: `1.12.3`
+- Local install: `.my-dev-kit-workflow/tools/v0.10-batch3/`
+- Fresh index: `.my-dev-kit-context/indexes/my-frontend-observer-v0.10-batch3-20260922`
+- Command: `node C:\Users\daile\Projects\my-frontend-observer\.my-dev-kit-workflow\tools\v0.10-batch3\node_modules\@dailephd\my-dev-kit\dist\cli.js index --root C:\Users\daile\Projects\my-frontend-observer --src src --src viewer/src --src tests --src scripts --out C:\Users\daile\Projects\my-frontend-observer\.my-dev-kit-context\indexes\my-frontend-observer-v0.10-batch3-20260922 --call-graph --json`
+- Summary: 169 files, 1,700 symbols, 3,639 edges, zero index warnings/errors.
+- Complete: syntax, call graph, frontend semantic, frontend reachability.
+- Partial: data model, 802 warnings; classification, 1,647 warnings.
+
+Bounded search, lookup, slice, exact symbol source, dependency expansion, continuation, and line ranges verified the one HTTP dispatcher, shared authoring gate, project-aware startup, annotation adapter precedent, memory-only authoring hook, explicit mutation hooks, top-level shell, workflow projection, index metadata, and Batch 2 application owner.
+
+## 3. Server surface
+
+Created `src/viewerServer/visualChangeAuthoring.ts` and extended the existing `httpServer.ts` dispatcher with exactly:
+
+- `GET /api/visual-changes/:handle/view`
+- `POST /api/visual-changes`
+- `POST /api/visual-changes/:handle/activate`
+- `POST /api/visual-changes/:handle/check`
+- `POST /api/visual-changes/:handle/restore-acceptance`
+
+No handoff or review route exists. GET uses `getVisualChangeWorkflowView`. Handle mutations resolve one supported workflow through the existing safe handle boundary and never accept paths. Create accepts exactly `{scope}`; mutation bodies accept exactly `{}`.
+
+The frozen failure mapping is 409 for activation/state/drift/scope/candidate/duplicate/limit/config conflicts, 422 for invalid workflows/references, and 500 for write/persistence/partial-state failures. Candidate-not-produced retains the canonical check body. Partial-state wording comes unchanged from the application service.
+
+Every POST passes through `readAuthoringJsonRequest`, which reuses exact Host, Origin, in-memory token, JSON content type, no-compression, and 256 KiB body guards. Standalone state has no authoring session and fails closed before application calls. All responses use `Cache-Control: no-store`.
+
+## 4. Viewer workspace
+
+The existing shell now has Evidence, Bounded context, and Visual changes modes using native `aria-pressed` buttons. `VisualChangeWorkspace` filters `/api/index` metadata to workflow records, loads only the exact selected handle, and shows bounded summary fields, all stored attempts in order, and honest linked-evidence availability. Available linked evidence navigates through its exact supported handle.
+
+Project-aware sessions expose only Activate, Run check, and Restore acceptance with server-authoritative eligibility. Check has a disabled `Running check…` pending state. There is no retry, automatic restore, review, handoff, approval, or coding-agent control. Standalone and capability-error sessions retain inspection and omit mutations.
+
+The action hook keeps the token only as an argument from the existing memory-only session hook. Mutation success explicitly refreshes `/api/index`, finds the exact returned workflow ID, and selects only that supported revision. Missing exact revisions produce a warning rather than fuzzy selection.
+
+The workspace uses keyboard-operable native controls, semantic lists and definition lists, textual status, `aria-live` mutation feedback, disabled states, and no focus trap.
+
+## 5. Leakage and protocol audit
+
+New success responses contain workflow/request IDs and bounded canonical evidence only. They expose no project root, absolute manifest/bindings/temp path, token, stack trace, or orchestrator path. Tests verify error output does not contain the project root and browser storage/visible text do not contain the token mechanism.
+
+`VIEWER_PROTOCOL_VERSION` remains exactly `1.3.0`; `/api/status` behavior is unchanged. The service worker continues to exclude `/api/` responses.
+
+## 6. Tests and validation
+
+Created:
+
+- `tests/unit/visualChangeAuthoring.test.ts`
+- `tests/unit/viewerVisualChangeAuthoring.test.ts`
+- `tests/browser/visualChangeWorkspace.test.ts`
+
+These cover closed parsers, frozen failure mapping, supported/unknown/wrong-family GET handling, standalone GET/read-only behavior, project-only POSTs, Host/Origin/token/content-type/compression/body bounds, no-store, path leakage, the third navigation mode, aria-pressed and keyboard operation, common actual-mode identities, honest unavailable links, read-only versus project-aware actions, prohibited later-batch actions, and browser storage/token visibility.
+
+Validation:
+
+- Focused unit/application tests: PASS.
+- `npm run typecheck`: PASS.
+- `npm run lint`: PASS.
+- `npm test`: PASS.
+- `npm run test:browser`: PASS.
+- `npm run test:security`: PASS.
+- `npm run test:pwa-hard-gate`: PASS.
+- `npm run build`: PASS.
+- `npm run check:docs`: PASS.
+- `git diff --check`: PASS.
+
+The initial browser command failed before meaningful assertions because the isolated project-local Playwright directory had no Chromium. Playwright Chromium 151.0.7922.34 was installed under `.my-dev-kit-workflow/playwright-browsers`, after which the complete browser gate passed.
+
+Existing annotation save, contract promotion, reference materialization, authoring security, standalone read-only mode, Evidence, Bounded context, Batch 1, and Batch 2 suites remain passing.
+
+## 7. Full-file read accounting
+
+Full source/test file reads: none. Bounded my-dev-kit retrieval provided the necessary route, security, startup, projection, hook, component, and test precedent. Where symbol end lines were unavailable, explicit bounded ranges and continuation markers supplied the missing local context.
+
+## 8. Exclusions and Batch 4 handoff
+
+No actual/reference entry composition, annotation-to-workflow creation UI, reference selection, binding authoring, handoff, orchestrator integration, retry loop, review/correction/acceptance, baseline/reference governance, version bump, release, PR, or publication was implemented.
+
+Batch 4 can add the actual-frontend entry workflow inside the existing Visual changes shell and call the already-secured create/activate boundaries. It must not replace the Batch 2 application service or Batch 3 security/reselection mechanisms.
+
+Generated tool, index, browser, cache, and temporary state remains beneath `.my-dev-kit-workflow/` and `.my-dev-kit-context/` and is not staged.