@dailephd/my-frontend-observer 0.10.0 → 0.10.1

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

@@ -1,195 +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)
+# 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)