@dailephd/my-frontend-observer 0.8.1

package/docs/reports/v0.7-pre-release-readiness.md

@@ -0,0 +1,337 @@
+# v0.7 Pre-Release Readiness Report
+
+**Verdict: `PASS_READY_FOR_RELEASE_PREP`**
+
+This report documents a pre-release readiness validation pass over the completed,
+audited v0.7 implementation. It proves the implementation is ready to enter a
+separate release-preparation stage. It does **not** authorize publication, does
+**not** bump the package version, and does **not** merge to `master`.
+
+## Commit identity
+
+| Label | Commit |
+|---|---|
+| Audited v0.7 baseline (starting point) | `4b2a51c62f47fd1244ceab42cb37bb111cb90259` — "Add v0.7 implementation-completeness audit report" |
+| Documentation reconciliation commit | `8b6c669` |
+| **VALIDATED_CANDIDATE_HEAD** (cross-platform CI run 34054085344 validated this exact commit) | `b2286bdc9550d70fa1047a1f732968a8eca46a1e` — "Close v0.7 pre-release readiness coverage gap in packed-candidate smoke" |
+| **REPORT_COMMIT** | this commit (added after the successful CI run; contains only this report — no product/readiness behavior changes) |
+
+Branch: `validation/v0.7-pre-release`, created from the exact audited v0.7 HEAD
+(`4b2a51c`), fast-forwarded by exactly one readiness-infrastructure commit
+(`b2286bd`), then this report commit. No product source under `src/` changed at
+any point in this readiness stage.
+
+Preflight confirmed the full Prompt 1–8 commit lineage is present and ancestors
+of HEAD, the working tree was clean, and Prompt 1's preserved speculative-write
+stash (`stash@{0}`, "stray-fork-writes-preserved-for-reference") remains
+untouched — never applied, dropped, committed, or used as test evidence.
+
+## Readiness infrastructure change (the only tracked change in this stage)
+
+Commit `b2286bd` on `validation/v0.7-pre-release`:
+
+1. **Closed a real v0.7 packed-candidate coverage gap.** Inspecting the
+   existing CI smoke (`scripts/ci/runPackedObservationSmoke.mjs`) before
+   running it showed thorough v0.1–v0.6 installed-candidate coverage but
+   **zero** v0.7 coverage — no `import-reference`/`approve-reference`/
+   `evaluate-reference-fidelity` CLI exercise, and none of the v0.7
+   programmatic exports (`evaluateReferenceCandidateFidelityFromArtifactRoots`,
+   `prepareReferenceCorrection`, `reviewReferenceCorrectionAttempt`). Per the
+   task's readiness-coverage-gap rule, this was treated as a readiness gap,
+   not a product defect, and closed narrowly inside the existing smoke script
+   rather than building a second parallel framework:
+   - Real CLI help-flag assertions for all three new v0.7 commands.
+   - A real external-reference image imported and approved through the
+     installed CLI, with explicit regions (`nav-region`/`workspace-region`/
+     `rail-region`), three requirement kinds (`region-property`,
+     `region-relationship`, and tolerance kinds `exact`/`absolute-reference-px`),
+     and declared `applicability.viewport`.
+   - Explicit region↔runtime-target bindings, reusing the same runtime
+     targets (`navigation`/`workspace`/`rail`) already used by the existing
+     v0.5 contract-fixture geometry — no second fixture was built.
+   - A genuine fidelity **PASS** (against the already-captured "success"
+     candidate) and a genuine fidelity **FAIL** (against the already-captured
+     "protected-regression" candidate), each checked both with and without
+     `--enforce`, mirroring the existing `evaluate-contract` PASS/FAIL/
+     `--enforce` proof pattern already in the script.
+   - An `observe --state-file` call proving `requestConfig.explicitState`
+     round-trips through the installed candidate.
+   - Programmatic exercise of `evaluateReferenceCandidateFidelityFromArtifactRoots`,
+     `readExternalReferenceArtifact`, `prepareReferenceCorrection` (asserting
+     `status: 'handoff-ready'` and a bounded-agent-context artifact with the
+     correct `artifactKind`, exercising v0.7 Prompt 7's bounded fidelity
+     projection and the v0.6 bounded-agent-context integration together), and
+     `reviewReferenceCorrectionAttempt` against both the success candidate
+     (`overallState: 'pass'`, `approvalEligible: true`) and the regression
+     candidate (`overallState: 'fail'`, `approvalEligible: false`) — all
+     resolved from the installed package's own `node_modules`, never the
+     source checkout.
+   - A re-hash of the pre-existing source observation manifest to confirm the
+     new v0.7 calls did not mutate it (observer source immutability).
+2. **Fixed an unrelated lint gap.** `eslint.config.js`'s `ignores` list
+   predates this task's mandated `.my-dev-kit-workflow/` project-local
+   workflow convention (npm cache, temp consumer installs, candidate
+   tarballs, Playwright browser downloads) and only covered
+   `.my-dev-kit/`/`.my-dev-kit-orchestrator/`. Running `npm run lint` with
+   Chromium downloaded to `.my-dev-kit-workflow/pw-browsers/` surfaced 20
+   `no-undef` errors from ESLint parsing Chromium's own bundled JS resources.
+   Added `.my-dev-kit-workflow/**` and `.my-dev-kit-context/**` to the ignore
+   list. This is a dev-tooling config fix, not a production behavior change.
+
+No production source (`src/**`) changed. No test was weakened, skipped, or
+deleted. No package metadata changed.
+
+## Local full validation (on `b2286bd`)
+
+Environment: Windows 11, Node `v24.11.0`, npm `11.14.0` (satisfies the
+repository's `"node": ">=24"` engines constraint). All caches/temp
+state/candidate artifacts kept under `.my-dev-kit-workflow/` (gitignored,
+project-local — npm cache, Playwright browser downloads, and the readiness
+output directory), never under `C:\`.
+
+| Step | Result |
+|---|---|
+| `npm ci` | clean install, 132 packages, 0 vulnerabilities |
+| Chromium install (`playwright install chromium`, `PLAYWRIGHT_BROWSERS_PATH` project-local) | succeeded |
+| `npm run typecheck` | clean |
+| `npm run lint` | clean (after the ignore-list fix above) |
+| `npm test` | **1000/1000 unit tests passed** (50 files) — matches the expected ~1000 baseline exactly |
+| `npm run test:browser` | **124/124 browser tests passed** (10 files, real Chromium) — matches the expected ~124 baseline exactly |
+| `npm run test:security` | **68/68 passed** (5 in `tests/unit/policy.test.ts` + 63 in `tests/browser/chromiumAdapter.test.ts`) |
+| `npm run build` | clean |
+| `npm run check:docs` | "Documentation check passed (17 required files)." |
+| `git diff --check` | clean (no whitespace errors) |
+| `npm pack --dry-run` | 207 entries, only `dist/**`, `README.md`, `CHANGELOG.md`, `docs/**`, `package.json` — no `.my-dev-kit-*`, no `node_modules`, no test/script files |
+
+No unexplained test-count reduction — every count matches the previous audited
+baseline exactly. No flake was encountered locally or in CI (see "Known flake
+investigation" below).
+
+## Version-specific v0.7 validation
+
+All of the following remain covered by passing unit and/or browser tests
+(confirmed present in `tests/unit/` and `tests/browser/` and passing in the
+1000+124 counts above): external-reference artifact/lifecycle
+(`externalReference.test.ts`, `externalReferenceArtifactWriter.test.ts`,
+`externalReferencePersistenceService.test.ts`, `cliExternalReference.test.ts`),
+regions/geometry (`externalReferenceRegions.test.ts`,
+`externalReferenceRegionRelationships.test.ts`), selected requirements
+(`externalReferenceRequirements.test.ts`,
+`externalReferenceRequirementIdentity.test.ts`), reference adequacy (covered
+within the requirements suite), explicit state/applicability
+(`explicitState.test.ts`, `externalReferenceApplicability.test.ts`),
+reference/candidate compatibility (`externalReferenceCompatibility.test.ts`),
+region↔runtime-target binding (`externalReferenceRuntimeBinding.test.ts`),
+fidelity evaluation (`externalReferenceFidelity.test.ts`,
+`cliEvaluateReferenceFidelity.test.ts`), bounded fidelity projection /
+bounded-agent-context integration (`boundedAgentContextProjection.test.ts`,
+`boundedAgentContext.test.ts`), and the end-to-end correction workflow
+(`referenceCorrectionWorkflow.test.ts`, a **browser** test using real
+Chromium). This readiness stage additionally proved every one of these
+capabilities through the **installed npm package**, not just the source
+checkout (see candidate coverage below) — something the pre-existing unit/
+browser suites alone do not prove.
+
+## Command smoke (built CLI, source checkout)
+
+`node dist/cli.js --help` and per-command `--help` were exercised for every
+v0.7 and inherited command. All present and exiting 0:
+`import-reference`, `approve-reference`, `evaluate-reference-fidelity`,
+`observe`, `compare`, `approve-baseline`, `save-change-contract`,
+`evaluate-contract`.
+
+## Package content inspection
+
+`npm pack --dry-run --json` on `b2286bd`: 207 files, package size 475.4 kB,
+unpacked 2.0 MB. Contents are exactly `dist/**` (built JS/`.d.ts`/source maps),
+`README.md`, `CHANGELOG.md`, `docs/**` (including the nine v0.7 prompt
+implementation reports and the documentation-reconciliation report), and
+`package.json`. No `.my-dev-kit-*` directory, no `node_modules`, no local
+cache, no temporary consumer files, no candidate logs, no secret/private
+file, and no Prompt 1 stash content appears anywhere in the inventory. No
+package inclusion rule was changed — the existing `"files"` policy already
+produces a correct inventory.
+
+## Candidate identity
+
+One exact candidate tarball was built from the validated `b2286bd` source
+state and used unmodified across the entire cross-platform matrix.
+
+| Field | Value |
+|---|---|
+| Candidate filename | `my-frontend-observer-0.6.0.tgz` |
+| Source commit | `b2286bdc9550d70fa1047a1f732968a8eca46a1e` |
+| Package version | `0.6.0` (unchanged) |
+| **CI-built candidate SHA-256 (the one validated cross-platform)** | `0347b1f3cfd5d311e13b405c0c2fbc2f507e250cb63223d58b4d2d31df029414` |
+| Package contents | identical 207-entry inventory described above |
+
+Note: a separate local `npm pack` invocation on the same commit (used for a
+local pre-push packed-smoke dry run under `.my-dev-kit-workflow/readiness/`,
+never pushed or distributed) produced a different SHA
+(`ab8c2b6432285c113026e2d4399f238cb13aea2617bc80ec5bbbe4318cb3189b`) — this is
+expected and immaterial: `npm pack` tarballs are not byte-reproducible across
+separate invocations (gzip/tar timestamp metadata differs) even for identical
+file content. The only SHA-256 that matters for the cross-platform readiness
+claim is the one the CI **candidate** job produced once and that all three
+matrix lanes independently verified — see below.
+
+## Local clean-consumer install / packed smoke
+
+The repository's existing packed-observation smoke
+(`scripts/ci/runPackedObservationSmoke.mjs`, extended as described above) was
+run locally against the exact locally-built candidate tarball before pushing.
+It installs the tarball into a fresh, disposable consumer directory (a
+temp directory, per this pre-existing script's own established design —
+matching what CI's `windows-latest`/`ubuntu-latest`/`macos-latest` runners
+also do, since GitHub-hosted runners have no meaningfully more "project-local"
+location for an ephemeral job container), installs Chromium through that
+consumer's own installed Playwright dependency (never the source checkout's),
+and exercises the installed bin/exports directly. Result: `SMOKE PASS`, with
+every `summary.*Ok` flag `true`, including the new `v07PackedSmokeOk`.
+
+## Security validation
+
+`npm run test:security` (68/68 passed) plus source/test inspection of v0.7
+security-sensitive surfaces:
+
+- **External image file input**: format/dimension detection reads only
+  bounded header bytes (`externalReferenceImage.ts`), never decodes pixel
+  data; malformed/truncated/oversized inputs are rejected with structured
+  diagnostics (`externalReferenceImage.test.ts`).
+- **Region/requirements/applicability config input**: all three CLI file
+  loaders (`loadRegionsFile`/`loadRequirementsFile`/`loadApplicabilityFile`)
+  own only root-shape/JSON-parse syntax; every content rule (bounds, id
+  patterns, category/tolerance/subject validity) is owned by the domain
+  validators they call into, covered by
+  `externalReferenceRegions.test.ts`/`externalReferenceRequirements.test.ts`/
+  `externalReferenceApplicability.test.ts`.
+- **State-file input**: `loadStateFile` is root-shape-only; label pattern and
+  `authenticatedState` enum are enforced by `isValidExplicitStateDimensions`
+  (`explicitState.test.ts`). The state vocabulary is explicitly documented as
+  never a place for credentials/tokens/cookies/session ids.
+- **Bindings file**: `loadBindingsFile` is root-shape-only; every bound-region
+  existence/uniqueness/pattern rule is owned by
+  `isValidReferenceRuntimeBindingDeclarations`
+  (`externalReferenceRuntimeBinding.test.ts`).
+- **Path traversal / operational-path privacy**: the extended smoke itself
+  re-verifies (as the pre-existing v0.4/v0.5/v0.6 sections already did) that
+  no operational absolute filesystem path (consumer dir, artifact roots,
+  config file paths) leaks into any persisted manifest, across the new v0.7
+  calls too.
+- **No credential-bearing explicit-state data**: confirmed by the
+  `ExplicitStateDimensions`/`ExternalReferenceApplicability` closed field
+  vocabularies (`theme`/`applicationState`/`authenticatedState`/`viewport`
+  only) — no field exists for tokens/cookies/headers.
+- **Reference/observation artifact immutability**: the extended smoke
+  re-hashes the pre-existing baseline observation manifest after running all
+  new v0.7 CLI/programmatic calls and confirms it is byte-identical.
+- **No external AI/network upload**: `referenceCorrectionWorkflow.ts`'s own
+  module doc explicitly states it "never calls a remote AI provider"; grep of
+  `src/` confirms no `fetch`/network client exists outside the browser
+  automation and observer's own disposable local HTTP fixture use in tests.
+- **No observer source editing**: `prepareReferenceCorrection`/
+  `reviewReferenceCorrectionAttempt` are pure, synchronous, in-memory
+  functions with no filesystem write capability — they return structured
+  results only; source-editing is explicitly the external actor's own
+  separate responsibility per the module's documented contract.
+
+No security failure, resolved or unresolved, was found.
+
+## Cross-platform CI result
+
+- **Run**: [34054085344](https://github.com/dailephd/my-frontend-observer/actions/runs/34054085344) ("Pre-release readiness"), triggered by the push of `validation/v0.7-pre-release` at commit `b2286bd`.
+- **Candidate job** ("Package exact candidate (Linux, Node 24)"): **success**, 1m34s. Node `v24.20.0`, npm `11.19.0`. Reproduced the exact same test counts as local: 1000 unit / 124 browser / 5+63 security. Produced exactly one tarball and one SHA-256.
+- **Windows matrix** (`windows-latest exact-candidate smoke`): **success**, 1m22s. Node `v24.19.0`.
+- **Linux matrix** (`ubuntu-latest exact-candidate smoke`): **success**, 54s. Node `v24.20.0`.
+- **macOS matrix** (`macos-latest exact-candidate smoke`): **success**, 36s. Node `v24.20.0`.
+
+### Same-candidate hash verification
+
+The candidate job produced exactly one tarball and computed its SHA-256 once
+(`0347b1f3cfd5d311e13b405c0c2fbc2f507e250cb63223d58b4d2d31df029414`). Each
+matrix lane downloaded that same uploaded `candidate-package` artifact and
+independently recomputed its SHA-256 before running any smoke step:
+
+```
+windows-latest: expected=0347b1f3... actual=0347b1f3...  (match)
+ubuntu-latest:  expected=0347b1f3... actual=0347b1f3...  (match)
+macos-latest:   expected=0347b1f3... actual=0347b1f3...  (match)
+```
+
+No matrix lane ran `npm pack` itself — the workflow's `matrix-smoke` job has
+no packaging step at all, only a download-and-verify step followed by the
+smoke script. Same-candidate architecture confirmed intact.
+
+### v0.7 cross-platform proof
+
+All three matrix lanes' `smoke-summary-<os>.json` artifacts carry
+`"v07PackedSmokeOk": true` plus every individual v0.7 flag true
+(`packedImportReferenceOk`, `packedApproveReferenceOk`,
+`packedExplicitStateOk`, `packedReferenceFidelityPassOk`,
+`packedReferenceFidelityFailOk`, `packedProgrammaticFidelityOk`,
+`packedPrepareReferenceCorrectionOk`,
+`packedReviewReferenceCorrectionAttemptOk`), confirmed directly from each
+job's raw log output (not merely inferred from the job's green checkmark).
+
+### v0.1–v0.6 regression proof (same candidate, same run)
+
+The same three logs also carry the pre-existing v0.1–v0.6 flags unchanged and
+still true: `legacyCssObservationPassed`, `windowScrollScenarioPassed`,
+`targetScrollScenarioPassed` (v0.1/v0.3), semantic-locator target coverage
+(v0.2), `comparableCompareOk`/`incomparableCompareOk` (v0.4),
+`packedApproveBaselineOk`/`packedSaveChangeContractOk`/`packedEvaluatePassOk`
+(v0.5), `v06PackedSmokeOk` (v0.6). No old assertion was removed or weakened to
+make room for the new v0.7 section — it was appended.
+
+## Known flake investigation
+
+Prompt 6 previously observed one unrelated browser-test flake that passed on
+rerun; Prompts 7/8 reported clean runs. No test failure of any kind occurred
+during this readiness stage, locally or in CI — nothing required
+investigation or rerun.
+
+## Ecosystem documentation
+
+`docs/ecosystem/TOOL_ECOSYSTEM_REFERENCE.txt` and
+`docs/ecosystem/WORKFLOW_PROMPT_ASSEMBLY_RULES.txt` do not exist in this
+repository. Ecosystem docs inspected; no update needed.
+
+## Report/commit discipline
+
+- `VALIDATED_CANDIDATE_HEAD` = `b2286bdc9550d70fa1047a1f732968a8eca46a1e` — this is the exact commit the successful cross-platform CI run (34054085344) validated.
+- `REPORT_COMMIT` = the commit that adds this file, made after the CI run completed successfully, containing only this report — no product or readiness-infrastructure behavior changes. Per the task's own instruction, the readiness workflow is not re-run a second time merely to fold the report commit's own SHA into itself.
+
+## Remaining risks
+
+- The packed-smoke script's temporary consumer install directory uses
+  `node:os`'s `tmpdir()` rather than a project-local path (a pre-existing
+  characteristic of `scripts/ci/runPackedObservationSmoke.mjs`, unchanged by
+  this readiness stage — modifying it was out of scope per the instruction
+  not to build a second, parallel package-smoke architecture, and CI's own
+  hosted runners have no more "project-local" location for an ephemeral job
+  container in any case). This does not affect the truth of any readiness
+  claim in this report.
+- `package.json`'s `engines.node` requires `>=24` with no upper bound;
+  runtime drift on future Node majors is a normal, unremarkable release-prep
+  concern, not a v0.7-specific risk.
+- No new product defect was discovered during this readiness stage.
+
+## Final verdict
+
+**`PASS_READY_FOR_RELEASE_PREP`**
+
+All conditions in the task's PASS-verdict checklist are satisfied: audited
+baseline present, clean install, typecheck, lint, full unit tests (1000),
+full browser tests (124), security tests (68), build, docs check, diff
+check, and pack dry-run all pass; one exact candidate tarball was built and
+its SHA-256 recorded; a clean consumer installed it and the installed-
+candidate smoke passed, meaningfully exercising the full v0.7 public surface
+(CLI + programmatic) in addition to preserving v0.1–v0.6 regression coverage;
+GitHub Actions' candidate job and all three (Windows/Linux/macOS) matrix
+lanes passed, each independently verifying the identical candidate SHA-256
+with no lane building a replacement tarball; no unresolved security,
+product, or coverage-gap issue exists; the package version remains `0.6.0`;
+no tag, release, or publish action occurred; and the repository's tracked
+state is clean at completion. This means the v0.7 implementation is **ready
+for release preparation** — not that release preparation has already
+happened.

package/docs/reports/v0.7-reference-binding-prompt5.md

@@ -0,0 +1,223 @@
+# v0.7 Prompt 5 — Explicit Reference-Region ↔ Runtime-Target Binding
+
+**VERDICT: PASS_V0_7_REFERENCE_BINDING_PROMPT5**
+
+## Repository / branch / heads
+
+- Repository: `my-frontend-observer` (path: `Z:\Users\newuser\Projects\my-frontend-observer`)
+- Branch: `implementation/v0.7-reference-binding`, branched from the exact completed Prompt 4 HEAD
+- Starting HEAD (this prompt's branch point): `023feccac2b4255a119282d359782691b4734bce` (Prompt 4 report commit)
+- Prompt 4 base HEAD confirmed to contain both required commits: `4da60be` (implementation) and `023fecc` (report) — verified via `git log --oneline` before branching.
+- Implementation commit (this prompt): `74cc148f6b4ccda1c2a394634a8e9d5de26285dd` — "Add v0.7 Prompt 5 explicit reference-region <-> runtime-target binding"
+- Ending HEAD (after this report is committed): the report commit that follows this file's commit.
+
+## Git status
+
+Preflight (`git status --short`) showed a clean working tree on `implementation/v0.7-reference-compatibility` at the exact Prompt 4 report HEAD; `git stash list` showed exactly the one preserved Prompt 1 stray-fork-writes entry. The branch was created from that HEAD with `git checkout -b implementation/v0.7-reference-binding` and ancestry verified with `git merge-base --is-ancestor 023fecc HEAD`. No unrelated dirty state was present at any point; no reset/clean/discard operation was used; the Prompt 1 stash was neither applied nor dropped. Post-implementation `git status --short` is clean except for this report file (staged and committed separately, per convention).
+
+## Tooling
+
+- Resolved latest published `@dailephd/my-dev-kit`: `1.12.3` (via `npm view @dailephd/my-dev-kit version`), pinned exactly via `npx -y @dailephd/my-dev-kit@1.12.3`.
+- Fresh Prompt 5 repository index built under a repository-local root (per this prompt's "project-contained workflow state" requirement, not `C:\`): `.my-dev-kit-context/index-prompt5/` (`manifest.json`, `symbol-index.json`, `code-graph.json`, `call-graph.json`; 56 files, 851 symbols indexed). This index was not reused from Prompt 1–4's indexes — a fresh retrieval was performed at execution start.
+- `.gitignore` extended with `.my-dev-kit-context/` and `.my-dev-kit-workflow/` (alongside the pre-existing `.my-dev-kit/`/`.my-dev-kit-orchestrator/` entries) so this and future prompts' workflow-owned state never appears as stageable.
+
+## Prompt 1–4 contracts verified
+
+Read directly (source, not the fresh index's summaries alone) before writing any code:
+
+- `src/domain/externalReference.ts` / `externalReferenceIdentity.ts` — confirmed `ExternalReferenceArtifact`'s `regions?`/`requirements?`/`applicability?` shape, both lifecycle variants, and `isValidExternalReferenceArtifact`'s existing structural gate (reused directly, not reimplemented).
+- `src/domain/externalReferenceRegions.ts` — confirmed `ReferenceRegion.id` (Prompt 2's region identity: no separate identity-hashing function exists for regions, just the authored `id` string with `REFERENCE_REGION_ID_PATTERN` and case-insensitive uniqueness) — reused verbatim as the reference-side half of a binding declaration.
+- `src/domain/externalReferenceRequirements.ts` — confirmed the exact precedent for "a reference to an unknown region id is a structural validation failure at authoring time, not a per-item unavailable result" (`regionIds`/`byId` lowercase-keyed lookups, `isValidReferenceRequirements` rejecting the whole collection on an unknown region reference), and the "no two requirements may share the same structural subject" duplicate/conflict rule — both reused as direct design precedent for binding-declaration validation.
+- `src/domain/externalReferenceCompatibility.ts` (Prompt 4) — confirmed `evaluateReferenceCandidateCompatibility`'s exact signature and `ReferenceCandidateCompatibilityResult` shape; reused verbatim as this prompt's compatibility gate.
+- `src/domain/comparisonEngine.ts` (v0.4) — confirmed the module-private `targetPresence(record): 'matched'|'not-found'|'ambiguous'|'unavailable'` helper, already the canonical rule v0.4's own before/after target comparison uses to read a `TargetEvidenceRecord`'s resolution outcome.
+- `src/domain/schema.ts` (v0.1/v0.2) — confirmed `TargetSelectionStatus = 'matched'|'not-found'|'ambiguous'|'unavailable'`, `TargetResolution`, `TargetEvidenceRecord` (keyed by exact configured target name in `ObservationArtifact.targetEvidence`), and `TargetVisibility` (a wholly separate concept from `TargetSelectionStatus` — visibility is never one of the four resolution states).
+- `src/request/request.ts` (v0.1/v0.2) — confirmed `NamedTarget { name, locators }` as the stable observer-owned runtime target identity, `TARGET_NAME_RE = /^[A-Za-z0-9_-]{1,64}$/` (private, mirrored independently rather than imported), and the case-insensitive target-name-resolution convention already used for `target-scroll-by`.
+- `src/domain/boundedAgentContextCorrelation.ts` (v0.6) — read in full; confirmed the uncertainty-handling discipline (never hide competing candidates, never guess through ambiguity, deterministic candidate/target ordering by sorted id rather than input order, count-based status derivation: zero candidates → `unavailable`, one → `correlated`, more than one → `ambiguous`) reused as *architectural discipline* only — v0.6's own `correlated`/`ambiguous`/`unavailable` correlation-status vocabulary was deliberately **not** reused verbatim, since it describes a different evidence boundary (ranking static candidates for one runtime target) than binding (resolving one runtime target's own existence for one declared region correspondence).
+
+## v0.2 runtime-target precedent
+
+The stable runtime target identity is `NamedTarget.name` (a bounded `^[A-Za-z0-9_-]{1,64}$` label), matched against `ObservationArtifact.requestConfig.targets` and used to key `ObservationArtifact.targetEvidence`. This prompt binds only to that name — never to a CSS selector, a Playwright locator, a DOM node handle, a source file, a React component name, or a my-dev-kit node id. Target-name matching in `evaluateReferenceRuntimeBindings` is case-insensitive, mirroring the exact convention already used for `target-scroll-by` target resolution in `request/request.ts`; the exact configured `name` (original case) is then used to index `targetEvidence`, matching how that record is actually keyed by `src/browser/evidenceCapture.ts`.
+
+## v0.6 uncertainty precedent
+
+Reused as architectural discipline (never guess through ambiguity, never silently prefer a "first" candidate/result, deterministic ordering by declared/sorted identity rather than input order, explicit unavailable-vs-ambiguous distinction) — not as a literal status-vocabulary reuse. `evaluateReferenceRuntimeBindings` never collapses an ambiguous v0.2 target resolution into `bound`, and never fabricates a binding when the underlying evidence is missing.
+
+## Binding model
+
+One new pure domain module: `src/domain/externalReferenceRuntimeBinding.ts`.
+
+```ts
+interface ReferenceRuntimeBindingDeclaration {
+  referenceRegion: string; // Prompt 2 ReferenceRegion.id
+  runtimeTarget: string;   // v0.2 NamedTarget.name
+}
+
+function isValidReferenceRuntimeBindingDeclarations(
+  value: unknown,
+  reference: ExternalReferenceArtifact,
+): { valid: true } | { valid: false; reason: string };
+
+function evaluateReferenceRuntimeBindings(
+  reference: ExternalReferenceArtifact,
+  candidate: ObservationArtifact,
+  declarations: readonly ReferenceRuntimeBindingDeclaration[],
+): { ok: true; evaluation: ReferenceRuntimeBindingEvaluation } | { ok: false; reason: string };
+```
+
+The binding declaration is explicit user/configuration input at every point — the module contains no code path that derives a correspondence from geometry, pixel content, matching name strings, matching text, or source code. A reference region id and a runtime target name that happen to share the same string value bind to each other only when an explicit declaration says so (verified directly by a dedicated test comparing the same observation/reference pair with and without the declaration).
+
+## Exact status vocabulary
+
+`REFERENCE_RUNTIME_BINDING_STATUSES = ['bound', 'ambiguous', 'unavailable'] as const`. No fourth "incompatible" status was added — per the task's own guidance (§14), Prompt 4's compatibility is represented separately (see below), never folded into a binding-local status enum.
+
+Reason codes (present only when `status !== 'bound'`): `runtime-target-not-configured`, `runtime-target-not-found`, `runtime-target-ambiguous`, `runtime-target-evidence-unavailable`.
+
+## Compatibility-gating behavior
+
+`evaluateReferenceRuntimeBindings` calls `evaluateReferenceCandidateCompatibility(reference, candidate)` exactly once, before evaluating any individual declaration. If the returned `compatibility.state === 'incomparable'`, the function returns `ok: true` with `bindings: []` and the full `compatibility` result embedded in `ReferenceRuntimeBindingEvaluation.compatibility` — the caller reads the blocker from that field. No per-declaration result is fabricated in this case (verified by behavior-F test: an incompatible viewport pair produces zero bindings, never a bound result). When `compatibility.state` is `comparable` or `comparable-with-warnings`, every declaration is evaluated normally. Compatibility rules (viewport/theme/application-state/authenticated-state comparison) are never recomputed or duplicated inside this module.
+
+## Reference-region identity behavior
+
+Reused exactly as Prompt 2 defined it: `ReferenceRegion.id`, matched case-insensitively (mirroring the existing region-uniqueness/requirement-region-reference convention). No new reference-region identity system was created. A declaration naming a `referenceRegion` not present in `reference.regions` (or a reference with no `regions` field at all) fails the **entire** evaluation closed at the structural-validation stage — `evaluateReferenceRuntimeBindings` returns `ok: false` before a candidate observation is even consulted, mirroring Prompt 3's exact "unknown region reference is a structural authoring-time failure" precedent for requirements.
+
+## Runtime-target identity behavior
+
+Reused exactly as v0.2 defined it: `NamedTarget.name`, matched case-insensitively against `candidate.requestConfig.targets`, then the exact configured name is used to index `candidate.targetEvidence`. Runtime-target *availability* (as opposed to reference-region *existence*) is evaluated per-candidate, inside `evaluateReferenceRuntimeBindings` itself, not during the candidate-independent structural validation pass — the same declaration can legitimately be `bound` against one candidate and `unavailable` against another.
+
+## Target-resolution-state handling
+
+`targetPresence` (v0.4 `comparisonEngine.ts`, additively exported this prompt alongside the already-exported `assessOptionalComparabilityDimension`) is the single reused rule for reading a `TargetEvidenceRecord`'s resolution:
+
+| `targetPresence` outcome | Binding status | Reason code |
+|---|---|---|
+| `matched` | `bound` | — |
+| `ambiguous` | `ambiguous` | `runtime-target-ambiguous` |
+| `not-found` | `unavailable` | `runtime-target-not-found` |
+| `unavailable` (no usable resolution evidence, or no record at all) | `unavailable` | `runtime-target-evidence-unavailable` |
+
+A fifth situation exists only at the binding-evaluation boundary itself, not inside `targetPresence`: a declared `runtimeTarget` that was never part of the candidate's own `requestConfig.targets` at all → `unavailable` / `runtime-target-not-configured`, resolved without ever dynamically searching the page (the evaluator consumes only the already-captured `ObservationArtifact`).
+
+## Hidden-target decision
+
+A uniquely resolved (`matched`) but hidden target (`TargetVisibility.visible === false`) is still reported `bound` — visibility is carried only as provenance (`targetVisible`) and never changes `status`. Rationale, documented in the module and in `docs/CONTRACTS.md`: binding identity ("does a stable correspondence exist") and fidelity evaluability ("can this evidence actually be used to check the design") are distinct questions; this prompt answers only the former, leaving the latter to Prompt 6. Verified by a dedicated test (`Q: a hidden but uniquely resolved runtime target is still reported bound, with targetVisible: false as provenance`).
+
+## Duplicate/conflicting binding behavior
+
+No two declarations may name the same `referenceRegion` (case-insensitively), whether their `runtimeTarget` values agree (an exact duplicate) or disagree (a conflict) — both fail the whole batch identically at structural-validation time, `ok: false`, never silently resolved by keeping the first declaration. This mirrors Prompt 3's "no two requirements may share the same structural subject, regardless of category" rule exactly. Verified by dedicated tests for both the exact-duplicate case (I) and the conflicting-target case (J).
+
+## Multiple-regions-to-one-target decision
+
+**Allowed, deliberately.** Several distinct reference regions may each declare a binding to the same `runtimeTarget` (e.g. two design sub-regions, such as a header's logo area and its nav area, both corresponding conceptually to one runtime container element). This is documented as a legitimate correspondence, unlike the reverse (one region needing several runtime targets), which is prohibited because it would be inherently ambiguous which target represents that region — the "one region, one explicit primary target" rule from §13. Verified by a dedicated test (K).
+
+## Bounds
+
+`MAX_REFERENCE_RUNTIME_BINDINGS = 20`, mirroring `MAX_REFERENCE_REGIONS`'s existing bound — a binding-declaration collection is authoring input over the same region set, so the same cap applies. Independently owned (not imported), consistent with the repository's established "coincidentally equal, independently owned bound" convention (e.g. `MAX_REFERENCE_REGIONS`/`MAX_TARGETS` already share the value 20 without being structurally coupled). Verified: exactly 20 declarations accepted, 21 rejected.
+
+## Deterministic ordering
+
+`bindings` in the evaluation result preserves the authored order of the `declarations` array passed in — never a sort by any derived key, mirroring the "authored order is semantic" convention already established for regions (Prompt 2) and requirements (Prompt 3). Verified by a dedicated test asserting result order matches declaration order even when it does not match the reference's own region-authoring order.
+
+## Identity decision
+
+**No new identity-hashing function was introduced.** Unlike `buildRequestIdentity`/`buildExternalReferenceRequestIdentity`, no deterministic content-hash identity is computed for a binding declaration or its evaluated result. This mirrors Prompt 4's own `ReferenceCandidateCompatibilityResult`, which took the identical approach: provenance is carried as plain, already-deterministic fields (`referenceId`, `referenceRequestId`, `candidateObservationId`, `candidateRequestId`, plus each result's own `referenceRegion`/`runtimeTarget`) rather than a fifth hashing convention for a value this prompt never persists and never looks up by id. Because no identity function exists, path-independence (test L in the task's behavior model) holds trivially — there is no file-loading code in this prompt at all (see CLI decision below), so no path could ever reach identity even indirectly.
+
+## Persistence decision
+
+**No persisted artifact family was introduced.** `evaluateReferenceRuntimeBindings` is a pure, synchronous, on-demand function over an already-persisted `ExternalReferenceArtifact`, an already-persisted `ObservationArtifact`, and an in-memory declaration collection — it produces no `ExternalReferenceBindingArtifact` or equivalent. Rationale (same reasoning Prompt 4 already applied to its own compatibility result): the result is cheap to recompute deterministically from its three inputs, and persisting it would invite drift (a re-imported reference or re-observed candidate could silently disagree with a stale persisted binding record) with no corresponding benefit at this stage. This decision may be revisited only if Prompt 6's architecture proves persistence necessary — not assumed here.
+
+## Reference / observation artifact immutability
+
+Neither `ExternalReferenceArtifact` nor `ObservationArtifact` gained any new field in this prompt, and `evaluateReferenceRuntimeBindings` never mutates either input (verified by a dedicated deep-equality-snapshot test, N, covering the reference, the candidate, and the declaration input array all three). A design reference remains evaluable against multiple future candidates; a candidate observation remains evaluable against multiple future references — binding results are kept as downstream, candidate-specific, reference-specific derived evidence, never embedded back into either source artifact.
+
+## Public / programmatic interface
+
+Exported from `src/index.ts` (additive):
+- Types: `ReferenceRuntimeBindingStatus`, `ReferenceRuntimeBindingReasonCode`, `ReferenceRuntimeBindingDeclaration`, `ReferenceRuntimeBindingValidationResult`, `ReferenceRuntimeBindingResult`, `ReferenceRuntimeBindingEvaluation`, `EvaluateReferenceRuntimeBindingsResult`.
+- Values: `RUNTIME_TARGET_NAME_PATTERN`, `MAX_REFERENCE_RUNTIME_BINDINGS`, `REFERENCE_RUNTIME_BINDING_STATUSES`, `REFERENCE_RUNTIME_BINDING_REASON_CODES`, `isValidReferenceRuntimeBindingDeclarations`, `evaluateReferenceRuntimeBindings`.
+- Additionally, `TargetPresence`/`targetPresence` (previously module-private in `comparisonEngine.ts`) are now additively exported, since this new module reuses that exact function rather than duplicating its logic.
+
+No internal helper clutter is exported (`findConfiguredTargetName`, `evaluateOneBinding`, `isValidBindingDeclarationShape` all remain module-private).
+
+## CLI changes
+
+**None.** Per the task's explicit guidance (§37: "Do not add a standalone CLI command merely for symmetry... Prompt 6 may become the first public consumer"), no CLI command or config-file loader was added this prompt. The full capability is exposed only through the programmatic API above. `docs/COMMANDS.md` was therefore not touched.
+
+## Files changed
+
+New:
+- `src/domain/externalReferenceRuntimeBinding.ts`
+- `tests/unit/externalReferenceRuntimeBinding.test.ts`
+
+Modified:
+- `src/domain/comparisonEngine.ts` (additively exported `targetPresence`/`TargetPresence`, previously module-private; zero behavior change)
+- `src/index.ts` (public export surface for the above)
+- `docs/ARCHITECTURE.md`, `docs/CONTRACTS.md`, `docs/WORKFLOWS.md`
+- `.gitignore` (added `.my-dev-kit-context/`, `.my-dev-kit-workflow/`)
+
+## Tests
+
+889 unit tests total (857 pre-existing + 32 new), all pure domain-level tests — zero Chromium launches for binding evaluation itself, per the task's explicit requirement. New coverage in `tests/unit/externalReferenceRuntimeBinding.test.ts` includes:
+
+- `isValidReferenceRuntimeBindingDeclarations`: valid single/empty declaration, non-array rejection, exact-bound acceptance (20) and one-over-bound rejection (21), malformed shape rejection (missing field/wrong type/unknown field), unknown reference region (behavior B), reference with no regions at all (behavior O), exact-duplicate rejection (behavior I), conflicting-target rejection (behavior J), multiple-regions-to-one-target acceptance (behavior K), unused-region tolerance (behavior P), case-insensitive region matching.
+- `evaluateReferenceRuntimeBindings`: valid binding with differing ids (behaviors A/H), same-string-ids-require-explicit-declaration (behavior G, both with and without the declaration), unknown-region whole-batch failure (behavior B), unknown/not-configured runtime target (behavior C), ambiguous runtime target (behavior D), not-found vs. evidence-unavailable distinction, incompatible reference/candidate blocks all bindings (behavior F), matching compatibility permits evaluation, hidden-target bound-with-provenance (behavior Q), deterministic authored-order preservation and pure-function repeatability (behavior M), full three-input immutability (behavior N), case-insensitive runtime-target-name resolution, full provenance carry-through, fail-closed on a structurally invalid reference or candidate artifact, and absence of any source-ownership-style field in the result (`sourceOwner`/`sourceFile`/`component`/`symbol`/`causedBy`).
+
+## Validation results
+
+All commands run from the repository root, after the implementation commit:
+
+- `npm run typecheck` — pass, zero errors.
+- `npm run lint` — pass, zero errors/warnings.
+- `npm test` — 46 test files, 889 tests, all pass.
+- `npm run build` — pass, clean `tsc` compile.
+- `npm run check:docs` — pass (17 required files present, `ROADMAP.md` format intact — no implementation batches added).
+- `git diff --check` — exit 0, no whitespace errors.
+- `npm pack --dry-run` — pass; `dist/domain/externalReferenceRuntimeBinding.{js,d.ts,js.map}` confirmed present in the tarball listing (public exports changed, so this was run per the task's requirement).
+- `npm run test:security` — pass (5 + 63 = 68 tests: `policy.test.ts` + real-Chromium `chromiumAdapter.test.ts`), run because a new public input surface (`ReferenceRuntimeBindingDeclaration`) was added.
+- `npm run test:browser` — pass (9 files, 120 tests, real Chromium), run as full regression confirmation per established repository policy, even though Prompt 5 itself has no Chromium dependency.
+
+## Regression results
+
+- Prompt 1 artifact/lifecycle: unaffected — `externalReference.ts` untouched this prompt.
+- Prompt 2 regions/relationships: unaffected — `externalReferenceRegions.ts`/`externalReferenceRegionRelationships.ts` untouched; `REFERENCE_REGION_ID_PATTERN` only imported, never modified.
+- Prompt 3 requirements/adequacy: unaffected — `externalReferenceRequirements.ts` untouched.
+- Prompt 4 state/compatibility: unaffected — `externalReferenceCompatibility.ts`, `explicitState.ts`, `externalReferenceApplicability.ts` untouched; `evaluateReferenceCandidateCompatibility` called, never modified.
+- v0.2 runtime target identity/resolution: unaffected — `request/request.ts`, `schema.ts`, `browser/evidenceCapture.ts` untouched.
+- v0.4 comparison: unaffected in behavior — `comparisonEngine.ts`'s only change is exporting a previously-private function (`targetPresence`) verbatim; every existing caller and every existing test of `evaluateComparability`/`compareObservations`/`compareTargetConfiguration` continues to pass unchanged.
+- v0.5 contracts: unaffected — no file in `frontendContracts*.ts` touched.
+- v0.6 runtime/static correlation: unaffected — `boundedAgentContext*.ts` untouched; its status vocabulary/discipline was read for precedent only, never imported or modified.
+- Full unit (889/889), browser (120/120), and security (68/68) suites all pass with zero regressions.
+
+## Security impact
+
+- No new external input surface beyond an in-memory, caller-supplied declaration array (no file, no CLI flag, no network call in this prompt) — the smallest possible surface, since no CLI/config-file loader was added.
+- `evaluateReferenceRuntimeBindings` performs no filesystem access, no network access, and no browser/Chromium invocation of any kind.
+- `test:security` (policy + real-Chromium adapter tests) re-run and passing, confirming no regression to the existing safety/navigation policy surface (untouched by this prompt).
+
+## Documentation changes
+
+- `docs/CONTRACTS.md` — new "v0.7 Prompt 5 explicit reference-region ↔ runtime-target binding" section (full type shapes, key rules, status-mapping table equivalent in prose, hidden-target/duplicate/multiple-regions decisions, persistence/identity decisions, CLI-surface decision).
+- `docs/ARCHITECTURE.md` — new paragraph in the "Planned v0.7–v0.10" section describing the Prompt 5 module addition, its reuse of Prompt 4's compatibility gate and v0.4's `targetPresence`, and its architectural-discipline-only (not vocabulary) reuse of v0.6's uncertainty handling.
+- `docs/WORKFLOWS.md` — "Current external-reference foundation workflow" retitled to "Prompts 1-5" and extended with a paragraph describing `evaluateReferenceRuntimeBindings`.
+- `docs/COMMANDS.md` — not touched (no CLI surface change this prompt).
+
+## Tooling incidents
+
+None. No orchestrator was invoked (direct-implementation mode used throughout, consistent with Prompts 2–5); no background/speculative subagent writes occurred; the Prompt 1 stray-fork-writes stash remains untouched, unapplied, and unmined as precedent.
+
+## Out-of-scope confirmation
+
+This prompt implements no automatic target matching, no computer vision, no screenshot segmentation, no OCR, no fuzzy matching, no geometry-based matching, no source-correlation changes, no source ownership, no reference/candidate geometry delta, no spacing delta, no relationship fidelity evaluation, no selected-requirement evaluation, no fidelity PASS/FAIL, no style fidelity, no image similarity, no bounded correction packet, no coding-agent context changes or invocation, no source edits, no correction loop, no viewer, and no annotation. `evaluateReferenceRuntimeBindings` reads only `reference.regions` (for structural validation), `reference.applicability` (via the reused compatibility gate), and `candidate.requestConfig.targets`/`candidate.targetEvidence` — it never reads `reference.requirements`, never compares geometry, and never touches source code or my-dev-kit retrieval of any kind.
+
+## Known limitations
+
+- A binding declaration supports exactly one `runtimeTarget` per `referenceRegion` — there is no "candidate alternatives" mechanism (deliberately; the task's own guidance treats this as the smallest, cleanest representation, and any future need for ranked/multiple candidate targets per region is left to a later prompt to design explicitly, not improvised here).
+- No CLI/config-file surface exists yet for authoring binding declarations outside of direct programmatic use — deferred to Prompt 6 per the task's own guidance.
+- `targetVisible` provenance is populated only when the underlying `TargetVisibility` evidence is itself available; a `bound` result for a target whose visibility evidence is unavailable simply omits the field rather than guessing a value.
+
+## Remaining risks
+
+- None identified that block this prompt's own scope. The primary forward consideration for Prompt 6 (structured fidelity evaluation) is how it will consume `ReferenceRuntimeBindingEvaluation.bindings` together with Prompt 3's per-requirement expectations to determine which selected requirements have sufficient bound evidence for evaluation — flagged for that prompt's own precedent review, not preempted here.
+
+## Exact next action
+
+v0.7 Prompt 6 — structured reference-vs-candidate fidelity evaluation.