@dailephd/my-frontend-observer 0.9.1 → 0.10.0

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

@@ -0,0 +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.

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

@@ -0,0 +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.

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

@@ -0,0 +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.

package/docs/reports/v0.10-batch4-actual-frontend-entry.md

@@ -0,0 +1,59 @@
+# v0.10 Batch 4 Actual-Frontend Entry
+
+## 1. Verdict and repository
+
+PASS.
+
+- Repository: `C:\Users\daile\Projects\my-frontend-observer`
+- Original blocked starting commit: `a2d0cbd264516173355cd950f1319532d0b95e39`
+- Planner clarification commit: `8451869ed235cfab802872edc581418162cbf678`
+- Implementation commit: the commit containing this report, with message `feat: add v0.10 actual frontend visual change flow`; its final hash is recorded in the execution handoff.
+- Branch: `feature/v0.10-full-visual-workflow`
+
+## 2. Planner correction and retrieval
+
+The original TST-B4-059 incorrectly expected equivalent repeated starts to retain one visual-change request identity. Canonical promotion deliberately creates a fresh contract instance, and Batch 1 request identity freezes that instance. The plan now records that repeated equivalent starts retain deterministic `contractRequestId` while producing different `contractId`, `visualChangeRequestId`, and `visualChangeWorkflowId`. No identity implementation or schema changed.
+
+- Latest published my-dev-kit: `1.12.3`
+- Install: `.my-dev-kit-workflow/tools/v0.10-batch4-resumed/`
+- Fresh index: `.my-dev-kit-context/indexes/my-frontend-observer-v0.10-batch4-resumed-20260922`
+- Exact command: `node C:\Users\daile\Projects\my-frontend-observer\.my-dev-kit-workflow\tools\v0.10-batch4-resumed\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-batch4-resumed-20260922 --call-graph --json`
+- Index: 173 files, 1,726 symbols, 3,763 edges, no index-level warnings or errors. Data-model and classification analyzers remained partial with 812 and 1,673 warnings respectively; syntax, call graph, frontend semantic, and frontend reachability were complete.
+
+Retrieval verified runtime draft/save ownership, explicit association and confirmation, canonical promotion eligibility, baseline reading, exact alias records, Batch 2 creation/activation, Batch 3 refresh/reselection, and the corrected identity hierarchy.
+
+## 3. Server composition
+
+`runtimeVisualChangeAuthoring.ts` implements the one project-aware composition adapter. `POST /api/annotations/:handle/start-visual-change` accepts only `{ itemIds }`, uses the shared Host, Origin, token, content-type, compression, body-size, no-store, and serialized-write boundaries, and fails closed in standalone mode.
+
+Before promotion it resolves the supported saved runtime annotation, exact source observation, valid project config, configured valid persistent baseline contract, and an alias whose observation ID, request ID, and exact evidence-relative directory all match. It then calls `promoteVisualAnnotationContract` exactly once with the configured baseline ID. The adapter never calls legacy activation and project acceptance remains byte-identical.
+
+The resulting `VisualChangeActualScope` freezes project-relative contained paths and canonical identities for the annotation, source observation, persistent baseline contract, and newly promoted contract. Creation delegates to `createProjectVisualChangeWorkflow`. A post-promotion workflow failure retains the immutable contract and returns bounded contract IDs with honest failure wording.
+
+## 4. Viewer workflow
+
+The existing runtime promotion selection now drives both legacy promotion and the distinct Create visual change action. Saved, clean, selected, confirmed promotable intent is required. Candidate, uninterpreted, inspect, remove, missing-association, and mismatched primitives remain non-executable. Legacy promotion and start disable one another while pending; the legacy activation checkbox affects only legacy promotion.
+
+Successful start displays contract/workflow identities and `Activation: not yet activated`, refreshes the evidence index, switches the App-owned mode to Visual changes, and requests one-shot exact workflow-ID selection. Missing exact revisions warn without fuzzy selection. The new workflow has no activation, attempts, or governance results. The existing Activate control creates the immutable activation revision; no check is invoked automatically.
+
+## 5. Identity and evidence proofs
+
+Tests prove repeated equivalent starts have equal `contractRequestId`, unequal `contractId`, unequal `visualChangeRequestId`, and unequal `visualChangeWorkflowId`, with two persisted contracts and unchanged acceptance. A saved annotation revision changes visual-change request identity. Selecting different executable semantics changes both contract request and visual-change request identity.
+
+A mixed saved annotation containing promotable intent, confirmed remove, and inspect evidence successfully creates a contract from only the selected promotable items. Remove and inspect remain annotation evidence and never become clauses.
+
+## 6. Tests and validation
+
+Focused server/application tests cover prerequisite-first rejection, selected subsets, exact scope, identity behavior, partial success, standalone/security behavior, and Batch 1/2 composition regression. The independently runnable real-Chromium ACCEPTANCE GATE creates fresh project evidence, authors and confirms runtime intent, saves it, starts an inactive workflow, opens the exact workflow, explicitly activates it, verifies unchanged request/new workflow identity, updates only the configured change contract, and confirms zero attempts/no automatic check.
+
+Final validation passed: `npm run typecheck`, `npm run lint`, `npm test` (94 files, 1494 tests), `npm run test:browser` (30 files, 278 tests), `npm run test:security` (16 unit files/168 tests, 3 browser files/77 tests, plus its nested PWA hard gate), `npm run test:pwa-hard-gate` (1 passed, 6 filtered), `npm run build`, `npm run check:docs`, and `git diff --check`. The aggregate browser/security runs used Playwright API diagnostics because the unchanged service-worker checks timed out under this Windows host's normal scheduling but passed deterministically with diagnostic scheduling enabled.
+
+## 7. Full-file read accounting
+
+Full source/test file reads: none. Bounded my-dev-kit search, lookup, slice, exact source, continuation, dependency expansion, and explicit line ranges supplied all required context.
+
+## 8. Exclusions and Batch 5 handoff
+
+No reference-driven entry, reference selection/binding authoring, handoff, orchestrator integration, source editing, automatic check/retry, review/correction/acceptance, governance action, protocol/schema change, version bump, release, publication, or PR was implemented.
+
+Batch 5 can add only the frozen reference-driven entry flow, reusing the Batch 2 workflow owner, Batch 3 secure workspace/reselection, and the explicit activation boundary preserved here.

package/docs/reports/v0.10-batch5-reference-driven-entry.md

@@ -0,0 +1,238 @@
+# v0.10 Batch 5 Reference-Driven Entry
+
+## 1. Verdict
+
+PASS. The original attempt remained preserved as failure history below. The correction completed the frozen responsibility coverage, independent browser proofs, and PWA hard-gate synchronization repair; every mandatory canonical command is green.
+
+## 2. Repository
+
+- Repository: `C:\Users\daile\Projects\my-frontend-observer`
+- Starting commit: `eeb8154180eea7cd143921f3fe52c328e153aab4`
+- Branch: `feature/v0.10-full-visual-workflow`
+
+## 3. Retrieval and fresh index
+
+- Resolved my-dev-kit: `1.12.4`; CLI reported `1.12.4`.
+- Install: `.my-dev-kit-workflow/tools/v0.10-batch5/`.
+- Index: `.my-dev-kit-context/indexes/my-frontend-observer-v0.10-batch5-20260922`.
+- Command: `node .my-dev-kit-workflow/tools/v0.10-batch5/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-batch5-20260922 --call-graph --json`.
+- Summary: 299 files, 2,460 symbols, 4,669 edges, zero index-level warnings/errors.
+- Syntax, call graph, frontend semantic, and frontend reachability were complete. Data-model and classification were partial with 820 and 2,407 warnings.
+
+## 4. Reused precedents and owners
+
+The implementation reuses `approveExternalReference`, `deriveReferenceRequirementAdequacy`, `isValidReferenceRuntimeBindingDeclarations`, `evaluateReferenceRuntimeBindings`, `buildReferenceRequirement`, `createProjectVisualChangeWorkflow`, the exact annotation/source view, project alias catalog, serialized authoring queue, Batch 3 authoring security, exact workflow-ID navigation, and Batch 2 activation.
+
+## 5. Approval route and supersession
+
+`POST /api/references/:handle/approve` accepts exactly `{}` and only a supported imported reference. It resolves a declared predecessor to one exact supported reference root and fails closed otherwise. It calls canonical approval once, returns bounded identity/count/adequacy data, and does not change project acceptance. The Viewer exposes a separate `Approve reference` action and exact approved-ID reselection.
+
+## 6. Materialization separation
+
+Existing materialization remains imported-only. It does not approve, create a workflow, activate acceptance, or run a check.
+
+## 7. Reference workflow start
+
+`POST /api/references/:handle/start-visual-change` accepts only `annotationHandle`, `itemIds`, `baselineObservationHandle`, and `bindings`. It requires an approved route target, exact approved-reference annotation source, confirmed executable reference intent already represented in the approved artifact, adequate requirements, an exact aliased baseline observation, configured reference acceptance, canonical compatibility, canonical declaration validation, complete required-region coverage, and `bound` canonical results.
+
+## 8. Baseline contract and scope
+
+The route freezes the selected exact observation. It freezes a valid configured persistent baseline contract only when contract acceptance exists. It creates the existing `VisualChangeReferenceScope` with contained project-relative paths and delegates persistence to `createProjectVisualChangeWorkflow`. Creation does not activate or change project configuration.
+
+## 9. Viewer binding authoring
+
+The workflow-binding draft is separate from session bindings, begins empty, and resets when the reference or baseline observation changes. Region/target selection alone does not bind. `Add workflow binding` creates an explicit pair; a duplicate region is disabled until explicit `Remove`. Different regions may use the same target. The existing reference-intent checkbox selection is shared with workflow start.
+
+## 10. Navigation, activation, and automatic checks
+
+Successful creation uses the existing exact workflow-ID callback to switch to Visual changes. Activation remains the existing explicit Batch 2 action. No materialization, approval, creation, or activation path invokes a check.
+
+## 11. Identity proof
+
+Unit tests prove that changing the approved reference, binding declaration, baseline observation, or saved annotation revision changes `visualChangeRequestId` through the unchanged Batch 1 identity owner.
+
+## 12. Validation
+
+- `npm run typecheck`: PASS.
+- `npm run lint`: PASS.
+- Focused suites: PASS, 58 tests.
+- `npm test`: PASS, 95 files and 1,500 tests.
+- `npm run build`: PASS.
+- `npm run test:browser`: FAIL, 29 files/277 tests passed; the unchanged PWA hard gate timed out at `navigator.serviceWorker.ready`.
+- `npm run test:pwa-hard-gate`: FAIL with the same 60-second timeout, both before and after a fresh build and with Playwright API diagnostics.
+- `npm run test:security`: FAIL because its 16 unit files/168 tests and other browser security tests passed, but the same PWA hard gate timed out.
+- `npm run check:docs`: PASS.
+- `git diff --check`: PASS (line-ending conversion warnings only).
+
+## 13. Browser acceptance and materialization/approval proof
+
+The frozen independent Batch 5 real-browser acceptance gate and focused materialization-plus-approval proof are not yet implemented. Existing Batch 1-4 browser regressions passed except for the unchanged PWA timeout described above. These missing proofs are ordinary correctable work and prevent PASS.
+
+## 14. Protocol and schema preservation
+
+`VIEWER_PROTOCOL_VERSION` remains `1.3.0`. No external-reference, annotation, visual-change, project-config, or observation schema was changed.
+
+## 15. Full-file read accounting
+
+Whole source/test fallback reads were used after bounded search, lookup, slice, symbol source, local dependency expansion, and continuation proved that my-dev-kit stores symbol start lines without reliable end lines and truncated multi-symbol bundles at the output/block bounds.
+
+- `viewer/src/components/ReferenceWorkspace.tsx` (493 lines, source): establish complete hook/state/JSX insertion points after symbol source omitted the function tail; changed implementation.
+- `src/viewerServer/annotationReferenceMaterialization.ts` (115 lines, source): establish the complete serialized materialization adapter precedent; did not change that file.
+- `src/viewerServer/evidence/index.ts` (153 lines, source): establish exact supported-handle and unique identity behavior; did not change that file.
+- `src/application/visualAnnotationReferenceMaterializationService.ts` (222 lines, source): establish exact intent representation and canonical requirement construction; did not change that file.
+- `src/domain/externalReferenceRuntimeBinding.ts` (290 lines, source): establish complete validator/evaluator result shape and hidden-target semantics; did not change that file.
+- `viewer/src/components/ArtifactPreview.tsx` (82 lines, source): establish reference workspace callback ownership; changed implementation.
+- `viewer/src/hooks/useRuntimeVisualChangeStart.ts` (19 lines, source): establish hook lifecycle/request precedent; did not change that file.
+- `viewer/src/App.tsx` (104 lines, source): establish exact workflow navigation and record selection ownership; changed implementation.
+- `viewer/src/hooks/useEvidenceIndex.ts` (42 lines, source): establish refresh return shape; did not change that file.
+
+Other source inspection used bounded ranges. Canonical documentation reads are excluded from source/test fallback accounting.
+
+## 16. Batch 6 and later exclusions
+
+No coding-agent handoff, orchestrator integration, source editing, automatic retry/check, correction, review, acceptance, abandon, final baseline/reference governance, version bump, release, publication, PR, or Batch 6 work was implemented.
+
+## 17. Exact next action
+
+Commit the reviewed Batch 5 files with `feat: add v0.10 reference visual change flow`, push the shared feature branch, and stop. Batch 6 begins only under a separate authorized task.
+
+## 18. Correction continuation (2026-09-22)
+
+The uncommitted implementation was preserved. Correction work added focused approval/start-route coverage, the two required fresh-state Chromium proofs, reference-mutation concurrency protection, and a state-based PWA readiness synchronization. No reference-domain redesign occurred.
+
+- Correction my-dev-kit: `1.12.4`, pinned at `.my-dev-kit-workflow/tools/v0.10-batch5-correction/`; CLI identity matched exactly.
+- Correction index: `.my-dev-kit-context/indexes/my-frontend-observer-v0.10-batch5-correction-20260922`.
+- Exact command: `node .my-dev-kit-workflow/tools/v0.10-batch5-correction/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-batch5-correction-20260922 --call-graph --json`.
+- Index result: 304 files, 2,480 symbols, 4,761 call-graph edges, zero index warnings/errors; syntax/call-graph/frontend analyzers complete; data-model/classification partial with 834/2,429 warnings.
+
+## 19. Required browser proofs
+
+`MATERIALIZATION + APPROVAL PROOF: keeps import and approval explicit, immutable, superseding, and acceptance-neutral` passes independently. It creates its project/evidence/server/context, proves the successor remains imported until the separate click, then proves fresh approval identity, request identity preservation, supersession, source/import immutability, exact approved reselection, and unchanged project acceptance.
+
+`ACCEPTANCE GATE: creates and explicitly activates an exact reference-mode workflow without running a check` passes independently. It creates a valid aliased baseline and adequate approved reference, authors/saves/confirms exact-source intent in Chromium, explicitly authors both bindings, creates and reselects the exact inactive workflow, proves exact annotation/reference/baseline/bindings and zero attempts, explicitly activates, proves same request/new workflow identity and exact acceptance paths, and proves zero attempts/latest check `none` remain.
+
+## 20. PWA diagnosis and correction
+
+The initial failure was **Class C — test synchronization defect**. On the loopback secure origin, the Service Worker API was present, built `/`, `/index.html`, `/registerSW.js`, `/sw.js`, and `/manifest.webmanifest` were HTTP-available, and `getRegistration()` reached an active worker at the exact origin scope while Chromium on this Windows host left the first `navigator.serviceWorker.ready` synchronization unresolved. There was no worker-script, registration, request, console, or precache failure.
+
+The hard gate now uses bounded Playwright polling of `getRegistration()` until the exact registration exists, is active, and owns `${origin}/`. It then separately retains the controller assertion and every substantive safety fact: live evidence, shell/entry precache, zero `/api/` cache entries, live API reachability, Node-side server-down proof, offline shell reload, controlled page, explicit unavailable evidence, stale identity disappearance, and cleanup. It does not manually register a worker, add sleeps/retries, cache API/media/evidence, or weaken any assertion.
+
+- First isolated hard gate: PASS (1 passed, 6 skipped).
+- Second consecutive fresh-profile hard gate: PASS (1 passed, 6 skipped).
+- Complete `pwaHardening.test.ts`: PASS (7/7).
+- Canonical browser: PASS (30 files, 280 tests).
+- Canonical security: PASS (16 unit files/168 tests; 3 browser files/77 tests; nested hard gate PASS).
+
+## 21. TST-B5 responsibility ledger
+
+Every entry below names the concrete automated proof. Shared tests are intentionally repeated where one scenario establishes several frozen facts.
+
+| ID | Test file — exact test name | Result |
+|---|---|---|
+| TST-B5-001 | `referenceApproval.test.ts` — `returns 404 for an unknown handle, 409 for an approved reference, and requires project authoring security` | PASS |
+| TST-B5-002 | same named approval rejection test | PASS |
+| TST-B5-003 | `referenceApproval.test.ts` — `approves exactly once into one fresh immutable instance, preserves request identity, leaks no path, and leaves acceptance unchanged` | PASS |
+| TST-B5-004 | same named immutable approval test | PASS |
+| TST-B5-005 | same named immutable approval test | PASS |
+| TST-B5-006 | `referenceAnnotationMaterialization.test.ts` — `MATERIALIZATION + APPROVAL PROOF: keeps import and approval explicit, immutable, superseding, and acceptance-neutral` | PASS |
+| TST-B5-007 | `referenceApproval.test.ts` — `fails closed when a declared predecessor cannot be uniquely resolved` | PASS |
+| TST-B5-008 | named immutable approval test | PASS |
+| TST-B5-009 | named immutable approval test | PASS |
+| TST-B5-010 | named approval rejection/security test | PASS |
+| TST-B5-011 | `referenceVisualChangeRoute.test.ts` — `rejects imported scope, exact-source mismatch, non-executable intent, missing alias, missing acceptance, and structural binding errors` | PASS |
+| TST-B5-012 | `referenceVisualChangeRoute.test.ts` — `creates an exact inactive reference scope with optional contract omitted, zero attempts, no config mutation, and no path leakage` | PASS |
+| TST-B5-013 | named route rejection test | PASS |
+| TST-B5-014 | named route rejection test | PASS |
+| TST-B5-015 | `referenceAnnotationMaterialization.test.ts` — `keeps informational and candidate items unselectable, and forced API requests for them are rejected without a write` | PASS |
+| TST-B5-016 | materialization subset test plus `ACCEPTANCE GATE...` exact represented region | PASS |
+| TST-B5-017 | `materializes only the selected subset: a created region and a requirement against it, never the unselected create` | PASS |
+| TST-B5-018 | `referenceCandidateWorkspace.test.ts` — `shows the image with no region rectangles and an honest "no requirements selected" state` | PASS |
+| TST-B5-019 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-020 | named route rejection test | PASS |
+| TST-B5-021 | named route rejection test | PASS |
+| TST-B5-022 | named route rejection test | PASS |
+| TST-B5-023 | `visualChangeProjectWorkflowService.test.ts` — `freezes exact project evidence without activating acceptance, then activates and restores immutable revisions` | PASS |
+| TST-B5-024 | named exact inactive reference-scope test | PASS |
+| TST-B5-025 | `externalReferenceRuntimeBinding.test.ts` — `F: an incompatible reference/candidate viewport blocks ordinary binding evaluation - no bound result fabricated` | PASS |
+| TST-B5-026 | named route rejection test | PASS |
+| TST-B5-027 | named route rejection test | PASS |
+| TST-B5-028 | named route rejection test | PASS |
+| TST-B5-029 | `referenceVisualChangeRoute.test.ts` — `allows several required regions to bind explicitly to the same unique runtime target` | PASS |
+| TST-B5-030 | named route rejection test | PASS |
+| TST-B5-031 | `externalReferenceRuntimeBinding.test.ts` — `D: an ambiguously resolved runtime target is reported ambiguous, never bound` | PASS |
+| TST-B5-032 | `externalReferenceRuntimeBinding.test.ts` — `C: an unknown runtime target (not configured on this candidate) is reported unavailable` | PASS |
+| TST-B5-033 | named exact inactive reference-scope test | PASS |
+| TST-B5-034 | named exact inactive reference-scope test | PASS |
+| TST-B5-035 | named exact inactive reference-scope test | PASS |
+| TST-B5-036 | named exact inactive reference-scope test | PASS |
+| TST-B5-037 | named exact inactive reference-scope test | PASS |
+| TST-B5-038 | named exact inactive reference-scope test | PASS |
+| TST-B5-039 | named exact inactive reference-scope test | PASS |
+| TST-B5-040 | named exact inactive reference-scope test | PASS |
+| TST-B5-041 | named exact inactive reference-scope test | PASS |
+| TST-B5-042 | named exact inactive reference-scope test | PASS |
+| TST-B5-043 | `MATERIALIZATION + APPROVAL PROOF...` | PASS |
+| TST-B5-044 | `materializes a confirmed created region into a new imported revision without approval, config change, or switching the viewed reference` | PASS |
+| TST-B5-045 | `MATERIALIZATION + APPROVAL PROOF...` | PASS |
+| TST-B5-046 | `MATERIALIZATION + APPROVAL PROOF...` | PASS |
+| TST-B5-047 | `MATERIALIZATION + APPROVAL PROOF...` | PASS |
+| TST-B5-048 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-049 | `referenceBindingFidelityWorkspace.test.ts` — `a reference region and runtime target sharing the literal name "header" never cross-select without an explicit declaration` | PASS |
+| TST-B5-050 | same named no-inference binding test | PASS |
+| TST-B5-051 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-052 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-053 | Batch 5 `ACCEPTANCE GATE...` (authored pair has explicit `Remove`) | PASS |
+| TST-B5-054 | `externalReferenceRuntimeBinding.test.ts` — `J: rejects a conflicting declaration mapping the same reference region to two different targets, never silently choosing the first` | PASS |
+| TST-B5-055 | fresh-project Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-056 | fresh baseline selection in Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-057 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-058 | `referenceVisualChangeAuthoring.test.ts` — `accepts exactly the four start fields and rejects activation/path injection` | PASS |
+| TST-B5-059 | same closed-request test | PASS |
+| TST-B5-060 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-061 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-062 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-063 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-064 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-065 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-066 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-067 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-068 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-069 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-070 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-071 | `referenceVisualChangeAuthoring.test.ts` — `changes identity when approved reference changes` | PASS |
+| TST-B5-072 | same table test — `changes identity when binding changes` | PASS |
+| TST-B5-073 | same table test — `changes identity when baseline observation changes` | PASS |
+| TST-B5-074 | same table test — `changes identity when annotation revision changes` | PASS |
+| TST-B5-075 | reference annotation authoring save/revision suite in canonical browser run | PASS |
+| TST-B5-076 | reference annotation explicit confirmation suite in canonical browser run | PASS |
+| TST-B5-077 | first four named `referenceAnnotationMaterialization.test.ts` tests | PASS |
+| TST-B5-078 | six named `referenceCandidateWorkspace.test.ts` cases | PASS |
+| TST-B5-079 | `referenceBindingFidelityWorkspace.test.ts` — `clicking a bound reference region cross-highlights its exact declared runtime target, and vice versa` | PASS |
+| TST-B5-080 | same file — `Case G: a real canonical PASS is displayed with requirement values only after the explicit trigger is clicked` | PASS |
+| TST-B5-081 | canonical `npm test` Batch 1 suites | PASS |
+| TST-B5-082 | canonical `npm test` Batch 2 suites | PASS |
+| TST-B5-083 | canonical browser/security Batch 3 suites | PASS |
+| TST-B5-084 | `runtimeAnnotationContractPromotion.test.ts` — `ACCEPTANCE GATE: creates an inactive actual workflow from confirmed runtime intent and explicitly activates its immutable revision` | PASS |
+| TST-B5-085 | viewer protocol assertion suite; `VIEWER_PROTOCOL_VERSION = '1.3.0'` | PASS |
+
+## 22. Final correction validation
+
+- `npm run typecheck`: PASS.
+- `npm run lint`: PASS.
+- `npm test`: PASS, 97 files/1,506 tests.
+- Focused approval/start-route: PASS, 12 tests.
+- Focused Batch 5 browser proof file: PASS, 6 tests.
+- `npm run test:browser`: PASS, 30 files/280 tests.
+- `npm run test:security`: PASS.
+- `npm run test:pwa-hard-gate`: PASS twice consecutively, plus once inside security.
+- Full `pwaHardening.test.ts`: PASS, 7 tests.
+- `npm run build`: PASS; generated PWA precache has 10 entries.
+- `npm run check:docs`: PASS.
+- `git diff --check`: PASS (Git line-ending notices only).
+- Viewer protocol remains `1.3.0`; no governed schema version changed.
+
+## 23. Correction retrieval and fallback accounting
+
+Correction retrieval followed search → lookup → slice → exact symbol source → continuation/dependency expansion → bounded ranges. Correction-run additional full source/test file reads: none.
+
+The historical fallback ledger in section 15 is retained unchanged.