@dailephd/my-frontend-observer 0.8.1

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

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

package/docs/reports/v0.7-reference-foundation-prompt1.md

@@ -0,0 +1,151 @@
+# v0.7 Prompt 1 — External Visual Reference Foundation
+
+## 1. Verdict
+
+**PASS_V0_7_REFERENCE_FOUNDATION_PROMPT1**
+
+## 2. Repository
+
+`Z:\Users\newuser\Projects\my-frontend-observer` (`https://github.com/dailephd/my-frontend-observer.git`)
+
+## 3. Branch
+
+`implementation/v0.7-reference-foundation`
+
+## 4. Starting head
+
+`be3e440e5f3570becde75717f9538c856e61cd97` (the tip of `docs/external-visual-reference-roadmap` / PR #7 at the time this stage began — the authoritative checkout containing the v0.7 external-reference roadmap)
+
+## 5. Ending head
+
+`4a15baf732cb1e545185b7242f0af6d575ec7e0a`
+
+## 6. Git status
+
+Clean at the ending head. `git diff --stat` against `package.json`/`package-lock.json` is empty — no dependency graph change. Only the 20 files listed in section 14 changed.
+
+## 7. Resolved my-dev-kit version
+
+`@dailephd/my-dev-kit@1.12.3` (the unscoped `my-dev-kit` package on the public registry is a deprecated alias pointing at this scoped package)
+
+## 8. Resolved orchestrator version
+
+`@dailephd/my-dev-kit-orchestrator@1.4.1` (the unscoped `my-dev-kit-orchestrator` package is likewise a deprecated alias)
+
+## 9. FULL_STAGE_CONTEXT run ID / location
+
+`20260906T053538-v0-7-reference-foundation-prompt1`, at `.my-dev-kit-orchestrator/runs/20260906T053538-v0-7-reference-foundation-prompt1/` (gitignored, repository-local, not committed — matches this repository's existing `.gitignore` convention for `.my-dev-kit-orchestrator/`). All ten stage artifacts (RequestBrief, ArchitectureContextPacket, BehaviorModel, PseudocodePacket, TestStrategyPacket, ImplementationReport, TestImplementationReport, VerificationReport, JudgeReport, FinalReport) were produced there.
+
+## 10. Architecture decision
+
+- **Chosen reference contract/artifact model**: a new, standalone **persisted** artifact family (not programmatic-only, unlike the v0.6 bounded-agent-context precedent). Persistence is justified by the request's own explicit forward-looking requirement (section 12A): later v0.7/v0.8/v0.9 stages need a stable, reloadable, approvable, supersedable reference identity across many separate invocations — unlike bounded-agent-context, which is a per-invocation projection over already-persisted upstream evidence and is consumed once, in-process.
+- **Chosen name**: `ExternalReferenceArtifact` — matching this repository's existing naming convention (`ObservationArtifact`, `ComparisonArtifact`) and the exact vocabulary already used throughout `docs/ROADMAP.md`/`docs/WORKFLOWS.md`/`docs/PROJECT_DESCRIPTION.md` ("external reference"), not the prompt's conceptual placeholder `ReferenceVisualArtifact`.
+- **Persistence decision**: `<outputLocation>/<referenceId>/manifest.json` (+ `reference.<ext>` only for an `'imported'` artifact), via the same atomic temp-dir-then-rename discipline as `writeObservationArtifact`/`writeComparisonArtifact`.
+- **Identity model**: `referenceRequestId` — deterministic sha256 over a canonicalized `{imageSha256, format, width, height, supersedesReferenceId}` view (never a path, label, or timestamp) — plus `referenceId`, a fresh nonce-suffixed instance identity per persisted write, exactly mirroring `identity.ts`/`comparisonIdentity.ts`/`frontendContractIdentity.ts`'s pattern (each module owning its own duplicated `canonicalize()`).
+- **Lifecycle model**: exactly two persisted states, `{state:'imported'}` and `{state:'approved'; approvedAt}`. There is **no literal `'superseded'` state** — supersession is represented only as a forward pointer (`supersedesReferenceId` on the newer artifact), so an existing persisted artifact's own manifest is never rewritten. This is a deliberate interpretation of the request's four-state conceptual model (section 12G), trading a literal reading for an unconditional immutability guarantee; it is flagged explicitly in the design artifacts and re-confirmed by the judge stage.
+- **Provenance model**: `producer` (name/version, via the existing `getProducerInfo()`), `provenance.importedAt` + optional `provenance.label` (pure metadata, never identity-bearing), and — for an approved artifact — a `sourceReference` back to the imported artifact's `{referenceId, referenceRequestId, producer, schemaVersion, image}`, mirroring `ComparisonSourceObservationReference`'s exact shape.
+- **Public export decision**: yes, this is a supported v0.7 contract — the complete type/constant/validator/identity/writer/reader/application-service surface is exported from `src/index.ts` in the same grouping order as every existing family.
+
+## 11. Canonical precedents
+
+| Existing owner | What was reused |
+|---|---|
+| `src/domain/identity.ts` / `comparisonIdentity.ts` / `frontendContractIdentity.ts` | canonicalize-then-sha256 request identity + nonce-based fresh instance identity pattern, including the "each module owns its own duplicated `canonicalize()`" convention |
+| `src/artifacts/artifactWriter.ts` | atomic temp-dir-then-rename persistence, media-before-manifest, collision-is-rejection |
+| `src/artifacts/comparisonArtifactWriter.ts` | manifest-only (no media copy) persistence pattern, reused for the `'approved'` lifecycle variant |
+| `src/artifacts/artifactReader.ts` | reader re-validates through the exact same structural gate the writer uses |
+| `src/domain/frontendContracts.ts` (`PersistentBaselineContract.supersedesBaselineId`) | explicit, append-only, forward-declared supersession |
+| `src/application/frontendContractPersistenceService.ts` (`approveAndPersistBaseline`) | single explicit approval action, separate from any other workflow step, refusing an already-approved/invalid target |
+| `src/domain/completion.ts` (`deriveCompletion`) | reused unchanged, not reimplemented |
+| `src/domain/schema.ts` (`getProducerInfo`, `PRODUCER_NAME`) | reused unchanged |
+| `src/domain/diagnostics.ts` (`DIAGNOSTIC_CODES`/`DIAGNOSTIC_SEVERITY`) | extended additively (5 new codes), never duplicated |
+| `src/domain/comparison.ts` (`ComparisonSourceObservationReference`) | direct shape precedent for `ExternalReferenceSourceReference` |
+| `src/request/paths.ts` (`normalizeOutputLocation`) | reused unchanged for path-traversal prevention |
+| `src/cli.ts` (`approve-baseline`/`save-change-contract` help/arg-parsing/dispatch) | direct template for `import-reference`/`approve-reference` |
+
+## 12. New owners introduced
+
+- `src/domain/externalReferenceImage.ts` — pure, dependency-free PNG/JPEG/WebP header-byte format detection and dimension parsing; bounded format/size/dimension constants.
+- `src/domain/externalReference.ts` — `ExternalReferenceArtifact` (discriminated union of `ImportedExternalReferenceArtifact`/`ApprovedExternalReferenceArtifact`), its lifecycle/provenance/image-reference/source-reference sub-types, and `isValidExternalReferenceArtifact` (+ sub-validators, + `isImportedExternalReferenceArtifact`/`isApprovedExternalReferenceArtifact` type guards).
+- `src/domain/externalReferenceIdentity.ts` — `buildExternalReferenceRequestIdentity`, `buildExternalReferenceInstanceIdentity`.
+- `src/artifacts/externalReferenceArtifactWriter.ts` / `externalReferenceArtifactReader.ts` — persistence and read-back.
+- `src/application/externalReferencePersistenceService.ts` — `importExternalReference`, `approveExternalReference`, the two canonical application-level use cases.
+- CLI: `import-reference`, `approve-reference` (in `src/cli.ts`, additive).
+
+## 13. Existing owners extended
+
+- `src/domain/diagnostics.ts` — 5 additive `DIAGNOSTIC_CODES` entries (`unsupported-image-format`, `invalid-image-dimensions`, `image-too-large`, `unsupported-schema-version`, `reference-not-found`), all severity `error`; no existing code/severity changed.
+- `src/index.ts` — one additive export block, same grouping order as every existing family.
+- `src/cli.ts` — additive help text, argument parsers, command runners, and dispatch entries for the two new commands; no existing command's help text, parsing, or behavior changed.
+
+## 14. Files changed
+
+Modified: `docs/ARCHITECTURE.md`, `docs/CONTRACTS.md`, `docs/CURRENT_STATE.md`, `docs/WORKFLOWS.md`, `src/domain/diagnostics.ts`, `src/index.ts`, `src/cli.ts`.
+New: `src/domain/externalReference.ts`, `externalReferenceIdentity.ts`, `externalReferenceImage.ts`; `src/artifacts/externalReferenceArtifactReader.ts`, `externalReferenceArtifactWriter.ts`; `src/application/externalReferencePersistenceService.ts`; `tests/unit/externalReference.test.ts`, `externalReferenceIdentity.test.ts`, `externalReferenceImage.test.ts`, `externalReferenceArtifactWriter.test.ts`, `externalReferencePersistenceService.test.ts`, `cliExternalReference.test.ts`, `externalReferenceImageFixtures.ts`.
+
+## 15. Tests added/changed
+
+Six new test files (38 total files, 668 total tests, up from 32/627) — zero existing test file modified. See the "Responsibility-to-test trace" in the run's `test-implementation-report.txt` for the full TST-NNN-to-test mapping; summary:
+
+- `externalReferenceImage.test.ts` — format detection, dimension parsing (valid + truncated/unrecognized), dimension bounds.
+- `externalReferenceIdentity.test.ts` — deterministic request identity, identity-bearing-change sensitivity, fresh instance identity.
+- `externalReference.test.ts` — the structural validator: valid imported/approved shapes, schema/kind mismatch, mixed lifecycle-variant fields, out-of-bound dimensions, nested image path, producer/diagnostics/supersedesReferenceId edge cases.
+- `externalReferenceArtifactWriter.test.ts` — atomic persistence, no-media-copy on approval, collision rejection, no leftover temp directory, reader/writer round-trip symmetry, reader fail-closed on corrupt/invalid content.
+- `externalReferencePersistenceService.test.ts` — the full import/approve behavior model: valid import, every failure mode (unsupported format, over-limit size, invalid dimensions, unresolvable supersession target), import-never-approves, approval producing a new non-media-copying instance without mutating the imported artifact, re-approval rejection, and forward-pointer-only supersession (with a direct byte-for-byte immutability assertion on the superseded artifact's manifest).
+- `cliExternalReference.test.ts` — end-to-end `import-reference`/`approve-reference` through `runCli()`, help text, and error paths — no Chromium.
+
+## 16. Validation results
+
+All commands run against commit `4a15baf` on `implementation/v0.7-reference-foundation`:
+
+| Command | Result |
+|---|---|
+| `npm run typecheck` | PASS |
+| `npm run lint` | PASS |
+| `npm test` | PASS — 38 files, 668 tests |
+| `npm run build` | PASS (all 6 new modules compiled into `dist/`) |
+| `npm run check:docs` | PASS (17 required files) |
+| `git diff --check` | PASS |
+| `npm pack --dry-run` | PASS (159 files, 284.3 kB / 1.3 MB unpacked) |
+| `npm run test:browser` | PASS — 9 files, 120 tests (unchanged count — no new browser test needed) |
+| `npm run test:security` | PASS — 68 tests |
+
+## 17. Public contract / schema changes
+
+New, independent `EXTERNAL_REFERENCE_SCHEMA_VERSION = '1.0.0'`. No existing schema version (`SCHEMA_VERSION '1.2.0'`, `COMPARISON_SCHEMA_VERSION`, `CONTRACT_SCHEMA_VERSION`, `EVALUATION_SCHEMA_VERSION`, `BOUNDED_AGENT_CONTEXT_SCHEMA_VERSION`) changed.
+
+## 18. Package/API impact
+
+`src/index.ts`'s public export surface grew additively (new types/constants/functions listed in section 12); nothing existing was renamed, removed, or changed in signature. `npm pack --dry-run` confirms the package still builds and packs cleanly. No new runtime dependency (`package.json`/`package-lock.json` unchanged).
+
+## 19. Security/privacy impact
+
+No network calls, no vision/AI API calls, no OCR, no automatic navigation to URLs in image metadata, no execution of image content — the entire image-handling boundary (`externalReferenceImage.ts`) only reads bounded header bytes via pure functions. Persisted manifests store only a bare relative image filename (never an absolute host path) — enforced by `isValidExternalReferenceImageReference` rejecting any path containing a separator. The target frontend is never touched by import/approval. Bounded input: max 20,000,000 bytes, dimensions `[1, 8192]` px per side, exactly three supported formats — all fail-closed on violation.
+
+## 20. Documentation changes
+
+Additive sections only, in `docs/ARCHITECTURE.md` (relationship of the new foundation to the existing engine boundaries), `docs/CONTRACTS.md` (the full `ExternalReferenceArtifact` shape and key rules — the primary contract reference), `docs/CURRENT_STATE.md` ("v0.7 Prompt 1 status" section, plus updated "Not implemented"/"Next target"), and `docs/WORKFLOWS.md` (the new import/approve workflow, and a correction to the "Planned v0.7 reference-driven correction flow" first line marking identity/provenance as now implemented). `docs/ROADMAP.md` was **not** rewritten into implementation batches, per the explicit instruction.
+
+## 21. Out-of-scope confirmation
+
+This stage did **not** implement: reference regions, requirements, tolerances, adequacy evaluation, compatibility/theme/viewport evaluation, reference-region↔runtime-target binding, reference-vs-candidate fidelity evaluation, bounded visual-correction packets, the coding-agent correction loop, the viewer, or annotation. Confirmed by direct grep of the new source files for that vocabulary (none found outside explicit "not implemented here" documentation comments) and by the judge stage's independent review (`judge-report.txt`, question 8).
+
+## 22. Known limitations
+
+1. No fuzz-testing of adversarial/malformed image files beyond the specific truncation/unsupported-chunk-layout cases already covered — a deliberate, documented scope boundary for a foundation stage (the parsing functions are defensively bounded by construction: no unbounded loops, no reads past a declared segment length without a check).
+2. `scripts/ci/runPackedObservationSmoke.mjs` was not extended to exercise `import-reference`/`approve-reference` from an installed tarball — `npm pack --dry-run` was run and passed, but the deeper packed-CLI smoke convention used by `observe`/`compare`/`approve-baseline` was deliberately not extended in this stage, to avoid scope creep beyond "the smallest complete foundation."
+3. A background research subagent tasked with pure read-only precedent retrieval instead wrote 5 speculative source files despite an explicit no-write instruction; it was stopped, and its uncommitted output was moved into `git stash` (preserved, not deleted, not treated as authoritative) before any design decision was made. Feedback on this was filed separately.
+4. The `my-dev-kit-orchestrator`'s automated `context` readiness gate for the test-implementation stage reports 21 of 26 test responsibilities as "partially-mapped" rather than "mapped," because its graph-based heuristic does not treat a comment-tagged vitest `it()` block as first-class "testFiles" evidence for this repository's plain-vitest test-authoring convention. This was investigated directly (see `test-implementation-report.txt`) and confirmed to be a tool heuristic gap, not an actual coverage gap — every `TST-NNN` responsibility was independently confirmed present by name in exactly one test.
+
+## 23. Remaining risks
+
+- The forward-pointer-only supersession design (no literal `'superseded'` state) means a consumer must query *all* references to determine whether a given one has been superseded, rather than reading a single field on that reference itself. This is an accepted tradeoff for immutability (see section 10), but Prompt 2+ should be aware of it when designing any "list active references" capability.
+- The two-instance (imported + approved) persistence model means every approval doubles the on-disk artifact count for a given logical reference. This is bounded and intentional (mirrors how baseline approval already works) but should inform any future retention/cleanup policy discussion — none exists yet, by design, per section 12G's "do not build a large content-management/history system."
+
+## 24. Exact next action
+
+**v0.7 Prompt 2** — explicit reference regions, geometry, and reusable reference relationships, built on top of the `referenceRequestId`/`referenceId` identity established here.
+
+## 25. Report path
+
+`docs/reports/v0.7-reference-foundation-prompt1.md` (this file)