@dailephd/my-frontend-observer 0.9.1 → 0.10.1

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

@@ -1,234 +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.
+# 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.