@dailephd/my-frontend-observer 0.8.1

package/docs/reports/v0.7-reference-regions-prompt2.md

@@ -0,0 +1,195 @@
+# v0.7 Prompt 2 — Explicit Reference Regions, Geometry, and Reusable Reference Relationships
+
+## 1. Verdict
+
+**PASS_V0_7_REFERENCE_REGIONS_PROMPT2**
+
+## 2. Repository
+
+`Z:\Users\newuser\Projects\my-frontend-observer` (`https://github.com/dailephd/my-frontend-observer.git`)
+
+## 3. Branch
+
+`implementation/v0.7-reference-regions`
+
+## 4. Starting head
+
+`ba61897e597451ae34f81583cbcffc8447b09738`
+
+## 5. Prompt 1 base head
+
+`ba61897e597451ae34f81583cbcffc8447b09738` (same commit — the branch was created directly from Prompt 1's completed, clean state; verified as an ancestor via `git merge-base --is-ancestor`)
+
+## 6. Ending head
+
+`c5c2eef66ddecb0365c2ced7d9a25f1b9e16c210`
+
+## 7. Git status
+
+Clean at the ending head. The Prompt 1 speculative research-agent stash (`stray-fork-writes-preserved-for-reference: ...`) remains present, untouched, unapplied, and unmined throughout this stage — verified with `git stash list` before and after implementation.
+
+## 8. Resolved my-dev-kit version
+
+`@dailephd/my-dev-kit@1.12.3` (unchanged from Prompt 1 — still the latest published version at execution start; re-checked via `npm view @dailephd/my-dev-kit version`, not assumed from memory)
+
+## 9. Fresh index path / ID
+
+`.my-dev-kit/index-prompt2` — a fresh index built this stage (`my-dev-kit index --root . --src src --out .my-dev-kit/index-prompt2 --call-graph --json`), independent of Prompt 1's `.my-dev-kit/index`/`index-after` indexes (not reused as the new-behavior evidence source, per instruction). This tooling directory is gitignored and was never staged.
+
+## 10. Prompt 1 contract verified
+
+Read directly from the maintained repository (not from the Prompt 1 report alone) before any change:
+
+- `src/domain/externalReference.ts` — `ExternalReferenceArtifact` (`ImportedExternalReferenceArtifact` | `ApprovedExternalReferenceArtifact`), `isValidExternalReferenceArtifact`, `isImportedExternalReferenceArtifact`/`isApprovedExternalReferenceArtifact`, `EXTERNAL_REFERENCE_ARTIFACT_KIND`/`EXTERNAL_REFERENCE_SCHEMA_VERSION`.
+- `src/domain/externalReferenceIdentity.ts` — `buildExternalReferenceRequestIdentity`/`buildExternalReferenceInstanceIdentity`.
+- `src/domain/externalReferenceImage.ts` — format/dimension boundary (unchanged this stage).
+- `src/artifacts/externalReferenceArtifactWriter.ts`/`Reader.ts` — atomic persistence (unchanged this stage).
+- `src/application/externalReferencePersistenceService.ts` — `importExternalReference`/`approveExternalReference`.
+- `src/cli.ts` — `import-reference`/`approve-reference` commands, their help text, arg parsers, and dispatch.
+- `tests/unit/externalReference*.test.ts`, `cliExternalReference.test.ts` — the full Prompt 1 test suite (668 tests at the time), confirmed still green before touching anything.
+
+The Prompt 1 report and the actual implementation matched exactly — no `BLOCKED_PROMPT1_IMPLEMENTATION_REPORT_MISMATCH` condition was encountered.
+
+## 11. Region model
+
+- **Type name**: `ReferenceRegion { id: string; rectangle: ReferenceRegionRectangle }`, `ReferenceRegionRectangle { x, y, width, height }` (`src/domain/externalReferenceRegions.ts`).
+- **Stable region ID semantics**: `^[A-Za-z0-9_-]{1,64}$`, unique case-insensitively within one artifact — reused verbatim from `request/request.ts`'s target-name convention (exact pattern and dedup rule).
+- **Canonical coordinate representation**: only `{x, y, width, height}` is authored/canonical; everything else is derived.
+- **Coordinate origin/unit**: top-left of the reference image; x rightward, y downward; unit is reference-image pixels (explicitly not CSS pixels); coordinates may be fractional.
+- **Numeric rules**: `x`/`y` finite and ≥ 0; `width`/`height` finite and > 0 (zero/negative/non-finite all rejected, never clamped).
+- **Image-boundary rule**: a region's derived `right`/`bottom` must not exceed the owning image's own already-validated width/height; rejected outright otherwise, exact-boundary regions accepted.
+- **Region-count bound**: `MAX_REFERENCE_REGIONS = 20` — a maximum capacity only, matching `request/request.ts`'s `MAX_TARGETS` value (independently owned constant, not imported/coupled).
+- **Deterministic ordering rule**: authored array order is preserved and treated as semantic (never re-sorted), mirroring `domain/identity.ts`'s treatment of configured targets — both for identity hashing and for relationship derivation.
+
+## 12. Derived geometry
+
+- **Exact derived anchors**: `deriveReferenceRegionGeometry(rectangle) -> { x, y, width, height, right, bottom, centerX, centerY }` — a pure function, called fresh every time.
+- **What is persisted**: only `{id, rectangle: {x, y, width, height}}` per region, inside the artifact's optional `regions` array.
+- **What is computed**: `right`, `bottom`, `centerX`, `centerY` — never stored, so `x + width` can never disagree with a stored `right` (there is no stored `right`).
+- **Normalized-coordinate decision**: not implemented in this stage. No normalized (`x / imageWidth`, etc.) field exists anywhere; if useful later, it would be derived on demand from the canonical rectangle plus the artifact's own image dimensions, never a second stored source of truth. This was a deliberate scope decision (request section 18 explicitly permits deferring it), not an oversight.
+
+## 13. Relationship precedent review
+
+- **Exact v0.4 owners inspected**: `src/domain/relationships.ts` (full file, 440 lines before this stage) — `PAIRWISE_RELATIONSHIP_KINDS`, `EvidenceReference`/`isValidEvidenceReference`, `LayoutRelationshipGraph`, `MAX_CONFIGURED_TARGETS_FOR_RELATIONSHIPS`/`MAX_PAIRWISE_RELATIONSHIP_RECORDS`, and the six pure predicates `horizontalOrderOf`/`verticalOrderOf`/`areaOverlapOf`/`relativeWidthOf`/`geometricFitOf`/`verticalSequenceOf` plus `deriveLayoutRelationships`'s pairwise-loop structure.
+- **Relationship families reused**: all six geometry-only families — horizontal order, vertical order, area overlap, relative width, geometric fit, vertical sequencing.
+- **Relationship families rejected as runtime-only**: `document-width-fits-viewport`/`document-width-exceeds-viewport` (page-level, needs document/viewport evidence a static image doesn't have); DOM containment (`TargetContainment` in `schema.ts` — explicitly documented there as never a layout/relationship graph concept, and an external image exposes no DOM at all); scroll ownership, runtime visibility, browser clipping, and semantic/accessibility relationships (all require live browser evidence).
+- **Shared geometry primitives extracted**: yes — the six predicate functions were changed from private to `export`ed in `relationships.ts` with **zero formula changes** (verified by diff: only the `function` keyword gained `export`, one added a doc comment). `PAIRWISE_RELATIONSHIP_KINDS`, `EvidenceReference`, and `isValidEvidenceReference` were already exported and are imported as-is.
+- **Proof v0.4 semantics did not change**: `npm test` (full suite), `npm run test:browser`, and a targeted run of `tests/unit/relationships.test.ts`, `relationshipDerivation.test.ts`, `comparisonEngine.test.ts`, and `frontendContractEvaluation.test.ts` all pass with identical counts to before this stage (132 tests across those four files, unchanged). No `BLOCKED_RELATIONSHIP_REUSE_REQUIRES_SEMANTIC_CHANGE` condition was encountered.
+
+## 14. Reference relationship model
+
+- **Type/function names**: `ReferenceRegionRelationship { kind: PairwiseRelationshipKind; subjectRegion: string; relatedRegion: string; evidence: EvidenceReference[] }`, `ReferenceRegionRelationshipGraph { referenceRequestId, geometryTolerancePx, regions: string[], pairwiseRelationships }`, `deriveReferenceRegionRelationships(referenceRequestId, regions, options)`, `isValidReferenceRegionRelationship`/`isValidReferenceRegionRelationshipGraph` (`src/domain/externalReferenceRegionRelationships.ts`).
+- **Bounds**: `MAX_REFERENCE_REGION_PAIRS = 20*19/2 = 190`, `REFERENCE_REGION_RELATIONSHIP_FAMILY_COUNT = 6`, `MAX_REFERENCE_REGION_RELATIONSHIP_RECORDS = 1140` — the same bounding shape as `relationships.ts`'s `MAX_PAIRWISE_RELATIONSHIP_RECORDS`, over `MAX_REFERENCE_REGIONS` instead of the runtime-target limit.
+- **Provenance model**: `evidence: [{ path: 'regions.<id>.rectangle' }, ...]` — never a `targetEvidence`/browser path; a relationship never claims runtime-target or DOM provenance (verified directly by test).
+- **Deterministic ordering**: earlier-authored region is always `subjectRegion` for every family except `follows-vertically` (direction decided by actual geometry, matching `deriveLayoutRelationships` exactly); same input always produces the identical graph (verified by test).
+- **Persistence decision**: relationships are **not persisted** on the artifact — always re-derivable on demand from the artifact's own `regions` field, eliminating any possibility of a stored relationship graph drifting from the region data.
+
+## 15. Schema / artifact decision
+
+- **Prompt 1 artifact schema changed**: yes, additively — one new optional field, `regions?: ReferenceRegion[]`, on both `ImportedExternalReferenceArtifact` and `ApprovedExternalReferenceArtifact`.
+- **Schema version decision**: **no bump** — `EXTERNAL_REFERENCE_SCHEMA_VERSION` remains `'1.0.0'`. Rationale: the field is genuinely optional and additive with no other coupled behavior change; bumping would force a strict-equality version check (this repository's established `isValid*Artifact` convention) to reject every Prompt 1 artifact, which directly contradicts the explicit "legacy Prompt 1 reference remains valid/readable" requirement. This differs from the observation family's historical per-batch version-bump convention; documented here as a deliberate, evidence-based departure, not an oversight.
+- **Historical Prompt 1 artifacts remain readable/valid**: yes — verified directly by test (`'a legacy (Prompt 1) artifact with no regions field at all remains valid'`), and by construction (`isValidExternalReferenceArtifact` only validates `regions` when the key is present).
+- **Structured regions and logical identity**: `buildExternalReferenceRequestIdentity` gained an additive, optional trailing `regions` parameter. When omitted, it is left out of the hashed semantic view entirely (not defaulted to `null`, unlike `supersedesReferenceId`) so every Prompt 1 call site — and every Prompt 2 call with no regions — produces the byte-identical hash Prompt 1 already produced. When present, region content (id, rectangle, and authored order) is fully identity-bearing.
+- **Immutable approved artifacts preserved**: `approveExternalReference` carries `imported.regions` forward verbatim (a plain copy, never re-validated or re-derived) into a **new** artifact instance; the imported artifact's own manifest is never opened for writing again. No code path in this stage ever mutates an existing persisted manifest.
+
+## 16. Public interface
+
+- **CLI changes**: `import-reference` gained an optional `--regions-file <json-file>` (root shape `{ "regions": [...] }`, validated by a new `loadRegionsFile` mirroring `loadTargetsFile` exactly — object root, exact allow-listed top-level field, JSON parse/read errors surfaced as `error:` lines). Both `import-reference` and `approve-reference` now print an additional `Regions: <count>` line. No existing flag, argument, or exit-code behavior changed.
+- **Programmatic export changes**: `src/index.ts` additively exports the complete new region/relationship type, constant, and function surface (`ReferenceRegion`, `ReferenceRegionRectangle`, `ReferenceRegionGeometry`, `deriveReferenceRegionGeometry`, `isValidReferenceRegion(s)`, `REFERENCE_REGION_ID_PATTERN`, `MAX_REFERENCE_REGIONS`, `ReferenceRegionRelationship`, `ReferenceRegionRelationshipGraph`, `deriveReferenceRegionRelationships`, `isValidReferenceRegionRelationship(Graph)`, plus the `MAX_REFERENCE_REGION_*` bound constants), and the two Prompt 1 type guards (`isImportedExternalReferenceArtifact`/`isApprovedExternalReferenceArtifact`) that had not yet been exported. `ImportExternalReferenceOptions` gained an additive `regions?` field; both application-result types gained an additive `regionCount: number` field.
+- **Exact user/config input shape**: `{ "regions": [ { "id": "current-page-card", "rectangle": { "x": 28, "y": 92, "width": 424, "height": 82 } }, ... ] }` — chosen after precedent review (matches `--targets-file`'s object-root-wrapper convention) rather than the prompt's illustrative nested YAML-style example.
+- **Backward compatibility**: every Prompt 1 CLI invocation and every existing `ApplicationImportExternalReferenceResult`/`ApplicationApproveExternalReferenceResult` consumer reading the pre-existing fields continues to work unchanged — verified by the full pre-existing test suite passing unmodified, plus a dedicated test confirming a regionless import reports `regionCount: 0` and no `regions` key on the manifest.
+
+## 17. 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/domain/relationships.ts` (six predicates made `export`, formulas unchanged), `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/externalReferenceRegions.ts`, `src/domain/externalReferenceRegionRelationships.ts`, `tests/unit/externalReferenceRegions.test.ts`, `tests/unit/externalReferenceRegionRelationships.test.ts`.
+
+## 18. Tests added / changed
+
+51 new tests across 2 new files and additions to 4 existing files (0 pre-existing test modified or removed):
+
+- `externalReferenceRegions.test.ts` (18 tests): derived geometry correctness/non-contradiction, id pattern/length/duplicate rejection, finite/negative/zero-size rejection, multi-region acceptance, out-of-bounds rejection (with exact-boundary acceptance), region-count bound (exactly-max accepted, one-over rejected), immutability.
+- `externalReferenceRegionRelationships.test.ts` (13 tests): horizontal/vertical order, overlap, relative width, geometric fit (with an explicit assertion that no DOM-containment-shaped field exists), vertical sequencing directed by geometry, determinism, evidence-path provenance (never `targetEvidence`), pair-count bound, tolerance validation, single-region no-relationships case, immutability, graph validator accept/reject.
+- `externalReferenceIdentity.test.ts` (+8 tests): backward-compatible omission, same-content-same-identity, geometry-change/add/remove/rename-changes-identity, authored-order-is-semantic.
+- `externalReference.test.ts` (+6 tests): legacy-no-regions-field validity, valid regions on both lifecycle variants, out-of-bounds rejection with a `"regions:"`-prefixed reason, malformed-value rejection, duplicate-id rejection.
+- `externalReferencePersistenceService.test.ts` (+7 tests): import-with-regions persists them with correct count, regionless import has no `regions` key, out-of-bounds/duplicate-id import rejection (nothing persisted), approval carries regions forward (and forward "no regions" correctly), approved-artifact-manifest-never-mutated-by-later-activity.
+- `cliExternalReference.test.ts` (+5 tests): end-to-end `--regions-file` import+approve, legacy no-flag invocation reports zero regions, out-of-bounds region CLI rejection, malformed-`--regions-file` rejection (bad JSON, array root, unknown top-level field).
+
+## 19. Validation results
+
+All on commit `c5c2eef` on `implementation/v0.7-reference-regions`:
+
+| Command | Result |
+|---|---|
+| `npm run typecheck` | PASS |
+| `npm run lint` | PASS |
+| `npm test` | PASS — 40 files, 719 tests (up from 38/668) |
+| `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 (166 files, 304.2 kB / 1.3 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 |
+
+## 20. Regression results
+
+- **Prompt 1 tests**: all 668 pre-existing tests (including every `externalReference*`/`cliExternalReference` test) pass unmodified.
+- **v0.4 relationship/comparison tests**: `relationships.test.ts`, `relationshipDerivation.test.ts`, `comparisonEngine.test.ts` — 132 combined tests (with `frontendContractEvaluation.test.ts`) pass unchanged; the six predicate functions' formulas are byte-identical to before (only their export visibility changed).
+- **v0.5 dependent tests**: `frontendContractEvaluation.test.ts`, `frontendContractPersistence.test.ts`, `frontendContracts.test.ts` all pass unchanged (part of the full 719-test run).
+- **v0.6 tests**: `boundedAgentContext*.test.ts` (4 files) pass unchanged.
+
+## 21. Boundedness
+
+- **Region bound**: `MAX_REFERENCE_REGIONS = 20` per artifact — explicit, tested at exactly-max (accepted) and one-over (rejected, no partial acceptance).
+- **Relationship/pair bound**: `MAX_REFERENCE_REGION_PAIRS = 190` pairs × 6 families = `MAX_REFERENCE_REGION_RELATIONSHIP_RECORDS = 1140` records maximum — explicit, tested at exactly-max region count.
+- **One-over behavior**: both the region-collection validator and the relationship-derivation function reject a one-over-bound input outright (`{valid:false}` / `{ok:false}`) — never a silently truncated partial result.
+
+## 22. Identity tests
+
+- **Path-independence**: `buildExternalReferenceRequestIdentity` takes no path argument at all (structurally impossible for an operational path to leak in); confirmed at the application level by `'produces the same referenceRequestId for byte-identical images from different output roots'` (extended in spirit by the new region tests, which exercise the same function directly).
+- **Region-content identity behavior**: same content → same identity (tested); geometry change → different identity (tested); add/remove region → different identity (tested, both directions); rename → different identity (tested); authored order → part of identity (tested); omission of the parameter entirely → byte-identical to the pre-Prompt-2 hash (tested explicitly).
+
+## 23. Immutability
+
+- No code path in `externalReferencePersistenceService.ts` opens an existing manifest file for writing — `writeExternalReferenceArtifact` always writes to a fresh temp directory and renames to a fresh `referenceId` directory that is verified not to already exist (Prompt 1 behavior, unchanged and re-verified this stage).
+- Direct test proof: importing a reference with regions, approving it, then performing unrelated later activity in the same output directory, re-reads the approved artifact's manifest byte-for-byte identical to before that later activity (`'an approved artifact's manifest is never mutated by any later import/approve call'`).
+- `approveExternalReference` reads the imported artifact's `regions` and copies the array reference into a new object literal — it never mutates the `imported` object in memory either (confirmed by TypeScript's structural typing plus the existing "never mutates" test convention carried into the new tests).
+
+## 24. Security / privacy impact
+
+No new network calls, no vision/AI API calls, no OCR, no automatic segmentation. `--regions-file`'s path is never persisted or included in any identity (same convention as `--targets-file`/`--contract-file`) — only its parsed, validated `regions` content reaches the artifact. Region geometry is plain numeric data; no new file-system write boundary was introduced (regions are embedded directly in the existing `manifest.json`, never a separate file). The unsupported-top-level-field rejection on `--regions-file`'s root prevents silently ignored/misinterpreted malformed input.
+
+## 25. Documentation changes
+
+Additive sections only: `docs/CONTRACTS.md` ("v0.7 Prompt 2 explicit reference regions and relationships" — the primary contract reference, with the exact type shapes and key rules), `docs/ARCHITECTURE.md` (relationship of the new region/relationship modules to the existing engine boundaries and to Prompt 1), `docs/CURRENT_STATE.md` ("v0.7 Prompt 2 status" section, plus updated "Not implemented"/"Next target"), `docs/WORKFLOWS.md` (the extended import/approve workflow diagram, the new relationship-derivation description, and a correction to the "Planned v0.7 reference-driven correction flow" first bullets marking regions/relationships as now implemented). `docs/ROADMAP.md` was **not** touched. `docs/COMMANDS.md` was **not** touched, consistent with Prompt 1's own precedent of not documenting `import-reference`/`approve-reference` there.
+
+## 26. Tooling incidents
+
+None this stage. No background/subagent write occurred during Prompt 2's implementation. The Prompt 1 speculative-write incident is historical (recorded in the Prompt 1 report) and its stash was confirmed untouched at both the start and end of this stage.
+
+## 27. Inherited orchestrator heuristic issue
+
+Not re-encountered as a product problem. Per instruction, `my-dev-kit-orchestrator` was not modified and no test was rewritten to satisfy its responsibility-mapping heuristic; this stage used `DIRECT_IMPLEMENTATION` and did not invoke the orchestrator's stage-context workflow at all, so the heuristic gap noted in Prompt 1 did not arise here.
+
+## 28. Out-of-scope confirmation
+
+This stage did **not** implement: selected design requirements, requested/expected-dependent/protected/preserved requirement mapping, design tolerance semantics, reference-evidence adequacy or sufficiency scoring, theme/application-state identity or compatibility evaluation, reference-region↔runtime-target binding, reference-vs-candidate fidelity evaluation, style/color/typography/pixel/image-similarity comparison, bounded visual correction packets, coding-agent invocation or correction, candidate rerender orchestration, the viewer, annotation, automatic segmentation/computer vision, or screenshot-to-code/raster-to-vector reconstruction. Confirmed by direct grep of the new source files for that vocabulary (none found outside explicit "not implemented here" documentation comments).
+
+## 29. Known limitations
+
+1. Normalized (0–1 range) region coordinates are not implemented — deliberately deferred per request section 18; if needed later, they should be derived on demand from the canonical rectangle plus image dimensions, never a second stored source of truth.
+2. `--regions-file` is the only public entry point for authoring regions in this stage — there is no way to retroactively attach regions to an already-imported Prompt 1 reference without re-supplying the original image bytes and re-running `import-reference`. This was a deliberate minimal-surface choice (Option A from the architecture review, not Option B); re-supplying a local image file is cheap and the resulting artifact is a legitimately distinct logical reference, not a duplicate.
+3. No fuzz-testing of adversarial region JSON beyond the specific malformed-shape cases already covered (bad JSON, array root, unknown field, non-object entry) — consistent with Prompt 1's own documented fuzz-testing scope boundary.
+
+## 30. Remaining risks
+
+- The `MAX_REFERENCE_REGIONS = 20` bound is a coincidental value-match with `request/request.ts`'s `MAX_TARGETS`, independently owned. A future change to one must not be assumed to require changing the other; this report documents that they are not structurally coupled, to prevent an accidental future assumption otherwise.
+- Because relationships are never persisted, every consumer that wants them must call `deriveReferenceRegionRelationships` itself. Prompt 3+ should be aware this is a deliberate choice (avoids drift) rather than an oversight, so it is not "fixed" by prematurely adding persistence.
+
+## 31. Exact next action
+
+**v0.7 Prompt 3** — selected design requirements, tolerance semantics, and reference-evidence adequacy.
+
+## 32. Report path
+
+`docs/reports/v0.7-reference-regions-prompt2.md` (this file)

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

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