@dailephd/my-frontend-observer 0.9.1 → 0.10.1

package/docs/reports/v0.7-reference-fidelity-prompt6.md

@@ -1,216 +1,216 @@
-# v0.7 Prompt 6 — Structured Reference-vs-Candidate Fidelity Evaluation
-
-**VERDICT: PASS_V0_7_REFERENCE_FIDELITY_PROMPT6**
-
-## Repository / branch / heads
-
-- Repository: `my-frontend-observer` (path: `Z:\Users\newuser\Projects\my-frontend-observer`)
-- Branch: `implementation/v0.7-reference-fidelity`, branched from the exact completed Prompt 5 HEAD
-- Starting HEAD (branch point, Prompt 5 report commit): `74c710daa62cd5a56f1b1b2eac3a43d24dfe69fb`
-- Prompt 5 base HEAD confirmed to contain both required commits: `74cc148` (implementation) and `74c710d` (report), and the full completed Prompt 1–4 lineage — verified via `git log --oneline` before branching.
-- Implementation commit (this prompt): `91f5e736a1a8472984b0c8c7a7e179e307f1a5ce` — "Add v0.7 Prompt 6 structured reference-vs-candidate fidelity evaluation"
-- 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 5 report HEAD; `git stash list` showed exactly the one preserved Prompt 1 stray-fork-writes entry. The branch was created with `git checkout -b implementation/v0.7-reference-fidelity` and ancestry verified with `git merge-base --is-ancestor 74c710d 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).
-
-## Tooling
-
-- Resolved latest published `@dailephd/my-dev-kit`: `1.12.3`, pinned exactly via `npx -y @dailephd/my-dev-kit@1.12.3`.
-- Fresh Prompt 6 repository index built under a repository-local, gitignored root: `.my-dev-kit-context/index-prompt6/` (57 files, 868 symbols indexed) — not reused from Prompt 1–5's indexes.
-
-## Prompt 1–5 contracts verified
-
-Read directly (source, not memory) before writing any code:
-
-- `src/domain/externalReferenceRequirements.ts` — the full Prompt 3 requirement/tolerance/expectation/adequacy model, including the exact `RELATIONSHIP_FAMILY_GROUPS`-scoped lookup fix and `deriveReferenceRequirementAdequacy`'s "100% unavailable requirements ⇒ inadequate" rule.
-- `src/domain/externalReferenceRegions.ts` — `ReferenceRegionGeometry`'s exact field set (`x`/`y`/`width`/`height`/`right`/`bottom`/`centerX`/`centerY`), reused as the shared shape for both reference and (converted) candidate geometry.
-- `src/domain/externalReference.ts` — `isImportedExternalReferenceArtifact`/`isApprovedExternalReferenceArtifact` type guards, reused to read image dimensions uniformly across both lifecycle variants without duplicating validation logic.
-- `src/domain/externalReferenceCompatibility.ts` (Prompt 4) — `evaluateReferenceCandidateCompatibility`'s exact signature and result shape, reused verbatim as the compatibility gate.
-- `src/domain/externalReferenceRuntimeBinding.ts` (Prompt 5) — `evaluateReferenceRuntimeBindings`'s exact signature/result shape and its own case-insensitive target-name-resolution convention (mirrored, not imported, per the established per-module small-helper convention).
-- `src/domain/schema.ts` (v0.2) — `TargetGeometry`, `TargetVisibility`, `TargetResolution`/`TargetSelectionStatus`, and `ObservationArtifact.targetEvidence`'s exact-configured-name keying.
-- `src/domain/comparisonEngine.ts` (v0.4) — `targetPresence` (already additively exported by Prompt 5), reused rather than re-derived.
-- `src/domain/relationships.ts` (v0.4) — `deriveLayoutRelationships`, `PairwiseLayoutRelationship`'s `subjectTarget`/`relatedTarget` fields, `UnresolvedRelationshipTarget`/`UNRESOLVED_TARGET_REASONS` (confirming hidden targets are already excluded from relationship derivation by v0.4 itself), and every pairwise relationship-family constant.
-- `src/domain/frontendContracts.ts`/`frontendContractEvaluation.ts` (v0.5) — `CLAUSE_RESULT_STATUSES`/`ClauseEvaluationResult` (the `pass`/`fail`/`unavailable`/`conflict` precedent), `evaluateFrontendContract`'s overall-verdict aggregation rule (`every clause pass && no unexpected changes ⇒ PASS`), `clauseMode`'s `required`/`permitted` handling (confirming it is a v0.5-only, directional-primitive-specific concept never mirrored in Prompt 3's own expectation/adequacy derivation), and `toleranceToPx`'s percent-denominator convention (`(amount/100) * abs(beforeValue)`), reused independently for reference-image-pixel units.
-- `src/application/comparisonService.ts` — the exact `compareAndPersistFromArtifactRoots` application-layer shape (read-both-artifacts-then-delegate-to-the-pure-function), mirrored for `evaluateReferenceCandidateFidelityFromArtifactRoots`.
-- `src/cli.ts` — the full `evaluate-contract` command (help text, argument parser, `--enforce` exit-code handling) as the direct precedent for `evaluate-reference-fidelity`, and every existing `--*-file` loader (`loadRegionsFile`/`loadRequirementsFile`/`loadApplicabilityFile`) as the precedent for `loadBindingsFile`.
-
-No architecture blocker was hit; no `BLOCKED_ESCALATE_TO_FULL_STAGE_CONTEXT` condition applied at any point.
-
-## Precedent review outcomes
-
-- **A. Result vocabulary** — `pass`/`fail`/`unavailable` reused as the same honest three-state shape v0.5's `CLAUSE_RESULT_STATUSES` already established, but as an independently-owned constant (`REFERENCE_REQUIREMENT_FIDELITY_STATUSES`) deliberately excluding `'conflict'` — Prompt 6 has no cross-requirement authoring-conflict concept (each requirement is evaluated independently against its own subject).
-- **B. Overall fidelity** — a compatible/evaluable pair reaches `state: 'pass'` only when every requirement result is `'pass'`; any `'fail'`/`'unavailable'` forces `'fail'`. An incompatible or reference-inadequate pair never reaches that computation at all — a distinct `not-evaluated` state, with `blockedBy: 'reference-inadequate' | 'incompatible'`, is returned instead.
-- **C. Relationship evaluation** — reuses Prompt 2's `deriveReferenceRequirementExpectation` (reference side) and v0.4's `deriveLayoutRelationships` (candidate side) exactly; no duplicated geometry predicate exists anywhere in the new module.
-- **D. Value derivation** — reference expected values always come from `deriveReferenceRequirementExpectation`/`deriveReferenceRequirementMeasurement` (Prompt 3), never recomputed by hand; candidate values always come from `ObservationArtifact.targetEvidence`'s existing `TargetGeometry`/`TargetVisibility` evidence, never a second derivation.
-- **E. Persistence** — no new persisted artifact family; documented decision below.
-
-## Fidelity evaluator type/function names
-
-- `domain/externalReferenceFidelity.ts`: `evaluateReferenceCandidateFidelity(reference, candidate, bindingDeclarations, options?)` → `{ ok: true; evaluation: ReferenceCandidateFidelityEvaluation } | { ok: false; reason: string }`.
-- `application/referenceFidelityEvaluationService.ts`: `evaluateReferenceCandidateFidelityFromArtifactRoots(referenceRoot, candidateRoot, bindingDeclarations, options?)` — the CLI-facing, artifact-root-reading counterpart.
-- CLI: `evaluate-reference-fidelity`.
-
-## Evaluation ordering / gates
-
-Frozen order, exactly as specified and never reordered: reference structural validation (`isValidExternalReferenceArtifact`) → candidate structural validation (`isValidObservationArtifact`) → binding-declaration structural validation (`isValidReferenceRuntimeBindingDeclarations`, invoked inside the Prompt 5 evaluator) → Prompt 3 reference adequacy (`deriveReferenceRequirementAdequacy`) → Prompt 4 compatibility (`evaluateReferenceCandidateCompatibility`) → Prompt 5 binding evaluation (`evaluateReferenceRuntimeBindings`) → per-requirement candidate-evidence/coordinate-mapping checks → per-requirement tolerance/relationship comparison → overall result.
-
-The first three (structural) failures return `{ ok: false, reason }` — a caller/config error, never a fidelity outcome. `adequacy.status === 'inadequate'` and `compatibility.state === 'incomparable'` each short-circuit to `state: 'not-evaluated'` with `requirementResults: []` — verified by dedicated tests (behaviors G/H). `adequacy.status === 'partial'` does **not** block evaluation; it proceeds normally, and the specific reference-side-unavailable requirements independently re-derive their own `unavailable` result at the per-requirement stage (not looked up from the adequacy result — verified by the "reference itself does not exhibit" test, which requires a second, evaluable requirement to keep adequacy at `partial` rather than `inadequate`, confirming the two computations are genuinely independent).
-
-## Coordinate-mapping model
-
-One explicit, deterministic full-frame scale: `scaleX = referenceImageWidth / applicableViewportWidth`, `scaleY = referenceImageHeight / applicableViewportHeight`, derived once per evaluation call from `reference.applicability.viewport` (Prompt 4) and the reference image's own pixel dimensions (Prompt 1, read uniformly across both lifecycle variants via the existing `isImportedExternalReferenceArtifact`/`isApprovedExternalReferenceArtifact` type guards). Candidate `TargetGeometry` (CSS pixels) is reshaped into a `ReferenceRegionGeometry`-shaped value (adding `centerX`/`centerY`, computed identically to `deriveReferenceRegionGeometry`) both raw and scaled; horizontal fields (`x`/`width`/`right`/`centerX`) always scale by `scaleX`, vertical fields (`y`/`height`/`bottom`/`centerY`) always scale by `scaleY` — this falls out automatically from the per-field conversion, never a hand-picked per-property axis table. `region-measurement` subjects reuse Prompt 3's exact `deriveReferenceRequirementMeasurement` on the converted geometries directly, rather than a parallel "runtime version" of the same gap/delta formulas.
-
-## Image/viewport scale rule and aspect-ratio rule
-
-`ASPECT_RATIO_MAPPING_TOLERANCE = 0.01` (1% relative difference between `scaleX` and `scaleY`) is an independently-owned, tiny coordinate-mapping-validity constant — never a user-authored Prompt 3 design tolerance. If `scaleX`/`scaleY` disagree beyond this bound, or `reference.applicability.viewport` is absent entirely, `deriveCoordinateScale` returns `{ ok: false, reason }` and every numeric (`region-property`/`region-measurement`) requirement in that evaluation becomes `unavailable`/`coordinate-mapping-unavailable` — verified by dedicated tests (behaviors E and F). No cropping, offset, rotation, or perspective registration is implemented anywhere; only this single bounded full-frame check. Categorical `region-relationship` requirements are unaffected by an unavailable scale (they never call `deriveCoordinateScale` at all).
-
-## Numeric precision rule
-
-No intermediate rounding anywhere in the arithmetic path (`referenceValue`, `candidateRawValue`, `candidateValue`, `delta` are all plain JS `number`s carried through at full floating-point precision). Tolerance comparison is a single `Math.abs(delta) <= allowed` check with no added epsilon — verified by the exact-boundary test (a delta equal to the tolerance passes; a delta a tiny fraction over it fails), matching the task's own worked boundary example (428 passes, 428.0001 fails against a reference of 424 ± 4).
-
-## Requirement result vocabulary
-
-`REFERENCE_REQUIREMENT_FIDELITY_STATUSES = ['pass', 'fail', 'unavailable']`. `reasonCode` (one of `reference-evidence-unavailable`, `reference-relationship-not-exhibited`, `binding-unavailable`, `candidate-evidence-unavailable`, `coordinate-mapping-unavailable`) and `detail` are present only when `status === 'unavailable'` — a `fail` is already fully explained by its numeric (`referenceValue`/`candidateRawValue`/`candidateValue`/`delta`/`tolerance`) or relationship (`expectedRelationship`/`actualRelationship`) fields, so no reason code is needed there.
-
-## Overall fidelity vocabulary
-
-`REFERENCE_FIDELITY_STATES = ['not-evaluated', 'pass', 'fail']`, with `REFERENCE_FIDELITY_BLOCK_REASONS = ['reference-inadequate', 'incompatible']` populated only when `state === 'not-evaluated'`. There is no separate "partial pass" bucket once evaluation has actually run: any `unavailable` requirement result forces `state: 'fail'`, satisfying "any required fail or unavailable must prevent overall PASS" (section 34) without inventing a fourth top-level state — an `unavailable`-only result set is honestly reported as `'fail'` (i.e. "not confirmed to satisfy every selected requirement"), which the report's per-requirement breakdown (`pass`/`fail`/`unavailable` counts) then disambiguates for a human/caller.
-
-## Region-property evaluation
-
-Reads the bound target's `TargetGeometry` from `targetEvidence`, requires `TargetVisibility.visible === true` (a `bound`-but-hidden target's geometry is treated as unusable, never fabricated as meaningful — see "hidden target" below), converts to both raw and reference-space geometry, and reads `[subject.property]` off each. Exactly Prompt 3's supported vocabulary (`x`/`y`/`width`/`height`/`right`/`bottom`/`centerX`/`centerY`) — no new property was added.
-
-## Relationship evaluation
-
-Confirms the reference itself exhibits its own selected relationship first (`deriveReferenceRequirementExpectation`'s `matches` field) — if not, `unavailable`/`reference-relationship-not-exhibited` (a reference-authoring problem, never a candidate `fail`). Then resolves both bound targets, calls `deriveLayoutRelationships` once over the whole candidate observation, and looks up the pairwise record for the bound-target pair **scoped to the exact requested relationship family** via an independently-owned, third duplicate of the `RELATIONSHIP_FAMILY_GROUPS` shape (already duplicated by `frontendContractEvaluation.ts` and `externalReferenceRequirements.ts`) — never "the first record for this pair regardless of family," the exact bug class Prompt 3 fixed. A record only derivable in the reversed target order is `unavailable`, never auto-flipped, mirroring Prompt 3's identical reference-side handling. Verified by dedicated tests for pass (M), fail (N), and family-scoping (O, using two regions/targets that simultaneously satisfy multiple relationship families to prove the lookup picks the correct family's record).
-
-## Spacing/alignment (measurement) evaluation
-
-Supported: exactly Prompt 3's `REFERENCE_REQUIREMENT_MEASUREMENTS` (`vertical-gap`/`horizontal-gap`/`center-x-delta`/`center-y-delta`/`left-edge-delta`/`right-edge-delta`), evaluated via `deriveReferenceRequirementMeasurement` on converted (both raw and reference-space) geometries — no generic geometry expression language was introduced. A geometrically-undefined gap (targets overlapping on the relevant axis) is `unavailable`, mirroring Prompt 3's reference-side treatment of the identical situation. Verified by a dedicated horizontal-gap pass/fail test (behavior P).
-
-## Tolerance behavior
-
-Reused exactly, never redefined. A single rule, `Math.abs(delta) <= allowed`, covers all three Prompt 3 kinds: `exact` ⇒ `allowed = 0`; `absolute-reference-px` ⇒ `allowed = tolerance.amount` (already in reference-image pixels); `percent` ⇒ `allowed = (tolerance.amount / 100) * Math.abs(referenceValue)`, mirroring v0.5's own `toleranceToPx` "may vary by up to N%" convention exactly, independently reimplemented in reference-image-pixel units (never imported — v0.5's `ContractTolerance` is a different, CSS-pixel-implicit unit). Verified by dedicated tests for `exact`, `absolute-reference-px`, `percent`, and the exact tolerance boundary (behavior C, plus the task's own worked example reproduced verbatim in both the domain and CLI test suites).
-
-## Unavailable-evidence behavior
-
-Unavailable evidence never becomes a fabricated zero/false/pass/fail anywhere in this module: an unbound/ambiguous/unavailable Prompt 5 binding, an invisible or evidence-less bound target, an unestablishable coordinate scale, and an undervied/not-exhibited reference relationship are each their own explicit `unavailable` result with a distinguishing `reasonCode` — never silently defaulted, never a `fail`.
-
-## Compatibility-blocker behavior
-
-`evaluateReferenceCandidateCompatibility` is called once; `state === 'incomparable'` short-circuits the whole evaluation to `state: 'not-evaluated'`, `blockedBy: 'incompatible'`, `requirementResults: []`, with the full `ComparabilityResult` embedded verbatim in the `compatibility` field for the caller to inspect the reason. No geometry delta, spacing delta, relationship comparison, or requirement PASS/FAIL is ever computed in this case. Verified by a dedicated test (behavior G, an incompatible candidate viewport).
-
-## Binding-blocker behavior
-
-`evaluateReferenceRuntimeBindings` is called once (after the compatibility gate has already confirmed a non-incomparable pair, so it is guaranteed not to re-trigger its own internal compatibility short-circuit); its `ok: false` result (a structural declaration/artifact problem) propagates as this function's own `ok: false`. For each requirement, every dependent reference region's binding must be `bound` — `ambiguous`, `unavailable`, or simply absent from the supplied declarations all produce `unavailable`/`binding-unavailable` for that requirement, never a guessed target and never an auto-bind based on geometry or names. Verified by dedicated tests for ambiguous (J), unavailable/not-found (K), and undeclared bindings.
-
-## Hidden-target decision
-
-A `bound` target (Prompt 5's question: does a stable correspondence exist) whose `TargetVisibility.visible !== true` — including when visibility evidence itself is unavailable — is treated as having no usable geometry: `unavailable`/`candidate-evidence-unavailable`, never a fabricated zero-geometry comparison. This preserves the documented distinction between binding success and fidelity evaluability. Verified by a dedicated test (behavior L).
-
-## Persistence decision
-
-**No new persisted artifact family.** `evaluateReferenceCandidateFidelity` (and its CLI-facing wrapper) is a pure, on-demand function over already-persisted/in-memory evidence — no `ExternalReferenceFidelityEvaluationArtifact` or equivalent was introduced. Rationale, identical to Prompt 4/5's own precedent: the result is cheap to recompute deterministically from its inputs, and persisting it would invite drift (a re-imported reference, re-observed candidate, or edited binding declaration could silently disagree with a stale persisted record) with no corresponding benefit at this stage. `--enforce`'s exit-code-only effect (mirroring `evaluate-contract` exactly) was judged sufficient CLI-side signal without persistence. This may be revisited only if Prompt 7's architecture (bounded visual-fidelity mismatch projection, v0.6 bounded-agent-context integration) proves persistence necessary — not assumed here, and no `BLOCKED_ESCALATE_TO_FULL_STAGE_CONTEXT` condition was triggered by this decision since the existing CLI could return a fully structured result without it.
-
-## Programmatic interface
-
-Exported from `src/index.ts` (additive): types `ReferenceRequirementFidelityStatus`, `ReferenceRequirementFidelityReasonCode`, `ReferenceRequirementFidelityResult`, `ReferenceFidelityState`, `ReferenceFidelityBlockReason`, `ReferenceCandidateFidelityEvaluation`, `EvaluateReferenceCandidateFidelityResult`, `EvaluateReferenceCandidateFidelityOptions`, `EvaluateReferenceFidelityOptions`, `ApplicationReferenceFidelityResult`; values `REFERENCE_REQUIREMENT_FIDELITY_STATUSES`, `REFERENCE_REQUIREMENT_FIDELITY_REASON_CODES`, `REFERENCE_FIDELITY_STATES`, `REFERENCE_FIDELITY_BLOCK_REASONS`, `evaluateReferenceCandidateFidelity`, `evaluateReferenceCandidateFidelityFromArtifactRoots`. No internal helper (`evaluateOneRequirement`, `deriveCoordinateScale`, `resolveConfiguredTargetName`, etc.) is exported.
-
-## CLI surface
-
-New command: `evaluate-reference-fidelity --reference <root> --candidate <root> [--bindings-file <json-file>] [--enforce]`. `--bindings-file` follows the exact `--requirements-file`/`--regions-file` wrapped-object convention (`{ "bindings": [...] }`, root-field allowlist enforced, unwrapped content handed straight to the domain validator). CLI code (`parseEvaluateReferenceFidelityArgs`, `loadBindingsFile`, `runEvaluateReferenceFidelityCommand`) owns only flag syntax, duplicate/missing-flag detection, file reading, JSON parsing, root-shape validation, output presentation, and exit-code selection — every semantic rule (adequacy, compatibility, binding, coordinate mapping, tolerance, relationship) stays owned by the domain module, and `evaluateReferenceCandidateFidelityFromArtifactRoots` owns artifact-root reading/orchestration. `TOP_LEVEL_HELP` and `runCli`'s dispatch table were updated; `cli.ts`'s existing "no browser/persistence implementation of its own" regression test (`B5-TST-008,009`) continues to pass unchanged, confirming the new command imports neither `artifacts/` nor a filesystem-write function.
-
-## CLI exit behavior
-
-Mirrors `evaluate-contract`'s exact precedent: `--enforce` is applied only after the fidelity evaluation has already been computed, and affects only the process exit status for an already-final `state: 'fail'` result (never its printed content). `state: 'not-evaluated'` always exits `0` regardless of `--enforce` — a reference-adequacy or compatibility blocker is a successful, honest non-evaluation, never treated as a design mismatch or an execution error. An actual operational failure (invalid syntax, unreadable/malformed `--reference`/`--candidate`, malformed `--bindings-file`, or an invalid binding declaration) always exits nonzero regardless of `--enforce`. Verified end-to-end by three CLI tests reproducing pass/fail/not-evaluated with and without `--enforce`.
-
-## Boundedness
-
-Reuses existing bounds without introducing new ones: `reference.requirements` is already bounded to ≤50 (`MAX_REFERENCE_REQUIREMENTS`, Prompt 3) at construction time, so `requirementResults` is bounded identically (1:1 with requirements); `bindingDeclarations` is already bounded to ≤20 (`MAX_REFERENCE_RUNTIME_BINDINGS`, Prompt 5); `deriveLayoutRelationships`'s own `MAX_CONFIGURED_TARGETS_FOR_RELATIONSHIPS`/`MAX_PAIRWISE_RELATIONSHIP_RECORDS` bounds (v0.4) apply unchanged, since it is called exactly once per relationship requirement over the same candidate. No unbounded diff/diagnostic collection is ever produced — Prompt 6 evaluates only explicitly authored Prompt 3 requirements, never "all visible differences."
-
-## Provenance
-
-Each `ReferenceRequirementFidelityResult` carries `requirementId`, `category`, `expectedDependentMode` (when present), `subject` (which itself names the reference region(s)/property/relationship/measurement), `boundRuntimeTargets`, and either the numeric (`referenceValue`/`candidateRawValue`/`candidateValue`/`delta`/`tolerance`) or relationship (`expectedRelationship`/`actualRelationship`) evidence that produced its status. The top-level `ReferenceCandidateFidelityEvaluation` additionally carries `referenceId`/`referenceRequestId`/`candidateObservationId`/`candidateRequestId`, the full Prompt 3 `adequacy`, the full Prompt 4 `compatibility` (when computed), and the full Prompt 5 `bindings` evaluation (when computed) — nothing is an unexplained delta.
-
-## Files changed
-
-New:
-- `src/domain/externalReferenceFidelity.ts`
-- `src/application/referenceFidelityEvaluationService.ts`
-- `tests/unit/externalReferenceFidelity.test.ts`
-- `tests/unit/cliEvaluateReferenceFidelity.test.ts`
-
-Modified:
-- `src/cli.ts` (`evaluate-reference-fidelity` command: help text, argument parser, `loadBindingsFile`, run function, `TOP_LEVEL_HELP`, dispatch table)
-- `src/index.ts` (public export surface for the above)
-- `docs/ARCHITECTURE.md`, `docs/CONTRACTS.md`, `docs/WORKFLOWS.md`, `docs/COMMANDS.md`
-
-## Tests
-
-927 unit tests total (889 pre-existing + 38 new), all pure domain/application/CLI-level tests — zero Chromium launches for fidelity evaluation itself (the one CLI end-to-end test constructs its candidate `ObservationArtifact` by writing a `manifest.json` directly to disk, exactly as `tests/unit/artifactWriter.test.ts` already does for writer-focused tests, never via `observe()`/a real browser).
-
-- `tests/unit/externalReferenceFidelity.test.ts` (29 tests): behaviors A–W from the task's own behavior model, including the exact worked example (424 reference px, 223→446 candidate px, delta 22, tolerance ±4, FAIL), the exact tolerance boundary (428 passes, 428.0001 fails), `exact`/`absolute-reference-px`/`percent` tolerance kinds, 2x coordinate scale, aspect-ratio-mismatch and missing-viewport coordinate-mapping unavailability, compatibility/adequacy blockers, bound/ambiguous/unavailable/undeclared bindings, hidden-target unavailability, relationship pass/fail/family-scoping and not-exhibited-by-reference, a supported numeric measurement (horizontal-gap), deterministic ordering and pure-function repeatability, all-pass/one-fail/one-unavailable overall results, zero-requirements inadequacy, full three-input immutability, fail-closed structural validation, absence of source-ownership fields, and a source-scan confirming no browser/filesystem import.
-- `tests/unit/cliEvaluateReferenceFidelity.test.ts` (9 tests): help text, top-level help listing, required-flag errors, missing `--reference`/`--candidate` errors, malformed `--bindings-file` (bad JSON/wrong root shape/unknown field), and three full end-to-end runs (pass, fail, not-evaluated) each checked with and without `--enforce`, reproducing the task's exact worked example through the real CLI/application/domain stack.
-
-## 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` — 48 test files, 927 tests, all pass.
-- `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; `dist/domain/externalReferenceFidelity.{js,d.ts,js.map}` and `dist/application/referenceFidelityEvaluationService.{js,d.ts,js.map}` confirmed present in the tarball listing.
-- `npm run test:security` — pass (5 + 63 = 68 tests), run because a new CLI/config-file input surface (`--bindings-file`) was added.
-- `npm run test:browser` — pass on re-run (9 files, 120 tests). One transient failure (`v0.2: an ambiguous locator stops immediately...`) occurred on the first full-suite run; re-running that single test in isolation passed immediately, and a full second `test:browser` run passed 120/120 — confirmed environmental flakiness in a real-Chromium timing-sensitive test unrelated to any file this prompt touched (Prompt 6 never imports or modifies `chromiumAdapter.ts`/`evidenceCapture.ts`), not a regression.
-
-## Regression results
-
-- Prompt 1 external-reference foundation: unaffected — `externalReference.ts` untouched (only its already-exported type guards were imported).
-- Prompt 2 regions/shared relationships: unaffected — `externalReferenceRegions.ts`/`externalReferenceRegionRelationships.ts` untouched.
-- Prompt 3 requirements/tolerances/adequacy: unaffected — `externalReferenceRequirements.ts` untouched; its exported functions were called, never modified.
-- Prompt 4 compatibility: unaffected — `externalReferenceCompatibility.ts`/`explicitState.ts`/`externalReferenceApplicability.ts` untouched.
-- Prompt 5 binding: unaffected — `externalReferenceRuntimeBinding.ts` untouched.
-- v0.4 comparison/relationship behavior: unaffected — `comparisonEngine.ts`/`relationships.ts` untouched (only already-exported functions were called).
-- v0.5 contracts/evaluation: unaffected — no file in `frontendContracts*.ts` touched.
-- v0.6 bounded context/correlation: unaffected — `boundedAgentContext*.ts` untouched; read for precedent only in an earlier prompt, not this one.
-- Full unit (927/927), browser (120/120 on the confirming re-run), and security (68/68) suites all pass with zero regressions.
-
-## Security impact
-
-- No new external input surface beyond a local, caller-controlled JSON file (`--bindings-file`) — the same trust boundary as every existing `--*-file` flag.
-- `evaluateReferenceCandidateFidelity` performs no filesystem access, no network access, and no browser/Chromium invocation of any kind; `evaluateReferenceCandidateFidelityFromArtifactRoots` performs only read-only artifact-manifest reads through the existing readers.
-- `test:security` (policy + real-Chromium adapter tests) re-run and passing, confirming no regression to the existing safety/navigation policy surface (untouched by this prompt).
-
-## Documentation changes
-
-- `docs/CONTRACTS.md` — new "v0.7 Prompt 6 structured reference-vs-candidate fidelity evaluation" section (full type shapes, evaluation order, coordinate-mapping/aspect-ratio rules, tolerance reuse, region-property/measurement/relationship evaluation, binding gate, category preservation, overall-result rule, persistence decision, CLI summary).
-- `docs/ARCHITECTURE.md` — new paragraph in the "Planned v0.7–v0.10" section describing the Prompt 6 module additions and their reuse of Prompts 3/4/5 and v0.4.
-- `docs/WORKFLOWS.md` — "Current external-reference foundation workflow" retitled to "Prompts 1-6" and extended with the `evaluate-reference-fidelity` command flow and test-coverage summary.
-- `docs/COMMANDS.md` — new `## `evaluate-reference-fidelity`` section, mirroring the existing `## `evaluate-contract`` section's structure exactly.
-
-## Tooling incidents
-
-None. No orchestrator was invoked (direct-implementation mode used throughout, consistent with Prompts 2–6); no background/speculative subagent writes occurred; the Prompt 1 stray-fork-writes stash remains untouched, unapplied, and unmined as precedent. The one transient real-Chromium test failure encountered during validation is documented under Validation/Regression results above as confirmed flakiness, not a tooling or implementation defect.
-
-## Out-of-scope confirmation
-
-This prompt implements no bounded coding-agent correction packet, no v0.6 bounded-agent-context change, no source/static correlation change, no coding-agent invocation, no source editing, no rerender/retry loop, no baseline/per-change overall workflow composition, no viewer, no annotation, no automatic target matching, no pixel/image similarity (no SSIM/perceptual hash/OCR/computer vision of any kind), and no new style-fidelity family (background color, text color, font size/weight, line height, border radius, shadow, gradient, opacity, icons) beyond Prompt 3's already-frozen requirement vocabulary. `evaluateReferenceCandidateFidelity` never attaches `sourceOwner`/`sourceFile`/`component`/`symbol`/`causedBy` to any result (verified by a dedicated test scanning the serialized evaluation for those exact terms).
-
-## Known limitations
-
-- The coordinate-mapping model supports only a single, deliberately bounded full-frame scale per evaluation — no per-region cropping, offset, rotation, or perspective mapping exists or was attempted, per the task's own explicit prohibition.
-- `expectedDependentMode` (`required`/`permitted`) is carried through as provenance only and never changes the pass/fail rule, since Prompt 3 itself never implemented a directional evaluation difference for its own expectation/adequacy derivation (unlike v0.5's runtime-directional contract clauses) — documented explicitly rather than silently ignored.
-- No `--output`/persistence flag exists for `evaluate-reference-fidelity`; a caller needing to save a fidelity result must do so itself (e.g. redirecting stdout, or consuming the programmatic API directly) until/unless a later prompt's architecture proves in-repository persistence necessary.
-
-## Remaining risks
-
-- None identified that block this prompt's own scope. The primary forward consideration for Prompt 7 (bounded visual-fidelity mismatch projection and v0.6 bounded-agent-context integration) is how it will attach `ReferenceRequirementFidelityResult`/`ReferenceCandidateFidelityEvaluation` evidence to `RuntimeStaticCorrelationRecord`-shaped context without conflating the two identity domains this prompt was careful to keep separate (reference-region/runtime-target vs. runtime-target/static-source) — flagged for that prompt's own precedent review, not preempted here.
-
-## Exact next action
-
-v0.7 Prompt 7 — bounded visual-fidelity mismatch projection and v0.6 bounded-agent-context integration.
+# v0.7 Prompt 6 — Structured Reference-vs-Candidate Fidelity Evaluation
+
+**VERDICT: PASS_V0_7_REFERENCE_FIDELITY_PROMPT6**
+
+## Repository / branch / heads
+
+- Repository: `my-frontend-observer` (path: `Z:\Users\newuser\Projects\my-frontend-observer`)
+- Branch: `implementation/v0.7-reference-fidelity`, branched from the exact completed Prompt 5 HEAD
+- Starting HEAD (branch point, Prompt 5 report commit): `74c710daa62cd5a56f1b1b2eac3a43d24dfe69fb`
+- Prompt 5 base HEAD confirmed to contain both required commits: `74cc148` (implementation) and `74c710d` (report), and the full completed Prompt 1–4 lineage — verified via `git log --oneline` before branching.
+- Implementation commit (this prompt): `91f5e736a1a8472984b0c8c7a7e179e307f1a5ce` — "Add v0.7 Prompt 6 structured reference-vs-candidate fidelity evaluation"
+- 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 5 report HEAD; `git stash list` showed exactly the one preserved Prompt 1 stray-fork-writes entry. The branch was created with `git checkout -b implementation/v0.7-reference-fidelity` and ancestry verified with `git merge-base --is-ancestor 74c710d 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).
+
+## Tooling
+
+- Resolved latest published `@dailephd/my-dev-kit`: `1.12.3`, pinned exactly via `npx -y @dailephd/my-dev-kit@1.12.3`.
+- Fresh Prompt 6 repository index built under a repository-local, gitignored root: `.my-dev-kit-context/index-prompt6/` (57 files, 868 symbols indexed) — not reused from Prompt 1–5's indexes.
+
+## Prompt 1–5 contracts verified
+
+Read directly (source, not memory) before writing any code:
+
+- `src/domain/externalReferenceRequirements.ts` — the full Prompt 3 requirement/tolerance/expectation/adequacy model, including the exact `RELATIONSHIP_FAMILY_GROUPS`-scoped lookup fix and `deriveReferenceRequirementAdequacy`'s "100% unavailable requirements ⇒ inadequate" rule.
+- `src/domain/externalReferenceRegions.ts` — `ReferenceRegionGeometry`'s exact field set (`x`/`y`/`width`/`height`/`right`/`bottom`/`centerX`/`centerY`), reused as the shared shape for both reference and (converted) candidate geometry.
+- `src/domain/externalReference.ts` — `isImportedExternalReferenceArtifact`/`isApprovedExternalReferenceArtifact` type guards, reused to read image dimensions uniformly across both lifecycle variants without duplicating validation logic.
+- `src/domain/externalReferenceCompatibility.ts` (Prompt 4) — `evaluateReferenceCandidateCompatibility`'s exact signature and result shape, reused verbatim as the compatibility gate.
+- `src/domain/externalReferenceRuntimeBinding.ts` (Prompt 5) — `evaluateReferenceRuntimeBindings`'s exact signature/result shape and its own case-insensitive target-name-resolution convention (mirrored, not imported, per the established per-module small-helper convention).
+- `src/domain/schema.ts` (v0.2) — `TargetGeometry`, `TargetVisibility`, `TargetResolution`/`TargetSelectionStatus`, and `ObservationArtifact.targetEvidence`'s exact-configured-name keying.
+- `src/domain/comparisonEngine.ts` (v0.4) — `targetPresence` (already additively exported by Prompt 5), reused rather than re-derived.
+- `src/domain/relationships.ts` (v0.4) — `deriveLayoutRelationships`, `PairwiseLayoutRelationship`'s `subjectTarget`/`relatedTarget` fields, `UnresolvedRelationshipTarget`/`UNRESOLVED_TARGET_REASONS` (confirming hidden targets are already excluded from relationship derivation by v0.4 itself), and every pairwise relationship-family constant.
+- `src/domain/frontendContracts.ts`/`frontendContractEvaluation.ts` (v0.5) — `CLAUSE_RESULT_STATUSES`/`ClauseEvaluationResult` (the `pass`/`fail`/`unavailable`/`conflict` precedent), `evaluateFrontendContract`'s overall-verdict aggregation rule (`every clause pass && no unexpected changes ⇒ PASS`), `clauseMode`'s `required`/`permitted` handling (confirming it is a v0.5-only, directional-primitive-specific concept never mirrored in Prompt 3's own expectation/adequacy derivation), and `toleranceToPx`'s percent-denominator convention (`(amount/100) * abs(beforeValue)`), reused independently for reference-image-pixel units.
+- `src/application/comparisonService.ts` — the exact `compareAndPersistFromArtifactRoots` application-layer shape (read-both-artifacts-then-delegate-to-the-pure-function), mirrored for `evaluateReferenceCandidateFidelityFromArtifactRoots`.
+- `src/cli.ts` — the full `evaluate-contract` command (help text, argument parser, `--enforce` exit-code handling) as the direct precedent for `evaluate-reference-fidelity`, and every existing `--*-file` loader (`loadRegionsFile`/`loadRequirementsFile`/`loadApplicabilityFile`) as the precedent for `loadBindingsFile`.
+
+No architecture blocker was hit; no `BLOCKED_ESCALATE_TO_FULL_STAGE_CONTEXT` condition applied at any point.
+
+## Precedent review outcomes
+
+- **A. Result vocabulary** — `pass`/`fail`/`unavailable` reused as the same honest three-state shape v0.5's `CLAUSE_RESULT_STATUSES` already established, but as an independently-owned constant (`REFERENCE_REQUIREMENT_FIDELITY_STATUSES`) deliberately excluding `'conflict'` — Prompt 6 has no cross-requirement authoring-conflict concept (each requirement is evaluated independently against its own subject).
+- **B. Overall fidelity** — a compatible/evaluable pair reaches `state: 'pass'` only when every requirement result is `'pass'`; any `'fail'`/`'unavailable'` forces `'fail'`. An incompatible or reference-inadequate pair never reaches that computation at all — a distinct `not-evaluated` state, with `blockedBy: 'reference-inadequate' | 'incompatible'`, is returned instead.
+- **C. Relationship evaluation** — reuses Prompt 2's `deriveReferenceRequirementExpectation` (reference side) and v0.4's `deriveLayoutRelationships` (candidate side) exactly; no duplicated geometry predicate exists anywhere in the new module.
+- **D. Value derivation** — reference expected values always come from `deriveReferenceRequirementExpectation`/`deriveReferenceRequirementMeasurement` (Prompt 3), never recomputed by hand; candidate values always come from `ObservationArtifact.targetEvidence`'s existing `TargetGeometry`/`TargetVisibility` evidence, never a second derivation.
+- **E. Persistence** — no new persisted artifact family; documented decision below.
+
+## Fidelity evaluator type/function names
+
+- `domain/externalReferenceFidelity.ts`: `evaluateReferenceCandidateFidelity(reference, candidate, bindingDeclarations, options?)` → `{ ok: true; evaluation: ReferenceCandidateFidelityEvaluation } | { ok: false; reason: string }`.
+- `application/referenceFidelityEvaluationService.ts`: `evaluateReferenceCandidateFidelityFromArtifactRoots(referenceRoot, candidateRoot, bindingDeclarations, options?)` — the CLI-facing, artifact-root-reading counterpart.
+- CLI: `evaluate-reference-fidelity`.
+
+## Evaluation ordering / gates
+
+Frozen order, exactly as specified and never reordered: reference structural validation (`isValidExternalReferenceArtifact`) → candidate structural validation (`isValidObservationArtifact`) → binding-declaration structural validation (`isValidReferenceRuntimeBindingDeclarations`, invoked inside the Prompt 5 evaluator) → Prompt 3 reference adequacy (`deriveReferenceRequirementAdequacy`) → Prompt 4 compatibility (`evaluateReferenceCandidateCompatibility`) → Prompt 5 binding evaluation (`evaluateReferenceRuntimeBindings`) → per-requirement candidate-evidence/coordinate-mapping checks → per-requirement tolerance/relationship comparison → overall result.
+
+The first three (structural) failures return `{ ok: false, reason }` — a caller/config error, never a fidelity outcome. `adequacy.status === 'inadequate'` and `compatibility.state === 'incomparable'` each short-circuit to `state: 'not-evaluated'` with `requirementResults: []` — verified by dedicated tests (behaviors G/H). `adequacy.status === 'partial'` does **not** block evaluation; it proceeds normally, and the specific reference-side-unavailable requirements independently re-derive their own `unavailable` result at the per-requirement stage (not looked up from the adequacy result — verified by the "reference itself does not exhibit" test, which requires a second, evaluable requirement to keep adequacy at `partial` rather than `inadequate`, confirming the two computations are genuinely independent).
+
+## Coordinate-mapping model
+
+One explicit, deterministic full-frame scale: `scaleX = referenceImageWidth / applicableViewportWidth`, `scaleY = referenceImageHeight / applicableViewportHeight`, derived once per evaluation call from `reference.applicability.viewport` (Prompt 4) and the reference image's own pixel dimensions (Prompt 1, read uniformly across both lifecycle variants via the existing `isImportedExternalReferenceArtifact`/`isApprovedExternalReferenceArtifact` type guards). Candidate `TargetGeometry` (CSS pixels) is reshaped into a `ReferenceRegionGeometry`-shaped value (adding `centerX`/`centerY`, computed identically to `deriveReferenceRegionGeometry`) both raw and scaled; horizontal fields (`x`/`width`/`right`/`centerX`) always scale by `scaleX`, vertical fields (`y`/`height`/`bottom`/`centerY`) always scale by `scaleY` — this falls out automatically from the per-field conversion, never a hand-picked per-property axis table. `region-measurement` subjects reuse Prompt 3's exact `deriveReferenceRequirementMeasurement` on the converted geometries directly, rather than a parallel "runtime version" of the same gap/delta formulas.
+
+## Image/viewport scale rule and aspect-ratio rule
+
+`ASPECT_RATIO_MAPPING_TOLERANCE = 0.01` (1% relative difference between `scaleX` and `scaleY`) is an independently-owned, tiny coordinate-mapping-validity constant — never a user-authored Prompt 3 design tolerance. If `scaleX`/`scaleY` disagree beyond this bound, or `reference.applicability.viewport` is absent entirely, `deriveCoordinateScale` returns `{ ok: false, reason }` and every numeric (`region-property`/`region-measurement`) requirement in that evaluation becomes `unavailable`/`coordinate-mapping-unavailable` — verified by dedicated tests (behaviors E and F). No cropping, offset, rotation, or perspective registration is implemented anywhere; only this single bounded full-frame check. Categorical `region-relationship` requirements are unaffected by an unavailable scale (they never call `deriveCoordinateScale` at all).
+
+## Numeric precision rule
+
+No intermediate rounding anywhere in the arithmetic path (`referenceValue`, `candidateRawValue`, `candidateValue`, `delta` are all plain JS `number`s carried through at full floating-point precision). Tolerance comparison is a single `Math.abs(delta) <= allowed` check with no added epsilon — verified by the exact-boundary test (a delta equal to the tolerance passes; a delta a tiny fraction over it fails), matching the task's own worked boundary example (428 passes, 428.0001 fails against a reference of 424 ± 4).
+
+## Requirement result vocabulary
+
+`REFERENCE_REQUIREMENT_FIDELITY_STATUSES = ['pass', 'fail', 'unavailable']`. `reasonCode` (one of `reference-evidence-unavailable`, `reference-relationship-not-exhibited`, `binding-unavailable`, `candidate-evidence-unavailable`, `coordinate-mapping-unavailable`) and `detail` are present only when `status === 'unavailable'` — a `fail` is already fully explained by its numeric (`referenceValue`/`candidateRawValue`/`candidateValue`/`delta`/`tolerance`) or relationship (`expectedRelationship`/`actualRelationship`) fields, so no reason code is needed there.
+
+## Overall fidelity vocabulary
+
+`REFERENCE_FIDELITY_STATES = ['not-evaluated', 'pass', 'fail']`, with `REFERENCE_FIDELITY_BLOCK_REASONS = ['reference-inadequate', 'incompatible']` populated only when `state === 'not-evaluated'`. There is no separate "partial pass" bucket once evaluation has actually run: any `unavailable` requirement result forces `state: 'fail'`, satisfying "any required fail or unavailable must prevent overall PASS" (section 34) without inventing a fourth top-level state — an `unavailable`-only result set is honestly reported as `'fail'` (i.e. "not confirmed to satisfy every selected requirement"), which the report's per-requirement breakdown (`pass`/`fail`/`unavailable` counts) then disambiguates for a human/caller.
+
+## Region-property evaluation
+
+Reads the bound target's `TargetGeometry` from `targetEvidence`, requires `TargetVisibility.visible === true` (a `bound`-but-hidden target's geometry is treated as unusable, never fabricated as meaningful — see "hidden target" below), converts to both raw and reference-space geometry, and reads `[subject.property]` off each. Exactly Prompt 3's supported vocabulary (`x`/`y`/`width`/`height`/`right`/`bottom`/`centerX`/`centerY`) — no new property was added.
+
+## Relationship evaluation
+
+Confirms the reference itself exhibits its own selected relationship first (`deriveReferenceRequirementExpectation`'s `matches` field) — if not, `unavailable`/`reference-relationship-not-exhibited` (a reference-authoring problem, never a candidate `fail`). Then resolves both bound targets, calls `deriveLayoutRelationships` once over the whole candidate observation, and looks up the pairwise record for the bound-target pair **scoped to the exact requested relationship family** via an independently-owned, third duplicate of the `RELATIONSHIP_FAMILY_GROUPS` shape (already duplicated by `frontendContractEvaluation.ts` and `externalReferenceRequirements.ts`) — never "the first record for this pair regardless of family," the exact bug class Prompt 3 fixed. A record only derivable in the reversed target order is `unavailable`, never auto-flipped, mirroring Prompt 3's identical reference-side handling. Verified by dedicated tests for pass (M), fail (N), and family-scoping (O, using two regions/targets that simultaneously satisfy multiple relationship families to prove the lookup picks the correct family's record).
+
+## Spacing/alignment (measurement) evaluation
+
+Supported: exactly Prompt 3's `REFERENCE_REQUIREMENT_MEASUREMENTS` (`vertical-gap`/`horizontal-gap`/`center-x-delta`/`center-y-delta`/`left-edge-delta`/`right-edge-delta`), evaluated via `deriveReferenceRequirementMeasurement` on converted (both raw and reference-space) geometries — no generic geometry expression language was introduced. A geometrically-undefined gap (targets overlapping on the relevant axis) is `unavailable`, mirroring Prompt 3's reference-side treatment of the identical situation. Verified by a dedicated horizontal-gap pass/fail test (behavior P).
+
+## Tolerance behavior
+
+Reused exactly, never redefined. A single rule, `Math.abs(delta) <= allowed`, covers all three Prompt 3 kinds: `exact` ⇒ `allowed = 0`; `absolute-reference-px` ⇒ `allowed = tolerance.amount` (already in reference-image pixels); `percent` ⇒ `allowed = (tolerance.amount / 100) * Math.abs(referenceValue)`, mirroring v0.5's own `toleranceToPx` "may vary by up to N%" convention exactly, independently reimplemented in reference-image-pixel units (never imported — v0.5's `ContractTolerance` is a different, CSS-pixel-implicit unit). Verified by dedicated tests for `exact`, `absolute-reference-px`, `percent`, and the exact tolerance boundary (behavior C, plus the task's own worked example reproduced verbatim in both the domain and CLI test suites).
+
+## Unavailable-evidence behavior
+
+Unavailable evidence never becomes a fabricated zero/false/pass/fail anywhere in this module: an unbound/ambiguous/unavailable Prompt 5 binding, an invisible or evidence-less bound target, an unestablishable coordinate scale, and an undervied/not-exhibited reference relationship are each their own explicit `unavailable` result with a distinguishing `reasonCode` — never silently defaulted, never a `fail`.
+
+## Compatibility-blocker behavior
+
+`evaluateReferenceCandidateCompatibility` is called once; `state === 'incomparable'` short-circuits the whole evaluation to `state: 'not-evaluated'`, `blockedBy: 'incompatible'`, `requirementResults: []`, with the full `ComparabilityResult` embedded verbatim in the `compatibility` field for the caller to inspect the reason. No geometry delta, spacing delta, relationship comparison, or requirement PASS/FAIL is ever computed in this case. Verified by a dedicated test (behavior G, an incompatible candidate viewport).
+
+## Binding-blocker behavior
+
+`evaluateReferenceRuntimeBindings` is called once (after the compatibility gate has already confirmed a non-incomparable pair, so it is guaranteed not to re-trigger its own internal compatibility short-circuit); its `ok: false` result (a structural declaration/artifact problem) propagates as this function's own `ok: false`. For each requirement, every dependent reference region's binding must be `bound` — `ambiguous`, `unavailable`, or simply absent from the supplied declarations all produce `unavailable`/`binding-unavailable` for that requirement, never a guessed target and never an auto-bind based on geometry or names. Verified by dedicated tests for ambiguous (J), unavailable/not-found (K), and undeclared bindings.
+
+## Hidden-target decision
+
+A `bound` target (Prompt 5's question: does a stable correspondence exist) whose `TargetVisibility.visible !== true` — including when visibility evidence itself is unavailable — is treated as having no usable geometry: `unavailable`/`candidate-evidence-unavailable`, never a fabricated zero-geometry comparison. This preserves the documented distinction between binding success and fidelity evaluability. Verified by a dedicated test (behavior L).
+
+## Persistence decision
+
+**No new persisted artifact family.** `evaluateReferenceCandidateFidelity` (and its CLI-facing wrapper) is a pure, on-demand function over already-persisted/in-memory evidence — no `ExternalReferenceFidelityEvaluationArtifact` or equivalent was introduced. Rationale, identical to Prompt 4/5's own precedent: the result is cheap to recompute deterministically from its inputs, and persisting it would invite drift (a re-imported reference, re-observed candidate, or edited binding declaration could silently disagree with a stale persisted record) with no corresponding benefit at this stage. `--enforce`'s exit-code-only effect (mirroring `evaluate-contract` exactly) was judged sufficient CLI-side signal without persistence. This may be revisited only if Prompt 7's architecture (bounded visual-fidelity mismatch projection, v0.6 bounded-agent-context integration) proves persistence necessary — not assumed here, and no `BLOCKED_ESCALATE_TO_FULL_STAGE_CONTEXT` condition was triggered by this decision since the existing CLI could return a fully structured result without it.
+
+## Programmatic interface
+
+Exported from `src/index.ts` (additive): types `ReferenceRequirementFidelityStatus`, `ReferenceRequirementFidelityReasonCode`, `ReferenceRequirementFidelityResult`, `ReferenceFidelityState`, `ReferenceFidelityBlockReason`, `ReferenceCandidateFidelityEvaluation`, `EvaluateReferenceCandidateFidelityResult`, `EvaluateReferenceCandidateFidelityOptions`, `EvaluateReferenceFidelityOptions`, `ApplicationReferenceFidelityResult`; values `REFERENCE_REQUIREMENT_FIDELITY_STATUSES`, `REFERENCE_REQUIREMENT_FIDELITY_REASON_CODES`, `REFERENCE_FIDELITY_STATES`, `REFERENCE_FIDELITY_BLOCK_REASONS`, `evaluateReferenceCandidateFidelity`, `evaluateReferenceCandidateFidelityFromArtifactRoots`. No internal helper (`evaluateOneRequirement`, `deriveCoordinateScale`, `resolveConfiguredTargetName`, etc.) is exported.
+
+## CLI surface
+
+New command: `evaluate-reference-fidelity --reference <root> --candidate <root> [--bindings-file <json-file>] [--enforce]`. `--bindings-file` follows the exact `--requirements-file`/`--regions-file` wrapped-object convention (`{ "bindings": [...] }`, root-field allowlist enforced, unwrapped content handed straight to the domain validator). CLI code (`parseEvaluateReferenceFidelityArgs`, `loadBindingsFile`, `runEvaluateReferenceFidelityCommand`) owns only flag syntax, duplicate/missing-flag detection, file reading, JSON parsing, root-shape validation, output presentation, and exit-code selection — every semantic rule (adequacy, compatibility, binding, coordinate mapping, tolerance, relationship) stays owned by the domain module, and `evaluateReferenceCandidateFidelityFromArtifactRoots` owns artifact-root reading/orchestration. `TOP_LEVEL_HELP` and `runCli`'s dispatch table were updated; `cli.ts`'s existing "no browser/persistence implementation of its own" regression test (`B5-TST-008,009`) continues to pass unchanged, confirming the new command imports neither `artifacts/` nor a filesystem-write function.
+
+## CLI exit behavior
+
+Mirrors `evaluate-contract`'s exact precedent: `--enforce` is applied only after the fidelity evaluation has already been computed, and affects only the process exit status for an already-final `state: 'fail'` result (never its printed content). `state: 'not-evaluated'` always exits `0` regardless of `--enforce` — a reference-adequacy or compatibility blocker is a successful, honest non-evaluation, never treated as a design mismatch or an execution error. An actual operational failure (invalid syntax, unreadable/malformed `--reference`/`--candidate`, malformed `--bindings-file`, or an invalid binding declaration) always exits nonzero regardless of `--enforce`. Verified end-to-end by three CLI tests reproducing pass/fail/not-evaluated with and without `--enforce`.
+
+## Boundedness
+
+Reuses existing bounds without introducing new ones: `reference.requirements` is already bounded to ≤50 (`MAX_REFERENCE_REQUIREMENTS`, Prompt 3) at construction time, so `requirementResults` is bounded identically (1:1 with requirements); `bindingDeclarations` is already bounded to ≤20 (`MAX_REFERENCE_RUNTIME_BINDINGS`, Prompt 5); `deriveLayoutRelationships`'s own `MAX_CONFIGURED_TARGETS_FOR_RELATIONSHIPS`/`MAX_PAIRWISE_RELATIONSHIP_RECORDS` bounds (v0.4) apply unchanged, since it is called exactly once per relationship requirement over the same candidate. No unbounded diff/diagnostic collection is ever produced — Prompt 6 evaluates only explicitly authored Prompt 3 requirements, never "all visible differences."
+
+## Provenance
+
+Each `ReferenceRequirementFidelityResult` carries `requirementId`, `category`, `expectedDependentMode` (when present), `subject` (which itself names the reference region(s)/property/relationship/measurement), `boundRuntimeTargets`, and either the numeric (`referenceValue`/`candidateRawValue`/`candidateValue`/`delta`/`tolerance`) or relationship (`expectedRelationship`/`actualRelationship`) evidence that produced its status. The top-level `ReferenceCandidateFidelityEvaluation` additionally carries `referenceId`/`referenceRequestId`/`candidateObservationId`/`candidateRequestId`, the full Prompt 3 `adequacy`, the full Prompt 4 `compatibility` (when computed), and the full Prompt 5 `bindings` evaluation (when computed) — nothing is an unexplained delta.
+
+## Files changed
+
+New:
+- `src/domain/externalReferenceFidelity.ts`
+- `src/application/referenceFidelityEvaluationService.ts`
+- `tests/unit/externalReferenceFidelity.test.ts`
+- `tests/unit/cliEvaluateReferenceFidelity.test.ts`
+
+Modified:
+- `src/cli.ts` (`evaluate-reference-fidelity` command: help text, argument parser, `loadBindingsFile`, run function, `TOP_LEVEL_HELP`, dispatch table)
+- `src/index.ts` (public export surface for the above)
+- `docs/ARCHITECTURE.md`, `docs/CONTRACTS.md`, `docs/WORKFLOWS.md`, `docs/COMMANDS.md`
+
+## Tests
+
+927 unit tests total (889 pre-existing + 38 new), all pure domain/application/CLI-level tests — zero Chromium launches for fidelity evaluation itself (the one CLI end-to-end test constructs its candidate `ObservationArtifact` by writing a `manifest.json` directly to disk, exactly as `tests/unit/artifactWriter.test.ts` already does for writer-focused tests, never via `observe()`/a real browser).
+
+- `tests/unit/externalReferenceFidelity.test.ts` (29 tests): behaviors A–W from the task's own behavior model, including the exact worked example (424 reference px, 223→446 candidate px, delta 22, tolerance ±4, FAIL), the exact tolerance boundary (428 passes, 428.0001 fails), `exact`/`absolute-reference-px`/`percent` tolerance kinds, 2x coordinate scale, aspect-ratio-mismatch and missing-viewport coordinate-mapping unavailability, compatibility/adequacy blockers, bound/ambiguous/unavailable/undeclared bindings, hidden-target unavailability, relationship pass/fail/family-scoping and not-exhibited-by-reference, a supported numeric measurement (horizontal-gap), deterministic ordering and pure-function repeatability, all-pass/one-fail/one-unavailable overall results, zero-requirements inadequacy, full three-input immutability, fail-closed structural validation, absence of source-ownership fields, and a source-scan confirming no browser/filesystem import.
+- `tests/unit/cliEvaluateReferenceFidelity.test.ts` (9 tests): help text, top-level help listing, required-flag errors, missing `--reference`/`--candidate` errors, malformed `--bindings-file` (bad JSON/wrong root shape/unknown field), and three full end-to-end runs (pass, fail, not-evaluated) each checked with and without `--enforce`, reproducing the task's exact worked example through the real CLI/application/domain stack.
+
+## 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` — 48 test files, 927 tests, all pass.
+- `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; `dist/domain/externalReferenceFidelity.{js,d.ts,js.map}` and `dist/application/referenceFidelityEvaluationService.{js,d.ts,js.map}` confirmed present in the tarball listing.
+- `npm run test:security` — pass (5 + 63 = 68 tests), run because a new CLI/config-file input surface (`--bindings-file`) was added.
+- `npm run test:browser` — pass on re-run (9 files, 120 tests). One transient failure (`v0.2: an ambiguous locator stops immediately...`) occurred on the first full-suite run; re-running that single test in isolation passed immediately, and a full second `test:browser` run passed 120/120 — confirmed environmental flakiness in a real-Chromium timing-sensitive test unrelated to any file this prompt touched (Prompt 6 never imports or modifies `chromiumAdapter.ts`/`evidenceCapture.ts`), not a regression.
+
+## Regression results
+
+- Prompt 1 external-reference foundation: unaffected — `externalReference.ts` untouched (only its already-exported type guards were imported).
+- Prompt 2 regions/shared relationships: unaffected — `externalReferenceRegions.ts`/`externalReferenceRegionRelationships.ts` untouched.
+- Prompt 3 requirements/tolerances/adequacy: unaffected — `externalReferenceRequirements.ts` untouched; its exported functions were called, never modified.
+- Prompt 4 compatibility: unaffected — `externalReferenceCompatibility.ts`/`explicitState.ts`/`externalReferenceApplicability.ts` untouched.
+- Prompt 5 binding: unaffected — `externalReferenceRuntimeBinding.ts` untouched.
+- v0.4 comparison/relationship behavior: unaffected — `comparisonEngine.ts`/`relationships.ts` untouched (only already-exported functions were called).
+- v0.5 contracts/evaluation: unaffected — no file in `frontendContracts*.ts` touched.
+- v0.6 bounded context/correlation: unaffected — `boundedAgentContext*.ts` untouched; read for precedent only in an earlier prompt, not this one.
+- Full unit (927/927), browser (120/120 on the confirming re-run), and security (68/68) suites all pass with zero regressions.
+
+## Security impact
+
+- No new external input surface beyond a local, caller-controlled JSON file (`--bindings-file`) — the same trust boundary as every existing `--*-file` flag.
+- `evaluateReferenceCandidateFidelity` performs no filesystem access, no network access, and no browser/Chromium invocation of any kind; `evaluateReferenceCandidateFidelityFromArtifactRoots` performs only read-only artifact-manifest reads through the existing readers.
+- `test:security` (policy + real-Chromium adapter tests) re-run and passing, confirming no regression to the existing safety/navigation policy surface (untouched by this prompt).
+
+## Documentation changes
+
+- `docs/CONTRACTS.md` — new "v0.7 Prompt 6 structured reference-vs-candidate fidelity evaluation" section (full type shapes, evaluation order, coordinate-mapping/aspect-ratio rules, tolerance reuse, region-property/measurement/relationship evaluation, binding gate, category preservation, overall-result rule, persistence decision, CLI summary).
+- `docs/ARCHITECTURE.md` — new paragraph in the "Planned v0.7–v0.10" section describing the Prompt 6 module additions and their reuse of Prompts 3/4/5 and v0.4.
+- `docs/WORKFLOWS.md` — "Current external-reference foundation workflow" retitled to "Prompts 1-6" and extended with the `evaluate-reference-fidelity` command flow and test-coverage summary.
+- `docs/COMMANDS.md` — new `## `evaluate-reference-fidelity`` section, mirroring the existing `## `evaluate-contract`` section's structure exactly.
+
+## Tooling incidents
+
+None. No orchestrator was invoked (direct-implementation mode used throughout, consistent with Prompts 2–6); no background/speculative subagent writes occurred; the Prompt 1 stray-fork-writes stash remains untouched, unapplied, and unmined as precedent. The one transient real-Chromium test failure encountered during validation is documented under Validation/Regression results above as confirmed flakiness, not a tooling or implementation defect.
+
+## Out-of-scope confirmation
+
+This prompt implements no bounded coding-agent correction packet, no v0.6 bounded-agent-context change, no source/static correlation change, no coding-agent invocation, no source editing, no rerender/retry loop, no baseline/per-change overall workflow composition, no viewer, no annotation, no automatic target matching, no pixel/image similarity (no SSIM/perceptual hash/OCR/computer vision of any kind), and no new style-fidelity family (background color, text color, font size/weight, line height, border radius, shadow, gradient, opacity, icons) beyond Prompt 3's already-frozen requirement vocabulary. `evaluateReferenceCandidateFidelity` never attaches `sourceOwner`/`sourceFile`/`component`/`symbol`/`causedBy` to any result (verified by a dedicated test scanning the serialized evaluation for those exact terms).
+
+## Known limitations
+
+- The coordinate-mapping model supports only a single, deliberately bounded full-frame scale per evaluation — no per-region cropping, offset, rotation, or perspective mapping exists or was attempted, per the task's own explicit prohibition.
+- `expectedDependentMode` (`required`/`permitted`) is carried through as provenance only and never changes the pass/fail rule, since Prompt 3 itself never implemented a directional evaluation difference for its own expectation/adequacy derivation (unlike v0.5's runtime-directional contract clauses) — documented explicitly rather than silently ignored.
+- No `--output`/persistence flag exists for `evaluate-reference-fidelity`; a caller needing to save a fidelity result must do so itself (e.g. redirecting stdout, or consuming the programmatic API directly) until/unless a later prompt's architecture proves in-repository persistence necessary.
+
+## Remaining risks
+
+- None identified that block this prompt's own scope. The primary forward consideration for Prompt 7 (bounded visual-fidelity mismatch projection and v0.6 bounded-agent-context integration) is how it will attach `ReferenceRequirementFidelityResult`/`ReferenceCandidateFidelityEvaluation` evidence to `RuntimeStaticCorrelationRecord`-shaped context without conflating the two identity domains this prompt was careful to keep separate (reference-region/runtime-target vs. runtime-target/static-source) — flagged for that prompt's own precedent review, not preempted here.
+
+## Exact next action
+
+v0.7 Prompt 7 — bounded visual-fidelity mismatch projection and v0.6 bounded-agent-context integration.