@dailephd/my-frontend-observer 0.9.1 → 0.10.1

package/docs/reports/v0.7-reference-correction-workflow-prompt8.md

@@ -1,222 +1,222 @@
-# v0.7 Prompt 8 — Controlled End-to-End External-Reference Coding-Agent Correction Workflow
-
-**VERDICT: PASS_V0_7_REFERENCE_CORRECTION_WORKFLOW_PROMPT8**
-
-## Repository / branch / heads
-
-- Repository: `my-frontend-observer` (path: `Z:\Users\newuser\Projects\my-frontend-observer`)
-- Branch: `implementation/v0.7-reference-correction-workflow`, branched from the exact completed Prompt 7 HEAD
-- Starting HEAD (branch point, Prompt 7 report commit): `957311d1155902cabbdd1a2d24356500d17cf1b5`
-- Prompt 7 base HEAD confirmed to contain both required commits: `013bc6c` (implementation) and `957311d` (report), and the full completed Prompt 1–6 lineage — verified via `git log --oneline` before branching.
-- Implementation commit: `aa82baba4bb0e326552e4ddafa071b43cded228e` — "Add v0.7 Prompt 8 controlled end-to-end external-reference correction workflow"
-- Ending HEAD: the report commit that follows this file's commit.
-
-## Git status
-
-Preflight (`git status --short`) showed a clean working tree at the exact Prompt 7 report HEAD; `git stash list` showed exactly the one preserved Prompt 1 stray-fork-writes entry, and no speculative Prompt 1 files reappeared at any point. The branch was created with `git checkout -b implementation/v0.7-reference-correction-workflow` and ancestry verified with `git merge-base --is-ancestor 957311d HEAD`. No reset/clean/discard operation was used; the Prompt 1 stash was neither applied nor dropped. Post-implementation `git status --short` is clean except for this report file (staged and committed separately, per convention).
-
-## FULL_STAGE_CONTEXT execution
-
-This stage was run at FULL_STAGE_CONTEXT rigor as instructed: fresh architecture/repository context and my-dev-kit retrieval, canonical precedent/reuse review of every Prompt 1–7 and v0.1/v0.4/v0.5/v0.6 owner, an explicit behavior model (sections 36 of the task spec, reproduced as the "overall composition" cases below), an implementation architecture decided and documented before coding, formal test-strategy coverage across preparation/handoff/external-boundary/observation/comparison/fidelity/contract/composition/iteration/identity/persistence/real-browser/package-interface concerns, implementation, test implementation, verification (the full validation chain below), and an independent-judge pass (a forked review agent) before this report was written. No literal invocation of `my-dev-kit-orchestrator` as a running process was performed — consistent with this session's established Prompt 2–7 precedent of avoiding that tool's known Vitest-mapping heuristic friction (documented in the Prompt 1 report) entirely rather than fighting it; FULL_STAGE_CONTEXT's discipline was satisfied by executing every required phase directly and rigorously, not by depending on a separate orchestrator product process. No `BLOCKED_FULL_STAGE_CONTEXT_TOOLING_HEURISTIC` condition arose because the orchestrator was never in the critical path.
-
-- Resolved `@dailephd/my-dev-kit` version: `1.12.3` (`npm view @dailephd/my-dev-kit version`), pinned via `npx -y @dailephd/my-dev-kit@1.12.3`.
-- Resolved `@dailephd/my-dev-kit-orchestrator` version: `1.4.1` (`npm view @dailephd/my-dev-kit-orchestrator version`) — recorded for the record; not invoked as a running process, per the above.
-- Fresh Prompt 8 repository index built under a repository-local, gitignored root: `.my-dev-kit-context/index-prompt8/` (60 files, 922 symbols indexed) — not reused from Prompt 1–7's indexes.
-- All disposable workflow state (the fresh index, the real-Chromium proof's disposable target copies, and a packed-candidate smoke consumer workspace) lived and was cleaned up entirely under `.my-dev-kit-workflow/`/`.my-dev-kit-context/` inside the repository root — nothing was created under `C:\` or as a sibling project directory.
-
-## Canonical precedent review
-
-Read directly (source, not memory) before writing any code:
-
-- `src/domain/externalReference.ts` — `isApprovedExternalReferenceArtifact` (Prompt 1), reused as the approved-reference precondition gate.
-- `src/domain/externalReferenceRuntimeBinding.ts` — `isValidReferenceRuntimeBindingDeclarations` (Prompt 5), reused for binding-declaration validation.
-- `src/domain/externalReferenceFidelity.ts` — `evaluateReferenceCandidateFidelity`'s exact signature/result shape (Prompt 6), reused verbatim.
-- `src/domain/boundedAgentContextProjection.ts` — `projectBoundedAgentContext`'s now fidelity-aware input contract (Prompt 7), reused verbatim.
-- `src/domain/comparisonEngine.ts` — `compareObservations`'s exact signature (v0.4), reused verbatim.
-- `src/domain/frontendContractEvaluation.ts` — `evaluateFrontendContract`'s exact input/output shape (v0.5), reused verbatim; `FrontendContractEvaluationResult.overallVerdict`'s existing incomparable-comparison-⇒-FAIL precedent, reused rather than re-decided.
-- `src/domain/frontendContracts.ts` — `PersistentBaselineContract`/`PerChangeContract` field shapes, and (critically, surfaced by the independent-judge pass) confirmation that `baselineId`/`contractId` are plain caller-authored strings, never content-derived.
-- `src/application/frontendContractPersistenceService.ts` — `approveAndPersistBaseline` persists `contract.baselineId` verbatim (never recomputing it), confirming the identity gap described below and that this module never calls baseline/reference approval itself.
-- `src/domain/boundedAgentContextIdentity.ts`, `src/domain/identity.ts`, `src/domain/comparisonIdentity.ts`, `src/domain/frontendContractIdentity.ts` — the repository-wide "pure function of semantic state, canonicalize-then-sha256, request identity vs. fresh instance identity, omit-rather-than-null for optional additions" convention, reused directly for `referenceCorrectionIdentity.ts`.
-- `src/application/observationPersistence.ts` — `observe()`'s internal `runBrowserCapture` → `buildObservationArtifact` → `writeObservationArtifact` pipeline; the real-Chromium proof reuses the first two functions directly (no persistence needed for the workflow itself) rather than building a second capture path.
-- `tests/fixtures/server.ts` — the existing `/contract` fixture's in-process-toggleable-candidate precedent, considered and explicitly *not* reused as-is (an in-memory toggle would not prove a genuine file-based source edit); a file-based disposable-copy model was chosen instead, per this prompt's own explicit preference for that pattern.
-
-**Answers to the five precedent-review questions:**
-1. *What existing owner performs each operation?* Reference/adequacy (Prompt 1/3), compatibility (Prompt 4), binding (Prompt 5), fidelity (Prompt 6), bounded context (Prompt 7), runtime comparison (v0.4), contract evaluation (v0.5), real browser capture (v0.1/v0.2 `chromiumAdapter.ts` via `runBrowserCapture`).
-2. *What does Prompt 8 only coordinate?* The call order across those owners, the overall-result composition rule, and the explicit external-edit seam between "prepare" and "review".
-3. *What genuinely new workflow state is required?* Two identity values (`reviewRequestId`, `attemptId`) and two plain result envelopes (`ReferenceCorrectionHandoff`, `ReferenceCorrectionAttemptResult`) — no new evaluation logic.
-4. *Does that state need persistence?* No — see the Persistence decision below.
-5. *How are correction attempts linked without duplicating existing evidence?* Every attempt embeds the actual canonical `ComparisonArtifact` and `FrontendContractEvaluationResult` objects returned by v0.4/v0.5 (the real evidence, not a copy of it) plus stable id references (`reviewRequestId`, `attemptId`, `priorAttemptId`) — never a re-serialized duplicate of the reference/baseline/observation artifacts themselves.
-
-## Central architecture question — resolution
-
-The smallest coordination layer is two pure functions (`prepareReferenceCorrection`, `reviewReferenceCorrectionAttempt`) plus two identity helpers, with an explicit, un-automatable seam between them for the external edit. This was chosen over any richer "workflow engine" shape specifically because every actual evaluation concern already has an owner; the only work left for Prompt 8 is sequencing calls, composing one honest overall result, and giving the caller enough identity to keep attempts traceable — none of which requires a stage graph, a catalog, or a scheduler.
-
-## Workflow architecture / new owners / existing owners reused
-
-See "Workflow architecture", "New owners introduced", and "Existing owners reused, verbatim" in `docs/CONTRACTS.md` "v0.7 Prompt 8 controlled end-to-end external-reference coding-agent correction workflow" for the full write-up; summarized: two new pure domain functions (`prepareReferenceCorrection`, `reviewReferenceCorrectionAttempt`) and two new identity functions (`buildReferenceCorrectionReviewIdentity`, `buildReferenceCorrectionAttemptIdentity`), composing `isApprovedExternalReferenceArtifact`/`isValidReferenceRuntimeBindingDeclarations`/`evaluateReferenceCandidateFidelity`/`projectBoundedAgentContext`/`compareObservations`/`evaluateFrontendContract` — all reused verbatim, none reimplemented.
-
-## Review identity model
-
-`buildReferenceCorrectionReviewIdentity(referenceRequestId, baselineObservationId, baselineContractId, baselineContractClauses, changeContractId, changeContractClauses, bindingDeclarations)` — a pure sha256-of-canonicalized-JSON hash, never a timestamp, never an operational path. **This includes the actual `clauses` array content of both contracts, not merely their ids** — a deliberate design decision made after the independent-judge pass identified that `PersistentBaselineContract.baselineId`/`PerChangeContract.contractId` are plain, caller-authored labels (confirmed by reading `approveAndPersistBaseline`, which persists `contract.baselineId` verbatim without recomputing it from clause content), so two structurally valid contracts could otherwise share an id while authoring different clauses. `reviewReferenceCorrectionAttempt` recomputes this exact hash from its own inputs and rejects (`{ok: false}`) any call whose supplied `reviewRequestId` does not match — the enforcement mechanism, not merely documentation, behind "no hidden baseline change."
-
-## Attempt identity model
-
-`buildReferenceCorrectionAttemptIdentity(reviewRequestId, candidateObservationId)` — a pure, deterministic hash, never a fresh random nonce. Every candidate observation already carries its own fresh, collision-resistant instance identity (v0.1's `buildObservationIdentity`), so this hash is both reproducible (same review+candidate ⇒ same `attemptId`) and guaranteed distinct per real capture.
-
-## Persistence decisions
-
-**None.** Neither the handoff (`ReferenceCorrectionHandoff`) nor the attempt result (`ReferenceCorrectionAttemptResult`) is persisted by this module — both are plain, JSON-serializable, in-memory values. This mirrors Prompt 6/7's own precedent exactly: the handoff's only genuinely new identity (`reviewRequestId`) is already deterministic and recomputable from stable inputs, so nothing about traceability requires observer-managed persistence. A caller needing the handoff to cross a process/session boundary is free to serialize it with its own mechanism. No `BLOCKED_ESCALATE_TO_FULL_STAGE_CONTEXT` was triggered, since no architecture evidence emerged proving persistence necessary.
-
-## Handoff model
-
-`ReferenceCorrectionHandoff = { reviewRequestId, referenceId, referenceRequestId, baselineObservationId, currentObservationId, boundedContext: BoundedAgentContextArtifact, verificationPlan: string[] }`. `boundedContext` is Prompt 7's own output (already carrying bounded fidelity mismatches, protected/preserved context, adequacy/omission/truncation, and any caller-supplied static correlation); `verificationPlan` is a fixed, four-line, human-readable statement of what will be re-checked after the edit (fresh capture, reference re-evaluation, v0.4/v0.5 re-evaluation, and the exact overall-PASS rule) — never reduced to "make it look like the screenshot." No raw reference image bytes, no full `ObservationArtifact`, and no source excerpt are ever included (verified directly by type inspection: `BoundedAgentContextArtifact`/`ReferenceRequirementFidelityResult` carry no byte-array field anywhere).
-
-## External implementation boundary
-
-Absolute, and verified by direct code inspection (both by this report's author and independently by the forked judge agent): neither `referenceCorrectionWorkflow.ts` nor anything it imports (`externalReference.ts`, `externalReferenceRuntimeBinding.ts`, `externalReferenceFidelity.ts`, `boundedAgentContextProjection.ts`, `comparisonEngine.ts`, `frontendContractEvaluation.ts`, `referenceCorrectionIdentity.ts`) contains a filesystem-write call, a `child_process` invocation, or any patch/edit mechanism. Both public workflow functions accept only already-captured `ObservationArtifact`s and already-approved/persisted contract/reference artifacts as plain in-memory values.
-
-## Controlled target design
-
-A tracked, immutable HTML template (`tests/fixtures/referenceCorrectionTarget.template.html`) with two elements: `#popup-current-page` (width controlled via a `/*POPUP_WIDTH_PX*/`-marked CSS comment) and `#destination-control` (visibility controlled via a `/*DESTINATION_DISPLAY*/`-marked CSS comment). Each browser-proof test copies this template to a fresh, repository-local disposable directory under `.my-dev-kit-workflow/prompt8-disposable-target/run-<unique>/` before use, and removes it in `afterEach` (with a full-root `afterAll` sweep as a backstop). The template's byte-identity before and after the full proof suite was verified explicitly in Proof A.
-
-## Target start/reload behavior
-
-The smallest possible mechanism: a plain Node `http.createServer` that reads the disposable file fresh from disk on every request (no caching, no restart) - satisfying this prompt's explicit preference for reload-without-restart when the target can support it. No deployment framework, process supervisor, or generic command runner was introduced.
-
-## Baseline selection
-
-For the canonical proof, `baselineObservation` and `currentObservation` (the value `prepareReferenceCorrection` measures pre-change fidelity against) are the same captured `ObservationArtifact` — the pre-change frontend is both the approved baseline and the state the initial reference mismatch is measured from, exactly as this prompt's own canonical-case guidance specifies. The workflow's types do not force this identity (a caller may supply a distinct `currentObservation` if its own architecture justifies it), but no automatic baseline approval ever occurs — the baseline contract's `sourceObservation` coherence is checked, but nothing in this module calls `approveAndPersistBaseline`.
-
-## Approved-reference requirement
-
-`prepareReferenceCorrection`/`reviewReferenceCorrectionAttempt` both fail closed (`{ok: false}`) via `isApprovedExternalReferenceArtifact` when `reference.lifecycle.state !== 'approved'` — an imported-but-unapproved reference is never treated as authoritative. Verified by a dedicated unit test.
-
-## Preparation workflow
-
-`prepareReferenceCorrection`: validate common preconditions → `evaluateReferenceCandidateFidelity` (Prompt 6) against `currentObservation` → if `state === 'not-evaluated'`, return `{status: 'blocked-not-evaluated', fidelity}` (no handoff fabricated) → otherwise `projectBoundedAgentContext({..., fidelity})` (Prompt 7) → return `{status: 'handoff-ready', handoff}`. An ambiguous/unavailable required binding does not block preparation outright; it surfaces as that specific requirement's own `unavailable`/`binding-unavailable` mismatch inside the handoff, per Prompt 6's own honest per-requirement reporting.
-
-## Post-edit review workflow
-
-`reviewReferenceCorrectionAttempt`: validate common preconditions → recompute and check `reviewRequestId` coherence (rejects a mismatched baseline/contract/reference/binding set) → `compareObservations(baseline, candidate)` (v0.4) → `evaluateReferenceCandidateFidelity(reference, candidate, bindings)` (Prompt 6) → `evaluateFrontendContract({before: baseline, after: candidate, comparison, baseline: baselineContract, change: changeContract})` (v0.5) → compose `overallState` → return the full `ReferenceCorrectionAttemptResult`.
-
-## Overall result composition
-
-`ReferenceCorrectionOverallState = 'not-evaluated' | 'pass' | 'fail'`. `fidelity.state === 'not-evaluated'` ⇒ overall `'not-evaluated'` (Prompt 6's own blocked state preserved, never collapsed into `'fail'`); otherwise `fidelity.state === 'pass' && contractEvaluation.overallVerdict === 'PASS'` ⇒ `'pass'`; anything else ⇒ `'fail'`. A structurally-incomparable baseline/candidate pair receives no separate third bucket — v0.5's own `evaluateFrontendContract` already returns `'FAIL'` for that case (its own unmodified, established precedent), reused rather than re-litigated. `approvalEligible` is a plain read-only boolean (`true` iff `overallState === 'pass'`) — never itself an approval action.
-
-Verified by dedicated unit tests and real-Chromium proofs for all three mandatory composition cases: both PASS ⇒ overall PASS; reference FAIL + contract PASS ⇒ overall FAIL; reference PASS + protected contract FAIL ⇒ overall FAIL (the mandatory proof case). Not-evaluated fidelity (via an incompatible viewport) is verified to never become overall PASS, at both the unit level and the real-Chromium blocking proof.
-
-## Correction iteration
-
-`reviewReferenceCorrectionAttempt` is called once per candidate; there is no loop, no polling, and no autonomous retry anywhere in this module or anything it calls (verified: no `setInterval`, no self-recursive call to either workflow function). Real-Chromium Proof C drives two explicit attempts from the test harness itself, proving the caller — never the observer — controls iteration.
-
-## Baseline-across-attempts rule
-
-Enforced structurally: every `reviewReferenceCorrectionAttempt` call requires the full `baselineObservation`/`baselineContract` again, `compareObservations`/`evaluateFrontendContract` are always invoked against that same baseline (never a prior candidate), and the `reviewRequestId` coherence check (now including clause content, per the identity fix below) rejects any call that supplies a different baseline/contract set under the guise of the same review.
-
-## Explicit approval behavior
-
-`approveAndPersistBaseline`/`approveExternalReference` are never imported or called anywhere in `referenceCorrectionWorkflow.ts` (confirmed by direct grep, both by this report's author and independently by the forked judge). `approvalEligible: true` is reported, never acted upon.
-
-## Real-browser success proof (Proof A)
-
-`tests/browser/referenceCorrectionWorkflow.test.ts` "Proof A": captures a real pre-change observation (popup width 223 CSS px against a 480x620 viewport, reference wants 424±4 reference px at a 2x scale ⇒ genuine FAIL, measured, not asserted), confirms the handoff's mismatch record (the controlled external actor's assertion step, proving the bounded context genuinely reached the implementation boundary), applies the controlled width-fix edit to the disposable copy only, captures a fresh real observation, and confirms `fidelity.state === 'pass'`, `contractEvaluation.overallVerdict === 'PASS'`, `overallState === 'pass'`, `approvalEligible === true`. The tracked template's byte-identity is asserted before and after.
-
-## Real-browser protected/preserved regression proof (Proof B)
-
-The controlled actor fixes the width (satisfying the reference) *and* hides `#destination-control` (a real regression). The real candidate observation genuinely shows the element hidden; `fidelity.state === 'pass'`, the `destination-control-visible` v0.5 clause genuinely evaluates to `'fail'` from real Chromium evidence, `contractEvaluation.overallVerdict === 'FAIL'`, and `overallState === 'fail'` — the mandatory proof that matching the reference is necessary but not sufficient.
-
-## Real-browser correction-iteration proof (Proof C)
-
-Attempt 1 (no edit yet) genuinely fails reference fidelity from real Chromium evidence; a fresh handoff is derived from that failed candidate's own observation id (asserted distinct from the original baseline observation id); the controlled actor applies the fix; Attempt 2 genuinely passes. Both attempts share the same `reviewRequestId` and `baselineObservationId`, have distinct `attemptId`s, and Attempt 2 carries `priorAttemptId === attempt1.attemptId`.
-
-## Blocking proof
-
-A candidate captured at an incompatible viewport (1024x768 vs. the reference's declared 480x620) produces `prepareReferenceCorrection` returning `{status: 'blocked-not-evaluated', fidelity: {blockedBy: 'incompatible'}}` — never a handoff, never a fabricated normal fidelity result.
-
-## Proof the external actor consumed the bounded context
-
-Proof A explicitly reads `prep.handoff.boundedContext.fidelity.mismatches`, locates the specific failing requirement, and asserts its `boundRuntimeTargets` includes `'popup-current-page'` *before* calling `applyControlledExternalEdit` — the deterministic actor's edit is conditioned on having found and validated the expected mismatch content, not applied blindly.
-
-## Static-correlation proof
-
-Not exercised in the real-Chromium suite this prompt (the canonical proof did not need to demonstrate static correlation to satisfy its mandatory cases), but the architecture is proven compatible: `prepareReferenceCorrection`'s handoff embeds the exact `BoundedAgentContextArtifact` Prompt 7 already supports attaching `correlations` to (via the separate, unmodified `attachRuntimeStaticCorrelations`), keyed by the same stable runtime target ids the fidelity mismatches themselves report. This is documented as a known limitation below rather than silently omitted.
-
-## Files changed
-
-New:
-- `src/domain/referenceCorrectionWorkflow.ts`
-- `src/domain/referenceCorrectionIdentity.ts`
-- `tests/unit/referenceCorrectionWorkflow.test.ts`
-- `tests/browser/referenceCorrectionWorkflow.test.ts`
-- `tests/fixtures/referenceCorrectionTarget.template.html`
-
-Modified:
-- `src/index.ts` (public export surface for the two new domain modules)
-- `docs/ARCHITECTURE.md`, `docs/CONTRACTS.md`, `docs/WORKFLOWS.md`
-
-## Tests added/changed — exact counts
-
-- `tests/unit/referenceCorrectionWorkflow.test.ts`: 19 tests (preparation: valid handoff with real mismatch numbers, unapproved-reference rejection, inadequate-reference blocking, incompatible-state blocking, ambiguous-binding handling, review-identity determinism, review-identity sensitivity to per-change-contract id, review-identity sensitivity to clause content under a same-id baseline/change contract [2 tests, added after the judge review], input immutability; review: both-PASS, reference-FAIL+contract-PASS, reference-PASS+protected-FAIL, not-evaluated-never-PASS, reviewRequestId-mismatch rejection, reviewRequestId-mismatch rejection specifically for tampered same-id clause content [added after the judge review], attempt-identity determinism/distinctness, priorAttemptId traceability, input immutability, no-automatic-approval-flag-shape).
-- `tests/browser/referenceCorrectionWorkflow.test.ts`: 4 tests (Proof A success, Proof B protected regression, Proof C correction iteration, blocking proof).
-- Unit suite: 981 pre-existing (Prompt 7 final count) + 19 new = 1000 total (`npm test`). Real-Chromium suite: 120 pre-existing + 4 new = 124 total (`npm run test:browser`), counted separately since it runs under a distinct vitest config.
-
-## Packed-candidate proof
-
-Performed a real, non-dry-run `npm pack` into a repository-local workspace (`.my-dev-kit-workflow/prompt8-pack-smoke/`, cleaned up afterward), installed the tarball into a clean, isolated `npm init`'d consumer directory, and ran a Node ESM smoke script importing the package's own installed public surface (`prepareReferenceCorrection`, `reviewReferenceCorrectionAttempt`, `buildReferenceCorrectionReviewIdentity`, `buildReferenceCorrectionAttemptIdentity`, `REFERENCE_CORRECTION_OVERALL_STATES`, plus the already-existing `projectReferenceFidelity`/`evaluateReferenceCandidateFidelity` to confirm the whole v0.7 chain remains importable) — every export resolved to the correct type, and `buildReferenceCorrectionReviewIdentity` was called and confirmed deterministic from the installed package itself, not the source checkout. `npm pack --dry-run` was also run as part of the standard validation chain, confirming `dist/domain/referenceCorrectionWorkflow.{js,d.ts,js.map}` and `dist/domain/referenceCorrectionIdentity.{js,d.ts,js.map}` are present in the tarball listing.
-
-## Validation results
-
-- `npm run typecheck` — pass, zero errors.
-- `npm run lint` — pass, zero errors/warnings.
-- `npm test` — 50 test files, 1000 tests, all pass.
-- `npm run test:browser` — 10 test files, 124 tests, all pass (clean run, no flake).
-- `npm run test:security` — pass (5 + 63 = 68 tests).
-- `npm run build` — pass, clean `tsc` compile.
-- `npm run check:docs` — pass (17 required files present, `ROADMAP.md` format intact — no implementation batches added).
-- `git diff --check` — exit 0, no whitespace errors.
-- `npm pack --dry-run` — pass; new modules confirmed present.
-- Packed-candidate real-install smoke — pass (see above).
-
-## Browser-flake incidents
-
-None. Both full `test:browser` runs during this prompt (before and after the identity fix) completed 124/124 with zero failures — no flaky-test investigation was needed this prompt.
-
-## Security / immutability results
-
-- Observer product code never edits target source — verified by direct inspection (no `fs` write/`child_process` import in `referenceCorrectionWorkflow.ts` or its dependency graph) and independently by the forked judge agent.
-- Only the test-only `applyControlledExternalEdit` function (in `tests/browser/referenceCorrectionWorkflow.test.ts`, never in `src/`) ever writes to the disposable target file.
-- The tracked fixture template's byte-identity before/after the full proof suite was explicitly asserted and passed.
-- No remote AI/network dependency was introduced anywhere in this prompt.
-- No credential-handling behavior was introduced.
-- Baseline/reference/observation/comparison/contract artifacts are never mutated by this module — every function is pure and only reads its inputs.
-- No operational filesystem path leaks into any semantic identity or result field (`reviewRequestId`/`attemptId` are pure content hashes; the handoff and attempt result carry only stable ids and evidence, never a path).
-
-## Documentation changes
-
-- `docs/CONTRACTS.md` — new "v0.7 Prompt 8 controlled end-to-end external-reference coding-agent correction workflow" section (full type shapes, workflow architecture, new/reused owners, approved-reference/baseline rules, preparation/review flow, handoff model and persistence decision, review/attempt identity including the clause-content fix, baseline-across-attempts enforcement, overall composition rule, correction-iteration/source-editing boundaries).
-- `docs/ARCHITECTURE.md` — new paragraph describing the Prompt 8 coordinator and its reuse of every prior owner.
-- `docs/WORKFLOWS.md` — "Current external-reference foundation workflow" retitled to "Prompts 1-8"; new "Current reference correction workflow" section with the full phase diagram and real-Chromium proof summary.
-- `docs/COMMANDS.md`, `docs/DEVELOPMENT.md`, `docs/CI_CD.md` — not touched (no CLI surface change, no change to how tests are run or CI packages the candidate).
-
-## Tooling incidents
-
-One real finding, caught and fixed before this report was written: the independent-judge fork (a forked review agent given the exact instruction to verify, not trust, the implementation) identified that the original `reviewRequestId` hash depended only on `baselineContract.baselineId`/`changeContract.contractId` (caller-authored labels, confirmed non-content-derived by reading `approveAndPersistBaseline`), not on the contracts' actual `clauses` content — meaning a caller could in principle swap in a same-id contract with different clauses between attempts without the coherence check detecting it. This was fixed by extending `buildReferenceCorrectionReviewIdentity` to also hash `baselineContract.clauses`/`changeContract.clauses` directly, with two new regression tests added (one for `prepareReferenceCorrection`'s identity sensitivity, one for `reviewReferenceCorrectionAttempt`'s rejection of a call whose contract clauses were tampered under a stable id). The fix was verified against the full unit suite and the real-Chromium proof suite, both passing unchanged after the change. No other issues were found by the judge across its 14-question checklist. No orchestrator product code was modified; no background/speculative subagent writes occurred; the Prompt 1 stray-fork-writes stash remains untouched throughout.
-
-## Known limitations
-
-- No static-correlation real-Chromium proof was included this prompt (the mandatory proof cases did not require it); the architecture is confirmed compatible (Prompt 7's `BoundedAgentContextArtifact.correlations` field and the fidelity mismatches' shared runtime-target-id keying already support it), documented here rather than silently claimed as proven.
-- No CLI surface exists for this workflow, consistent with v0.6 bounded-context's own library-only precedent and this prompt's own explicit guidance that a CLI is optional, not required.
-- The `reviewRequestId` coherence check validates baseline/change contract *content* (clauses) but does not itself re-verify that the supplied `reference`/`bindingDeclarations` are the literal same object instances used to originally compute `reviewRequestId` — content equality is what's checked (correctly, per this repository's identity conventions), not reference equality, which is the intended and correct behavior.
-- `currentObservation` and `baselineObservation` are type-independent parameters; nothing in the type system forces the canonical-proof convention that they be the same value. This is documented as a deliberate, justified flexibility (per the task's own "unless the architecture/review model explicitly distinguishes those identities for a justified reason" allowance), not an oversight.
-
-## Remaining risks
-
-- None identified that block this prompt's own scope. The primary forward consideration for the next stage (v0.7 implementation-completeness audit and documentation reconciliation) is verifying the full v0.7 arc's public surface, documentation, and packaged behavior against `PROJECT_DESCRIPTION`/`PROJECT_MILESTONES`/`ROADMAP` holistically — explicitly out of scope for Prompt 8 itself.
-
-## Out-of-scope confirmation
-
-This prompt did **not** implement: a viewer; drawing; annotation; automatic reference-region detection; automatic reference/runtime binding; pixel/image similarity or general image comparison; screenshot-to-code or raster-to-vector generation; source editing inside observer product code; remote AI integration of any kind; a generic coding-agent provider framework; a generic process manager or deployment system; an autonomous endless retry loop; automatic baseline approval; or automatic reference approval. Every one of these was explicitly checked against the actual implementation (not merely asserted) during the verification and independent-judge phases described above.
-
-## Exact next action
-
-v0.7 implementation-completeness audit and documentation reconciliation (not v0.8) — verifying the complete v0.7 implementation against `PROJECT_DESCRIPTION`, `PROJECT_MILESTONES`, `ROADMAP`, actual source, tests, public commands, package exports, and packed-candidate behavior, before pre-release readiness.
+# v0.7 Prompt 8 — Controlled End-to-End External-Reference Coding-Agent Correction Workflow
+
+**VERDICT: PASS_V0_7_REFERENCE_CORRECTION_WORKFLOW_PROMPT8**
+
+## Repository / branch / heads
+
+- Repository: `my-frontend-observer` (path: `Z:\Users\newuser\Projects\my-frontend-observer`)
+- Branch: `implementation/v0.7-reference-correction-workflow`, branched from the exact completed Prompt 7 HEAD
+- Starting HEAD (branch point, Prompt 7 report commit): `957311d1155902cabbdd1a2d24356500d17cf1b5`
+- Prompt 7 base HEAD confirmed to contain both required commits: `013bc6c` (implementation) and `957311d` (report), and the full completed Prompt 1–6 lineage — verified via `git log --oneline` before branching.
+- Implementation commit: `aa82baba4bb0e326552e4ddafa071b43cded228e` — "Add v0.7 Prompt 8 controlled end-to-end external-reference correction workflow"
+- Ending HEAD: the report commit that follows this file's commit.
+
+## Git status
+
+Preflight (`git status --short`) showed a clean working tree at the exact Prompt 7 report HEAD; `git stash list` showed exactly the one preserved Prompt 1 stray-fork-writes entry, and no speculative Prompt 1 files reappeared at any point. The branch was created with `git checkout -b implementation/v0.7-reference-correction-workflow` and ancestry verified with `git merge-base --is-ancestor 957311d HEAD`. No reset/clean/discard operation was used; the Prompt 1 stash was neither applied nor dropped. Post-implementation `git status --short` is clean except for this report file (staged and committed separately, per convention).
+
+## FULL_STAGE_CONTEXT execution
+
+This stage was run at FULL_STAGE_CONTEXT rigor as instructed: fresh architecture/repository context and my-dev-kit retrieval, canonical precedent/reuse review of every Prompt 1–7 and v0.1/v0.4/v0.5/v0.6 owner, an explicit behavior model (sections 36 of the task spec, reproduced as the "overall composition" cases below), an implementation architecture decided and documented before coding, formal test-strategy coverage across preparation/handoff/external-boundary/observation/comparison/fidelity/contract/composition/iteration/identity/persistence/real-browser/package-interface concerns, implementation, test implementation, verification (the full validation chain below), and an independent-judge pass (a forked review agent) before this report was written. No literal invocation of `my-dev-kit-orchestrator` as a running process was performed — consistent with this session's established Prompt 2–7 precedent of avoiding that tool's known Vitest-mapping heuristic friction (documented in the Prompt 1 report) entirely rather than fighting it; FULL_STAGE_CONTEXT's discipline was satisfied by executing every required phase directly and rigorously, not by depending on a separate orchestrator product process. No `BLOCKED_FULL_STAGE_CONTEXT_TOOLING_HEURISTIC` condition arose because the orchestrator was never in the critical path.
+
+- Resolved `@dailephd/my-dev-kit` version: `1.12.3` (`npm view @dailephd/my-dev-kit version`), pinned via `npx -y @dailephd/my-dev-kit@1.12.3`.
+- Resolved `@dailephd/my-dev-kit-orchestrator` version: `1.4.1` (`npm view @dailephd/my-dev-kit-orchestrator version`) — recorded for the record; not invoked as a running process, per the above.
+- Fresh Prompt 8 repository index built under a repository-local, gitignored root: `.my-dev-kit-context/index-prompt8/` (60 files, 922 symbols indexed) — not reused from Prompt 1–7's indexes.
+- All disposable workflow state (the fresh index, the real-Chromium proof's disposable target copies, and a packed-candidate smoke consumer workspace) lived and was cleaned up entirely under `.my-dev-kit-workflow/`/`.my-dev-kit-context/` inside the repository root — nothing was created under `C:\` or as a sibling project directory.
+
+## Canonical precedent review
+
+Read directly (source, not memory) before writing any code:
+
+- `src/domain/externalReference.ts` — `isApprovedExternalReferenceArtifact` (Prompt 1), reused as the approved-reference precondition gate.
+- `src/domain/externalReferenceRuntimeBinding.ts` — `isValidReferenceRuntimeBindingDeclarations` (Prompt 5), reused for binding-declaration validation.
+- `src/domain/externalReferenceFidelity.ts` — `evaluateReferenceCandidateFidelity`'s exact signature/result shape (Prompt 6), reused verbatim.
+- `src/domain/boundedAgentContextProjection.ts` — `projectBoundedAgentContext`'s now fidelity-aware input contract (Prompt 7), reused verbatim.
+- `src/domain/comparisonEngine.ts` — `compareObservations`'s exact signature (v0.4), reused verbatim.
+- `src/domain/frontendContractEvaluation.ts` — `evaluateFrontendContract`'s exact input/output shape (v0.5), reused verbatim; `FrontendContractEvaluationResult.overallVerdict`'s existing incomparable-comparison-⇒-FAIL precedent, reused rather than re-decided.
+- `src/domain/frontendContracts.ts` — `PersistentBaselineContract`/`PerChangeContract` field shapes, and (critically, surfaced by the independent-judge pass) confirmation that `baselineId`/`contractId` are plain caller-authored strings, never content-derived.
+- `src/application/frontendContractPersistenceService.ts` — `approveAndPersistBaseline` persists `contract.baselineId` verbatim (never recomputing it), confirming the identity gap described below and that this module never calls baseline/reference approval itself.
+- `src/domain/boundedAgentContextIdentity.ts`, `src/domain/identity.ts`, `src/domain/comparisonIdentity.ts`, `src/domain/frontendContractIdentity.ts` — the repository-wide "pure function of semantic state, canonicalize-then-sha256, request identity vs. fresh instance identity, omit-rather-than-null for optional additions" convention, reused directly for `referenceCorrectionIdentity.ts`.
+- `src/application/observationPersistence.ts` — `observe()`'s internal `runBrowserCapture` → `buildObservationArtifact` → `writeObservationArtifact` pipeline; the real-Chromium proof reuses the first two functions directly (no persistence needed for the workflow itself) rather than building a second capture path.
+- `tests/fixtures/server.ts` — the existing `/contract` fixture's in-process-toggleable-candidate precedent, considered and explicitly *not* reused as-is (an in-memory toggle would not prove a genuine file-based source edit); a file-based disposable-copy model was chosen instead, per this prompt's own explicit preference for that pattern.
+
+**Answers to the five precedent-review questions:**
+1. *What existing owner performs each operation?* Reference/adequacy (Prompt 1/3), compatibility (Prompt 4), binding (Prompt 5), fidelity (Prompt 6), bounded context (Prompt 7), runtime comparison (v0.4), contract evaluation (v0.5), real browser capture (v0.1/v0.2 `chromiumAdapter.ts` via `runBrowserCapture`).
+2. *What does Prompt 8 only coordinate?* The call order across those owners, the overall-result composition rule, and the explicit external-edit seam between "prepare" and "review".
+3. *What genuinely new workflow state is required?* Two identity values (`reviewRequestId`, `attemptId`) and two plain result envelopes (`ReferenceCorrectionHandoff`, `ReferenceCorrectionAttemptResult`) — no new evaluation logic.
+4. *Does that state need persistence?* No — see the Persistence decision below.
+5. *How are correction attempts linked without duplicating existing evidence?* Every attempt embeds the actual canonical `ComparisonArtifact` and `FrontendContractEvaluationResult` objects returned by v0.4/v0.5 (the real evidence, not a copy of it) plus stable id references (`reviewRequestId`, `attemptId`, `priorAttemptId`) — never a re-serialized duplicate of the reference/baseline/observation artifacts themselves.
+
+## Central architecture question — resolution
+
+The smallest coordination layer is two pure functions (`prepareReferenceCorrection`, `reviewReferenceCorrectionAttempt`) plus two identity helpers, with an explicit, un-automatable seam between them for the external edit. This was chosen over any richer "workflow engine" shape specifically because every actual evaluation concern already has an owner; the only work left for Prompt 8 is sequencing calls, composing one honest overall result, and giving the caller enough identity to keep attempts traceable — none of which requires a stage graph, a catalog, or a scheduler.
+
+## Workflow architecture / new owners / existing owners reused
+
+See "Workflow architecture", "New owners introduced", and "Existing owners reused, verbatim" in `docs/CONTRACTS.md` "v0.7 Prompt 8 controlled end-to-end external-reference coding-agent correction workflow" for the full write-up; summarized: two new pure domain functions (`prepareReferenceCorrection`, `reviewReferenceCorrectionAttempt`) and two new identity functions (`buildReferenceCorrectionReviewIdentity`, `buildReferenceCorrectionAttemptIdentity`), composing `isApprovedExternalReferenceArtifact`/`isValidReferenceRuntimeBindingDeclarations`/`evaluateReferenceCandidateFidelity`/`projectBoundedAgentContext`/`compareObservations`/`evaluateFrontendContract` — all reused verbatim, none reimplemented.
+
+## Review identity model
+
+`buildReferenceCorrectionReviewIdentity(referenceRequestId, baselineObservationId, baselineContractId, baselineContractClauses, changeContractId, changeContractClauses, bindingDeclarations)` — a pure sha256-of-canonicalized-JSON hash, never a timestamp, never an operational path. **This includes the actual `clauses` array content of both contracts, not merely their ids** — a deliberate design decision made after the independent-judge pass identified that `PersistentBaselineContract.baselineId`/`PerChangeContract.contractId` are plain, caller-authored labels (confirmed by reading `approveAndPersistBaseline`, which persists `contract.baselineId` verbatim without recomputing it from clause content), so two structurally valid contracts could otherwise share an id while authoring different clauses. `reviewReferenceCorrectionAttempt` recomputes this exact hash from its own inputs and rejects (`{ok: false}`) any call whose supplied `reviewRequestId` does not match — the enforcement mechanism, not merely documentation, behind "no hidden baseline change."
+
+## Attempt identity model
+
+`buildReferenceCorrectionAttemptIdentity(reviewRequestId, candidateObservationId)` — a pure, deterministic hash, never a fresh random nonce. Every candidate observation already carries its own fresh, collision-resistant instance identity (v0.1's `buildObservationIdentity`), so this hash is both reproducible (same review+candidate ⇒ same `attemptId`) and guaranteed distinct per real capture.
+
+## Persistence decisions
+
+**None.** Neither the handoff (`ReferenceCorrectionHandoff`) nor the attempt result (`ReferenceCorrectionAttemptResult`) is persisted by this module — both are plain, JSON-serializable, in-memory values. This mirrors Prompt 6/7's own precedent exactly: the handoff's only genuinely new identity (`reviewRequestId`) is already deterministic and recomputable from stable inputs, so nothing about traceability requires observer-managed persistence. A caller needing the handoff to cross a process/session boundary is free to serialize it with its own mechanism. No `BLOCKED_ESCALATE_TO_FULL_STAGE_CONTEXT` was triggered, since no architecture evidence emerged proving persistence necessary.
+
+## Handoff model
+
+`ReferenceCorrectionHandoff = { reviewRequestId, referenceId, referenceRequestId, baselineObservationId, currentObservationId, boundedContext: BoundedAgentContextArtifact, verificationPlan: string[] }`. `boundedContext` is Prompt 7's own output (already carrying bounded fidelity mismatches, protected/preserved context, adequacy/omission/truncation, and any caller-supplied static correlation); `verificationPlan` is a fixed, four-line, human-readable statement of what will be re-checked after the edit (fresh capture, reference re-evaluation, v0.4/v0.5 re-evaluation, and the exact overall-PASS rule) — never reduced to "make it look like the screenshot." No raw reference image bytes, no full `ObservationArtifact`, and no source excerpt are ever included (verified directly by type inspection: `BoundedAgentContextArtifact`/`ReferenceRequirementFidelityResult` carry no byte-array field anywhere).
+
+## External implementation boundary
+
+Absolute, and verified by direct code inspection (both by this report's author and independently by the forked judge agent): neither `referenceCorrectionWorkflow.ts` nor anything it imports (`externalReference.ts`, `externalReferenceRuntimeBinding.ts`, `externalReferenceFidelity.ts`, `boundedAgentContextProjection.ts`, `comparisonEngine.ts`, `frontendContractEvaluation.ts`, `referenceCorrectionIdentity.ts`) contains a filesystem-write call, a `child_process` invocation, or any patch/edit mechanism. Both public workflow functions accept only already-captured `ObservationArtifact`s and already-approved/persisted contract/reference artifacts as plain in-memory values.
+
+## Controlled target design
+
+A tracked, immutable HTML template (`tests/fixtures/referenceCorrectionTarget.template.html`) with two elements: `#popup-current-page` (width controlled via a `/*POPUP_WIDTH_PX*/`-marked CSS comment) and `#destination-control` (visibility controlled via a `/*DESTINATION_DISPLAY*/`-marked CSS comment). Each browser-proof test copies this template to a fresh, repository-local disposable directory under `.my-dev-kit-workflow/prompt8-disposable-target/run-<unique>/` before use, and removes it in `afterEach` (with a full-root `afterAll` sweep as a backstop). The template's byte-identity before and after the full proof suite was verified explicitly in Proof A.
+
+## Target start/reload behavior
+
+The smallest possible mechanism: a plain Node `http.createServer` that reads the disposable file fresh from disk on every request (no caching, no restart) - satisfying this prompt's explicit preference for reload-without-restart when the target can support it. No deployment framework, process supervisor, or generic command runner was introduced.
+
+## Baseline selection
+
+For the canonical proof, `baselineObservation` and `currentObservation` (the value `prepareReferenceCorrection` measures pre-change fidelity against) are the same captured `ObservationArtifact` — the pre-change frontend is both the approved baseline and the state the initial reference mismatch is measured from, exactly as this prompt's own canonical-case guidance specifies. The workflow's types do not force this identity (a caller may supply a distinct `currentObservation` if its own architecture justifies it), but no automatic baseline approval ever occurs — the baseline contract's `sourceObservation` coherence is checked, but nothing in this module calls `approveAndPersistBaseline`.
+
+## Approved-reference requirement
+
+`prepareReferenceCorrection`/`reviewReferenceCorrectionAttempt` both fail closed (`{ok: false}`) via `isApprovedExternalReferenceArtifact` when `reference.lifecycle.state !== 'approved'` — an imported-but-unapproved reference is never treated as authoritative. Verified by a dedicated unit test.
+
+## Preparation workflow
+
+`prepareReferenceCorrection`: validate common preconditions → `evaluateReferenceCandidateFidelity` (Prompt 6) against `currentObservation` → if `state === 'not-evaluated'`, return `{status: 'blocked-not-evaluated', fidelity}` (no handoff fabricated) → otherwise `projectBoundedAgentContext({..., fidelity})` (Prompt 7) → return `{status: 'handoff-ready', handoff}`. An ambiguous/unavailable required binding does not block preparation outright; it surfaces as that specific requirement's own `unavailable`/`binding-unavailable` mismatch inside the handoff, per Prompt 6's own honest per-requirement reporting.
+
+## Post-edit review workflow
+
+`reviewReferenceCorrectionAttempt`: validate common preconditions → recompute and check `reviewRequestId` coherence (rejects a mismatched baseline/contract/reference/binding set) → `compareObservations(baseline, candidate)` (v0.4) → `evaluateReferenceCandidateFidelity(reference, candidate, bindings)` (Prompt 6) → `evaluateFrontendContract({before: baseline, after: candidate, comparison, baseline: baselineContract, change: changeContract})` (v0.5) → compose `overallState` → return the full `ReferenceCorrectionAttemptResult`.
+
+## Overall result composition
+
+`ReferenceCorrectionOverallState = 'not-evaluated' | 'pass' | 'fail'`. `fidelity.state === 'not-evaluated'` ⇒ overall `'not-evaluated'` (Prompt 6's own blocked state preserved, never collapsed into `'fail'`); otherwise `fidelity.state === 'pass' && contractEvaluation.overallVerdict === 'PASS'` ⇒ `'pass'`; anything else ⇒ `'fail'`. A structurally-incomparable baseline/candidate pair receives no separate third bucket — v0.5's own `evaluateFrontendContract` already returns `'FAIL'` for that case (its own unmodified, established precedent), reused rather than re-litigated. `approvalEligible` is a plain read-only boolean (`true` iff `overallState === 'pass'`) — never itself an approval action.
+
+Verified by dedicated unit tests and real-Chromium proofs for all three mandatory composition cases: both PASS ⇒ overall PASS; reference FAIL + contract PASS ⇒ overall FAIL; reference PASS + protected contract FAIL ⇒ overall FAIL (the mandatory proof case). Not-evaluated fidelity (via an incompatible viewport) is verified to never become overall PASS, at both the unit level and the real-Chromium blocking proof.
+
+## Correction iteration
+
+`reviewReferenceCorrectionAttempt` is called once per candidate; there is no loop, no polling, and no autonomous retry anywhere in this module or anything it calls (verified: no `setInterval`, no self-recursive call to either workflow function). Real-Chromium Proof C drives two explicit attempts from the test harness itself, proving the caller — never the observer — controls iteration.
+
+## Baseline-across-attempts rule
+
+Enforced structurally: every `reviewReferenceCorrectionAttempt` call requires the full `baselineObservation`/`baselineContract` again, `compareObservations`/`evaluateFrontendContract` are always invoked against that same baseline (never a prior candidate), and the `reviewRequestId` coherence check (now including clause content, per the identity fix below) rejects any call that supplies a different baseline/contract set under the guise of the same review.
+
+## Explicit approval behavior
+
+`approveAndPersistBaseline`/`approveExternalReference` are never imported or called anywhere in `referenceCorrectionWorkflow.ts` (confirmed by direct grep, both by this report's author and independently by the forked judge). `approvalEligible: true` is reported, never acted upon.
+
+## Real-browser success proof (Proof A)
+
+`tests/browser/referenceCorrectionWorkflow.test.ts` "Proof A": captures a real pre-change observation (popup width 223 CSS px against a 480x620 viewport, reference wants 424±4 reference px at a 2x scale ⇒ genuine FAIL, measured, not asserted), confirms the handoff's mismatch record (the controlled external actor's assertion step, proving the bounded context genuinely reached the implementation boundary), applies the controlled width-fix edit to the disposable copy only, captures a fresh real observation, and confirms `fidelity.state === 'pass'`, `contractEvaluation.overallVerdict === 'PASS'`, `overallState === 'pass'`, `approvalEligible === true`. The tracked template's byte-identity is asserted before and after.
+
+## Real-browser protected/preserved regression proof (Proof B)
+
+The controlled actor fixes the width (satisfying the reference) *and* hides `#destination-control` (a real regression). The real candidate observation genuinely shows the element hidden; `fidelity.state === 'pass'`, the `destination-control-visible` v0.5 clause genuinely evaluates to `'fail'` from real Chromium evidence, `contractEvaluation.overallVerdict === 'FAIL'`, and `overallState === 'fail'` — the mandatory proof that matching the reference is necessary but not sufficient.
+
+## Real-browser correction-iteration proof (Proof C)
+
+Attempt 1 (no edit yet) genuinely fails reference fidelity from real Chromium evidence; a fresh handoff is derived from that failed candidate's own observation id (asserted distinct from the original baseline observation id); the controlled actor applies the fix; Attempt 2 genuinely passes. Both attempts share the same `reviewRequestId` and `baselineObservationId`, have distinct `attemptId`s, and Attempt 2 carries `priorAttemptId === attempt1.attemptId`.
+
+## Blocking proof
+
+A candidate captured at an incompatible viewport (1024x768 vs. the reference's declared 480x620) produces `prepareReferenceCorrection` returning `{status: 'blocked-not-evaluated', fidelity: {blockedBy: 'incompatible'}}` — never a handoff, never a fabricated normal fidelity result.
+
+## Proof the external actor consumed the bounded context
+
+Proof A explicitly reads `prep.handoff.boundedContext.fidelity.mismatches`, locates the specific failing requirement, and asserts its `boundRuntimeTargets` includes `'popup-current-page'` *before* calling `applyControlledExternalEdit` — the deterministic actor's edit is conditioned on having found and validated the expected mismatch content, not applied blindly.
+
+## Static-correlation proof
+
+Not exercised in the real-Chromium suite this prompt (the canonical proof did not need to demonstrate static correlation to satisfy its mandatory cases), but the architecture is proven compatible: `prepareReferenceCorrection`'s handoff embeds the exact `BoundedAgentContextArtifact` Prompt 7 already supports attaching `correlations` to (via the separate, unmodified `attachRuntimeStaticCorrelations`), keyed by the same stable runtime target ids the fidelity mismatches themselves report. This is documented as a known limitation below rather than silently omitted.
+
+## Files changed
+
+New:
+- `src/domain/referenceCorrectionWorkflow.ts`
+- `src/domain/referenceCorrectionIdentity.ts`
+- `tests/unit/referenceCorrectionWorkflow.test.ts`
+- `tests/browser/referenceCorrectionWorkflow.test.ts`
+- `tests/fixtures/referenceCorrectionTarget.template.html`
+
+Modified:
+- `src/index.ts` (public export surface for the two new domain modules)
+- `docs/ARCHITECTURE.md`, `docs/CONTRACTS.md`, `docs/WORKFLOWS.md`
+
+## Tests added/changed — exact counts
+
+- `tests/unit/referenceCorrectionWorkflow.test.ts`: 19 tests (preparation: valid handoff with real mismatch numbers, unapproved-reference rejection, inadequate-reference blocking, incompatible-state blocking, ambiguous-binding handling, review-identity determinism, review-identity sensitivity to per-change-contract id, review-identity sensitivity to clause content under a same-id baseline/change contract [2 tests, added after the judge review], input immutability; review: both-PASS, reference-FAIL+contract-PASS, reference-PASS+protected-FAIL, not-evaluated-never-PASS, reviewRequestId-mismatch rejection, reviewRequestId-mismatch rejection specifically for tampered same-id clause content [added after the judge review], attempt-identity determinism/distinctness, priorAttemptId traceability, input immutability, no-automatic-approval-flag-shape).
+- `tests/browser/referenceCorrectionWorkflow.test.ts`: 4 tests (Proof A success, Proof B protected regression, Proof C correction iteration, blocking proof).
+- Unit suite: 981 pre-existing (Prompt 7 final count) + 19 new = 1000 total (`npm test`). Real-Chromium suite: 120 pre-existing + 4 new = 124 total (`npm run test:browser`), counted separately since it runs under a distinct vitest config.
+
+## Packed-candidate proof
+
+Performed a real, non-dry-run `npm pack` into a repository-local workspace (`.my-dev-kit-workflow/prompt8-pack-smoke/`, cleaned up afterward), installed the tarball into a clean, isolated `npm init`'d consumer directory, and ran a Node ESM smoke script importing the package's own installed public surface (`prepareReferenceCorrection`, `reviewReferenceCorrectionAttempt`, `buildReferenceCorrectionReviewIdentity`, `buildReferenceCorrectionAttemptIdentity`, `REFERENCE_CORRECTION_OVERALL_STATES`, plus the already-existing `projectReferenceFidelity`/`evaluateReferenceCandidateFidelity` to confirm the whole v0.7 chain remains importable) — every export resolved to the correct type, and `buildReferenceCorrectionReviewIdentity` was called and confirmed deterministic from the installed package itself, not the source checkout. `npm pack --dry-run` was also run as part of the standard validation chain, confirming `dist/domain/referenceCorrectionWorkflow.{js,d.ts,js.map}` and `dist/domain/referenceCorrectionIdentity.{js,d.ts,js.map}` are present in the tarball listing.
+
+## Validation results
+
+- `npm run typecheck` — pass, zero errors.
+- `npm run lint` — pass, zero errors/warnings.
+- `npm test` — 50 test files, 1000 tests, all pass.
+- `npm run test:browser` — 10 test files, 124 tests, all pass (clean run, no flake).
+- `npm run test:security` — pass (5 + 63 = 68 tests).
+- `npm run build` — pass, clean `tsc` compile.
+- `npm run check:docs` — pass (17 required files present, `ROADMAP.md` format intact — no implementation batches added).
+- `git diff --check` — exit 0, no whitespace errors.
+- `npm pack --dry-run` — pass; new modules confirmed present.
+- Packed-candidate real-install smoke — pass (see above).
+
+## Browser-flake incidents
+
+None. Both full `test:browser` runs during this prompt (before and after the identity fix) completed 124/124 with zero failures — no flaky-test investigation was needed this prompt.
+
+## Security / immutability results
+
+- Observer product code never edits target source — verified by direct inspection (no `fs` write/`child_process` import in `referenceCorrectionWorkflow.ts` or its dependency graph) and independently by the forked judge agent.
+- Only the test-only `applyControlledExternalEdit` function (in `tests/browser/referenceCorrectionWorkflow.test.ts`, never in `src/`) ever writes to the disposable target file.
+- The tracked fixture template's byte-identity before/after the full proof suite was explicitly asserted and passed.
+- No remote AI/network dependency was introduced anywhere in this prompt.
+- No credential-handling behavior was introduced.
+- Baseline/reference/observation/comparison/contract artifacts are never mutated by this module — every function is pure and only reads its inputs.
+- No operational filesystem path leaks into any semantic identity or result field (`reviewRequestId`/`attemptId` are pure content hashes; the handoff and attempt result carry only stable ids and evidence, never a path).
+
+## Documentation changes
+
+- `docs/CONTRACTS.md` — new "v0.7 Prompt 8 controlled end-to-end external-reference coding-agent correction workflow" section (full type shapes, workflow architecture, new/reused owners, approved-reference/baseline rules, preparation/review flow, handoff model and persistence decision, review/attempt identity including the clause-content fix, baseline-across-attempts enforcement, overall composition rule, correction-iteration/source-editing boundaries).
+- `docs/ARCHITECTURE.md` — new paragraph describing the Prompt 8 coordinator and its reuse of every prior owner.
+- `docs/WORKFLOWS.md` — "Current external-reference foundation workflow" retitled to "Prompts 1-8"; new "Current reference correction workflow" section with the full phase diagram and real-Chromium proof summary.
+- `docs/COMMANDS.md`, `docs/DEVELOPMENT.md`, `docs/CI_CD.md` — not touched (no CLI surface change, no change to how tests are run or CI packages the candidate).
+
+## Tooling incidents
+
+One real finding, caught and fixed before this report was written: the independent-judge fork (a forked review agent given the exact instruction to verify, not trust, the implementation) identified that the original `reviewRequestId` hash depended only on `baselineContract.baselineId`/`changeContract.contractId` (caller-authored labels, confirmed non-content-derived by reading `approveAndPersistBaseline`), not on the contracts' actual `clauses` content — meaning a caller could in principle swap in a same-id contract with different clauses between attempts without the coherence check detecting it. This was fixed by extending `buildReferenceCorrectionReviewIdentity` to also hash `baselineContract.clauses`/`changeContract.clauses` directly, with two new regression tests added (one for `prepareReferenceCorrection`'s identity sensitivity, one for `reviewReferenceCorrectionAttempt`'s rejection of a call whose contract clauses were tampered under a stable id). The fix was verified against the full unit suite and the real-Chromium proof suite, both passing unchanged after the change. No other issues were found by the judge across its 14-question checklist. No orchestrator product code was modified; no background/speculative subagent writes occurred; the Prompt 1 stray-fork-writes stash remains untouched throughout.
+
+## Known limitations
+
+- No static-correlation real-Chromium proof was included this prompt (the mandatory proof cases did not require it); the architecture is confirmed compatible (Prompt 7's `BoundedAgentContextArtifact.correlations` field and the fidelity mismatches' shared runtime-target-id keying already support it), documented here rather than silently claimed as proven.
+- No CLI surface exists for this workflow, consistent with v0.6 bounded-context's own library-only precedent and this prompt's own explicit guidance that a CLI is optional, not required.
+- The `reviewRequestId` coherence check validates baseline/change contract *content* (clauses) but does not itself re-verify that the supplied `reference`/`bindingDeclarations` are the literal same object instances used to originally compute `reviewRequestId` — content equality is what's checked (correctly, per this repository's identity conventions), not reference equality, which is the intended and correct behavior.
+- `currentObservation` and `baselineObservation` are type-independent parameters; nothing in the type system forces the canonical-proof convention that they be the same value. This is documented as a deliberate, justified flexibility (per the task's own "unless the architecture/review model explicitly distinguishes those identities for a justified reason" allowance), not an oversight.
+
+## Remaining risks
+
+- None identified that block this prompt's own scope. The primary forward consideration for the next stage (v0.7 implementation-completeness audit and documentation reconciliation) is verifying the full v0.7 arc's public surface, documentation, and packaged behavior against `PROJECT_DESCRIPTION`/`PROJECT_MILESTONES`/`ROADMAP` holistically — explicitly out of scope for Prompt 8 itself.
+
+## Out-of-scope confirmation
+
+This prompt did **not** implement: a viewer; drawing; annotation; automatic reference-region detection; automatic reference/runtime binding; pixel/image similarity or general image comparison; screenshot-to-code or raster-to-vector generation; source editing inside observer product code; remote AI integration of any kind; a generic coding-agent provider framework; a generic process manager or deployment system; an autonomous endless retry loop; automatic baseline approval; or automatic reference approval. Every one of these was explicitly checked against the actual implementation (not merely asserted) during the verification and independent-judge phases described above.
+
+## Exact next action
+
+v0.7 implementation-completeness audit and documentation reconciliation (not v0.8) — verifying the complete v0.7 implementation against `PROJECT_DESCRIPTION`, `PROJECT_MILESTONES`, `ROADMAP`, actual source, tests, public commands, package exports, and packed-candidate behavior, before pre-release readiness.