@dailephd/my-frontend-observer 0.10.0 → 0.10.1

package/docs/reports/v0.7-reference-requirements-prompt3.md

@@ -1,217 +1,217 @@
-# v0.7 Prompt 3 — Selected Design Requirements, Tolerance Semantics, and Reference-Evidence Adequacy
-
-## 1. Verdict
-
-**PASS_V0_7_REFERENCE_REQUIREMENTS_PROMPT3**
-
-## 2. Repository
-
-`Z:\Users\newuser\Projects\my-frontend-observer` (`https://github.com/dailephd/my-frontend-observer.git`)
-
-## 3. Branch
-
-`implementation/v0.7-reference-requirements`
-
-## 4. Starting head
-
-`3a4a2e3b2968b5788e6f3b11a3cda6d83053d9cb`
-
-## 5. Prompt 2 base head
-
-`3a4a2e3b2968b5788e6f3b11a3cda6d83053d9cb` (same commit — the branch was created directly from Prompt 2's completed, clean state; verified as an ancestor via `git merge-base --is-ancestor` for both `c5c2eef` and `3a4a2e3`)
-
-## 6. Ending head
-
-`4d7bd610d8b3ca8ed6e228eee39e08003c21161c` (implementation commit; the report commit that follows this file's own commit will be one ahead of this)
-
-## 7. Git status
-
-Clean at the ending head. The Prompt 1 speculative-write stash (`stray-fork-writes-preserved-for-reference: ...`) remains present, untouched, unapplied, unmined, verified via `git stash list` at both the start and end of this stage.
-
-## 8. Resolved my-dev-kit version
-
-`@dailephd/my-dev-kit@1.12.3` (re-checked via `npm view @dailephd/my-dev-kit version` at execution start — unchanged from Prompt 1/2, still latest)
-
-## 9. Fresh index path / ID
-
-`.my-dev-kit/index-prompt3` — a fresh index built this stage (`my-dev-kit index --root . --src src --out .my-dev-kit/index-prompt3 --call-graph --json`), independent of the Prompt 1/2 indexes. Gitignored, never staged.
-
-## 10. Previous contract verification
-
-Read directly from the maintained repository before any change:
-
-- `src/domain/externalReference.ts` — `ExternalReferenceArtifact` (imported/approved variants), `isValidExternalReferenceArtifact`, the `regions?` field and its validation wiring (Prompt 2).
-- `src/domain/externalReferenceRegions.ts` — `ReferenceRegion`, `ReferenceRegionGeometry`, `deriveReferenceRegionGeometry`, `isValidReferenceRegions`, `MAX_REFERENCE_REGIONS`, `REFERENCE_REGION_ID_PATTERN`.
-- `src/domain/externalReferenceRegionRelationships.ts` — `deriveReferenceRegionRelationships`, `ReferenceRegionRelationship`, bound constants.
-- `src/domain/externalReferenceIdentity.ts` — `buildExternalReferenceRequestIdentity`'s existing `regions` backward-compatible-omission pattern (directly extended, not redesigned).
-- `src/application/externalReferencePersistenceService.ts` — `importExternalReference`/`approveExternalReference`'s existing region-handling shape.
-- `src/cli.ts` — `import-reference`/`approve-reference`'s existing `--regions-file` handling and `loadRegionsFile` pattern.
-- The full Prompt 1/2 test suite (719 tests at the time), confirmed green before touching anything.
-
-Prompt 1/2 reports and current source matched exactly — no `BLOCKED_PREVIOUS_PROMPT_REPORT_MISMATCH` condition was encountered.
-
-## 11. v0.5 precedent review
-
-- **Exact category types inspected**: `src/domain/frontendContracts.ts` — `AUTHORED_CHANGE_SCOPE_CATEGORIES`/`AuthoredChangeScopeCategory`/`isAuthoredChangeScopeCategory` (`requested`/`expected-dependent`/`protected`/`preserved`; `'unexpected'` is a separate, derived-only `CHANGE_SCOPE_CLASSIFICATIONS` member, never authorable), `EXPECTED_DEPENDENT_MODES`/`ExpectedDependentMode`/`isValidExpectedDependentMode` (`required`/`permitted`).
-- **Contract primitive witnesses**: `ContractPrimitive`'s closed vocabulary and `hasOnlyKeys` discipline (structural style precedent, not directly reused — Prompt 3's subjects are a different, reference-specific shape).
-- **Tolerance witnesses**: `ContractTolerance` (`exact`/`absolute-px`/`percent`) and its bounds (`CONTRACT_TOLERANCE_ABSOLUTE_PX_MIN/MAX` = 0/100, `_PERCENT_MIN/MAX` = 0/100), and `frontendContractEvaluation.ts#toleranceToPx`'s "percent denominator is the before-value" convention.
-- **Conflict semantics inspected**: `frontendContractEvaluation.ts#primitivesConflict`/`evaluateFrontendContract`'s per-clause conflict detection — confirmed this runs at **runtime evaluation time** against actual before/after `ObservationArtifact` evidence (`toClauseResult`, `EvalContext`), not at authoring time.
-- **What was reused**: `AuthoredChangeScopeCategory`/`AUTHORED_CHANGE_SCOPE_CATEGORIES`/`isAuthoredChangeScopeCategory` and `ExpectedDependentMode`/`EXPECTED_DEPENDENT_MODES`/`isValidExpectedDependentMode` are imported **directly** from `frontendContracts.ts` (zero duplication) — these types carry no runtime-only coupling in their own definition, so direct reuse was safe and correct. The `CONTRACT_TOLERANCE_*` numeric bound *values* (0–100 for both absolute and percent) were mirrored as independently-owned constants.
-- **What was not reused, and why**:
-  - `ContractTolerance` was **not** reused as a type — its `absolute-px` member is implicitly runtime/CSS pixels (compared against live `TargetGeometry`); reusing it for reference-image pixels would silently mislabel the unit, which request section 20 explicitly forbids. A new `ReferenceRequirementTolerance` type was introduced instead, with the same numeric bounds but an explicitly-named `absolute-reference-px` kind.
-  - `primitivesConflict`/the whole runtime conflict-detection pass was **not** reused — it operates over before/after `ObservationArtifact` evidence that does not exist at this authoring-time stage. Prompt 3 instead restricts invalid combinations directly: no two requirements in a collection may share the same structural subject, regardless of category (see section 25).
-
-## 12. v0.6 adequacy precedent review
-
-- **Exact types/functions inspected**: `src/domain/boundedAgentContext.ts` — `Adequacy { state; reasons }`, `AdequacyState` (`adequate`/`partial`/`inadequate`), `ADEQUACY_REASON_CODES` (`required-runtime-target-unavailable`, `static-correlation-ambiguous`, `consumer-incompatibility`, etc.), `isValidAdequacy`.
-- **Whether the `Adequacy` type was reused**: no.
-- **Whether a separate reason family was introduced**: yes — `REFERENCE_REQUIREMENT_ADEQUACY_STATES` (a freshly-declared, textually-identical three-value vocabulary: `adequate`/`partial`/`inadequate`) and `REFERENCE_REQUIREMENT_ADEQUACY_REASON_CODES` (exactly two codes: `no-selected-requirements`, `missing-reference-relationship-evidence`), both owned by `externalReferenceRequirements.ts`.
-- **Why**: `boundedAgentContext.ts`'s reason codes describe runtime-target availability and static-correlation ambiguity — concerns that do not exist at this stage (there is no runtime target, no candidate, no static correlation yet). Reusing that exact reason-code union would either force nonsensical codes onto reference-side adequacy or silently expand a runtime-specific vocabulary to mean something unrelated - both violate the explicit "must not mislabel reference adequacy as bounded-agent-context adequacy" requirement. The three-state *shape* (`adequate`/`partial`/`inadequate`) is coincidentally identical text but is an independently-declared constant in the reference module, following this repository's established convention of duplicating small shared vocabularies per family (e.g. `canonicalize()` duplicated five times) rather than cross-importing between otherwise-unrelated domains.
-
-## 13. Requirement model
-
-- **Actual type names**: `ExternalReferenceRequirement`, `RawReferenceRequirement` (unidentified authored input), `ReferenceRequirementSubject` (`RegionPropertyRequirementSubject | RegionRelationshipRequirementSubject | RegionMeasurementRequirementSubject`), all in `src/domain/externalReferenceRequirements.ts`.
-- **Requirement ID semantics**: `requirementId` is **always system-computed** via `buildReferenceRequirementIdentity(subject, category, tolerance, expectedDependentMode)` (`src/domain/externalReferenceRequirementIdentity.ts`, mirroring `frontendContractIdentity.ts#buildClauseIdentity`'s exact canonicalize+sha256 shape). Authoring a `requirementId` in raw input is a validation error (`isValidRawReferenceRequirement` rejects it) — deliberately different from v0.5's `clauseId` (which authors do supply, because clauses need a cross-document-reference id for `supersedesBaselineClauseIds`; requirements have no equivalent need yet).
-- **Category semantics**: exactly v0.5's `AuthoredChangeScopeCategory`, imported directly. `expectedDependentMode` required iff category is `expected-dependent`, forbidden otherwise (identical shape to `isValidPerChangeClause`'s rule).
-- **Supported subjects**: `region-property` (one region + `ReferenceRequirementRegionProperty`), `region-relationship` (two regions + `PairwiseRelationshipKind`, reused from `relationships.ts`, geometry-only families only), `region-measurement` (two regions + `ReferenceRequirementMeasurement`).
-- **Supported properties**: `REFERENCE_REQUIREMENT_REGION_PROPERTIES = ['x','y','width','height','right','bottom','centerX','centerY']` — exactly `ReferenceRegionGeometry`'s own fields, nothing invented (no separate `left`/`top` aliases).
-- **Relationship/measurement requirements**: relationship subjects reuse Prompt 2's `PairwiseRelationshipKind` vocabulary directly (no tolerance permitted — a categorical fact). Measurement subjects use one of six pure derived measurements: `vertical-gap`, `horizontal-gap`, `center-x-delta`, `center-y-delta`, `left-edge-delta`, `right-edge-delta` (a tolerance is required).
-- **Bounds**: `MAX_REFERENCE_REQUIREMENTS = 50` per artifact — a maximum capacity, never a required minimum; no per-region sub-cap was added (the overall bound plus the duplicate-subject rule already bounds practical growth well within it).
-
-## 14. Tolerance model
-
-- **Exact tolerance kinds**: `ReferenceRequirementTolerance = { kind: 'exact' } | { kind: 'absolute-reference-px'; amount } | { kind: 'percent'; amount }`.
-- **Units**: `absolute-reference-px` is explicitly reference-image pixels, never silently treated as CSS/runtime pixels — no scale/compatibility mapping exists yet (deferred to Prompt 6, per request section 20).
-- **Bounds**: `REFERENCE_REQUIREMENT_TOLERANCE_ABSOLUTE_PX_MIN/MAX = 0/100`, `_PERCENT_MIN/MAX = 0/100` — same numeric values as v0.5's `CONTRACT_TOLERANCE_*` constants, independently owned (not imported) for the unit-labeling reason above.
-- **Validation**: negative, non-finite, and unsupported-kind tolerances fail closed (`isValidReferenceRequirementTolerance`); an `exact` tolerance permits no `amount` field at all.
-- **Relationship vs numeric applicability**: `region-relationship` subjects must **not** carry a tolerance (categorical fact); `region-property`/`region-measurement` subjects **must** carry one — enforced explicitly, in both directions, by `validateAuthoredRequirementFields`.
-- **Reuse of v0.5**: numeric bounds mirrored (see section 11); the type itself is a fresh, reference-owned type, not a v0.5 reuse (see section 11's rationale).
-
-## 15. Reference expectation derivation
-
-Nothing is stored beyond `{subject, category, expectedDependentMode?, tolerance?}` per requirement — no numeric expected value (e.g. `width: 424`) and no relationship-match boolean are ever persisted. `deriveReferenceRequirementExpectation(subject, regions, options)` is a pure function computing, on demand:
-
-- for `region-property`: the named region's `ReferenceRegionGeometry[property]`, freshly derived from its canonical rectangle every call;
-- for `region-measurement`: the named pure measurement over the two regions' derived geometries;
-- for `region-relationship`: whether the reference actually exhibits the claimed relationship, by deriving the region pair's relationships via `deriveReferenceRegionRelationships` and checking within the **correct relationship family** (a bug caught and fixed during test-writing — see section 20) for a match in either declared or geometry-determined order (only `follows-vertically` can differ from declared order, since it is the one family whose direction depends on actual geometry rather than input order).
-
-This directly satisfies the "avoid redundant storage, derive from canonical geometry" instruction — there is no possibility of a stored expected value drifting from the region it describes, because none is ever stored.
-
-## 16. Adequacy model
-
-- **Status vocabulary**: `REFERENCE_REQUIREMENT_ADEQUACY_STATES = ['adequate', 'partial', 'inadequate']`.
-- **Reason codes**: exactly two — `no-selected-requirements`, `missing-reference-relationship-evidence`. No other reason code exists because no other condition is possible: an unknown region id, unsupported property, or malformed requirement is a **construction-time validation failure** (`isValidReferenceRequirements`) that never reaches adequacy computation at all.
-- **Zero-requirement behavior**: explicitly `inadequate`, with a `no-selected-requirements` reason — a documented product decision (request section 24F): a region-rich, fully-valid reference is still not usable for a correction task until the user has actually selected what matters.
-- **Missing-region behavior**: not an adequacy concern — rejected at validation time before adequacy ever runs (see section 11's "what was not reused" discussion of the D behavior choice: "authored reference requirement pointing to a nonexistent authored region should fail validation rather than become normal unavailable evidence").
-- **Missing-relationship-evidence behavior**: a structurally-valid `region-relationship`/`region-measurement` requirement whose claimed evidence cannot actually be derived from the geometry (wrong relationship, or a measurement that is geometrically undefined, e.g. `vertical-gap` between overlapping regions) is reported `missing-reference-relationship-evidence`, contributing to a `partial` or `inadequate` overall status.
-- **Deterministic ordering**: reasons are pushed in authored-requirement-array order, never object-key or Set-iteration order — verified by test.
-- **Blocking intent for later stages**: `ReferenceRequirementAdequacy` is returned by both `importExternalReference`/`approveExternalReference` and printed by the CLI (`Adequacy: <status>`) so a later orchestration stage can enforce "inadequate reference → do not begin correction" without Prompt 3 itself running any coding-agent workflow.
-
-## 17. Identity
-
-- `buildExternalReferenceRequestIdentity` gained one additional optional trailing parameter, `requirements?: readonly ExternalReferenceRequirement[]`, following the exact `regions` precedent: omitted from the hashed semantic view entirely (never defaulted to `null`) when absent, so every Prompt 1/2 call site — and every Prompt 3 call with no requirements — produces a byte-identical hash to before this parameter existed (verified by test: `'omitting requirements produces the exact same identity as before this parameter existed'`).
-- Path independence: the function still takes no path argument of any kind; this holds by construction, not merely by test.
-- Content participation: verified by test that changing a requirement's category, adding, or removing a requirement each changes the artifact-level `referenceRequestId`. Each requirement's own `requirementId` additionally changes with its subject/category/mode/tolerance (tested directly in `externalReferenceRequirementIdentity.test.ts`), so a change to any requirement changes both that requirement's own id and the artifact-level identity.
-
-## 18. Artifact / schema decision
-
-- Requirements live as an additive, optional `requirements?: ExternalReferenceRequirement[]` field directly on `ExternalReferenceArtifactBase` (both `ImportedExternalReferenceArtifact` and `ApprovedExternalReferenceArtifact` inherit it) — the same minimal-extension shape as Prompt 2's `regions`, not a separate derived artifact family (no new persisted artifact kind was introduced).
-- **No schema version bump** — `EXTERNAL_REFERENCE_SCHEMA_VERSION` remains `'1.0.0'`, for the identical reasoning already established in the Prompt 2 report: the field is genuinely optional/additive, and this repository's `isValid*Artifact` convention performs a strict version-equality check, so bumping would make every Prompt 1/2 artifact fail validation under the current reader — directly contradicting the explicit "legacy artifacts remain valid" requirement.
-- **Historical artifact compatibility**: verified by test (`'U: a legacy (Prompt 1/2) artifact with no requirements field at all remains valid'`) that an artifact predating this field validates successfully.
-- **Immutable approved-reference handling**: `approveExternalReference` copies `imported.requirements` into a **new** artifact object (fresh `referenceId`, same `referenceRequestId`) — it never reopens or rewrites the imported artifact's own manifest file. Verified by test that an approved artifact's manifest is byte-for-byte unchanged after later, unrelated import/approve activity in the same output directory (reusing the exact test already established in Prompt 2 for this purpose, now also covering requirements).
-
-## 19. Public interface
-
-- **CLI changes**: `import-reference` gained an optional `--requirements-file <json-file>` (root shape `{ "requirements": [...] }`, validated by a new `loadRequirementsFile` mirroring `loadRegionsFile` exactly — object root, exact allow-listed top-level field). Both `import-reference` and `approve-reference` now additionally print `Requirements: <count>` and `Adequacy: <status>` lines. No existing flag, argument, help text section, or exit code changed in meaning.
-- **Input file shape**: `{ "requirements": [ { "category": "requested", "subject": { "kind": "region-property", "region": "current-page-card", "property": "width" }, "tolerance": { "kind": "absolute-reference-px", "amount": 4 } } ] }` — chosen directly from the `--regions-file`/`--targets-file` object-root-wrapper precedent, not the prompt's illustrative example verbatim. No `requirementId` field is accepted in this file (system-computed).
-- **Programmatic export changes**: `src/index.ts` additively exports the complete new requirement/tolerance/adequacy type, constant, and function surface (`ExternalReferenceRequirement`, `RawReferenceRequirement`, `ReferenceRequirementSubject` variants, `ReferenceRequirementTolerance`, `ReferenceRequirementAdequacy`, `deriveReferenceRequirementExpectation`, `deriveReferenceRequirementAdequacy`, `buildReferenceRequirement`, `isValidRawReferenceRequirement`, `isValidReferenceRequirements`, plus bound/vocabulary constants). `AuthoredChangeScopeCategory`/`ExpectedDependentMode` and their constants are **not** re-exported a second time from the new module (they were already exported from `frontendContracts.js` — re-exporting would have been a duplicate-name compile error, caught and fixed during implementation). `ImportExternalReferenceOptions` gained an additive `requirements?` field; both application-result types gained additive `requirementCount: number` and `adequacy: ReferenceRequirementAdequacy` fields.
-- **Backward compatibility**: every Prompt 1/2 CLI invocation and every existing result-consumer reading the pre-existing fields continues to work unchanged — verified by the full pre-existing suite passing unmodified, plus dedicated tests confirming a requirements-less import reports `requirementCount: 0`, `adequacy.status: 'inadequate'`, and no `requirements` key on the manifest.
-
-## 20. Files changed
-
-Modified: `docs/ARCHITECTURE.md`, `docs/CONTRACTS.md`, `docs/CURRENT_STATE.md`, `docs/WORKFLOWS.md`, `src/application/externalReferencePersistenceService.ts`, `src/cli.ts`, `src/domain/diagnostics.ts`, `src/domain/externalReference.ts`, `src/domain/externalReferenceIdentity.ts`, `src/index.ts`, `tests/unit/cliExternalReference.test.ts`, `tests/unit/externalReference.test.ts`, `tests/unit/externalReferenceIdentity.test.ts`, `tests/unit/externalReferencePersistenceService.test.ts`.
-New: `src/domain/externalReferenceRequirements.ts`, `src/domain/externalReferenceRequirementIdentity.ts`, `tests/unit/externalReferenceRequirements.test.ts`, `tests/unit/externalReferenceRequirementIdentity.test.ts`.
-
-`src/domain/relationships.ts` was **not** modified this stage (its Prompt 2 additive exports were reused as-is, imported alongside three additional pre-existing family-constant exports `HORIZONTAL_ORDER_RELATIONSHIPS`/`VERTICAL_ORDER_RELATIONSHIPS`/etc. that were already exported).
-
-## 21. Tests added / changed
-
-60 new tests across 2 new files and additions to 4 existing files (0 pre-existing test modified or removed):
-
-- `externalReferenceRequirementIdentity.test.ts` (6 tests): content-determinism, subject/category/tolerance/mode sensitivity, call-site independence.
-- `externalReferenceRequirements.test.ts` (35 tests): all four categories valid, authored `unexpected` rejected, mode required/forbidden correctly, authored `requirementId` rejected, all three subject kinds valid/invalid (including unsupported property/measurement/relationship), tolerance-applicability-by-subject-kind, unknown-region-id rejection, duplicate/conflicting-subject rejection (including relationship-subject order-independence), requirement-limit exact-max/one-over, exact/absolute/percent tolerance boundaries, negative/non-finite/unsupported-kind tolerance rejection, all six measurement derivations (including overlap-undefined cases), reference-expectation derivation for all three subject kinds (including the family-lookup bug fix - see section 20), zero/all/some-unavailable adequacy states, deterministic reason ordering, no-numeric-score assertion, immutability.
-- `externalReferenceIdentity.test.ts` (+5 tests): requirements-omission backward compatibility, same-content-same-identity, category-change/add/remove-changes-identity.
-- `externalReference.test.ts` (+6 tests): legacy-no-requirements validity, valid requirements on both lifecycle variants, unknown-region rejection, regions-absent rejection, malformed-value rejection.
-- `externalReferencePersistenceService.test.ts` (+5 tests): import-with-requirements persists them and reports adequacy, regionless/requirement-less import reports zero/inadequate, unknown-region import rejection (nothing persisted), authored-id rejection, approval carries requirements forward with matching adequacy.
-- `cliExternalReference.test.ts` (+5 tests): end-to-end `--requirements-file` import+approve with adequacy reporting, legacy no-flag invocation reports zero/inadequate, unknown-region CLI rejection, malformed-`--requirements-file` rejection (bad JSON, array root, unknown field).
-
-## 22. Validation results
-
-All on the ending commit (`4d7bd61`) on `implementation/v0.7-reference-requirements`:
-
-| Command | Result |
-|---|---|
-| `npm run typecheck` | PASS |
-| `npm run lint` | PASS (one `no-unused-vars` finding during development, fixed before commit) |
-| `npm test` | PASS — 42 files, 779 tests (up from 40/719) |
-| `npm run build` | PASS (both new modules compiled into `dist/`) |
-| `npm run check:docs` | PASS (17 required files) |
-| `git diff --check` | PASS |
-| `npm pack --dry-run` | PASS (173 files, 330.5 kB / 1.4 MB unpacked; both new modules present in the tarball listing) |
-| `npm run test:browser` | PASS — 9 files, 120 tests (unchanged count) |
-| `npm run test:security` | PASS — 68 tests |
-
-## 23. Regression results
-
-- **Prompt 1 tests**: all pre-existing `externalReference*`/`cliExternalReference` tests pass unmodified.
-- **Prompt 2 tests**: `externalReferenceRegions.test.ts`, `externalReferenceRegionRelationships.test.ts` pass unmodified.
-- **v0.5 dependent tests**: `frontendContracts.test.ts`, `frontendContractEvaluation.test.ts`, `frontendContractPersistence.test.ts` explicitly re-run — 207 combined tests (with `boundedAgentContext.test.ts`, `boundedAgentContextProjection.test.ts`, `relationships.test.ts`, `relationshipDerivation.test.ts`) pass unchanged. `frontendContracts.ts` itself was not modified at all (only imported from, read-only).
-- **v0.6 tests**: `boundedAgentContext*.test.ts` (4 files) pass unchanged; `boundedAgentContext.ts` was not modified (only inspected for precedent, never imported from — see section 12).
-
-## 24. Boundedness
-
-- **Requirement bound**: `MAX_REFERENCE_REQUIREMENTS = 50` per artifact — explicit, tested at exactly-max (accepted) and one-over (rejected, no partial acceptance).
-- No separate per-region requirement cap was added; the overall bound plus the duplicate-subject rule already bounds practical per-region growth (at most one requirement per distinct property/relationship/measurement combination can exist at all, well within 50 even for the maximum 20-region case).
-
-## 25. Conflict handling
-
-v0.5's `primitivesConflict`/`evaluateFrontendContract` conflict detection is a **runtime-evaluation-time** mechanism requiring before/after `ObservationArtifact` evidence that does not exist at requirement-authoring time — it was not reused, per request section 45's explicit permission to restrict invalid combinations instead when v0.5 semantics cannot be safely reused. Prompt 3's chosen rule: **no two requirements in one collection may share the same structural subject**, regardless of category (`sameSubject()` in `externalReferenceRequirements.ts`, with relationship/measurement subjects treated as the same regardless of which region is declared first). This single rule resolves both the "duplicate requirement" and "conflicting categories on the same subject" behavior-model questions with one mechanism, is fully deterministic, and is enforced at collection-validation time (`isValidReferenceRequirements`) — never silently choosing one requirement over another.
-
-## 26. Security / privacy impact
-
-No new network calls, no vision/AI API calls. `--requirements-file`'s path is never persisted or included in any identity, matching `--regions-file`/`--targets-file`/`--contract-file` convention exactly. Requirement content is plain structured data (category strings, region-id references, numeric tolerances) with no new file-system write boundary — requirements are embedded directly in the existing `manifest.json`. The unsupported-top-level-field rejection on `--requirements-file`'s root prevents silently ignored/misinterpreted malformed input, matching the existing `--regions-file` convention.
-
-## 27. Documentation changes
-
-Additive sections only: `docs/CONTRACTS.md` ("v0.7 Prompt 3 selected design requirements, tolerance semantics, and reference-evidence adequacy" — the primary contract reference), `docs/ARCHITECTURE.md` (relationship of the new requirement/adequacy modules to v0.5/v0.6 precedent and to Prompt 1/2), `docs/CURRENT_STATE.md` ("v0.7 Prompt 3 status" section, plus updated "Not implemented"/"Next target"), `docs/WORKFLOWS.md` (the extended import/approve workflow diagram, the new requirement/adequacy description, and a correction to the "Planned v0.7 reference-driven correction flow" marking requirements/tolerances/adequacy as now implemented). `docs/ROADMAP.md` was **not** touched. `docs/COMMANDS.md` was **not** touched, consistent with Prompt 1/2's own precedent of not documenting `import-reference`/`approve-reference` there.
-
-## 28. Tooling incidents
-
-None this stage. No background/subagent write occurred during Prompt 3's implementation - all work was performed directly in the main session, per the stricter no-background-speculative-writes instruction carried forward from Prompt 2. The Prompt 1 speculative-write incident remains historical; its stash was confirmed untouched at both the start and end of this stage.
-
-## 29. Inherited orchestrator heuristic issue
-
-Not encountered as a product problem this stage. `my-dev-kit-orchestrator` was not modified, no test was rewritten to satisfy its responsibility-mapping heuristic, and no fake evidence tags were added. This stage used `DIRECT_IMPLEMENTATION` without invoking the orchestrator's stage-context workflow at all, so the heuristic gap noted in Prompt 1 did not arise here (consistent with Prompt 2).
-
-## 30. Out-of-scope confirmation
-
-This stage did **not** implement: theme identity evaluation, application-state compatibility, viewport compatibility evaluation, reference/candidate comparability, reference-region↔runtime-target binding, runtime target identity in requirement subjects, candidate observation lookup or geometry, reference-vs-candidate delta, fidelity PASS/FAIL, style/color/typography/pixel/image-similarity comparison, visual score, source correlation changes, bounded correction packets, v0.6 agent-context extension, coding-agent invocation, source editing, rerender orchestration, correction iteration, the viewer, annotation, automatic requirement inference, or automatic region detection. Confirmed by direct grep of the new source files for that vocabulary (none found outside explicit "not yet implemented" documentation comments) and by direct code inspection: `ReferenceRequirementSubject` and `ReferenceRequirementAdequacy` contain no runtime-target/candidate/binding field of any kind, not even as a placeholder.
-
-## 31. Known limitations
-
-1. No fuzz-testing of adversarial requirement JSON beyond the specific malformed-shape cases already covered (bad JSON, array root, unknown field, non-object entry, unsupported property/measurement/relationship) — consistent with Prompt 1/2's own documented fuzz-testing scope boundary.
-2. The `region-relationship` reference-expectation lookup can report "opposite region order" unavailability for the one family (`follows-vertically`) whose direction is decided by geometry rather than authored order; a user must author `subjectRegion`/`relatedRegion` matching the geometrically-determined direction to get a `matches: true/false` result for that specific family. This is documented behavior (see section 15), not a defect, but is a rough edge a future prompt's UI/authoring tooling should smooth over (e.g. by trying both orders automatically) rather than something Prompt 3 should paper over silently now.
-3. `MAX_REFERENCE_REQUIREMENTS = 50` has no cited external precedent value (unlike `MAX_REFERENCE_REGIONS`, which coincidentally matches `MAX_TARGETS`) — it is a reasonable, documented, but ultimately judgment-call bound.
-
-## 32. Remaining risks
-
-- Because reference expectations and adequacy are never persisted, every future consumer (Prompt 4+) that needs them must call `deriveReferenceRequirementExpectation`/`deriveReferenceRequirementAdequacy` itself. This mirrors Prompt 2's relationship-derivation design deliberately (avoids drift) and should not be "fixed" by prematurely adding persistence.
-- The duplicate-subject conflict rule is stricter than v0.5's category-aware conflict model (it rejects same-subject-different-category outright rather than trying to reconcile them). If a future prompt determines users genuinely need e.g. a `requested` and a `protected` requirement coexisting on the same subject for some legitimate reason, that will require a deliberate architecture revisit, not a quiet loosening of this rule.
-
-## 33. Exact next action
-
-**v0.7 Prompt 4** — reference applicability/state compatibility and comparability foundation.
-
-## 34. Report path
-
-`docs/reports/v0.7-reference-requirements-prompt3.md` (this file)
+# v0.7 Prompt 3 — Selected Design Requirements, Tolerance Semantics, and Reference-Evidence Adequacy
+
+## 1. Verdict
+
+**PASS_V0_7_REFERENCE_REQUIREMENTS_PROMPT3**
+
+## 2. Repository
+
+`Z:\Users\newuser\Projects\my-frontend-observer` (`https://github.com/dailephd/my-frontend-observer.git`)
+
+## 3. Branch
+
+`implementation/v0.7-reference-requirements`
+
+## 4. Starting head
+
+`3a4a2e3b2968b5788e6f3b11a3cda6d83053d9cb`
+
+## 5. Prompt 2 base head
+
+`3a4a2e3b2968b5788e6f3b11a3cda6d83053d9cb` (same commit — the branch was created directly from Prompt 2's completed, clean state; verified as an ancestor via `git merge-base --is-ancestor` for both `c5c2eef` and `3a4a2e3`)
+
+## 6. Ending head
+
+`4d7bd610d8b3ca8ed6e228eee39e08003c21161c` (implementation commit; the report commit that follows this file's own commit will be one ahead of this)
+
+## 7. Git status
+
+Clean at the ending head. The Prompt 1 speculative-write stash (`stray-fork-writes-preserved-for-reference: ...`) remains present, untouched, unapplied, unmined, verified via `git stash list` at both the start and end of this stage.
+
+## 8. Resolved my-dev-kit version
+
+`@dailephd/my-dev-kit@1.12.3` (re-checked via `npm view @dailephd/my-dev-kit version` at execution start — unchanged from Prompt 1/2, still latest)
+
+## 9. Fresh index path / ID
+
+`.my-dev-kit/index-prompt3` — a fresh index built this stage (`my-dev-kit index --root . --src src --out .my-dev-kit/index-prompt3 --call-graph --json`), independent of the Prompt 1/2 indexes. Gitignored, never staged.
+
+## 10. Previous contract verification
+
+Read directly from the maintained repository before any change:
+
+- `src/domain/externalReference.ts` — `ExternalReferenceArtifact` (imported/approved variants), `isValidExternalReferenceArtifact`, the `regions?` field and its validation wiring (Prompt 2).
+- `src/domain/externalReferenceRegions.ts` — `ReferenceRegion`, `ReferenceRegionGeometry`, `deriveReferenceRegionGeometry`, `isValidReferenceRegions`, `MAX_REFERENCE_REGIONS`, `REFERENCE_REGION_ID_PATTERN`.
+- `src/domain/externalReferenceRegionRelationships.ts` — `deriveReferenceRegionRelationships`, `ReferenceRegionRelationship`, bound constants.
+- `src/domain/externalReferenceIdentity.ts` — `buildExternalReferenceRequestIdentity`'s existing `regions` backward-compatible-omission pattern (directly extended, not redesigned).
+- `src/application/externalReferencePersistenceService.ts` — `importExternalReference`/`approveExternalReference`'s existing region-handling shape.
+- `src/cli.ts` — `import-reference`/`approve-reference`'s existing `--regions-file` handling and `loadRegionsFile` pattern.
+- The full Prompt 1/2 test suite (719 tests at the time), confirmed green before touching anything.
+
+Prompt 1/2 reports and current source matched exactly — no `BLOCKED_PREVIOUS_PROMPT_REPORT_MISMATCH` condition was encountered.
+
+## 11. v0.5 precedent review
+
+- **Exact category types inspected**: `src/domain/frontendContracts.ts` — `AUTHORED_CHANGE_SCOPE_CATEGORIES`/`AuthoredChangeScopeCategory`/`isAuthoredChangeScopeCategory` (`requested`/`expected-dependent`/`protected`/`preserved`; `'unexpected'` is a separate, derived-only `CHANGE_SCOPE_CLASSIFICATIONS` member, never authorable), `EXPECTED_DEPENDENT_MODES`/`ExpectedDependentMode`/`isValidExpectedDependentMode` (`required`/`permitted`).
+- **Contract primitive witnesses**: `ContractPrimitive`'s closed vocabulary and `hasOnlyKeys` discipline (structural style precedent, not directly reused — Prompt 3's subjects are a different, reference-specific shape).
+- **Tolerance witnesses**: `ContractTolerance` (`exact`/`absolute-px`/`percent`) and its bounds (`CONTRACT_TOLERANCE_ABSOLUTE_PX_MIN/MAX` = 0/100, `_PERCENT_MIN/MAX` = 0/100), and `frontendContractEvaluation.ts#toleranceToPx`'s "percent denominator is the before-value" convention.
+- **Conflict semantics inspected**: `frontendContractEvaluation.ts#primitivesConflict`/`evaluateFrontendContract`'s per-clause conflict detection — confirmed this runs at **runtime evaluation time** against actual before/after `ObservationArtifact` evidence (`toClauseResult`, `EvalContext`), not at authoring time.
+- **What was reused**: `AuthoredChangeScopeCategory`/`AUTHORED_CHANGE_SCOPE_CATEGORIES`/`isAuthoredChangeScopeCategory` and `ExpectedDependentMode`/`EXPECTED_DEPENDENT_MODES`/`isValidExpectedDependentMode` are imported **directly** from `frontendContracts.ts` (zero duplication) — these types carry no runtime-only coupling in their own definition, so direct reuse was safe and correct. The `CONTRACT_TOLERANCE_*` numeric bound *values* (0–100 for both absolute and percent) were mirrored as independently-owned constants.
+- **What was not reused, and why**:
+  - `ContractTolerance` was **not** reused as a type — its `absolute-px` member is implicitly runtime/CSS pixels (compared against live `TargetGeometry`); reusing it for reference-image pixels would silently mislabel the unit, which request section 20 explicitly forbids. A new `ReferenceRequirementTolerance` type was introduced instead, with the same numeric bounds but an explicitly-named `absolute-reference-px` kind.
+  - `primitivesConflict`/the whole runtime conflict-detection pass was **not** reused — it operates over before/after `ObservationArtifact` evidence that does not exist at this authoring-time stage. Prompt 3 instead restricts invalid combinations directly: no two requirements in a collection may share the same structural subject, regardless of category (see section 25).
+
+## 12. v0.6 adequacy precedent review
+
+- **Exact types/functions inspected**: `src/domain/boundedAgentContext.ts` — `Adequacy { state; reasons }`, `AdequacyState` (`adequate`/`partial`/`inadequate`), `ADEQUACY_REASON_CODES` (`required-runtime-target-unavailable`, `static-correlation-ambiguous`, `consumer-incompatibility`, etc.), `isValidAdequacy`.
+- **Whether the `Adequacy` type was reused**: no.
+- **Whether a separate reason family was introduced**: yes — `REFERENCE_REQUIREMENT_ADEQUACY_STATES` (a freshly-declared, textually-identical three-value vocabulary: `adequate`/`partial`/`inadequate`) and `REFERENCE_REQUIREMENT_ADEQUACY_REASON_CODES` (exactly two codes: `no-selected-requirements`, `missing-reference-relationship-evidence`), both owned by `externalReferenceRequirements.ts`.
+- **Why**: `boundedAgentContext.ts`'s reason codes describe runtime-target availability and static-correlation ambiguity — concerns that do not exist at this stage (there is no runtime target, no candidate, no static correlation yet). Reusing that exact reason-code union would either force nonsensical codes onto reference-side adequacy or silently expand a runtime-specific vocabulary to mean something unrelated - both violate the explicit "must not mislabel reference adequacy as bounded-agent-context adequacy" requirement. The three-state *shape* (`adequate`/`partial`/`inadequate`) is coincidentally identical text but is an independently-declared constant in the reference module, following this repository's established convention of duplicating small shared vocabularies per family (e.g. `canonicalize()` duplicated five times) rather than cross-importing between otherwise-unrelated domains.
+
+## 13. Requirement model
+
+- **Actual type names**: `ExternalReferenceRequirement`, `RawReferenceRequirement` (unidentified authored input), `ReferenceRequirementSubject` (`RegionPropertyRequirementSubject | RegionRelationshipRequirementSubject | RegionMeasurementRequirementSubject`), all in `src/domain/externalReferenceRequirements.ts`.
+- **Requirement ID semantics**: `requirementId` is **always system-computed** via `buildReferenceRequirementIdentity(subject, category, tolerance, expectedDependentMode)` (`src/domain/externalReferenceRequirementIdentity.ts`, mirroring `frontendContractIdentity.ts#buildClauseIdentity`'s exact canonicalize+sha256 shape). Authoring a `requirementId` in raw input is a validation error (`isValidRawReferenceRequirement` rejects it) — deliberately different from v0.5's `clauseId` (which authors do supply, because clauses need a cross-document-reference id for `supersedesBaselineClauseIds`; requirements have no equivalent need yet).
+- **Category semantics**: exactly v0.5's `AuthoredChangeScopeCategory`, imported directly. `expectedDependentMode` required iff category is `expected-dependent`, forbidden otherwise (identical shape to `isValidPerChangeClause`'s rule).
+- **Supported subjects**: `region-property` (one region + `ReferenceRequirementRegionProperty`), `region-relationship` (two regions + `PairwiseRelationshipKind`, reused from `relationships.ts`, geometry-only families only), `region-measurement` (two regions + `ReferenceRequirementMeasurement`).
+- **Supported properties**: `REFERENCE_REQUIREMENT_REGION_PROPERTIES = ['x','y','width','height','right','bottom','centerX','centerY']` — exactly `ReferenceRegionGeometry`'s own fields, nothing invented (no separate `left`/`top` aliases).
+- **Relationship/measurement requirements**: relationship subjects reuse Prompt 2's `PairwiseRelationshipKind` vocabulary directly (no tolerance permitted — a categorical fact). Measurement subjects use one of six pure derived measurements: `vertical-gap`, `horizontal-gap`, `center-x-delta`, `center-y-delta`, `left-edge-delta`, `right-edge-delta` (a tolerance is required).
+- **Bounds**: `MAX_REFERENCE_REQUIREMENTS = 50` per artifact — a maximum capacity, never a required minimum; no per-region sub-cap was added (the overall bound plus the duplicate-subject rule already bounds practical growth well within it).
+
+## 14. Tolerance model
+
+- **Exact tolerance kinds**: `ReferenceRequirementTolerance = { kind: 'exact' } | { kind: 'absolute-reference-px'; amount } | { kind: 'percent'; amount }`.
+- **Units**: `absolute-reference-px` is explicitly reference-image pixels, never silently treated as CSS/runtime pixels — no scale/compatibility mapping exists yet (deferred to Prompt 6, per request section 20).
+- **Bounds**: `REFERENCE_REQUIREMENT_TOLERANCE_ABSOLUTE_PX_MIN/MAX = 0/100`, `_PERCENT_MIN/MAX = 0/100` — same numeric values as v0.5's `CONTRACT_TOLERANCE_*` constants, independently owned (not imported) for the unit-labeling reason above.
+- **Validation**: negative, non-finite, and unsupported-kind tolerances fail closed (`isValidReferenceRequirementTolerance`); an `exact` tolerance permits no `amount` field at all.
+- **Relationship vs numeric applicability**: `region-relationship` subjects must **not** carry a tolerance (categorical fact); `region-property`/`region-measurement` subjects **must** carry one — enforced explicitly, in both directions, by `validateAuthoredRequirementFields`.
+- **Reuse of v0.5**: numeric bounds mirrored (see section 11); the type itself is a fresh, reference-owned type, not a v0.5 reuse (see section 11's rationale).
+
+## 15. Reference expectation derivation
+
+Nothing is stored beyond `{subject, category, expectedDependentMode?, tolerance?}` per requirement — no numeric expected value (e.g. `width: 424`) and no relationship-match boolean are ever persisted. `deriveReferenceRequirementExpectation(subject, regions, options)` is a pure function computing, on demand:
+
+- for `region-property`: the named region's `ReferenceRegionGeometry[property]`, freshly derived from its canonical rectangle every call;
+- for `region-measurement`: the named pure measurement over the two regions' derived geometries;
+- for `region-relationship`: whether the reference actually exhibits the claimed relationship, by deriving the region pair's relationships via `deriveReferenceRegionRelationships` and checking within the **correct relationship family** (a bug caught and fixed during test-writing — see section 20) for a match in either declared or geometry-determined order (only `follows-vertically` can differ from declared order, since it is the one family whose direction depends on actual geometry rather than input order).
+
+This directly satisfies the "avoid redundant storage, derive from canonical geometry" instruction — there is no possibility of a stored expected value drifting from the region it describes, because none is ever stored.
+
+## 16. Adequacy model
+
+- **Status vocabulary**: `REFERENCE_REQUIREMENT_ADEQUACY_STATES = ['adequate', 'partial', 'inadequate']`.
+- **Reason codes**: exactly two — `no-selected-requirements`, `missing-reference-relationship-evidence`. No other reason code exists because no other condition is possible: an unknown region id, unsupported property, or malformed requirement is a **construction-time validation failure** (`isValidReferenceRequirements`) that never reaches adequacy computation at all.
+- **Zero-requirement behavior**: explicitly `inadequate`, with a `no-selected-requirements` reason — a documented product decision (request section 24F): a region-rich, fully-valid reference is still not usable for a correction task until the user has actually selected what matters.
+- **Missing-region behavior**: not an adequacy concern — rejected at validation time before adequacy ever runs (see section 11's "what was not reused" discussion of the D behavior choice: "authored reference requirement pointing to a nonexistent authored region should fail validation rather than become normal unavailable evidence").
+- **Missing-relationship-evidence behavior**: a structurally-valid `region-relationship`/`region-measurement` requirement whose claimed evidence cannot actually be derived from the geometry (wrong relationship, or a measurement that is geometrically undefined, e.g. `vertical-gap` between overlapping regions) is reported `missing-reference-relationship-evidence`, contributing to a `partial` or `inadequate` overall status.
+- **Deterministic ordering**: reasons are pushed in authored-requirement-array order, never object-key or Set-iteration order — verified by test.
+- **Blocking intent for later stages**: `ReferenceRequirementAdequacy` is returned by both `importExternalReference`/`approveExternalReference` and printed by the CLI (`Adequacy: <status>`) so a later orchestration stage can enforce "inadequate reference → do not begin correction" without Prompt 3 itself running any coding-agent workflow.
+
+## 17. Identity
+
+- `buildExternalReferenceRequestIdentity` gained one additional optional trailing parameter, `requirements?: readonly ExternalReferenceRequirement[]`, following the exact `regions` precedent: omitted from the hashed semantic view entirely (never defaulted to `null`) when absent, so every Prompt 1/2 call site — and every Prompt 3 call with no requirements — produces a byte-identical hash to before this parameter existed (verified by test: `'omitting requirements produces the exact same identity as before this parameter existed'`).
+- Path independence: the function still takes no path argument of any kind; this holds by construction, not merely by test.
+- Content participation: verified by test that changing a requirement's category, adding, or removing a requirement each changes the artifact-level `referenceRequestId`. Each requirement's own `requirementId` additionally changes with its subject/category/mode/tolerance (tested directly in `externalReferenceRequirementIdentity.test.ts`), so a change to any requirement changes both that requirement's own id and the artifact-level identity.
+
+## 18. Artifact / schema decision
+
+- Requirements live as an additive, optional `requirements?: ExternalReferenceRequirement[]` field directly on `ExternalReferenceArtifactBase` (both `ImportedExternalReferenceArtifact` and `ApprovedExternalReferenceArtifact` inherit it) — the same minimal-extension shape as Prompt 2's `regions`, not a separate derived artifact family (no new persisted artifact kind was introduced).
+- **No schema version bump** — `EXTERNAL_REFERENCE_SCHEMA_VERSION` remains `'1.0.0'`, for the identical reasoning already established in the Prompt 2 report: the field is genuinely optional/additive, and this repository's `isValid*Artifact` convention performs a strict version-equality check, so bumping would make every Prompt 1/2 artifact fail validation under the current reader — directly contradicting the explicit "legacy artifacts remain valid" requirement.
+- **Historical artifact compatibility**: verified by test (`'U: a legacy (Prompt 1/2) artifact with no requirements field at all remains valid'`) that an artifact predating this field validates successfully.
+- **Immutable approved-reference handling**: `approveExternalReference` copies `imported.requirements` into a **new** artifact object (fresh `referenceId`, same `referenceRequestId`) — it never reopens or rewrites the imported artifact's own manifest file. Verified by test that an approved artifact's manifest is byte-for-byte unchanged after later, unrelated import/approve activity in the same output directory (reusing the exact test already established in Prompt 2 for this purpose, now also covering requirements).
+
+## 19. Public interface
+
+- **CLI changes**: `import-reference` gained an optional `--requirements-file <json-file>` (root shape `{ "requirements": [...] }`, validated by a new `loadRequirementsFile` mirroring `loadRegionsFile` exactly — object root, exact allow-listed top-level field). Both `import-reference` and `approve-reference` now additionally print `Requirements: <count>` and `Adequacy: <status>` lines. No existing flag, argument, help text section, or exit code changed in meaning.
+- **Input file shape**: `{ "requirements": [ { "category": "requested", "subject": { "kind": "region-property", "region": "current-page-card", "property": "width" }, "tolerance": { "kind": "absolute-reference-px", "amount": 4 } } ] }` — chosen directly from the `--regions-file`/`--targets-file` object-root-wrapper precedent, not the prompt's illustrative example verbatim. No `requirementId` field is accepted in this file (system-computed).
+- **Programmatic export changes**: `src/index.ts` additively exports the complete new requirement/tolerance/adequacy type, constant, and function surface (`ExternalReferenceRequirement`, `RawReferenceRequirement`, `ReferenceRequirementSubject` variants, `ReferenceRequirementTolerance`, `ReferenceRequirementAdequacy`, `deriveReferenceRequirementExpectation`, `deriveReferenceRequirementAdequacy`, `buildReferenceRequirement`, `isValidRawReferenceRequirement`, `isValidReferenceRequirements`, plus bound/vocabulary constants). `AuthoredChangeScopeCategory`/`ExpectedDependentMode` and their constants are **not** re-exported a second time from the new module (they were already exported from `frontendContracts.js` — re-exporting would have been a duplicate-name compile error, caught and fixed during implementation). `ImportExternalReferenceOptions` gained an additive `requirements?` field; both application-result types gained additive `requirementCount: number` and `adequacy: ReferenceRequirementAdequacy` fields.
+- **Backward compatibility**: every Prompt 1/2 CLI invocation and every existing result-consumer reading the pre-existing fields continues to work unchanged — verified by the full pre-existing suite passing unmodified, plus dedicated tests confirming a requirements-less import reports `requirementCount: 0`, `adequacy.status: 'inadequate'`, and no `requirements` key on the manifest.
+
+## 20. Files changed
+
+Modified: `docs/ARCHITECTURE.md`, `docs/CONTRACTS.md`, `docs/CURRENT_STATE.md`, `docs/WORKFLOWS.md`, `src/application/externalReferencePersistenceService.ts`, `src/cli.ts`, `src/domain/diagnostics.ts`, `src/domain/externalReference.ts`, `src/domain/externalReferenceIdentity.ts`, `src/index.ts`, `tests/unit/cliExternalReference.test.ts`, `tests/unit/externalReference.test.ts`, `tests/unit/externalReferenceIdentity.test.ts`, `tests/unit/externalReferencePersistenceService.test.ts`.
+New: `src/domain/externalReferenceRequirements.ts`, `src/domain/externalReferenceRequirementIdentity.ts`, `tests/unit/externalReferenceRequirements.test.ts`, `tests/unit/externalReferenceRequirementIdentity.test.ts`.
+
+`src/domain/relationships.ts` was **not** modified this stage (its Prompt 2 additive exports were reused as-is, imported alongside three additional pre-existing family-constant exports `HORIZONTAL_ORDER_RELATIONSHIPS`/`VERTICAL_ORDER_RELATIONSHIPS`/etc. that were already exported).
+
+## 21. Tests added / changed
+
+60 new tests across 2 new files and additions to 4 existing files (0 pre-existing test modified or removed):
+
+- `externalReferenceRequirementIdentity.test.ts` (6 tests): content-determinism, subject/category/tolerance/mode sensitivity, call-site independence.
+- `externalReferenceRequirements.test.ts` (35 tests): all four categories valid, authored `unexpected` rejected, mode required/forbidden correctly, authored `requirementId` rejected, all three subject kinds valid/invalid (including unsupported property/measurement/relationship), tolerance-applicability-by-subject-kind, unknown-region-id rejection, duplicate/conflicting-subject rejection (including relationship-subject order-independence), requirement-limit exact-max/one-over, exact/absolute/percent tolerance boundaries, negative/non-finite/unsupported-kind tolerance rejection, all six measurement derivations (including overlap-undefined cases), reference-expectation derivation for all three subject kinds (including the family-lookup bug fix - see section 20), zero/all/some-unavailable adequacy states, deterministic reason ordering, no-numeric-score assertion, immutability.
+- `externalReferenceIdentity.test.ts` (+5 tests): requirements-omission backward compatibility, same-content-same-identity, category-change/add/remove-changes-identity.
+- `externalReference.test.ts` (+6 tests): legacy-no-requirements validity, valid requirements on both lifecycle variants, unknown-region rejection, regions-absent rejection, malformed-value rejection.
+- `externalReferencePersistenceService.test.ts` (+5 tests): import-with-requirements persists them and reports adequacy, regionless/requirement-less import reports zero/inadequate, unknown-region import rejection (nothing persisted), authored-id rejection, approval carries requirements forward with matching adequacy.
+- `cliExternalReference.test.ts` (+5 tests): end-to-end `--requirements-file` import+approve with adequacy reporting, legacy no-flag invocation reports zero/inadequate, unknown-region CLI rejection, malformed-`--requirements-file` rejection (bad JSON, array root, unknown field).
+
+## 22. Validation results
+
+All on the ending commit (`4d7bd61`) on `implementation/v0.7-reference-requirements`:
+
+| Command | Result |
+|---|---|
+| `npm run typecheck` | PASS |
+| `npm run lint` | PASS (one `no-unused-vars` finding during development, fixed before commit) |
+| `npm test` | PASS — 42 files, 779 tests (up from 40/719) |
+| `npm run build` | PASS (both new modules compiled into `dist/`) |
+| `npm run check:docs` | PASS (17 required files) |
+| `git diff --check` | PASS |
+| `npm pack --dry-run` | PASS (173 files, 330.5 kB / 1.4 MB unpacked; both new modules present in the tarball listing) |
+| `npm run test:browser` | PASS — 9 files, 120 tests (unchanged count) |
+| `npm run test:security` | PASS — 68 tests |
+
+## 23. Regression results
+
+- **Prompt 1 tests**: all pre-existing `externalReference*`/`cliExternalReference` tests pass unmodified.
+- **Prompt 2 tests**: `externalReferenceRegions.test.ts`, `externalReferenceRegionRelationships.test.ts` pass unmodified.
+- **v0.5 dependent tests**: `frontendContracts.test.ts`, `frontendContractEvaluation.test.ts`, `frontendContractPersistence.test.ts` explicitly re-run — 207 combined tests (with `boundedAgentContext.test.ts`, `boundedAgentContextProjection.test.ts`, `relationships.test.ts`, `relationshipDerivation.test.ts`) pass unchanged. `frontendContracts.ts` itself was not modified at all (only imported from, read-only).
+- **v0.6 tests**: `boundedAgentContext*.test.ts` (4 files) pass unchanged; `boundedAgentContext.ts` was not modified (only inspected for precedent, never imported from — see section 12).
+
+## 24. Boundedness
+
+- **Requirement bound**: `MAX_REFERENCE_REQUIREMENTS = 50` per artifact — explicit, tested at exactly-max (accepted) and one-over (rejected, no partial acceptance).
+- No separate per-region requirement cap was added; the overall bound plus the duplicate-subject rule already bounds practical per-region growth (at most one requirement per distinct property/relationship/measurement combination can exist at all, well within 50 even for the maximum 20-region case).
+
+## 25. Conflict handling
+
+v0.5's `primitivesConflict`/`evaluateFrontendContract` conflict detection is a **runtime-evaluation-time** mechanism requiring before/after `ObservationArtifact` evidence that does not exist at requirement-authoring time — it was not reused, per request section 45's explicit permission to restrict invalid combinations instead when v0.5 semantics cannot be safely reused. Prompt 3's chosen rule: **no two requirements in one collection may share the same structural subject**, regardless of category (`sameSubject()` in `externalReferenceRequirements.ts`, with relationship/measurement subjects treated as the same regardless of which region is declared first). This single rule resolves both the "duplicate requirement" and "conflicting categories on the same subject" behavior-model questions with one mechanism, is fully deterministic, and is enforced at collection-validation time (`isValidReferenceRequirements`) — never silently choosing one requirement over another.
+
+## 26. Security / privacy impact
+
+No new network calls, no vision/AI API calls. `--requirements-file`'s path is never persisted or included in any identity, matching `--regions-file`/`--targets-file`/`--contract-file` convention exactly. Requirement content is plain structured data (category strings, region-id references, numeric tolerances) with no new file-system write boundary — requirements are embedded directly in the existing `manifest.json`. The unsupported-top-level-field rejection on `--requirements-file`'s root prevents silently ignored/misinterpreted malformed input, matching the existing `--regions-file` convention.
+
+## 27. Documentation changes
+
+Additive sections only: `docs/CONTRACTS.md` ("v0.7 Prompt 3 selected design requirements, tolerance semantics, and reference-evidence adequacy" — the primary contract reference), `docs/ARCHITECTURE.md` (relationship of the new requirement/adequacy modules to v0.5/v0.6 precedent and to Prompt 1/2), `docs/CURRENT_STATE.md` ("v0.7 Prompt 3 status" section, plus updated "Not implemented"/"Next target"), `docs/WORKFLOWS.md` (the extended import/approve workflow diagram, the new requirement/adequacy description, and a correction to the "Planned v0.7 reference-driven correction flow" marking requirements/tolerances/adequacy as now implemented). `docs/ROADMAP.md` was **not** touched. `docs/COMMANDS.md` was **not** touched, consistent with Prompt 1/2's own precedent of not documenting `import-reference`/`approve-reference` there.
+
+## 28. Tooling incidents
+
+None this stage. No background/subagent write occurred during Prompt 3's implementation - all work was performed directly in the main session, per the stricter no-background-speculative-writes instruction carried forward from Prompt 2. The Prompt 1 speculative-write incident remains historical; its stash was confirmed untouched at both the start and end of this stage.
+
+## 29. Inherited orchestrator heuristic issue
+
+Not encountered as a product problem this stage. `my-dev-kit-orchestrator` was not modified, no test was rewritten to satisfy its responsibility-mapping heuristic, and no fake evidence tags were added. This stage used `DIRECT_IMPLEMENTATION` without invoking the orchestrator's stage-context workflow at all, so the heuristic gap noted in Prompt 1 did not arise here (consistent with Prompt 2).
+
+## 30. Out-of-scope confirmation
+
+This stage did **not** implement: theme identity evaluation, application-state compatibility, viewport compatibility evaluation, reference/candidate comparability, reference-region↔runtime-target binding, runtime target identity in requirement subjects, candidate observation lookup or geometry, reference-vs-candidate delta, fidelity PASS/FAIL, style/color/typography/pixel/image-similarity comparison, visual score, source correlation changes, bounded correction packets, v0.6 agent-context extension, coding-agent invocation, source editing, rerender orchestration, correction iteration, the viewer, annotation, automatic requirement inference, or automatic region detection. Confirmed by direct grep of the new source files for that vocabulary (none found outside explicit "not yet implemented" documentation comments) and by direct code inspection: `ReferenceRequirementSubject` and `ReferenceRequirementAdequacy` contain no runtime-target/candidate/binding field of any kind, not even as a placeholder.
+
+## 31. Known limitations
+
+1. No fuzz-testing of adversarial requirement JSON beyond the specific malformed-shape cases already covered (bad JSON, array root, unknown field, non-object entry, unsupported property/measurement/relationship) — consistent with Prompt 1/2's own documented fuzz-testing scope boundary.
+2. The `region-relationship` reference-expectation lookup can report "opposite region order" unavailability for the one family (`follows-vertically`) whose direction is decided by geometry rather than authored order; a user must author `subjectRegion`/`relatedRegion` matching the geometrically-determined direction to get a `matches: true/false` result for that specific family. This is documented behavior (see section 15), not a defect, but is a rough edge a future prompt's UI/authoring tooling should smooth over (e.g. by trying both orders automatically) rather than something Prompt 3 should paper over silently now.
+3. `MAX_REFERENCE_REQUIREMENTS = 50` has no cited external precedent value (unlike `MAX_REFERENCE_REGIONS`, which coincidentally matches `MAX_TARGETS`) — it is a reasonable, documented, but ultimately judgment-call bound.
+
+## 32. Remaining risks
+
+- Because reference expectations and adequacy are never persisted, every future consumer (Prompt 4+) that needs them must call `deriveReferenceRequirementExpectation`/`deriveReferenceRequirementAdequacy` itself. This mirrors Prompt 2's relationship-derivation design deliberately (avoids drift) and should not be "fixed" by prematurely adding persistence.
+- The duplicate-subject conflict rule is stricter than v0.5's category-aware conflict model (it rejects same-subject-different-category outright rather than trying to reconcile them). If a future prompt determines users genuinely need e.g. a `requested` and a `protected` requirement coexisting on the same subject for some legitimate reason, that will require a deliberate architecture revisit, not a quiet loosening of this rule.
+
+## 33. Exact next action
+
+**v0.7 Prompt 4** — reference applicability/state compatibility and comparability foundation.
+
+## 34. Report path
+
+`docs/reports/v0.7-reference-requirements-prompt3.md` (this file)