@dailephd/my-frontend-observer 0.9.0 → 0.10.0

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.

package/docs/reports/v0.10-batch6-coding-agent-handoff.md

@@ -0,0 +1,85 @@
+# v0.10 Batch 6 Coding-Agent Handoff
+
+## 1. Verdict and repository
+
+PASS. Repository `C:\Users\daile\Projects\my-frontend-observer`, branch `feature/v0.10-full-visual-workflow`, starting commit `ac79b2c41e53ac36c825c4b398bbeb4856d5db0e`.
+
+## 2. Retrieval and fresh index
+
+- Resolved my-dev-kit: `1.12.4`; CLI identity and `index`, `search`, `lookup`, `slice`, `source`, `graph-diff`, and `context` were verified.
+- Install: `.my-dev-kit-workflow/tools/v0.10-batch6/mdk-1.12.4/`.
+- Index: `.my-dev-kit-context/indexes/my-frontend-observer-v0.10-batch6-20260922`.
+- Command: `node .my-dev-kit-workflow/tools/v0.10-batch6/mdk-1.12.4/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-batch6-20260922 --call-graph --json`.
+- Result: 306 files, 2,487 symbols, 4,796 edges, zero index warnings/errors. Frontend analysis was complete; data-model and classification were partial with 834 and 2,436 warnings.
+
+## 3. Contract and canonical owners
+
+`VisualChangeAgentHandoff` is a non-persisted, closed `my-frontend-observer/visual-change-agent-handoff` `1.0.0` transfer contract with deterministic canonical JSON and a terminal newline. Batch 2 readiness was extracted into `prepareActiveVisualChangeWorkflow`; canonical check recording and handoff preparation now share activation, restoration, acceptance-drift, exact-alias, and frozen-evidence checks. Existing `projectBoundedAgentContext`, `evaluateReferenceCandidateFidelity`, and `prepareReferenceCorrection` remain the projection/evaluation owners. No evidence schema changed.
+
+## 4. Actual and reference projections
+
+Actual mode carries exact workflow/request and annotation identities, baseline identity and clauses, and all per-change clauses including protected/preserved categories. Reference mode carries exact approved-reference identity and bounded requirements, explicit bindings, optional coherent contract clauses, canonical fidelity-derived context, and binding target focus IDs. A `not-evaluated` fidelity result fails closed. When v0.7 prerequisites exist, the exact `prepareReferenceCorrection` review ID is exposed; otherwise an explicit narrow `not-applicable` reason is returned without a fabricated ID.
+
+## 5. Context and external coordination
+
+Observer-generated bounded context is primary. No context file omits supplemental context; unsupported versions fail; coherent valid context is included unchanged, retaining static producer/correlation ownership. The application never invokes my-dev-kit. Optional coordination accepts only provider `my-dev-kit-orchestrator` and a bounded non-path run ID/version. It is handoff-only traceability and is never persisted to the workflow or inspected on disk.
+
+## 6. Post-edit contract and Viewer
+
+Every handoff contains `{ command: 'check', baselineAlias: <exact Batch 2 alias>, json: true }` and the Viewer renders `my-frontend-observer check <alias> --json`. The secured project-aware route is `POST /api/visual-changes/:handle/prepare-handoff`. Active, non-restored workflows expose Prepare handoff, optional coordination fields, a bounded summary, Copy handoff, and Download handoff. Copy/download share canonical serialization and the filename `visual-change-handoff-<workflowId>.json`. Preparation creates no attempt, check, review, source edit, handoff artifact, or orchestrator action.
+
+## 7. Disposable published-orchestrator compatibility proof
+
+- Published version: `1.4.1`; installed under `.my-dev-kit-workflow/tools/v0.10-batch6/orchestrator-1.4.1/`; version plus `init/start/status/export --help` passed.
+- Root: `.my-dev-kit-workflow/v0.10-batch6/orchestrator-proof/project/`.
+- A real application-owner-generated `observer-visual-change-handoff.json` was referenced by an ordinary feature request specifying external editing and the exact Observer check command.
+- Run ID: `20260922T121702-observer-handoff-proof`.
+- `status` honestly remained at request-brief with 0/10 artifacts and a blocked final report. `export` produced `orchestrator-export.txt` retaining the run identity. No run was advanced or completed.
+- SHA comparison proved handoff bytes unchanged. Observer source/evidence remained unchanged. A second generated handoff round-tripped provider, run ID, and package version without changing Observer workflow/request identity.
+- No orchestrator dependency was added and no production Observer code invokes or reads orchestrator state.
+
+## 8. Browser, security, regressions, and validation
+
+The actual-mode real-Chromium ACCEPTANCE GATE starts from a fresh project/workflow, prepares and inspects a handoff, checks the exact command, copies and downloads identical canonical JSON, verifies the filename, and proves the active workflow remains byte-identical with zero attempts and no check. Reference application tests cover exact requirements/bindings, canonical fidelity, focused context, protected/preserved projection, and both v0.7 trace states.
+
+- Typecheck: PASS.
+- Lint: PASS.
+- Unit: PASS, 99 files / 1,514 tests.
+- Browser: PASS, 30 files / 280 tests.
+- Security: PASS, 16 unit files / 168 tests plus 3 browser files / 77 tests and the hard gate.
+- PWA hard gate: PASS; `/api/` remains uncached and Batch 5 synchronization is unchanged.
+- Build: PASS.
+- Documentation check: PASS.
+- `git diff --check`: PASS (line-ending notices only).
+- Batch 1-5, bounded-context, and reference-correction regressions pass. Viewer protocol remains `1.3.0`.
+
+## 9. Frozen responsibility ledger
+
+Each line names the concrete test owner and test name (or canonical shared suite) that proves the responsibility.
+
+- TST-B6-001..004 — `visualChangeAgentHandoffService.test.ts` — `rejects inactive, restored, acceptance-drifted, and baseline-drifted workflows through the shared readiness owner` — PASS.
+- TST-B6-005..013 — `visualChangeAgentHandoffService.test.ts` — `projects exact actual scope and bounded context without checking, capturing, editing, or persisting a handoff` — PASS.
+- TST-B6-014..018, TST-B6-022..026 — `visualChangeAgentHandoffService.test.ts` — `projects canonical reference fidelity, exact requirements/bindings, focus targets, and an honest not-applicable correction trace` — PASS.
+- TST-B6-019..021 — `visualChangeAgentHandoffService.test.ts` — `reuses the canonical v0.7 reference correction identity when its exact contract preconditions apply` — PASS.
+- TST-B6-027..035 — `visualChangeAgentHandoffService.test.ts` — `includes coherent supplemental context verbatim and rejects unsupported or mismatched context` plus actual/reference projection tests — PASS.
+- TST-B6-036..043 — `visualChangeAgentHandoff.test.ts` — `accepts only bounded opaque orchestrator correlation and changes no workflow semantics`; disposable CLI proof — PASS.
+- TST-B6-044..048 — `visualChangeAgentHandoffService.test.ts` actual projection and `runtimeAnnotationContractPromotion.test.ts` ACCEPTANCE GATE — PASS.
+- TST-B6-049..057 — `visualChangeAgentHandoff.test.ts` — `uses the exact non-artifact kind/version, validates the closed bounded contract, and serializes deterministically with a newline`; unchanged canonical schema suites — PASS.
+- TST-B6-058..060 — `viewerVisualChangeAuthoring.test.ts` — `keeps every POST project-aware, token/Host/Origin/JSON guarded, closed, bounded, and no-store`; browser ACCEPTANCE GATE — PASS.
+- TST-B6-061..069 — `runtimeAnnotationContractPromotion.test.ts` — `ACCEPTANCE GATE: creates an inactive actual workflow from confirmed runtime intent and explicitly activates its immutable revision`; contract tests — PASS.
+- TST-B6-070 — `visualChangeWorkflow.test.ts` canonical Batch 1 suite — PASS.
+- TST-B6-071 — `visualChangeProjectWorkflowService.test.ts` canonical Batch 2 suite — PASS.
+- TST-B6-072 — Viewer/security canonical suites — PASS.
+- TST-B6-073 — `runtimeAnnotationContractPromotion.test.ts` actual entry flow — PASS.
+- TST-B6-074 — Batch 5 reference route/workspace/browser suites — PASS.
+- TST-B6-075 — `boundedAgentContext*.test.ts` canonical suites — PASS.
+- TST-B6-076 — `referenceCorrectionWorkflow.test.ts` canonical suite — PASS.
+- TST-B6-077 — `viewerAuthoringSecurity.test.ts` — `keeps existing read-only routes answering GET and HEAD in authoring mode` — PASS (`1.3.0`).
+
+## 10. Full-file read accounting
+
+Full source/test file reads: none. Retrieval used my-dev-kit search, lookup, slice, exact source, continuation/dependency expansion, then bounded PowerShell ranges only.
+
+## 11. Batch 7+ exclusions and handoff
+
+No source editing, agent/LLM execution, automatic check, attempt recording, correction/review/accept/abandon behavior, governance, release, or orchestrator runtime integration was implemented. Batch 7 should begin from the committed Batch 6 result and add only the separately planned review/correction behavior.