@dailephd/my-frontend-observer 0.10.0 → 0.10.1

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

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