@dailephd/my-frontend-observer 0.9.1 → 0.10.1

package/docs/reports/v0.8-reference-candidate-inspection-batch5.md

@@ -1,232 +1,232 @@
-# v0.8 Batch 5 — External Reference and Reference/Candidate Inspection — Implementation Report
-
-## 1. Starting state
-
-- Branch: `master`
-- Starting HEAD: `319b7638d18edfcbba9902c8de7c68a02c377115` ("feat: add v0.8 comparison and contract inspection", Batch 4)
-- `origin/master` after `git fetch`: `a1de8ac01e1367b60021cb04226f56369fa2debb`
-- `git rev-list --left-right --count origin/master...HEAD`: `0  4` — local is exactly Batches 1-4 ahead of origin.
-- `git merge-base --is-ancestor origin/master HEAD` → succeeded (exit 0): origin/master is a strict ancestor of local HEAD, no divergence. No pull/rebase/merge/reset performed.
-- Starting `git status --short`: clean.
-- Package version confirmed `0.7.0` throughout; never bumped.
-
-## 2. The same path contradiction as Batch 4, resolved the same way
-
-Task §5 gave an explicit, executable `Join-Path` algorithm with five verification assertions producing an inside-repository path, then separately restated the old Batches-1-3 sibling directory as the "Required resolved Batch 5 path" - textually inconsistent with its own algorithm (the sibling path fails assertion 1: it does not start with `$REPO_ROOT\`). Re-ran the literal algorithm:
-
-```
-REPO_ROOT=Z:\Users\newuser\Projects\my-frontend-observer
-WORKFLOW_BASE=Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow
-WORKFLOW_VERSION_ROOT=Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8
-WORKFLOW_ROOT=Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8\batch-05
-TestPathRepoRoot=True
-ContainmentCheck=True
-ParentOfBase=Z:\Users\newuser\Projects\my-frontend-observer
-ParentOfRoot=Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8
-```
-
-All required checks pass for the inside-repository path. Per the same precedent established and documented in the Batch 4 report (`docs/reports/v0.8-comparison-contract-inspection-batch4.md` §2) - itself cross-checked against the repository's own `.gitignore` `.my-dev-kit-workflow/` entry, which only makes sense for an inside-repository path - Batch 5 followed the executable algorithm rather than the inconsistent restated sentence, and used **`Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8\batch-05`**.
-
-## 3. Prior workflow-root audit
-
-- Sibling `Z:\Users\newuser\Projects\my-frontend-observer.my-dev-kit-workflow\v0.8\` contains exactly `batch-01`, `batch-02`, `batch-03` - untouched, not migrated, not reused.
-- Inside-repo `.my-dev-kit-workflow\v0.8\` contained `batch-04` (from the prior batch) before this batch started; Batch 5 added only `batch-05` alongside it without touching `batch-04`.
-
-## 4. Predecessor reports/plan inspected
-
-All four predecessor reports read in full (Batch 1-4). `docs/plans/v0.8-implementation-plan.md`'s "Batch 5 — External reference and reference/candidate inspection" section (goal/in-scope/out-of-scope/gate) matches the task's own scope exactly - no material difference found. `docs/ARCHITECTURE.md`, `docs/CONTRACTS.md`, `docs/CURRENT_STATE.md`, `docs/WORKFLOWS.md`, `docs/COMMANDS.md`, `docs/PROJECT_MILESTONES.md` (Milestone 8), `docs/ROADMAP.md` (v0.8), `docs/DOCUMENTATION_PRESERVATION_POLICY.md`, `docs/PROJECT_DESCRIPTION.md` all read/re-confirmed.
-
-## 5. my-dev-kit retrieval
-
-Index built at `$WORKFLOW_ROOT\my-dev-kit-index`. All seven required searches were run; results were cross-checked against direct source reads of `src/domain/externalReference*.ts`, `src/artifacts/externalReferenceArtifactReader.ts`, `src/application/externalReferencePersistenceService.ts`, and `src/viewerServer/evidence/{classify,mediaResolver,index}.ts` - every result matched.
-
-## 6. Pre-edit reference-contract audit (task §10)
-
-Read `src/domain/externalReference.ts`, `externalReferenceRegions.ts`, `externalReferenceRegionRelationships.ts`, `externalReferenceRequirements.ts`, `externalReferenceApplicability.ts`, `externalReferenceCompatibility.ts` in full. Confirmed exactly:
-
-- `ExternalReferenceArtifact = ImportedExternalReferenceArtifact | ApprovedExternalReferenceArtifact` - discriminated by `lifecycle.state`; imported carries `image` and never `sourceReference`; approved carries `sourceReference` and never `image` (`isValidExternalReferenceArtifact` rejects any mix).
-- `regions?: ReferenceRegion[]`, `requirements?: ExternalReferenceRequirement[]`, `applicability?: ExternalReferenceApplicability` are additive/optional on both lifecycle variants, carried forward verbatim by `approveExternalReference` (never re-derived on approval).
-- `ReferenceRegion = {id, rectangle:{x,y,width,height}}` in reference-image pixels; `deriveReferenceRegionGeometry` is the sole pure derivation of `right/bottom/centerX/centerY` - never persisted.
-- `ExternalReferenceRequirement` reuses the exact v0.5 `AuthoredChangeScopeCategory` vocabulary (`requested`/`expected-dependent`/`protected`/`preserved`) - `'unexpected'` is not an authorable member.
-- `evaluateReferenceCandidateCompatibility` is page/state-level only (viewport/theme/applicationState/authenticatedState), reuses `ComparabilityResult`/`assessOptionalComparabilityDimension` from the v0.4 comparison engine verbatim - never a second compatibility model.
-
-## 7. Reference image ownership rule (task §11) - already built in Batch 2, verified, reused unchanged
-
-Read `src/viewerServer/evidence/mediaResolver.ts` in full: role `'image'` requires `family === 'external-reference-imported'`, resolved from that artifact's own directory. Role `'source-image'` requires `family === 'external-reference-approved'`, resolved via `findImportedReferenceDir(root, sourceReference.referenceId)` (`src/viewerServer/evidence/index.ts`) - a bounded exact-`referenceId` walk of the current evidence root, never assuming co-location, never copying bytes. Batch 5 added **zero** changes to `mediaResolver.ts` or `index.ts` - this mechanism already existed and is reused verbatim (confirmed via real Chromium proof, §17 Cases A/B below).
-
-## 8. Reference region coordinate model (task §12/§13)
-
-`ReferenceRegionOverlaySvg.tsx` (new): `viewBox="0 0 <imageWidth> <imageHeight>"` where `imageWidth`/`imageHeight` come from the artifact's own `image.width/height` (imported) or `sourceReference.image.width/height` (approved) - never the candidate's runtime viewport, never devicePixelRatio-multiplied, never normalized to percentages. Each region's canonical `{x,y,width,height}` is rendered unchanged. This is a deliberately distinct, sibling component from `TargetOverlaySvg` (a genuinely different coordinate domain and data source), not a reuse/parameterization of it - reusing that component would have silently conflated reference-image pixels with runtime CSS pixels.
-
-## 9. Reference region selection (task §14/§15)
-
-Region list clicks and SVG rectangle clicks both call the same `setSelectedRegionId` handler in `ReferenceWorkspace.tsx`; selection identity is exact `ReferenceRegion.id` (never a runtime target name). Labels render `region.id` verbatim - no OCR, no computer vision, no name inference. Proven bidirectionally in real Chromium (`referenceCandidateWorkspace.test.ts`, Case A: clicking the SVG rectangle sets `aria-pressed="true"` and the inspector shows "Reference region: header").
-
-## 10. Reference relationships (task §16) - server-side derivation, reused canonical function
-
-`src/viewerServer/evidence/referenceView.ts#getReferenceView` calls the existing canonical `deriveReferenceRegionRelationships` (never a duplicated predicate set, never `deriveLayoutRelationships` over reference regions) over the artifact's own `regions`, exposed via `GET /api/references/<handle>/view`. Only the six geometry-only relationship families it already supports are ever shown; no DOM containment/scroll/visibility is fabricated for a static image.
-
-## 11. Reference requirements / distinction from evidence (task §17/§18)
-
-`ReferenceInspector.tsx` renders each authored `ExternalReferenceRequirement` distinctly from raw region geometry: `requirementId`, `category`, `expectedDependentMode` (when `expected-dependent`), `subject` (region-property/region-relationship/region-measurement), and `tolerance` (exact/absolute-reference-px/percent) are all shown verbatim. A region's own geometry is displayed only under "Reference region: `<id>`" when that region is explicitly selected - it is never presented as an implied requirement. No `'unexpected'` category is ever fabricated (the type does not admit it).
-
-## 12. Reference requirement expectation / adequacy (task §19/§20)
-
-Server-side `deriveReferenceRequirementAdequacy` (existing canonical function, never a competing derivation) computes `status`/`totalRequirements`/`evaluableRequirements`/`reasons` over the artifact's own `regions`+`requirements`, exposed via the same `GET /api/references/<handle>/view` route, rendered under "Reference requirement adequacy" - kept in its own section, visually and semantically distinct from "Reference/candidate compatibility" (task §20's required distinction between reference adequacy and reference/candidate compatibility).
-
-## 13. Reference applicability (task §21)
-
-`ReferenceInspector.tsx` renders `applicability.viewport`/`.theme`/`.applicationState`/`.authenticatedState` exactly as persisted, or "not declared" when absent - never inferred from image pixels, theme is never visually guessed, application/auth state are never inferred from screenshot content.
-
-## 14. Candidate selection (task §22)
-
-`ReferenceWorkspace.tsx` renders a `<select id="reference-candidate-select">` populated from `useEvidenceIndex()`'s `observation`-family, `supported` records only. The initial value is always empty ("(none selected)") - no default candidate is ever pre-selected based on viewport/URL/target-name/timestamp/geometry similarity. Compatibility and side-by-side candidate rendering are gated entirely on `candidateHandle !== undefined`.
-
-## 15. Reference/candidate compatibility (task §23/§24)
-
-`getReferenceCandidateView` (new, `src/viewerServer/evidence/referenceView.ts`) calls the existing canonical `evaluateReferenceCandidateCompatibility(reference, candidate)` unchanged - never reimplemented in React or the viewer server. `comparable`/`comparable-with-warnings`/`incomparable` and each reason's `blocking`/`warning`/`unassessed` severity are rendered exactly as returned (`.comparability-banner--<state>`, reused styling from Batch 4's comparison workspace). An `incomparable` result gets `role="alert"`. No pixel/geometry/fidelity failure is ever fabricated from an incompatible state - the side-by-side panes remain fully inspectable regardless (proven in Case D).
-
-## 16. Side-by-side layout and candidate rendering reuse (task §25/§26)
-
-Default layout is a two-column grid (`.reference-workspace__panes`) - reference pane (image-domain SVG) beside candidate pane. The candidate pane is `ComparisonObservationPane` (Batch 4, unchanged) fed a synthetic `LinkStatus = {status:'resolved', handle: candidateHandle}` once a candidate is explicitly chosen - **zero** new candidate screenshot/coordinate-transform/target-rendering code was written; `TargetOverlaySvg` (Batch 3) renders the runtime viewport/targets exactly as it already did. No blended/alpha image, no pixel-difference heat map.
-
-## 17. Real-browser proof (task §51, all cases)
-
-`tests/browser/referenceCandidateWorkspace.test.ts` - 6 tests, all real Chromium against real canonically-produced fixtures (`writeReferenceCandidateFixture`, built through the real `importExternalReference`/`approveExternalReference`/`writeObservationArtifact` — never hand-forged JSON):
-
-- **Case A (imported)**: real decodable image loads via `/api/media/<handle>/image`; `header`/`sidebar` rectangles render at their exact canonical width/height (400/240); region selection sets `aria-pressed`; lifecycle reads "imported". **PASS.**
-- **Case B (approved)**: image loads via `/api/media/<handle>/source-image`; body text shows "approved (" and "owned by imported source referenceId" - proving the exact-source resolution, never a duplicated image. **PASS.**
-- **Case C (compatible)**: reference and candidate render side by side with distinct viewBoxes (`0 0 400 300` vs `0 0 1200 800`); compatibility banner is `comparable`; the "not evaluated in this batch" fidelity note is present. **PASS.**
-- **Case D (incompatible)**: `comparability-banner--incomparable` with real `viewport-mismatch`/`theme-mismatch` reasons; both panes still render; no "fidelity ... PASS/FAIL" text ever appears. **PASS.**
-- **Case E (equal names, no binding)**: selecting the reference region `"header"` sets its own `aria-pressed="true"`; the candidate's identically-named runtime target `"header"` remains `aria-pressed="false"`; zero `[data-binding-connector]` elements exist. **PASS.**
-- **Reference with no regions/requirements**: honest zero-rectangle SVG plus explicit "No requirements selected on this reference." / "No design requirements selected for this reference." messages - proven with the pre-existing `writeExternalReferencePairFixture`. **PASS.**
-
-## 18. Optional candidate contract context (task §29)
-
-`getReferenceCandidateView` additionally lists every existing `contract-evaluation` artifact whose own persisted `after` reference exactly identifies the selected candidate (same exact-identity comparison Batch 4's `linkedEvidence.ts` uses, applied here independently since this is a *forward* lookup - candidate → evaluations, not evaluation → candidate). Verified with a dedicated unit test (`referenceViewerServer.test.ts`, "never fabricates an evaluation context") that a candidate with zero matching evaluations returns `evaluationHandles: []`. When one or more exist, `ReferenceWorkspace.tsx` requires an explicit `<select>` choice before showing any verdict; `evaluateFrontendContract` is never called - the selected evaluation's own persisted `overallVerdict` is rendered unchanged.
-
-## 19. Binding boundary (task §31/§45/§46)
-
-Grep-verified: `evaluateReferenceRuntimeBindings` is imported/called nowhere under `src/viewerServer/` or `viewer/src/` (only named in `referenceView.ts`'s own doc comment, explaining why it is *not* called). No binding-declaration authoring UI, no connector rendering, no name/geometry/proximity-based inference exists anywhere in this batch's diff.
-
-## 20. Fidelity boundary (task §32/§33/§47/§48)
-
-Grep-verified: `evaluateReferenceCandidateFidelity` is likewise imported/called nowhere in this batch. The UI always shows an explicit, static "Fidelity: not evaluated in this batch — on-demand reference/candidate fidelity evaluation is Batch 6" note beside the compatibility result - a compatibility PASS or an "adequate" reference adequacy status is never rephrased as a fidelity PASS. No pixel-diff/perceptual-hash/OCR/computer-vision mechanism exists anywhere in this batch.
-
-## 21. API changes
-
-| Route | Method | Semantics |
-|---|---|---|
-| `GET /api/references/<handle>/view` | GET/HEAD | `{ok:true, regionRelationships: ReferenceRegionRelationshipGraph \| null, requirementAdequacy: ReferenceRequirementAdequacy \| null}`. `404` unknown handle, `409` not-a-reference/not-currently-loadable, `405` write methods. |
-| `GET /api/references/<handle>/candidate/<handle>/view` | GET/HEAD | `{ok:true, compatibility: ReferenceCandidateCompatibilityResult, evaluationHandles: string[]}`. `404` unknown reference/candidate handle, `409` wrong family/not-currently-loadable, `405` write methods. |
-
-`/api/status`, `/api/index`, `/api/artifacts/<handle>`, `/api/media/<handle>/<role>`, `/api/observations/<handle>/relationships`, `/api/comparisons/<handle>/view`, `/api/evaluations/<handle>/view` are byte-for-byte unchanged.
-
-## 22. PWA cache boundary
-
-**PASS.** Both new routes live under `/api/`, already covered by Batch 1's `navigateFallbackDenylist: [/^\/api\//]`. Verified against the real built `dist/viewer/sw.js` in the built-viewer smoke test (§25): zero occurrences of `api/references`, no second `registerRoute` call.
-
-## 23. Files created
-
-- `src/viewerServer/evidence/referenceView.ts`
-- `viewer/src/components/ReferenceWorkspace.tsx`, `ReferenceRegionOverlaySvg.tsx`, `ReferenceInspector.tsx`
-- `viewer/src/hooks/useReferenceView.ts`
-- `viewer/src/types/reference.ts`
-- `tests/unit/referenceViewerServer.test.ts`
-- `tests/browser/referenceCandidateWorkspace.test.ts`
-- `docs/reports/v0.8-reference-candidate-inspection-batch5.md` (this file)
-
-## 24. Files modified
-
-- `src/viewerServer/httpServer.ts` - added the two new routes (§21); every existing route unchanged.
-- `viewer/src/components/ArtifactPreview.tsx` - added the `external-reference-imported`/`external-reference-approved` branch to `ReferenceWorkspace`; every other family's branching unchanged.
-- `viewer/src/styles/index.css` - additive rules for `.reference-workspace`/`.reference-pane`/`.reference-adequacy`/`.reference-region-overlay-svg__rect--has-requirement`.
-- `tests/support/evidenceFixtures.ts` - added `writeReferenceCandidateFixture` (real imported+approved reference with 2 regions/4 requirements/applicability, plus one real compatible and one real incompatible candidate observation, all built through the real canonical application services - never hand-forged JSON). The pre-existing `writeExternalReferencePairFixture` (Batch 2) was reused unchanged for the no-regions negative case.
-- `docs/ARCHITECTURE.md`, `docs/COMMANDS.md` - new/updated Batch 5 sections.
-
-## 25. Tests added and behavior protected
-
-| Test file | Level | Protects |
-|---|---|---|
-| `referenceViewerServer.test.ts` (11 tests) | unit/integration (real HTTP) | Region-relationship/adequacy derivation via real canonical functions for both imported and approved references; honest `null`/`null` for a reference with no regions/requirements; 409 for a non-reference handle; 404 unknown handle; 405 write methods; real `comparable` compatibility (with real unassessed reasons) for a matching candidate; real `incomparable` compatibility with real `viewport-mismatch`/`theme-mismatch` blocking reasons for a mismatched candidate; zero fabricated evaluation-context handles; 404 unknown candidate; 409 non-observation candidate. |
-| `referenceCandidateWorkspace.test.ts` (6 tests, real Chromium) | browser | Cases A-E per task §51 plus the no-regions honest-empty case (§17). |
-
-## 26. Fixture verification methodology
-
-Before writing browser-test assertions, `writeReferenceCandidateFixture`'s actual output was verified directly against the real `getReferenceView`/`getReferenceCandidateView` server functions in `referenceViewerServer.test.ts` first (unit level, faster iteration) - this is how the initial `follows-vertically` requirement-direction mismatch was caught and fixed (the pairwise derivation loop orders `(subjectRegion, relatedRegion)` by authored-array index, not alphabetically or by geometry-obvious direction; `header` precedes `sidebar` in the array but `verticalSequenceOf` returns `sidebar` as the vertically-later, hence `subjectTarget`, region - the fixture's requirement was corrected to `subjectRegion: 'sidebar', relatedRegion: 'header'` to match the actual canonical derivation, achieving a genuine `adequate` (not `partial`) status). The `writeReferenceCandidateFixture`'s built-in call already asserts nothing on its own; correctness was established entirely by the passing assertions in `referenceViewerServer.test.ts` and the browser test, both of which read real derived output rather than assuming it.
-
-## 27. Validation results
-
-| Command | Result |
-|---|---|
-| `npm run typecheck` | **PASS** (zero errors, both `tsconfig.json` and `viewer/tsconfig.json`) |
-| `npm run lint` | **PASS** (zero errors/warnings) |
-| `npm test` (`vitest run`) | **PASS** — 1112/1112 tests, 61/61 files |
-| `npm run build` | **PASS** — `dist/viewerServer/evidence/referenceView.js` plus the rebuilt `dist/viewer/**` PWA |
-| `npm run check:docs` | **PASS** — "Documentation check passed (17 required files)." |
-| `npm run test:browser` | **PASS** — 147/147 tests, 15/15 files (real Chromium) |
-| `git diff --check` | **PASS** — no whitespace errors (only expected LF→CRLF notices) |
-
-## 28. Built viewer smoke (task §54)
-
-Fixture: one real imported+approved reference pair (2 regions, 4 requirements across all four categories, applicability) and one real compatible + one real incompatible candidate observation, built via `.my-dev-kit-workflow\v0.8\batch-05\tmp\build-smoke-reference.mjs` (not committed) against the actual compiled `dist/artifacts/artifactWriter.js`/`dist/application/externalReferencePersistenceService.js`.
-
-Command: `node dist/cli.js view --root "<WORKFLOW_ROOT>\smoke\evidence-root" --port 4319 --no-open`
-
-All required checks passed against the real running built server:
-
-- `/api/index` → 4 real records (`observation` x2, `external-reference-imported`, `external-reference-approved`), all `supported`.
-- `/api/references/<imported-handle>/view` → `200`, real `regionRelationships` (`horizontally-overlapping`/`above`/`does-not-overlap`/`wider-than`/... /`follows-vertically`) and `requirementAdequacy`.
-- `/api/references/<approved-handle>/candidate/<compatible>/view` → `200`, `compatibility.state:"comparable"`, `evaluationHandles:[]`.
-- `/api/references/<approved-handle>/candidate/<incompatible>/view` → `200`, `compatibility.state:"incomparable"` with real `viewport-mismatch`(1200x800 vs 800x600)/`theme-mismatch`("light" vs "dark") blocking reasons.
-- `/api/media/<imported-handle>/image` → `200 image/png`; `/api/media/<approved-handle>/source-image` → `200 image/png` (resolved through the exact imported source, not a co-located duplicate - confirmed no `reference.png` exists under the approved artifact's own directory, §29 filesystem listing).
-- Unknown reference handle → `404`; write method (`POST`) → `405`.
-- `/` (PWA shell) → `200`; `sw.js` contains zero occurrences of `api/references`.
-- `netstat` confirmed `127.0.0.1:4319` only, never `0.0.0.0`.
-- Server located by its real PID (`2436`) and terminated with `taskkill /F`; a follow-up `netstat` confirmed the port was released.
-
-**Result: PASS.** Logs retained under `$WORKFLOW_ROOT\logs\`.
-
-## 29. Generated path inventory
-
-| Path | Disposition |
-|---|---|
-| `WORKFLOW_ROOT\tmp\build-smoke-reference.mjs` | Retained (dev/readiness tooling only, not committed) |
-| `WORKFLOW_ROOT\smoke\evidence-root` | Retained - listed and confirmed exactly 6 real fixture files (2 observations × manifest+screenshot, 1 imported reference's manifest+image, 1 approved reference's manifest only - **no** second image file under the approved artifact's directory, proving image ownership was never duplicated) |
-| `WORKFLOW_ROOT\logs\*` | Retained (smoke evidence) |
-| `WORKFLOW_ROOT\my-dev-kit-index\*` | Retained (successful index) |
-| `WORKFLOW_ROOT\{cache,fixtures}` | Retained, empty/unused |
-| Repo-root `dist/` | Ordinary build output (gitignored) |
-| Sibling `...my-frontend-observer.my-dev-kit-workflow\v0.8\{batch-01,batch-02,batch-03}` | Untouched (verified, §3) |
-| Inside-repo `.my-dev-kit-workflow\v0.8\batch-04` | Untouched (verified, §3) |
-
-## 30. Repository pollution check
-
-**PASS.** `git status --short` before staging showed only the 6 modified + 8 new Batch-5-owned paths listed in §23/§24. No unexpected file or directory appeared anywhere in the repository. No malformed sibling Batch 5 workflow path exists anywhere under `Z:\Users\newuser\Projects\`.
-
-## 31. Batch 1-4 regression check
-
-**PASS.** All 147 browser tests across all 15 browser test files (Batch 1 PWA/shell, Batch 2 evidence indexing/media, Batch 3 observation SVG workspace, Batch 4 comparison/evaluation workspace, and this batch's own 6 reference/candidate tests) pass unmodified. Zero pre-existing test files were altered this batch (unlike Batch 4, which had to update 2 Batch-2-era tests - no such conflict arose here since Batch 5 only adds a new branch to `ArtifactPreview.tsx` for a family that previously had no visual workspace at all, so no prior assertion about the raw-JSON preview for `external-reference-imported`/`external-reference-approved` existed to become stale).
-
-## 32. v0.1-v0.7 regression check
-
-**PASS.** Every pre-v0.8 unit and browser test suite (`observe`, `compare`, `approve-baseline`, `save-change-contract`, `evaluate-contract`, `import-reference`, `approve-reference`, `evaluate-reference-fidelity`) remains covered and passing - none was touched by this batch's diff. `src/domain/externalReference*.ts` and every existing reader/service (`importExternalReference`, `approveExternalReference`, `evaluateReferenceCandidateCompatibility`, `deriveReferenceRegionRelationships`, `deriveReferenceRequirementAdequacy`) are byte-for-byte unchanged.
-
-## 33. Deviations
-
-- The same `$WORKFLOW_ROOT` path-instruction contradiction as Batch 4 recurred verbatim in this task's §5; resolved identically and for the identical, previously-documented reason (§2 above). No other deviation from the task's literal text.
-
-## 34. Remaining uncovered risks
-
-- **`getReferenceCandidateView`'s evaluation-matching walk is a full bounded re-scan of the evidence tree per request** (same category of finding as Batch 4's linked-evidence walks) - for an evidence root near `MAX_MANIFEST_CANDIDATES`, this is more filesystem work per reference/candidate-view request than a single shared index pass would need. Not a correctness risk.
-- **No explicit reference/candidate cross-selection or binding-driven highlight exists yet** - by design (Batch 6 scope), but a first-time viewer user may reasonably expect clicking a reference region to highlight a candidate target; the current UI relies on the "not evaluated"/independent-selection copy text to communicate this boundary rather than a stronger visual affordance.
-- **The candidate `<select>` list is unbounded by relevance** - every `supported` `observation` record in the evidence root appears, with no viewport/applicability-based pre-filtering (deliberately, per task §22's prohibition on heuristic pre-selection) - for a very large evidence root this could become a long dropdown; not a correctness risk, a possible future usability improvement for Batch 6+.
-- Batches 1-4's previously reported risks (install-prompt "available" branch untested in headless Chromium, no live service-worker execution test, per-request linked-evidence walk cost) remain unresolved and out of this batch's scope.
-
-## 35. Out-of-scope confirmation
-
-Confirmed absent from this batch's diff: explicit reference-region/runtime-target binding interaction, binding authoring UI, binding connectors, on-demand reference-fidelity evaluation, fidelity artifact persistence, candidate/reference delta computation, zoom/pan controls, synchronized/locked views, annotation, graphical region/requirement authoring, contract editing, baseline/reference approval or supersession actions through the viewer, source editing, pixel-difference scoring, computer vision, OCR, image similarity scoring, cloud hosting, database, authentication, collaboration.
-
-## 36. Final verdict
-
-Batch 5 ("External reference and reference/candidate inspection") is implemented and independently validated: a developer can select an existing imported or approved `ExternalReferenceArtifact`, inspect its image in the reference's own pixel coordinate domain with real SVG region overlays, inspect canonical region relationships and selected requirements/tolerances/adequacy/applicability/provenance/lifecycle/supersession exactly as persisted, explicitly select a candidate `ObservationArtifact` (never auto-selected), see the two side by side with the candidate reusing Batch 3/4's exact runtime screenshot/SVG machinery unchanged, see real canonical reference/candidate compatibility (comparable/comparable-with-warnings/incomparable, with honest reasons) via the existing `evaluateReferenceCandidateCompatibility`, and optionally select an exactly-matching existing contract-evaluation context - all while reference-region selection and runtime-target selection remain two independent, never-synchronized domains (proven with a real equal-names Chromium fixture), and while binding evaluation and fidelity evaluation are never invoked anywhere in this batch. No Batch 6 interaction (explicit binding, zoom/pan, conditional lock, on-demand fidelity) was implemented, and no release/publication action was taken. Package version remains `0.7.0`.
+# v0.8 Batch 5 — External Reference and Reference/Candidate Inspection — Implementation Report
+
+## 1. Starting state
+
+- Branch: `master`
+- Starting HEAD: `319b7638d18edfcbba9902c8de7c68a02c377115` ("feat: add v0.8 comparison and contract inspection", Batch 4)
+- `origin/master` after `git fetch`: `a1de8ac01e1367b60021cb04226f56369fa2debb`
+- `git rev-list --left-right --count origin/master...HEAD`: `0  4` — local is exactly Batches 1-4 ahead of origin.
+- `git merge-base --is-ancestor origin/master HEAD` → succeeded (exit 0): origin/master is a strict ancestor of local HEAD, no divergence. No pull/rebase/merge/reset performed.
+- Starting `git status --short`: clean.
+- Package version confirmed `0.7.0` throughout; never bumped.
+
+## 2. The same path contradiction as Batch 4, resolved the same way
+
+Task §5 gave an explicit, executable `Join-Path` algorithm with five verification assertions producing an inside-repository path, then separately restated the old Batches-1-3 sibling directory as the "Required resolved Batch 5 path" - textually inconsistent with its own algorithm (the sibling path fails assertion 1: it does not start with `$REPO_ROOT\`). Re-ran the literal algorithm:
+
+```
+REPO_ROOT=Z:\Users\newuser\Projects\my-frontend-observer
+WORKFLOW_BASE=Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow
+WORKFLOW_VERSION_ROOT=Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8
+WORKFLOW_ROOT=Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8\batch-05
+TestPathRepoRoot=True
+ContainmentCheck=True
+ParentOfBase=Z:\Users\newuser\Projects\my-frontend-observer
+ParentOfRoot=Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8
+```
+
+All required checks pass for the inside-repository path. Per the same precedent established and documented in the Batch 4 report (`docs/reports/v0.8-comparison-contract-inspection-batch4.md` §2) - itself cross-checked against the repository's own `.gitignore` `.my-dev-kit-workflow/` entry, which only makes sense for an inside-repository path - Batch 5 followed the executable algorithm rather than the inconsistent restated sentence, and used **`Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8\batch-05`**.
+
+## 3. Prior workflow-root audit
+
+- Sibling `Z:\Users\newuser\Projects\my-frontend-observer.my-dev-kit-workflow\v0.8\` contains exactly `batch-01`, `batch-02`, `batch-03` - untouched, not migrated, not reused.
+- Inside-repo `.my-dev-kit-workflow\v0.8\` contained `batch-04` (from the prior batch) before this batch started; Batch 5 added only `batch-05` alongside it without touching `batch-04`.
+
+## 4. Predecessor reports/plan inspected
+
+All four predecessor reports read in full (Batch 1-4). `docs/plans/v0.8-implementation-plan.md`'s "Batch 5 — External reference and reference/candidate inspection" section (goal/in-scope/out-of-scope/gate) matches the task's own scope exactly - no material difference found. `docs/ARCHITECTURE.md`, `docs/CONTRACTS.md`, `docs/CURRENT_STATE.md`, `docs/WORKFLOWS.md`, `docs/COMMANDS.md`, `docs/PROJECT_MILESTONES.md` (Milestone 8), `docs/ROADMAP.md` (v0.8), `docs/DOCUMENTATION_PRESERVATION_POLICY.md`, `docs/PROJECT_DESCRIPTION.md` all read/re-confirmed.
+
+## 5. my-dev-kit retrieval
+
+Index built at `$WORKFLOW_ROOT\my-dev-kit-index`. All seven required searches were run; results were cross-checked against direct source reads of `src/domain/externalReference*.ts`, `src/artifacts/externalReferenceArtifactReader.ts`, `src/application/externalReferencePersistenceService.ts`, and `src/viewerServer/evidence/{classify,mediaResolver,index}.ts` - every result matched.
+
+## 6. Pre-edit reference-contract audit (task §10)
+
+Read `src/domain/externalReference.ts`, `externalReferenceRegions.ts`, `externalReferenceRegionRelationships.ts`, `externalReferenceRequirements.ts`, `externalReferenceApplicability.ts`, `externalReferenceCompatibility.ts` in full. Confirmed exactly:
+
+- `ExternalReferenceArtifact = ImportedExternalReferenceArtifact | ApprovedExternalReferenceArtifact` - discriminated by `lifecycle.state`; imported carries `image` and never `sourceReference`; approved carries `sourceReference` and never `image` (`isValidExternalReferenceArtifact` rejects any mix).
+- `regions?: ReferenceRegion[]`, `requirements?: ExternalReferenceRequirement[]`, `applicability?: ExternalReferenceApplicability` are additive/optional on both lifecycle variants, carried forward verbatim by `approveExternalReference` (never re-derived on approval).
+- `ReferenceRegion = {id, rectangle:{x,y,width,height}}` in reference-image pixels; `deriveReferenceRegionGeometry` is the sole pure derivation of `right/bottom/centerX/centerY` - never persisted.
+- `ExternalReferenceRequirement` reuses the exact v0.5 `AuthoredChangeScopeCategory` vocabulary (`requested`/`expected-dependent`/`protected`/`preserved`) - `'unexpected'` is not an authorable member.
+- `evaluateReferenceCandidateCompatibility` is page/state-level only (viewport/theme/applicationState/authenticatedState), reuses `ComparabilityResult`/`assessOptionalComparabilityDimension` from the v0.4 comparison engine verbatim - never a second compatibility model.
+
+## 7. Reference image ownership rule (task §11) - already built in Batch 2, verified, reused unchanged
+
+Read `src/viewerServer/evidence/mediaResolver.ts` in full: role `'image'` requires `family === 'external-reference-imported'`, resolved from that artifact's own directory. Role `'source-image'` requires `family === 'external-reference-approved'`, resolved via `findImportedReferenceDir(root, sourceReference.referenceId)` (`src/viewerServer/evidence/index.ts`) - a bounded exact-`referenceId` walk of the current evidence root, never assuming co-location, never copying bytes. Batch 5 added **zero** changes to `mediaResolver.ts` or `index.ts` - this mechanism already existed and is reused verbatim (confirmed via real Chromium proof, §17 Cases A/B below).
+
+## 8. Reference region coordinate model (task §12/§13)
+
+`ReferenceRegionOverlaySvg.tsx` (new): `viewBox="0 0 <imageWidth> <imageHeight>"` where `imageWidth`/`imageHeight` come from the artifact's own `image.width/height` (imported) or `sourceReference.image.width/height` (approved) - never the candidate's runtime viewport, never devicePixelRatio-multiplied, never normalized to percentages. Each region's canonical `{x,y,width,height}` is rendered unchanged. This is a deliberately distinct, sibling component from `TargetOverlaySvg` (a genuinely different coordinate domain and data source), not a reuse/parameterization of it - reusing that component would have silently conflated reference-image pixels with runtime CSS pixels.
+
+## 9. Reference region selection (task §14/§15)
+
+Region list clicks and SVG rectangle clicks both call the same `setSelectedRegionId` handler in `ReferenceWorkspace.tsx`; selection identity is exact `ReferenceRegion.id` (never a runtime target name). Labels render `region.id` verbatim - no OCR, no computer vision, no name inference. Proven bidirectionally in real Chromium (`referenceCandidateWorkspace.test.ts`, Case A: clicking the SVG rectangle sets `aria-pressed="true"` and the inspector shows "Reference region: header").
+
+## 10. Reference relationships (task §16) - server-side derivation, reused canonical function
+
+`src/viewerServer/evidence/referenceView.ts#getReferenceView` calls the existing canonical `deriveReferenceRegionRelationships` (never a duplicated predicate set, never `deriveLayoutRelationships` over reference regions) over the artifact's own `regions`, exposed via `GET /api/references/<handle>/view`. Only the six geometry-only relationship families it already supports are ever shown; no DOM containment/scroll/visibility is fabricated for a static image.
+
+## 11. Reference requirements / distinction from evidence (task §17/§18)
+
+`ReferenceInspector.tsx` renders each authored `ExternalReferenceRequirement` distinctly from raw region geometry: `requirementId`, `category`, `expectedDependentMode` (when `expected-dependent`), `subject` (region-property/region-relationship/region-measurement), and `tolerance` (exact/absolute-reference-px/percent) are all shown verbatim. A region's own geometry is displayed only under "Reference region: `<id>`" when that region is explicitly selected - it is never presented as an implied requirement. No `'unexpected'` category is ever fabricated (the type does not admit it).
+
+## 12. Reference requirement expectation / adequacy (task §19/§20)
+
+Server-side `deriveReferenceRequirementAdequacy` (existing canonical function, never a competing derivation) computes `status`/`totalRequirements`/`evaluableRequirements`/`reasons` over the artifact's own `regions`+`requirements`, exposed via the same `GET /api/references/<handle>/view` route, rendered under "Reference requirement adequacy" - kept in its own section, visually and semantically distinct from "Reference/candidate compatibility" (task §20's required distinction between reference adequacy and reference/candidate compatibility).
+
+## 13. Reference applicability (task §21)
+
+`ReferenceInspector.tsx` renders `applicability.viewport`/`.theme`/`.applicationState`/`.authenticatedState` exactly as persisted, or "not declared" when absent - never inferred from image pixels, theme is never visually guessed, application/auth state are never inferred from screenshot content.
+
+## 14. Candidate selection (task §22)
+
+`ReferenceWorkspace.tsx` renders a `<select id="reference-candidate-select">` populated from `useEvidenceIndex()`'s `observation`-family, `supported` records only. The initial value is always empty ("(none selected)") - no default candidate is ever pre-selected based on viewport/URL/target-name/timestamp/geometry similarity. Compatibility and side-by-side candidate rendering are gated entirely on `candidateHandle !== undefined`.
+
+## 15. Reference/candidate compatibility (task §23/§24)
+
+`getReferenceCandidateView` (new, `src/viewerServer/evidence/referenceView.ts`) calls the existing canonical `evaluateReferenceCandidateCompatibility(reference, candidate)` unchanged - never reimplemented in React or the viewer server. `comparable`/`comparable-with-warnings`/`incomparable` and each reason's `blocking`/`warning`/`unassessed` severity are rendered exactly as returned (`.comparability-banner--<state>`, reused styling from Batch 4's comparison workspace). An `incomparable` result gets `role="alert"`. No pixel/geometry/fidelity failure is ever fabricated from an incompatible state - the side-by-side panes remain fully inspectable regardless (proven in Case D).
+
+## 16. Side-by-side layout and candidate rendering reuse (task §25/§26)
+
+Default layout is a two-column grid (`.reference-workspace__panes`) - reference pane (image-domain SVG) beside candidate pane. The candidate pane is `ComparisonObservationPane` (Batch 4, unchanged) fed a synthetic `LinkStatus = {status:'resolved', handle: candidateHandle}` once a candidate is explicitly chosen - **zero** new candidate screenshot/coordinate-transform/target-rendering code was written; `TargetOverlaySvg` (Batch 3) renders the runtime viewport/targets exactly as it already did. No blended/alpha image, no pixel-difference heat map.
+
+## 17. Real-browser proof (task §51, all cases)
+
+`tests/browser/referenceCandidateWorkspace.test.ts` - 6 tests, all real Chromium against real canonically-produced fixtures (`writeReferenceCandidateFixture`, built through the real `importExternalReference`/`approveExternalReference`/`writeObservationArtifact` — never hand-forged JSON):
+
+- **Case A (imported)**: real decodable image loads via `/api/media/<handle>/image`; `header`/`sidebar` rectangles render at their exact canonical width/height (400/240); region selection sets `aria-pressed`; lifecycle reads "imported". **PASS.**
+- **Case B (approved)**: image loads via `/api/media/<handle>/source-image`; body text shows "approved (" and "owned by imported source referenceId" - proving the exact-source resolution, never a duplicated image. **PASS.**
+- **Case C (compatible)**: reference and candidate render side by side with distinct viewBoxes (`0 0 400 300` vs `0 0 1200 800`); compatibility banner is `comparable`; the "not evaluated in this batch" fidelity note is present. **PASS.**
+- **Case D (incompatible)**: `comparability-banner--incomparable` with real `viewport-mismatch`/`theme-mismatch` reasons; both panes still render; no "fidelity ... PASS/FAIL" text ever appears. **PASS.**
+- **Case E (equal names, no binding)**: selecting the reference region `"header"` sets its own `aria-pressed="true"`; the candidate's identically-named runtime target `"header"` remains `aria-pressed="false"`; zero `[data-binding-connector]` elements exist. **PASS.**
+- **Reference with no regions/requirements**: honest zero-rectangle SVG plus explicit "No requirements selected on this reference." / "No design requirements selected for this reference." messages - proven with the pre-existing `writeExternalReferencePairFixture`. **PASS.**
+
+## 18. Optional candidate contract context (task §29)
+
+`getReferenceCandidateView` additionally lists every existing `contract-evaluation` artifact whose own persisted `after` reference exactly identifies the selected candidate (same exact-identity comparison Batch 4's `linkedEvidence.ts` uses, applied here independently since this is a *forward* lookup - candidate → evaluations, not evaluation → candidate). Verified with a dedicated unit test (`referenceViewerServer.test.ts`, "never fabricates an evaluation context") that a candidate with zero matching evaluations returns `evaluationHandles: []`. When one or more exist, `ReferenceWorkspace.tsx` requires an explicit `<select>` choice before showing any verdict; `evaluateFrontendContract` is never called - the selected evaluation's own persisted `overallVerdict` is rendered unchanged.
+
+## 19. Binding boundary (task §31/§45/§46)
+
+Grep-verified: `evaluateReferenceRuntimeBindings` is imported/called nowhere under `src/viewerServer/` or `viewer/src/` (only named in `referenceView.ts`'s own doc comment, explaining why it is *not* called). No binding-declaration authoring UI, no connector rendering, no name/geometry/proximity-based inference exists anywhere in this batch's diff.
+
+## 20. Fidelity boundary (task §32/§33/§47/§48)
+
+Grep-verified: `evaluateReferenceCandidateFidelity` is likewise imported/called nowhere in this batch. The UI always shows an explicit, static "Fidelity: not evaluated in this batch — on-demand reference/candidate fidelity evaluation is Batch 6" note beside the compatibility result - a compatibility PASS or an "adequate" reference adequacy status is never rephrased as a fidelity PASS. No pixel-diff/perceptual-hash/OCR/computer-vision mechanism exists anywhere in this batch.
+
+## 21. API changes
+
+| Route | Method | Semantics |
+|---|---|---|
+| `GET /api/references/<handle>/view` | GET/HEAD | `{ok:true, regionRelationships: ReferenceRegionRelationshipGraph \| null, requirementAdequacy: ReferenceRequirementAdequacy \| null}`. `404` unknown handle, `409` not-a-reference/not-currently-loadable, `405` write methods. |
+| `GET /api/references/<handle>/candidate/<handle>/view` | GET/HEAD | `{ok:true, compatibility: ReferenceCandidateCompatibilityResult, evaluationHandles: string[]}`. `404` unknown reference/candidate handle, `409` wrong family/not-currently-loadable, `405` write methods. |
+
+`/api/status`, `/api/index`, `/api/artifacts/<handle>`, `/api/media/<handle>/<role>`, `/api/observations/<handle>/relationships`, `/api/comparisons/<handle>/view`, `/api/evaluations/<handle>/view` are byte-for-byte unchanged.
+
+## 22. PWA cache boundary
+
+**PASS.** Both new routes live under `/api/`, already covered by Batch 1's `navigateFallbackDenylist: [/^\/api\//]`. Verified against the real built `dist/viewer/sw.js` in the built-viewer smoke test (§25): zero occurrences of `api/references`, no second `registerRoute` call.
+
+## 23. Files created
+
+- `src/viewerServer/evidence/referenceView.ts`
+- `viewer/src/components/ReferenceWorkspace.tsx`, `ReferenceRegionOverlaySvg.tsx`, `ReferenceInspector.tsx`
+- `viewer/src/hooks/useReferenceView.ts`
+- `viewer/src/types/reference.ts`
+- `tests/unit/referenceViewerServer.test.ts`
+- `tests/browser/referenceCandidateWorkspace.test.ts`
+- `docs/reports/v0.8-reference-candidate-inspection-batch5.md` (this file)
+
+## 24. Files modified
+
+- `src/viewerServer/httpServer.ts` - added the two new routes (§21); every existing route unchanged.
+- `viewer/src/components/ArtifactPreview.tsx` - added the `external-reference-imported`/`external-reference-approved` branch to `ReferenceWorkspace`; every other family's branching unchanged.
+- `viewer/src/styles/index.css` - additive rules for `.reference-workspace`/`.reference-pane`/`.reference-adequacy`/`.reference-region-overlay-svg__rect--has-requirement`.
+- `tests/support/evidenceFixtures.ts` - added `writeReferenceCandidateFixture` (real imported+approved reference with 2 regions/4 requirements/applicability, plus one real compatible and one real incompatible candidate observation, all built through the real canonical application services - never hand-forged JSON). The pre-existing `writeExternalReferencePairFixture` (Batch 2) was reused unchanged for the no-regions negative case.
+- `docs/ARCHITECTURE.md`, `docs/COMMANDS.md` - new/updated Batch 5 sections.
+
+## 25. Tests added and behavior protected
+
+| Test file | Level | Protects |
+|---|---|---|
+| `referenceViewerServer.test.ts` (11 tests) | unit/integration (real HTTP) | Region-relationship/adequacy derivation via real canonical functions for both imported and approved references; honest `null`/`null` for a reference with no regions/requirements; 409 for a non-reference handle; 404 unknown handle; 405 write methods; real `comparable` compatibility (with real unassessed reasons) for a matching candidate; real `incomparable` compatibility with real `viewport-mismatch`/`theme-mismatch` blocking reasons for a mismatched candidate; zero fabricated evaluation-context handles; 404 unknown candidate; 409 non-observation candidate. |
+| `referenceCandidateWorkspace.test.ts` (6 tests, real Chromium) | browser | Cases A-E per task §51 plus the no-regions honest-empty case (§17). |
+
+## 26. Fixture verification methodology
+
+Before writing browser-test assertions, `writeReferenceCandidateFixture`'s actual output was verified directly against the real `getReferenceView`/`getReferenceCandidateView` server functions in `referenceViewerServer.test.ts` first (unit level, faster iteration) - this is how the initial `follows-vertically` requirement-direction mismatch was caught and fixed (the pairwise derivation loop orders `(subjectRegion, relatedRegion)` by authored-array index, not alphabetically or by geometry-obvious direction; `header` precedes `sidebar` in the array but `verticalSequenceOf` returns `sidebar` as the vertically-later, hence `subjectTarget`, region - the fixture's requirement was corrected to `subjectRegion: 'sidebar', relatedRegion: 'header'` to match the actual canonical derivation, achieving a genuine `adequate` (not `partial`) status). The `writeReferenceCandidateFixture`'s built-in call already asserts nothing on its own; correctness was established entirely by the passing assertions in `referenceViewerServer.test.ts` and the browser test, both of which read real derived output rather than assuming it.
+
+## 27. Validation results
+
+| Command | Result |
+|---|---|
+| `npm run typecheck` | **PASS** (zero errors, both `tsconfig.json` and `viewer/tsconfig.json`) |
+| `npm run lint` | **PASS** (zero errors/warnings) |
+| `npm test` (`vitest run`) | **PASS** — 1112/1112 tests, 61/61 files |
+| `npm run build` | **PASS** — `dist/viewerServer/evidence/referenceView.js` plus the rebuilt `dist/viewer/**` PWA |
+| `npm run check:docs` | **PASS** — "Documentation check passed (17 required files)." |
+| `npm run test:browser` | **PASS** — 147/147 tests, 15/15 files (real Chromium) |
+| `git diff --check` | **PASS** — no whitespace errors (only expected LF→CRLF notices) |
+
+## 28. Built viewer smoke (task §54)
+
+Fixture: one real imported+approved reference pair (2 regions, 4 requirements across all four categories, applicability) and one real compatible + one real incompatible candidate observation, built via `.my-dev-kit-workflow\v0.8\batch-05\tmp\build-smoke-reference.mjs` (not committed) against the actual compiled `dist/artifacts/artifactWriter.js`/`dist/application/externalReferencePersistenceService.js`.
+
+Command: `node dist/cli.js view --root "<WORKFLOW_ROOT>\smoke\evidence-root" --port 4319 --no-open`
+
+All required checks passed against the real running built server:
+
+- `/api/index` → 4 real records (`observation` x2, `external-reference-imported`, `external-reference-approved`), all `supported`.
+- `/api/references/<imported-handle>/view` → `200`, real `regionRelationships` (`horizontally-overlapping`/`above`/`does-not-overlap`/`wider-than`/... /`follows-vertically`) and `requirementAdequacy`.
+- `/api/references/<approved-handle>/candidate/<compatible>/view` → `200`, `compatibility.state:"comparable"`, `evaluationHandles:[]`.
+- `/api/references/<approved-handle>/candidate/<incompatible>/view` → `200`, `compatibility.state:"incomparable"` with real `viewport-mismatch`(1200x800 vs 800x600)/`theme-mismatch`("light" vs "dark") blocking reasons.
+- `/api/media/<imported-handle>/image` → `200 image/png`; `/api/media/<approved-handle>/source-image` → `200 image/png` (resolved through the exact imported source, not a co-located duplicate - confirmed no `reference.png` exists under the approved artifact's own directory, §29 filesystem listing).
+- Unknown reference handle → `404`; write method (`POST`) → `405`.
+- `/` (PWA shell) → `200`; `sw.js` contains zero occurrences of `api/references`.
+- `netstat` confirmed `127.0.0.1:4319` only, never `0.0.0.0`.
+- Server located by its real PID (`2436`) and terminated with `taskkill /F`; a follow-up `netstat` confirmed the port was released.
+
+**Result: PASS.** Logs retained under `$WORKFLOW_ROOT\logs\`.
+
+## 29. Generated path inventory
+
+| Path | Disposition |
+|---|---|
+| `WORKFLOW_ROOT\tmp\build-smoke-reference.mjs` | Retained (dev/readiness tooling only, not committed) |
+| `WORKFLOW_ROOT\smoke\evidence-root` | Retained - listed and confirmed exactly 6 real fixture files (2 observations × manifest+screenshot, 1 imported reference's manifest+image, 1 approved reference's manifest only - **no** second image file under the approved artifact's directory, proving image ownership was never duplicated) |
+| `WORKFLOW_ROOT\logs\*` | Retained (smoke evidence) |
+| `WORKFLOW_ROOT\my-dev-kit-index\*` | Retained (successful index) |
+| `WORKFLOW_ROOT\{cache,fixtures}` | Retained, empty/unused |
+| Repo-root `dist/` | Ordinary build output (gitignored) |
+| Sibling `...my-frontend-observer.my-dev-kit-workflow\v0.8\{batch-01,batch-02,batch-03}` | Untouched (verified, §3) |
+| Inside-repo `.my-dev-kit-workflow\v0.8\batch-04` | Untouched (verified, §3) |
+
+## 30. Repository pollution check
+
+**PASS.** `git status --short` before staging showed only the 6 modified + 8 new Batch-5-owned paths listed in §23/§24. No unexpected file or directory appeared anywhere in the repository. No malformed sibling Batch 5 workflow path exists anywhere under `Z:\Users\newuser\Projects\`.
+
+## 31. Batch 1-4 regression check
+
+**PASS.** All 147 browser tests across all 15 browser test files (Batch 1 PWA/shell, Batch 2 evidence indexing/media, Batch 3 observation SVG workspace, Batch 4 comparison/evaluation workspace, and this batch's own 6 reference/candidate tests) pass unmodified. Zero pre-existing test files were altered this batch (unlike Batch 4, which had to update 2 Batch-2-era tests - no such conflict arose here since Batch 5 only adds a new branch to `ArtifactPreview.tsx` for a family that previously had no visual workspace at all, so no prior assertion about the raw-JSON preview for `external-reference-imported`/`external-reference-approved` existed to become stale).
+
+## 32. v0.1-v0.7 regression check
+
+**PASS.** Every pre-v0.8 unit and browser test suite (`observe`, `compare`, `approve-baseline`, `save-change-contract`, `evaluate-contract`, `import-reference`, `approve-reference`, `evaluate-reference-fidelity`) remains covered and passing - none was touched by this batch's diff. `src/domain/externalReference*.ts` and every existing reader/service (`importExternalReference`, `approveExternalReference`, `evaluateReferenceCandidateCompatibility`, `deriveReferenceRegionRelationships`, `deriveReferenceRequirementAdequacy`) are byte-for-byte unchanged.
+
+## 33. Deviations
+
+- The same `$WORKFLOW_ROOT` path-instruction contradiction as Batch 4 recurred verbatim in this task's §5; resolved identically and for the identical, previously-documented reason (§2 above). No other deviation from the task's literal text.
+
+## 34. Remaining uncovered risks
+
+- **`getReferenceCandidateView`'s evaluation-matching walk is a full bounded re-scan of the evidence tree per request** (same category of finding as Batch 4's linked-evidence walks) - for an evidence root near `MAX_MANIFEST_CANDIDATES`, this is more filesystem work per reference/candidate-view request than a single shared index pass would need. Not a correctness risk.
+- **No explicit reference/candidate cross-selection or binding-driven highlight exists yet** - by design (Batch 6 scope), but a first-time viewer user may reasonably expect clicking a reference region to highlight a candidate target; the current UI relies on the "not evaluated"/independent-selection copy text to communicate this boundary rather than a stronger visual affordance.
+- **The candidate `<select>` list is unbounded by relevance** - every `supported` `observation` record in the evidence root appears, with no viewport/applicability-based pre-filtering (deliberately, per task §22's prohibition on heuristic pre-selection) - for a very large evidence root this could become a long dropdown; not a correctness risk, a possible future usability improvement for Batch 6+.
+- Batches 1-4's previously reported risks (install-prompt "available" branch untested in headless Chromium, no live service-worker execution test, per-request linked-evidence walk cost) remain unresolved and out of this batch's scope.
+
+## 35. Out-of-scope confirmation
+
+Confirmed absent from this batch's diff: explicit reference-region/runtime-target binding interaction, binding authoring UI, binding connectors, on-demand reference-fidelity evaluation, fidelity artifact persistence, candidate/reference delta computation, zoom/pan controls, synchronized/locked views, annotation, graphical region/requirement authoring, contract editing, baseline/reference approval or supersession actions through the viewer, source editing, pixel-difference scoring, computer vision, OCR, image similarity scoring, cloud hosting, database, authentication, collaboration.
+
+## 36. Final verdict
+
+Batch 5 ("External reference and reference/candidate inspection") is implemented and independently validated: a developer can select an existing imported or approved `ExternalReferenceArtifact`, inspect its image in the reference's own pixel coordinate domain with real SVG region overlays, inspect canonical region relationships and selected requirements/tolerances/adequacy/applicability/provenance/lifecycle/supersession exactly as persisted, explicitly select a candidate `ObservationArtifact` (never auto-selected), see the two side by side with the candidate reusing Batch 3/4's exact runtime screenshot/SVG machinery unchanged, see real canonical reference/candidate compatibility (comparable/comparable-with-warnings/incomparable, with honest reasons) via the existing `evaluateReferenceCandidateCompatibility`, and optionally select an exactly-matching existing contract-evaluation context - all while reference-region selection and runtime-target selection remain two independent, never-synchronized domains (proven with a real equal-names Chromium fixture), and while binding evaluation and fidelity evaluation are never invoked anywhere in this batch. No Batch 6 interaction (explicit binding, zoom/pan, conditional lock, on-demand fidelity) was implemented, and no release/publication action was taken. Package version remains `0.7.0`.