@dailephd/my-frontend-observer 0.8.1

package/docs/reports/v0.7-reference-compatibility-prompt4.md

@@ -0,0 +1,234 @@
+# v0.7 Prompt 4 — Reference Applicability and Candidate-State Compatibility
+
+**VERDICT: PASS_V0_7_REFERENCE_COMPATIBILITY_PROMPT4**
+
+## Repository / branch / heads
+
+- Repository: `my-frontend-observer` (path: `Z:\Users\newuser\Projects\my-frontend-observer`)
+- Branch: `implementation/v0.7-reference-compatibility`, branched from Prompt 3's exact completed HEAD
+- Prior HEAD (Prompt 3 report commit): `271087309386342a87aeec5b47d668bc02c457c9`
+- Implementation commit (this prompt): `4da60be63c68a8c2138a0a28c1c6fa48242c2856` — "Add v0.7 Prompt 4 reference applicability and candidate-state compatibility"
+- `git merge-base --is-ancestor` confirmed the branch point is exactly Prompt 3's report commit before any implementation work began.
+
+## Git status at time of report
+
+Working tree clean except for this report file (about to be added and committed separately). `git status --short` immediately before staging the implementation showed exactly the intentional Prompt 4 file set — 15 modified source files, 3 new source files, 11 modified test files, 3 new test files, and 4 modified docs files — nothing else. `git stash list` still shows exactly one entry, the Prompt 1 stray-fork-writes stash, untouched throughout this prompt (`stash@{0}: On implementation/v0.7-reference-foundation: stray-fork-writes-preserved-for-reference: ...`).
+
+## Tooling
+
+- `@dailephd/my-dev-kit` resolved version: `1.12.2` (via `npx @dailephd/my-dev-kit --version`).
+- Fresh per-prompt code index built at `.my-dev-kit/index-prompt4/` before any implementation code was written, consulted during precedent review.
+- Package version at time of work: `0.6.0` (unchanged — no schema/package version bump this prompt).
+
+## Precedent review
+
+Before writing any Prompt 4 code, the following existing modules were read in full (source, not memory, and not the fresh index's summaries alone):
+
+- `src/domain/comparison.ts` — v0.4's frozen `ComparabilityState`/`ComparabilityReasonCode`/`ComparabilityReasonSeverity`/`ComparabilityReason`/`ComparabilityResult` vocabulary and its `isValidComparabilityReason` validator.
+- `src/domain/comparisonEngine.ts` — v0.4's `evaluateComparability(before, after)`, including its three unconditional `theme-unassessed`/`authenticated-state-unassessed`/`application-state-unassessed` reason emissions (the exact hook point for this prompt's "additive improvement" requirement).
+- `src/request/request.ts` — `NormalizedObservationRequest`/`RawObservationRequest`, `normalizeRequest()`'s validation-and-diagnostics pattern, and the existing `scrollScenario` additive-field precedent (validate raw input, push `invalid-request` diagnostics on failure, spread the field into the result only when defined).
+- `src/domain/identity.ts` — `buildRequestIdentity`'s exact "new optional trailing parameter, omitted (never `null`) from the hashed semantic view when `undefined`" pattern, applied previously for `scrollScenario`.
+- `src/domain/externalReference.ts`, `externalReferenceIdentity.ts`, `externalReferenceRegions.ts`, `externalReferenceRequirements.ts` — Prompt 1–3's additive-field/identity-parameter conventions, region/requirement validation shape, and the CLI file-loading precedent (`loadScrollScenarioFile`, `--regions-file`/`--requirements-file` wrapped-object convention vs. an unwrapped single-object convention).
+- `src/application/externalReferencePersistenceService.ts` — the `importExternalReference`/`approveExternalReference` validate-then-persist-then-carry-forward pattern used for `regions`/`requirements`, reused identically for `applicability`.
+- `src/domain/diagnostics.ts` — the single-diagnostic-code-per-validation-domain convention (`invalid-reference-region`, `invalid-reference-requirement`) that `invalid-reference-applicability` follows.
+- `src/domain/frontendContracts.ts` — confirmed `AuthoredChangeScopeCategory` reuse precedent was not applicable here (Prompt 4 introduces no new authored-scope concept).
+- `src/cli.ts` — the full `observe`/`import-reference`/`approve-reference` command implementations, their help-text blocks, and argument-parsing conventions (`--scroll-scenario-file`, `--regions-file`, `--requirements-file`) that `--state-file`/`--applicability-file` mirror.
+
+No architecture blocker was hit; no `BLOCKED_ESCALATE_TO_FULL_STAGE_CONTEXT` condition applied at any point.
+
+## Previous owners reused (not duplicated)
+
+- `ComparabilityState`/`ComparabilityReasonCode`/`ComparabilityReasonSeverity`/`ComparabilityReason`/`ComparabilityResult` (from `domain/comparison.ts`) — reused wholesale as the compatibility result's `compatibility` field type. No parallel "compatibility state" enum was invented.
+- `assessOptionalComparabilityDimension` — newly extracted from `comparisonEngine.ts` as an exported pure helper, and reused by both v0.4's `evaluateComparability` and the new `evaluateReferenceCandidateCompatibility`. This is the one point of actual code-sharing between the Observation↔Observation and Reference↔Observation compatibility checks; everything else about the two functions (their input types, their result envelopes) remains separately owned.
+- `AuthenticatedState`/`ExplicitStateDimensions`/label pattern (`domain/explicitState.ts`) — one new, small, independently-owned module shared by both `ExternalReferenceApplicability` (via `extends ExplicitStateDimensions`) and `ObservationArtifact.requestConfig.explicitState`. This is a genuinely new vocabulary (nothing pre-existing captured "explicit state identity"), not a duplication of anything.
+- `isValidStateLabel`/`STATE_LABEL_PATTERN` reuse of the existing `^[A-Za-z0-9_-]{1,64}$` convention already used for target names/region ids — not reinvented.
+- `DIAGNOSTIC_CODES`/`DIAGNOSTIC_SEVERITY` (from `domain/diagnostics.ts`) — extended additively with one new code (`invalid-reference-applicability`), not a new diagnostics subsystem.
+
+## State/applicability model
+
+```ts
+// domain/explicitState.ts
+export const STATE_LABEL_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+export const AUTHENTICATED_STATE_VALUES = ['authenticated', 'unauthenticated'] as const;
+export type AuthenticatedState = (typeof AUTHENTICATED_STATE_VALUES)[number];
+export interface ExplicitStateDimensions {
+  theme?: string;
+  applicationState?: string;
+  authenticatedState?: AuthenticatedState;
+}
+// isValidExplicitStateDimensions: rejects unknown keys, validates each present
+// field, and requires at least one declared dimension.
+
+// domain/externalReferenceApplicability.ts
+export const APPLICABLE_VIEWPORT_MIN = 200;
+export const APPLICABLE_VIEWPORT_MAX = 3840;
+export interface ApplicableViewport { width: number; height: number }
+export interface ExternalReferenceApplicability extends ExplicitStateDimensions {
+  viewport?: ApplicableViewport;
+}
+// isValidExternalReferenceApplicability: its own independent validator (not a
+// delegation to isValidExplicitStateDimensions, whose "at least one of three"
+// rule would incorrectly reject a viewport-only object).
+```
+
+This is a bounded, closed shape — never an arbitrary `Record<string, unknown>` metadata bag. Unknown fields are rejected outright by both validators. Nothing in either module reads a browser, the DOM, a screenshot, a URL, source code, a filename, an accessibility label, `localStorage`, or a cookie; both are pure structural validators over caller-supplied plain objects.
+
+## Exact image dimensions vs. applicable viewport
+
+`ExternalReferenceImageReference.width/height` (Prompt 1, unchanged) continues to describe only the reference image file's own pixel dimensions, detected from header bytes. `ExternalReferenceApplicability.viewport` is a wholly distinct, independently-validated field describing the CSS-pixel runtime viewport the design represents. Neither field is derived from the other anywhere in the codebase; a reference image may be captured at any resolution/DPI relative to its declared applicable viewport, and `isValidExternalReferenceApplicability` never consults `image.width`/`image.height`.
+
+## Provenance / state-identity source
+
+`theme`, `applicationState`, and `authenticatedState` are accepted only as caller/config-supplied JSON input, on both the reference-import side (`--applicability-file`) and the observation side (`--state-file`). Neither `chromiumAdapter.ts`, `evidenceCapture.ts`, nor any other browser-facing module was touched by this prompt — there is no automatic state-detection code path anywhere in the repository, and none was added. `authenticatedState` is restricted to the closed two-value vocabulary `authenticated`/`unauthenticated`; nothing in `ExplicitStateDimensions`/`ExternalReferenceApplicability` can carry a password, token, cookie, session id, API key, or authorization header — the type system has no field for any of them, and the validators reject any unrecognized key.
+
+## Compatibility result model
+
+```ts
+// domain/externalReferenceCompatibility.ts
+export interface ReferenceCandidateCompatibilityResult {
+  referenceId: string;
+  referenceRequestId: string;
+  candidateObservationId: string;
+  candidateRequestId: string;
+  compatibility: ComparabilityResult; // reused v0.4 type: { state, reasons[] }
+}
+export function evaluateReferenceCandidateCompatibility(
+  reference: ExternalReferenceArtifact,
+  candidate: ObservationArtifact,
+): ReferenceCandidateCompatibilityResult;
+```
+
+Structured, never boolean, never a numeric/visual score. `compatibility.reasons` carries per-dimension `{ code, severity, message, referenceValue?, candidateValue? }` records; `referenceValue`/`candidateValue` are populated only on a mismatch reason (never on an unassessed reason, since there is nothing to compare). The function is pure and synchronous — verified by an explicit "same inputs produce a deep-equal result" test.
+
+## Blocking / unassessed / missing-dimension semantics (behaviors A–I)
+
+All nine required behaviors are implemented via the single shared helper `assessOptionalComparabilityDimension(mismatchCode, unassessedCode, referenceValue, candidateValue, mismatchMessage, unassessedMessage)`:
+
+- Both values defined and equal → no reason emitted (comparable on that dimension).
+- Both values defined and different → a `blocking`-severity mismatch reason, with `referenceValue`/`candidateValue` populated (behaviors B, D, E, F for viewport/theme/application-state/authenticated-state mismatches — all four dimensions use the identical rule).
+- Either value `undefined` (reference constrains but candidate lacks it, reference omits it entirely, or both omit it) → an `unassessed`-severity reason, **never** a fabricated match and **never** a fabricated mismatch (behaviors G, H, I). This is fail-closed: an unassessed dimension never contributes to `compatible`, but it also never forces `incomparable` — only an actual detected mismatch does that.
+- Overall `compatibility.state` is `incomparable` if any reason is `blocking`, else `comparable-with-warnings` if any is `warning` (this prompt introduces no warning-severity reasons of its own — only blocking/unassessed), else `comparable`.
+- A reference declaring no `applicability` at all produces a fully unassessed result across every dimension — verified explicitly; Prompt 1/2/3 references remain fully usable, just unassessed for compatibility until `applicability` is authored.
+
+All nine behaviors (A–I) plus the "no applicability at all" and "pure function" cases are covered by dedicated tests in `tests/unit/externalReferenceCompatibility.test.ts`.
+
+## v0.4 reuse / refactor proof
+
+`assessOptionalComparabilityDimension` was extracted directly out of the body of `evaluateComparability` (its three `theme`/`authenticatedState`/`applicationState` blocks previously called `add('theme-unassessed', ...)` etc. unconditionally). After extraction:
+
+- `evaluateComparability`'s three state-dimension blocks now call the shared helper against `before.requestConfig.explicitState`/`after.requestConfig.explicitState`.
+- `evaluateReferenceCandidateCompatibility` calls the identical helper against `reference.applicability`/`candidate.requestConfig` (viewport) and `candidate.requestConfig.explicitState` (theme/authenticatedState/applicationState).
+- The reason-code sort rule (`reasons.sort((a, b) => COMPARABILITY_REASON_CODES.indexOf(a.code) - COMPARABILITY_REASON_CODES.indexOf(b.code))`) and the `state` derivation (`hasBlocking → incomparable`, else `hasWarning → comparable-with-warnings`, else `comparable`) are duplicated verbatim in `externalReferenceCompatibility.ts` (deliberately not extracted into a second shared helper, since a two-line duplication was judged lower-risk than adding a third shared dependency between v0.4 and v0.7 module boundaries for something this small).
+
+## Old-behavior-unchanged proof
+
+The pre-existing frozen regression test in `tests/unit/comparisonEngine.test.ts` (`'is comparable with no reasons beyond the always-present unassessed dimensions'`) asserts `result.reasons.map((r) => r.code)` equals exactly `['theme-unassessed', 'authenticated-state-unassessed', 'application-state-unassessed']` for a before/after pair with no `explicitState` on either side — this test was **not modified** and still passes unchanged, because neither observation declares `explicitState`, so the shared helper's "either value undefined" branch fires for all three dimensions, exactly reproducing the pre-Prompt-4 unconditional-unassessed behavior. Three new tests were added alongside it exercising the additive "both declare, match", "both declare, mismatch", and "only one declares" cases. Full v0.1–v0.6 regression suites (unit + browser + security) were re-run and are unaffected — see Validation below.
+
+## Identity impacts
+
+- `buildExternalReferenceRequestIdentity(imageSha256, format, width, height, supersedesReferenceId?, regions?, requirements?, applicability?)` — `applicability` is the new 8th, final, optional parameter, omitted entirely (never `null`) from the hashed semantic view when `undefined`. Verified: `buildExternalReferenceRequestIdentity(...args)` and `buildExternalReferenceRequestIdentity(...args, undefined)` produce byte-identical hashes.
+- `buildRequestIdentity(request)` — `request.explicitState` is now included in the semantic view only when present (`...(request.explicitState ? { explicitState: request.explicitState } : {})`), mirroring the existing `scrollScenario` treatment exactly. The pre-existing frozen regression vector (`buildRequestIdentity(baseRequest())` === a specific fixed hash string) is asserted unchanged by a new test in `identity.test.ts`.
+- No operational file path (`--state-file`'s or `--applicability-file`'s path argument) enters either identity function — both functions take only already-parsed, in-memory values, never a path.
+
+## Schema / version decisions
+
+No `SCHEMA_VERSION`/`EXTERNAL_REFERENCE_SCHEMA_VERSION` bump. Both new fields (`requestConfig.explicitState`, `ExternalReferenceArtifact.applicability`) are purely additive and optional, following the exact precedent set by `scrollScenario` (Prompt/Batch 3) and `regions`/`requirements` (v0.7 Prompts 2/3), none of which bumped their respective schema versions either.
+
+## CLI changes
+
+- `observe` gains `--state-file <json-file>`: unwrapped `{theme?, applicationState?, authenticatedState?}` object, no wrapper field, mirroring `--scroll-scenario-file`'s file-loading shape exactly (read → JSON.parse → plain-object-root check only; all semantic validation deferred to `normalizeRequest()`/`isValidExplicitStateDimensions`). Compatible with `--target`/`--targets-file`/`--scroll-scenario-file` (independent, non-conflicting flag).
+- `import-reference` gains `--applicability-file <json-file>`: unwrapped raw applicability object (not a `{"requirements": [...]}`-style wrapper, since applicability is a single object, not a named list) — read → JSON.parse → plain-object-root check only; all semantic validation deferred to `isValidExternalReferenceApplicability`.
+- Both commands' `--help` text, and `approve-reference --help`, were updated to document the new flag and its failure modes.
+- `import-reference`/`approve-reference` success output gained one new line: `Applicability: declared|none`.
+- CLI code owns only flag syntax, file reading, JSON parsing, and object-root shape validation for both new flags — zero semantic validation logic lives in `cli.ts` itself; every actual rule (label pattern, authenticated-state vocabulary, viewport bounds, "at least one dimension") is owned by `domain/explicitState.ts`/`domain/externalReferenceApplicability.ts`.
+
+## Persistence decision
+
+No new persisted artifact kind was introduced for the compatibility result. `evaluateReferenceCandidateCompatibility` is a pure, synchronous, on-demand function over two already-persisted artifacts (an `ExternalReferenceArtifact` and an `ObservationArtifact`), invoked directly by a caller (application code, a future CLI command, or a test) — never something the observer writes to disk automatically. Rationale: the result is cheap to recompute deterministically from its two inputs; persisting it would introduce a drift risk (a re-imported/re-observed artifact could silently disagree with a stale persisted compatibility record) with no corresponding benefit at this stage of the architecture. This decision may be revisited only if a later v0.7 prompt's architecture proves persistence necessary — documented per instruction, not assumed.
+
+## Files changed
+
+New:
+- `src/domain/explicitState.ts`
+- `src/domain/externalReferenceApplicability.ts`
+- `src/domain/externalReferenceCompatibility.ts`
+- `tests/unit/explicitState.test.ts`
+- `tests/unit/externalReferenceApplicability.test.ts`
+- `tests/unit/externalReferenceCompatibility.test.ts`
+
+Modified:
+- `src/domain/comparison.ts` (4 new reason codes, 2 new optional `ComparabilityReason` fields)
+- `src/domain/comparisonEngine.ts` (extracted+exported `assessOptionalComparabilityDimension`; `evaluateComparability` now uses it additively)
+- `src/domain/diagnostics.ts` (`invalid-reference-applicability` code)
+- `src/domain/externalReference.ts` (`applicability?` field + validation)
+- `src/domain/externalReferenceIdentity.ts` (`applicability` identity parameter)
+- `src/domain/identity.ts` (`explicitState` identity inclusion)
+- `src/domain/schema.ts` (`requestConfig.explicitState` defense-in-depth validation)
+- `src/request/request.ts` (`explicitState` request field + validation)
+- `src/application/externalReferencePersistenceService.ts` (`applicability` import/approve wiring, `hasApplicability` result field)
+- `src/cli.ts` (`--state-file`, `--applicability-file`, help text, output lines)
+- `src/index.ts` (public export surface for all of the above)
+- `docs/ARCHITECTURE.md`, `docs/CONTRACTS.md`, `docs/WORKFLOWS.md`, `docs/COMMANDS.md`
+- 11 existing test files extended with Prompt 4 coverage (see Tests below)
+
+## Tests
+
+857 unit tests total (779 pre-existing + 78 new/extended this prompt), across:
+- New: `explicitState.test.ts` (10 tests), `externalReferenceApplicability.test.ts` (8 tests), `externalReferenceCompatibility.test.ts` (14 tests covering behaviors A–I plus identity/purity checks).
+- Extended: `comparisonEngine.test.ts` (+3, v0.4 additive-assessment behavior), `identity.test.ts` (+4, `explicitState` identity), `externalReferenceIdentity.test.ts` (+4, `applicability` identity), `externalReference.test.ts` (+4, `applicability` schema validation), `schema.test.ts` (+3, `requestConfig.explicitState` validation), `request.test.ts` (+7, `explicitState` request normalization), `externalReferencePersistenceService.test.ts` (+4, import/approve applicability wiring), `cli.test.ts` (+9, `--state-file` CLI boundary + help text), `cliExternalReference.test.ts` (+6, `--applicability-file` CLI boundary + end-to-end import/approve).
+
+## Validation results
+
+All commands run from the repository root, after the implementation commit:
+
+- `npm run typecheck` — pass, zero errors.
+- `npm run lint` — pass, zero errors/warnings.
+- `npm test` — 45 test files, 857 tests, all pass.
+- `npm run build` — pass, clean `tsc` compile.
+- `npm run check:docs` — pass (17 required files present, `ROADMAP.md` format intact).
+- `git diff --check` — exit 0 (only benign LF→CRLF normalization notices on Windows checkout, no actual whitespace-error content).
+- `npm pack --dry-run` — pass; new `dist/domain/explicitState.js`, `externalReferenceApplicability.js`, `externalReferenceCompatibility.js` (and their `.d.ts`/`.js.map`) confirmed present in the tarball listing alongside updated `dist/index.d.ts`.
+- `npm run test:security` — pass (5 + 63 = 68 tests: `policy.test.ts` + real-Chromium `chromiumAdapter.test.ts`), run because this prompt changes state/config input surface.
+- `npm run test:browser` — pass (9 files, 120 tests, real Chromium), run as full regression confirmation.
+
+## Regression results
+
+- Full v0.1–v0.6 unit suite: unaffected, all passing (779 pre-existing tests unchanged in assertions, all still passing verbatim).
+- Full real-Chromium browser suite: 120/120 passing, unaffected.
+- Full security suite: 68/68 passing, unaffected.
+- The one pre-existing frozen `evaluateComparability` regression test (no-`explicitState` case) passes unchanged, proving the v0.4 additive-assessment change is genuinely additive, not a behavior change for any historical/legacy observation pair.
+- The one pre-existing frozen `buildRequestIdentity` regression hash (`baseRequest()` with no `scrollScenario`/`explicitState`) passes unchanged, proving the `explicitState` identity extension is genuinely additive.
+
+## Security impact
+
+- No new external input surface beyond local JSON files the caller already controls (same trust boundary as `--targets-file`/`--scroll-scenario-file`/`--regions-file`/`--requirements-file`).
+- `authenticatedState`'s closed two-value vocabulary and the complete absence of any credential/token/cookie/session-id field in `ExplicitStateDimensions`/`ExternalReferenceApplicability` were verified by direct type/field inspection — there is no field anywhere in either interface capable of holding a secret.
+- `test:security` (policy + real-Chromium adapter tests) re-run and passing, confirming no regression to the existing safety/navigation policy surface (this prompt touches none of that code).
+
+## Documentation changes
+
+- `docs/CONTRACTS.md` — new "v0.7 Prompt 4 reference applicability and candidate-state compatibility" section (full type shapes, key rules, image-vs-viewport distinction, v0.4 reuse proof, persistence decision, identity impact, CLI summary).
+- `docs/ARCHITECTURE.md` — new paragraph in the "Planned v0.7–v0.10" section describing the Prompt 4 module additions and the v0.4 extraction/reuse story.
+- `docs/WORKFLOWS.md` — "Current external-reference foundation workflow" section retitled to "Prompts 1-4" and extended with `--applicability-file`/`--state-file` steps and the new compatibility-evaluation paragraph.
+- `docs/COMMANDS.md` — `observe` options list extended with `--state-file`.
+
+## Tooling incidents
+
+None this prompt. No orchestrator was invoked (direct-implementation mode used throughout, consistent with Prompts 2–3); no background/speculative subagent writes occurred; the Prompt 1 stray-fork-writes stash remains untouched, unapplied, and unmined as precedent.
+
+## Out-of-scope confirmation
+
+This prompt implements no region/runtime binding, no candidate/reference geometry comparison, no fidelity PASS/FAIL evaluation, no style/color/typography comparison, no image/pixel similarity, no change to source correlation, no coding-agent correction logic, no rerender loop, no viewer, no annotation UI, and no automatic state/authentication detection of any kind. `evaluateReferenceCandidateCompatibility` reads only `reference.applicability` and `candidate.requestConfig` (viewport/explicitState) — it never reads `reference.regions`, `reference.requirements`, or any target/geometry evidence from the candidate.
+
+## Known limitations
+
+- Applicable-viewport comparison is an exact string-equality check on `"WxH"` — there is no tolerance/near-match concept for viewport compatibility (deliberately; a viewport is either the one the reference represents or it isn't, unlike the pixel-tolerance semantics that belong to Prompt 3's region-property requirements).
+- `evaluateReferenceCandidateCompatibility` has no CLI command of its own yet (no `check-compatibility`-style entry point) — it is exposed only as a library function via `src/index.ts`, since Prompt 4's scope was the domain model and its reuse story, not a new user-facing workflow entry point. A future prompt may add a CLI surface once region binding (Prompt 5) makes an end-to-end command meaningful.
+
+## Remaining risks
+
+- None identified that block this prompt's own scope. The main forward risk is Prompt 5 (region↔runtime-target binding) needing to compose region-level and page-level (this prompt's) compatibility results coherently — flagged for that prompt's own precedent review, not something this prompt can or should preempt.
+
+## Exact next action
+
+v0.7 Prompt 5 — explicit reference-region ↔ runtime-target binding.

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

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