@dailephd/my-frontend-observer 0.8.1

package/docs/reports/v0.8-prerelease-readiness-cross-platform-security-code-rot.md

@@ -0,0 +1,687 @@
+# v0.8 Pre-Release Readiness: Cross-Platform, Security, and Code-Rot Audit
+
+## 1. Purpose and scope
+
+This report is the formal pre-release readiness audit for v0.8 (Interactive
+Local Observation Viewer), following the completed and documentation-
+reconciled implementation (Batches 1-8) and its entry-gate audit. This stage
+is **pre-release readiness** - not release preparation, not version bump, not
+publication. Package metadata remains `0.7.0` throughout and at the end of
+this stage.
+
+## 2. Entry gate
+
+Required predecessor report:
+`docs/reports/v0.8-implementation-completeness-documentation-reconciliation.md`
+
+Read in full. Its final verdict is
+`PASS_V08_HARDENED_DOCUMENTATION_AND_IMPLEMENTATION_COMPLETENESS_AUDIT`, its
+batch-gate matrix (§15) shows all 8 batches `Confirmed`/`PASS`, and its
+next-stage decision (§36) is `READY_FOR_V08_PRERELEASE_READINESS`. Entry gate
+satisfied.
+
+## 3. Starting repository state
+
+- Branch: `master`
+- Starting HEAD: `b75a68f0bc4e8d16b582e8aa28aaf831ed496ec1` ("docs: reconcile
+  v0.8 implementation and documentation")
+- `origin/master`: `a1de8ac01e1367b60021cb04226f56369fa2debb`
+- Ahead/behind at start: 9 ahead, 0 behind; `git merge-base --is-ancestor
+  origin/master HEAD` exited 0 (no divergence)
+- `package.json` version / `package-lock.json` version /
+  `package-lock.json` `packages[''].version`: `0.7.0` / `0.7.0` / `0.7.0`
+- Working tree clean
+
+## 4. Workflow filesystem policy
+
+All generated readiness state lives under:
+`.my-dev-kit-workflow/v0.8/prerelease-readiness/` (`tmp/`, `cache/npm/`,
+`logs/`, `audit/`, `security/`, `code-rot/`, `pack/`, `consumer/`,
+`fixtures/`, `smoke/`, `pwa-profile/`, `my-dev-kit-index/`, `ci/`). Nothing
+was written to `C:`, Downloads, a prior batch workflow root, or a sibling
+`my-frontend-observer.my-dev-kit-workflow` directory. Prior workflow roots
+(Batches 1-8, the documentation-reconciliation audit) were inspected but not
+migrated, deleted, or repurposed.
+
+## 5. Readiness architecture audit
+
+Public behavior was traced end to end: CLI command (`observe`, `compare`,
+`approve-baseline`, `save-change-contract`, `evaluate-contract`,
+`import-reference`, `approve-reference`, `evaluate-reference-fidelity`,
+`view`) -> package entry point (`src/cli.ts`) -> domain/application engine ->
+tests -> packed validation. For `view`: `src/viewerServer/viewerService.ts`
+-> `httpServer.ts` route handlers -> `evidence/*` (discovery, classify,
+mediaResolver, observationView, comparisonView, evaluationView,
+referenceView, contextSourceView) -> `viewer/src` React components -> PWA
+service worker (`vite-plugin-pwa`). No gap found between documented public
+behavior and actual implementation. `PASS`.
+
+## 6. Duplicate-engine audit
+
+Checked for a second implementation of each canonical engine named in the
+task (`deriveLayoutRelationships`, `compareObservations`,
+`evaluateFrontendContract`, `evaluateReferenceCandidateCompatibility`,
+`evaluateReferenceRuntimeBindings`, `evaluateReferenceCandidateFidelity`,
+`projectBoundedAgentContext`, `deriveRuntimeStaticCorrelations`). Each has
+exactly one domain-layer definition. `evaluateReferenceCandidateFidelity`
+also has a distinct `evaluateReferenceCandidateFidelityFromArtifactRoots` in
+the application layer - a thin artifact-reading wrapper around the same
+domain function, matching this codebase's established layering (mirrors
+`evaluateAndPersistFromArtifactRoots` elsewhere), not a duplicate
+implementation. `PASS`, no findings.
+
+## 7. `my-dev-kit` retrieval
+
+`npx @dailephd/my-dev-kit@latest index/search` was not available in this
+execution environment (no network path to that package in the sandbox this
+task ran in). Retrieval and architecture mapping were instead performed
+directly against the repository with `git grep`, `Grep`, and manual read-
+through of `src/`, `viewer/src/`, `scripts/`, and `.github/workflows/`,
+covering the same surfaces the mandated searches target (CLI/package
+surface, viewer server/security, canonical engines, PWA, CI, potential rot).
+`MY_DEV_KIT_INDEX`: not produced (tool unavailable); the architecture and
+code-rot audits below are the substitute evidence.
+
+## 8. Baseline local validation (before corrections)
+
+Run against the starting HEAD, in order:
+
+| Command | Result |
+|---|---|
+| `npm run typecheck` | PASS, clean |
+| `npm run lint` | PASS, clean |
+| `npm test` | PASS - 63 files, 1156 tests |
+| `npm run build` | PASS |
+| `npm run check:docs` | PASS - 17 required files |
+| `npm run test:browser` | PASS, but one test (`referenceBindingFidelityWorkspace.test.ts`) failed reproducibly on reruns under full-suite parallel load (see §14, Flakes) |
+| `npm run test:security` | PASS, but scope gap identified (see §9) |
+
+## 9. v0.8 cross-platform packed-viewer readiness gap (found and closed)
+
+`.github/workflows/pre-release-readiness.yml`'s matrix job ran only
+`scripts/ci/runPackedObservationSmoke.mjs` - installed-tarball proof of
+`observe`/`compare` only, never the v0.8 viewer. `npm run test:security`
+covered only `tests/unit/policy.test.ts` +
+`tests/browser/chromiumAdapter.test.ts` (pre-v0.8 browser-navigation
+policy) - none of the viewer/evidence-server security surface.
+
+`CI_READINESS_GAP_FOUND: YES`. Closed by:
+
+- **`scripts/ci/runPackedViewerSmoke.mjs`** (new): installs the exact
+  candidate tarball into a clean consumer, builds real evidence (one
+  observation with two resolved targets, one imported external reference
+  with a region, one approved reference) entirely through the installed
+  CLI, builds a real `BoundedAgentContextArtifact` through the installed
+  package's exported `projectBoundedAgentContext` (never hand-edited),
+  starts the installed `view` command with `--bindings-file` and
+  `--context-file`, and in real Chromium proves: loopback-only binding;
+  read-only API (`POST`/`PUT`/`PATCH`/`DELETE` -> 405 on every route);
+  `/api/status` and `/api/index`; encoded-path-traversal rejection against
+  both the media route and the asset-fallback route; the SVG target overlay
+  renders against real media; the reference view renders; no page-level
+  fatal error; service-worker registration/activation; the PWA manifest
+  (`standalone` display); the API-never-cached-as-authoritative boundary
+  (`caches.keys()`/`cache.keys()` inspected directly); and the hard
+  server-down stale-evidence gate (kill the viewer process, reload, confirm
+  `/api/index` is unreachable rather than silently serving prior data).
+  Readiness/CI infrastructure only - listed under neither `package.json`
+  `files` nor referenced by any shipped `dist` output.
+- Wired into `pre-release-readiness.yml`'s existing matrix step sequence,
+  immediately after the pre-existing observation smoke, preserving that
+  step unchanged and using the same downloaded/verified candidate tarball.
+- `npm run test:security` expanded to also run
+  `tests/unit/viewerServer.test.ts`, `viewerEvidenceServer.test.ts`,
+  `referenceViewerServer.test.ts`, `contextViewerServer.test.ts`,
+  `paths.test.ts`, `evidenceDiscovery.test.ts`, and
+  `tests/browser/pwaHardening.test.ts` (all pre-existing coverage that
+  simply wasn't wired into this script before).
+
+`CI_CHANGES`: `.github/workflows/pre-release-readiness.yml` (added one step
++ one artifact-upload path, matrix architecture unchanged - still exactly
+one candidate tarball built once, verified by SHA-256 on every runner, no
+platform packs its own); `package.json` `test:security` script expanded.
+
+## 10. Security audit
+
+### 10.1 A confirmed, fixed finding: symlinked media file escape
+
+**SEC-1 (CRITICAL, fixed).** `src/viewerServer/evidence/mediaResolver.ts`'s
+`checkExists()` used `fs.stat()`, which follows symlinks. The upstream
+containment check (`resolveContainedFile`) only proves the *filename* is a
+safe bare name inside an already-contained artifact directory - it never
+proves that filename isn't itself a symlink/junction whose target resolves
+outside the evidence root. A crafted evidence directory containing, e.g., a
+`screenshot.png` that is actually a symlink to an arbitrary file elsewhere on
+disk would have that file's real content served through
+`/api/media/<handle>/screenshot`.
+
+This was undetectable on the Windows development machine this repository's
+Batches 1-8 and the entry-gate audit were built on (creating a file symlink
+there requires a privilege this account lacks - confirmed `EPERM`), which is
+exactly why the entry-gate report (§35) carried it forward as an untested
+risk rather than a resolved one. A new regression test
+(`tests/unit/viewerEvidenceServer.test.ts`, "a media filename that is itself
+a symlink/junction...") creates such a symlink and asserts the linked
+content is never served; it no-ops (with an explicit `EPERM`/`ENOSYS`
+assertion) where symlink creation isn't permitted, and ran for real on the
+Linux CI matrix job, where it caught the vulnerability on the first CI run
+of the un-fixed candidate.
+
+**Fix**: `checkExists()` now uses `fs.lstat()` and rejects any entry that
+isn't `isFile()` - a symlink's `lstat().isFile()` is `false`, so the media
+route now refuses to serve through a symlinked filename at all, closing the
+escape without weakening any legitimate behavior. Verified: the regression
+test passed on the Linux and macOS matrix runners in the corrected candidate
+CI run (see §13); Windows still no-ops on this specific test (symlink
+creation unsupported for this account) but the fix itself is
+platform-agnostic (`lstat` behaves identically everywhere) and the
+Windows-specific traversal/absolute-path tests in the same file continue to
+pass.
+
+### 10.2 Loopback network security
+
+`src/viewerServer/httpServer.ts`'s server is created via plain
+`node:http.createServer` and bound explicitly to `127.0.0.1` by
+`viewerService.ts`/`port.ts` (never `0.0.0.0`, `::`, or a LAN address).
+Verified by live listener behavior, not source inspection alone: both the
+local packed-viewer smoke and the CI packed-viewer smoke (all three
+platforms) assert `viewerUrl.startsWith('http://127.0.0.1:')` against the
+actual bound socket address. `tests/unit/viewerServer.test.ts` additionally
+asserts the reported URL and default-host behavior directly. `PASS`.
+
+### 10.3 Observer/browser security regression (pre-existing, re-verified)
+
+`npm run test:security` (expanded, see §9) reruns `policy.test.ts` (http/
+https-only, loopback-only, credential-bearing-URL rejection) and
+`chromiumAdapter.test.ts` (redirect/subresource/popup/download/timeout/
+cleanup/target-immutability behavior) unchanged. Both pass. No weakening of
+existing security behavior was made to accommodate viewer work. `PASS`.
+
+### 10.4 Viewer filesystem boundary
+
+Re-proven via `tests/unit/viewerEvidenceServer.test.ts` and
+`tests/unit/viewerServer.test.ts`: evidence-root containment (`../`
+rejection, encoded-`../` rejection, absolute Windows-path rejection,
+absolute POSIX-path rejection, unknown-handle rejection, no generic
+file-server behavior for repository/source files), plus the new
+symlink/junction-escape regression from §10.1. `SYMLINK_JUNCTION_SECURITY`:
+`PASS` (Linux/macOS CI, real symlink), `NOT_SUPPORTED_ON_CURRENT_LOCAL_PLATFORM`
+(this Windows dev machine's account). `PASS` overall.
+
+### 10.5 `EvidenceReference`/static-candidate non-path semantics
+
+`EvidenceReference.path` values and `file:...`/`symbol:...` static
+correlation candidate ids are only ever used as opaque display/provenance
+strings in `viewer/src` and `src/domain/*` - grepped for any
+`fs.`/`open`/`require`/dynamic-import use of these fields; none found. They
+are never resolved as filesystem paths, URLs, shell input, or source-open
+targets. `PASS`.
+
+### 10.6 `--bindings-file` / `--context-file` security
+
+Both are explicit local CLI inputs read once at startup
+(`loadBindingsFile`/`loadContextFile` in `src/cli.ts`), parsed as JSON,
+structurally validated (`isValidBoundedAgentContextArtifact` for context;
+the bindings wrapper shape for bindings), held only in server memory
+(`ViewerServerState`), never persisted, never rewritten, and never exposed
+as a browser-controllable path - no `/api/` route accepts a replacement file
+path for either. Confirmed live in the packed-viewer smoke (both flags
+accepted, both file contents reflected only through their respective `/api/`
+views). `PASS`.
+
+### 10.7 Dynamic code/command execution audit
+
+`git grep` for `eval(`, `new Function(`, `vm.`, `child_process`, `exec(`,
+`execFile(`, `spawn(`, `shell:\s*true` across `src/`, `viewer/`, `scripts/`,
+`tests/`:
+
+- `src/viewerServer/openBrowser.ts` uses `child_process.spawn()` with a
+  fixed command (`cmd`/`open`/`xdg-open`) and an args array containing only
+  the viewer's own constructed loopback URL - never evidence- or
+  user-controlled input, no shell. Best-effort convenience only (failure is
+  non-fatal). **Not security-critical.**
+- `scripts/ci/*.mjs`, `scripts/dev/*.mjs`, and `tests/browser/*.test.ts` use
+  `child_process.spawn`/`execFileSync` with fixed commands/args
+  (`npm`/`npx`/`node`) for build/test orchestration only - readiness/dev/test
+  infrastructure, never shipped in the package (`files` allowlist), never
+  fed attacker- or evidence-controlled strings. **Dev/test-only exposure,
+  non-blocking.**
+- All other `.exec(` matches are `RegExp.prototype.exec` (false positives
+  of the grep pattern), not code execution.
+
+No production/runtime code path allows evidence, request, or reference
+content to become executable code or shell command text. `PASS`.
+
+### 10.8 CORS/origin audit
+
+No `Access-Control-Allow-Origin` (or any other CORS) header is set anywhere
+in `httpServer.ts` - confirmed by direct grep of every `writeHead` call
+site. The viewer relies entirely on the browser's same-origin policy against
+its own loopback origin. `PASS`.
+
+### 10.9 Security headers
+
+`httpServer.ts` sets `content-type` and `cache-control: no-store` on every
+dynamic response, and `content-type`/`content-length`/`cache-control` on
+media/asset responses, but sets no `X-Content-Type-Options`,
+`Content-Security-Policy`, or frame-embedding header. Given this is a
+strictly loopback-only server serving only its own built assets (no
+third-party content, no user-supplied HTML rendering, no cross-origin
+exposure per §10.8), this is a low-risk gap, not an exploitable one.
+**Deferred, non-blocking**: adding `X-Content-Type-Options: nosniff` (and
+possibly a same-origin-only CSP) would be a reasonable focused addition for
+a future hardening pass, but is not required for this stage's PASS and was
+not added here to keep this stage's change surface narrow. `SECURITY_HEADER_AUDIT`:
+justified current state (no critical/high gap; low-risk item recorded for
+follow-up).
+
+### 10.10 Read-only API audit
+
+Every `/api/*` route is reached through one shared method gate at the very
+top of `handleRequest()`: any method other than `GET`/`HEAD` returns `405`
+with `Allow: GET, HEAD` before any route-specific logic runs. This was
+verified directly (not just by source inspection) against every route
+family via the packed-viewer smoke's read-only-API loop
+(`POST`/`PUT`/`PATCH`/`DELETE` against `/api/status`, all returning `405`)
+and via `tests/unit/viewerServer.test.ts`/`viewerEvidenceServer.test.ts`'s
+explicit write-method-rejection tests. No route mutates evidence; there is
+no write path anywhere in the viewer server. `PASS`.
+
+| Route | Methods | Input source | Mutation |
+|---|---|---|---|
+| `/api/status` | GET/HEAD | none | none |
+| `/api/index` | GET/HEAD | evidence root (read) | none |
+| `/api/artifacts/:handle` | GET/HEAD | opaque handle | none |
+| `/api/media/:handle/:role` | GET/HEAD | opaque handle+role | none |
+| `/api/observations/:handle/relationships` | GET/HEAD | opaque handle | none |
+| `/api/comparisons/:handle/view` | GET/HEAD | opaque handle | none |
+| `/api/evaluations/:handle/view` | GET/HEAD | opaque handle | none |
+| `/api/references/:handle/view` | GET/HEAD | opaque handle | none |
+| `/api/references/:ref/candidate/:cand/view` | GET/HEAD | opaque handles | none |
+| `/api/references/:ref/candidate/:cand/bindings` | GET/HEAD | opaque handles + session bindings | none |
+| `/api/references/:ref/candidate/:cand/fidelity` | GET/HEAD | opaque handles + session bindings | none |
+| `/api/context` | GET/HEAD | session context state | none |
+
+### 10.11 PWA cache-storage boundary
+
+`tests/browser/pwaHardening.test.ts` (real service worker, real Chromium)
+and the packed-viewer smoke (direct `caches.keys()`/`cache.keys()`
+inspection after real `/api/status` and `/api/index` fetches) both confirm
+no `/api/*` response - status, index, artifact JSON, media, bindings,
+fidelity, or context - is ever present in service-worker cache storage.
+`vite.config.ts`'s workbox config declares zero `runtimeCaching` rules and
+denylists `/^\/api\//` from the navigation fallback. `PASS`.
+
+### 10.12 Server-down stale-evidence hard gate
+
+Repeated in both `pwaHardening.test.ts` (source-checkout, all platforms via
+`npm run test:security`) and the new packed-viewer smoke (installed
+candidate, all three CI platforms): start viewer -> load evidence -> service
+worker active -> kill the server process -> reload the cached shell ->
+`/api/index` unreachable -> no stale evidence presented as current.
+`SERVER_DOWN_STALE_EVIDENCE: PASS` on Windows, Linux, and macOS against the
+exact same candidate tarball (see §13).
+
+### 10.13 Package path/privacy audit
+
+Grepped persisted-manifest and viewer-response code paths for
+`bindingsFilePath`/`contextFilePath`/`targetsFilePath`/
+`scrollScenarioFilePath`/`WORKFLOW_ROOT`/consumer-install-path/npm-cache-path
+leakage. `runPackedObservationSmoke.mjs`'s existing assertions already
+proved targets-file/scroll-scenario-file paths never leak into persisted
+manifests; the same discipline holds for the viewer (bindings/context file
+paths are read once at CLI startup and never attached to any `/api/`
+response body - confirmed by reading `httpServer.ts`'s response payloads,
+none of which include the file-path fields at all). `PASS`.
+
+### 10.14 Secret/credential audit
+
+`git ls-files` shows no `.env`, `.pem`, `.key`, or `id_rsa*` files tracked.
+`git grep` (case-insensitive) for private-key headers, and
+`api_key`/`password`/`secret` literal-assignment patterns across tracked
+source (excluding markdown and the lockfile) returned zero matches.
+`.gitignore` already excludes `.my-dev-kit-workflow/`, `node_modules/`,
+`dist/`, `*.tgz`. `PASS`.
+
+### 10.15 Dependency security audit
+
+`npm audit --json` (all) and `npm audit --omit=dev --json` (runtime only)
+were run before and after remediation:
+
+| | Before | After |
+|---|---|---|
+| `npm audit` (all) | 2 moderate (both `vitest`/`@vitest/mocker`, path-traversal-in-mock-redirect) | **0** |
+| `npm audit --omit=dev` (runtime) | 0 | 0 |
+
+The runtime dependency tree (`playwright` is the only production
+dependency) had zero findings throughout. The two moderate findings were
+dev-only (`vitest`), with a compatible non-major fix available
+(`vitest@4.1.11`). Applied (`npm install vitest@4.1.11 --save-exact`); full
+local validation reran clean afterward (§12); no public contract changed.
+Raw audit JSON stored under `.my-dev-kit-workflow/v0.8/prerelease-readiness/security/`.
+
+**`BLOCKING_SECURITY_FINDINGS`: NONE** (SEC-1 above was found and fixed
+within this stage, before candidate freeze; it is not an unresolved
+blocker).
+
+## 11. Dependency freshness (code-rot: `STALE_DEPENDENCY`)
+
+`npm outdated --json`, classified:
+
+| Package | Current -> Latest | Classification |
+|---|---|---|
+| `vitest` | 4.1.11 (patched) -> 5.0.0 | Major; `LOW_RISK_STALE`, deferred (no security requirement beyond the patch already applied; a major bump is out of this stage's narrow-hardening scope) |
+| `playwright` (runtime dep) | 1.62.1 -> 1.63.0 | Minor, same declared range (`^1.62.1`); `npm audit --omit=dev` clean; `LOW_RISK_STALE`, deferred (no forcing security issue) |
+| `react`, `react-dom` | 19.2.8 -> 19.3.0 | Minor; `LOW_RISK_STALE`, deferred |
+| `vite` | 8.2.2 -> 8.3.0 | Minor; `LOW_RISK_STALE`, deferred |
+| `eslint`, `typescript-eslint` | minor version behind | `LOW_RISK_STALE`, deferred |
+| `typescript` | 6.0.3 -> 7.0.2 | Major; `LOW_RISK_STALE`, deferred (a major TS upgrade is explicitly out of this stage's scope per task §43/100) |
+
+No dependency is unsupported/EOL for its declared environment.
+`UNSUPPORTED_EOL_DEPENDENCIES: NONE`. No further updates were made beyond
+the security-driven `vitest` patch, per the "do not churn dependencies for
+cosmetic freshness" instruction.
+
+## 12. Node engine / compatibility
+
+`package.json` `engines.node`: `>=24`. This machine and the CI candidate job
+both resolved Node `v24.11.0`/`24` respectively (CI: exact `node --version`
+recorded per job, see §13's table). `MINIMUM_SUPPORTED_NODE_TEST: PASS`
+(Node 24, the declared minimum, is what the existing CI matrix already
+runs - `.github/workflows/pre-release-readiness.yml` pins `node-version:
+'24'` throughout). The existing CI workflow does not additionally test a
+newer floating Node line; adding one was not done in this stage to avoid
+CI-architecture changes beyond the packed-viewer-smoke gap this stage was
+scoped to close (task §98 forbids matrix redesign). `CURRENT_NODE_COMPATIBILITY:
+NOT_REQUIRED` (not exercised beyond the declared minimum in this stage).
+
+## 13. Cross-platform CI validation
+
+Two candidate cycles ran (within the task's two-correction-cycle limit):
+
+### 13.1 Cycle 1 - `55299e5` (initial candidate)
+
+Pushed to `validation/v0.8-pre-release-readiness`, triggering run
+[`34503201007`](https://github.com/dailephd/my-frontend-observer/actions/runs/34503201007).
+**Result: FAILED at the candidate job** (`npm test`), before any tarball was
+built or any matrix runner started (matrix job correctly skipped - no
+platform built its own candidate).
+
+Two real failures, both invisible on this session's Windows development
+machine:
+
+1. The new symlink-escape regression test (§10.1) failed on Linux - it
+   *should* fail against the un-fixed `mediaResolver.ts`; this is exactly
+   the vulnerability being proven, not a test defect.
+2. `tests/unit/viewerPwaBuild.test.ts`'s denylist-pattern assertion failed
+   against an unminified `sw.js`/~2x-larger JS bundle. Root-caused to ten
+   test files' `beforeAll` build-fallback hooks (`if (!existsSync(dist))
+   execFileSync('npx', ['vite','build',...], { env: {...process.env} })`)
+   inheriting vitest's own `NODE_ENV=test` into the child build process.
+   This fallback path had never actually executed end-to-end in any prior
+   local session (`dist/` always pre-existed locally from an earlier
+   `npm run build`), so it silently carried this latent defect until a
+   genuinely fresh CI checkout exercised it for the first time.
+
+Classified: **(1) security defect** (the exact gap this test suite exists
+to close) and **(2) reproducible product/test-infrastructure defect** - not
+flakes (see §14 for the actual flakes found and their evidence), not
+infrastructure/platform unavailability. Both are `NEEDS_CORRECTION`-class
+findings that were corrected within this stage's allowed retry budget.
+
+### 13.2 Correction
+
+- `src/viewerServer/evidence/mediaResolver.ts`: `stat` -> `lstat`, reject
+  non-regular-file entries (§10.1).
+- All ten `beforeAll` build-fallback hooks: added explicit
+  `NODE_ENV: 'production'` to the spawned `vite build`'s `env`.
+- `tests/unit/viewerPwaBuild.test.ts`: relaxed the denylist-pattern regex to
+  tolerate minifier whitespace variation without weakening the semantic
+  assertion (the literal `/^\/api\//` denylist source must still be
+  present).
+
+Full local validation reran clean (typecheck, lint, 1157 unit tests, build,
+docs check, 178 browser tests, expanded security suite - see §14 for one
+genuine local-only flake found and fixed along the way). Local packed-viewer
+smoke rerun against a freshly rebuilt local tarball: `PASS`.
+
+Committed as `d8eb0fc2b652ecf05a8c778b7ab5f1c32c18a3e9`
+("fix: harden v0.8 pre-release security and build reproducibility").
+`validation/v0.8-pre-release-readiness` fast-forwarded and pushed.
+
+### 13.3 Cycle 2 - `d8eb0fc` (corrected candidate) - PASS
+
+Run
+[`34504220423`](https://github.com/dailephd/my-frontend-observer/actions/runs/34504220423),
+head SHA `d8eb0fc2b652ecf05a8c778b7ab5f1c32c18a3e9` (verified to match the
+validated candidate commit). **Conclusion: `success`.**
+
+| Job | Conclusion |
+|---|---|
+| Package exact candidate (Linux, Node 24) | success (typecheck, lint, 1157 unit tests, 178 browser tests, expanded security suite, build, docs check, pack, SHA-256, upload - all steps green) |
+| `ubuntu-latest` exact-candidate smoke | success |
+| `macos-latest` exact-candidate smoke | success |
+| `windows-latest` exact-candidate smoke | success |
+
+Exactly one `candidate-package` artifact was uploaded (no duplicate/
+independently-packed candidates), plus one `smoke-summary-<os>` artifact per
+platform. Downloaded and inspected all four.
+
+**Candidate tarball**: `my-frontend-observer-0.7.0.tgz`
+**Candidate SHA-256** (as recorded by the candidate job and independently
+recomputed locally after download - identical):
+`b80729bc64b3b01378effd2b8aa3b7743ccedc46b3148ba0b1ff1ae5a4b68c55`
+
+| Platform | Node version | Packed observation smoke | Packed viewer smoke | PWA/browser proof |
+|---|---|---|---|---|
+| Windows | v24.19.0 | PASS | PASS | PASS |
+| Linux | v24.20.0 | PASS | PASS | PASS |
+| macOS (arm64) | v24.20.0 | PASS | PASS | PASS |
+
+Each platform's `viewer-smoke-summary.json` independently confirms:
+`packageVersion: "0.7.0"`, loopback `viewerUrl`, `readOnlyApiOk`,
+`traversalRejected`, `svgOverlayRendered`, `screenshotMediaLoaded`,
+`referenceViewRendered`, `noPageErrors`, `serviceWorkerRegistered`,
+`pwaManifestOk`, `apiNeverCached`, `serverDownStaleEvidenceGatePassed`, all
+`true`, `result: "PASS"` - the exact same candidate tarball on all three
+operating systems. Each platform's `smoke-summary.json` (pre-existing
+observation/compare smoke) likewise shows `comparableCompareOk`,
+`comparisonPathPrivacyPassed`, and `v05HelpCommandsExposed` all `true` -
+pre-v0.8 packed workflows remain valid on the same candidate.
+
+**`ACTUAL_OS_PWA_INSTALLATION_AUTOMATED: NO`** - each platform's smoke
+proves manifest reachability, service-worker registration/activation, and
+the cache-storage boundary at the browser level (real Chromium via
+Playwright); none of the three CI runners attempt an actual OS-level "Add to
+Home Screen"/installed-app launch, matching the entry-gate report's
+already-documented boundary (browser-level CDP proof, not genuine platform
+install).
+
+**Cross-platform filesystem behavior**: the packed-viewer smoke exercises
+evidence-root resolution, media-path handling, `--bindings-file`/
+`--context-file` input, and traversal rejection identically on Windows and
+POSIX runners via the same script logic (no OS-conditional assumptions in
+`scripts/ci/runPackedViewerSmoke.mjs`); all three passed. `PASS`.
+
+## 14. Flakes
+
+One genuine, evidence-backed local flake was found and fixed (not left
+undiagnosed):
+
+**`referenceBindingFidelityWorkspace.test.ts`** ("lock is also disabled for
+a compatible-but-incoherent-aspect-ratio pair"): failed reproducibly on full
+local `npm run test:browser` reruns (2 of the first 3 runs, under this
+session's Windows machine's parallel-Chromium resource contention), passed
+every time in isolation. Root cause: it asserted on `body` text immediately
+after `expect.poll(() => lockButton.isEnabled()).toBe(false)` resolved - but
+the button is *also* disabled while compatibility is still asynchronously
+evaluating ("Evaluating compatibility..."), before the real settled reason
+text appears. Fixed by polling the settled body text itself
+(`expect.poll(() => page.textContent('body'), {...}).toContain(...)`)
+instead of a single post-poll read. Verified stable across three subsequent
+clean full-suite reruns (both default and reduced-worker-count local runs),
+and passed on all three CI platforms in the final candidate run.
+
+No other flake was observed or is being carried forward undiagnosed. The two
+Cycle-1 failures (§13.1) were **not** flakes - both were reproducible,
+root-caused, and fixed as real defects, per the task's flake-policy
+distinction (a failure classified as a flake requires no deterministic
+defect being found; both of those had one).
+
+## 15. Code-rot audit
+
+### 15.1 Search sweep
+
+`git grep` across `src/`, `viewer/`, `scripts/` for
+`TODO|FIXME|HACK|XXX|TEMPORARY|REMOVE AFTER|DEPRECATED|deprecated`: **zero
+matches.** Across `tests/` for
+`test\.skip|describe\.skip|it\.skip|test\.only|describe\.only|it\.only`:
+**zero matches.** Across `src/`/`viewer/` for
+`placeholder|legacy|compatibility shim|temporary workaround`
+(case-insensitive): all matches are either (a) genuine, intentional
+empty/loading-state UI text (the `.placeholder-note` CSS class used
+throughout `viewer/src/components/*` for honest "No X recorded"/"Loading…"
+states - not stale scaffolding, a consistent and still-current design
+pattern), or (b) one doc-comment use of "legacy" correctly describing the
+CSS-shorthand `--target` flag's continued-support status relative to the
+canonical `--targets-file`/`locators` shape - accurate, not stale.
+
+### 15.2 Findings ledger
+
+| ID | Category | File/path | Evidence | Risk | Disposition | Change made | Tests | Blocking |
+|---|---|---|---|---|---|---|---|---|
+| ROT-1 | `STALE_PLACEHOLDER` | `viewer/src/components/ArtifactPreview.tsx:25` | The empty-selection message read "No observation, comparison, contract, or reference viewing is implemented yet" - false since Batches 3-5 shipped exactly those workspaces (imported and rendered two lines below in the same file) | Low (user-visible, misleading) | `CORRECT` | Message simplified to "Select evidence from the list to load it on demand."; the one test asserting the stale string (`viewerShell.test.ts`) updated to match | `tests/browser/viewerShell.test.ts` reruns green | Non-blocking (readiness-narrow doc/text fix) |
+| ROT-2 | `STALE_TEST` (over-fit assertion) | `tests/unit/viewerPwaBuild.test.ts:63` | Regex asserted on exact minified-output whitespace (`denylist:[/^\/api\//]`), fragile against minifier-environment variation | Low (test robustness, not product) | `CORRECT` | Regex relaxed to tolerate whitespace while preserving the semantic assertion | Green on Windows and CI Linux | Non-blocking |
+| ROT-3 | `OBSOLETE_SCRIPT` (candidate, not acted on) | `scripts/dev/*.mjs` (5 files) | Not referenced by any `package.json` script name; manual dev-invocation only | Low | `KEEP_WITH_JUSTIFICATION` - each is a distinct manual dev smoke (compare, frontend-contracts unit+browser, scroll-scenario, targets-file) with no newer script providing equivalent coverage; not proven dead | None | N/A | Non-blocking |
+| ROT-4 | `DEAD_CODE` (checked, none found) | repository-wide `src/**/*.ts` | Every non-test `.ts` file under `src/` has at least one cross-reference from `src/`, `viewer/`, `tests/`, or `scripts/` (checked via basename cross-reference sweep) | N/A | N/A - no finding | None | N/A | N/A |
+| ROT-5 | `DUPLICATE_IMPLEMENTATION` (checked, none found) | canonical engines (§6) | One definition each; the one apparent second `evaluateReferenceCandidateFidelity*` match is a legitimate application-layer artifact-reading wrapper, not a duplicate | N/A | N/A - no finding | None | N/A | N/A |
+| ROT-6 | `UNUSED_DEPENDENCY` (checked, none found) | `package.json` deps/devDeps | Every declared dependency has at least one config/source/tooling reference (`vite`: 95 files via config+build; `vitest`: 91 files; `playwright`: 20 files including production `src/browser/chromiumAdapter.ts`; all others similarly referenced) | N/A | N/A - no finding | None | N/A | N/A |
+| ROT-7 | `STALE_CONFIG` (checked, none found) | `tsconfig.json`, `viewer/tsconfig.json`, `eslint.config.js` | `include`/`exclude` globs match only current, existing paths; no reference to a deleted directory | N/A | N/A - no finding | None | N/A | N/A |
+
+No `TODO_FIXME_FINDINGS`, no `SKIPPED_DISABLED_TEST_FINDINGS`, no
+`UNUSED_EXPORT_FINDINGS` beyond what's already covered by ROT-4/ROT-6.
+`CODE_ROT_BLOCKERS: NONE`.
+
+### 15.3 Package/build/export audit
+
+Clean-build proof: `rm -rf node_modules && npm ci && npm run build`
+(prebuild's `scripts/clean.mjs` removes stale `dist` first, non-destructively
+- no Git-level cleanup used) produced the same `dist/cli.js`, `dist/index.js`
+(both referenced correctly by `package.json` `bin`/`exports`),
+`dist/viewerServer/**`, and `dist/viewer/**` (PWA manifest/service
+worker/icons) confirmed present in both `npm pack --dry-run --json` and the
+actual packed tarball (see §16). No obsolete path in `files`/`bin`/
+`exports`. `PASS`.
+
+## 16. Package audit
+
+### 16.1 Local dry-run and content audit
+
+`npm pack --dry-run --json`: 285 files, ~3.0 MB unpacked. Inspected the full
+file list: required v0.8 assets present (`dist/cli.js`, `dist/index.js`,
+`dist/viewerServer/**`, `dist/viewer/**` including
+`manifest.webmanifest`/`sw.js`/icons). No accidental content: zero matches
+for `.my-dev-kit-workflow`, tarballs, logs, smoke data, browser profiles,
+temporary binding/context files, coverage output, Git metadata, or local
+caches. `docs/` (all `docs/*.md` including `docs/reports/*`) is intentionally
+shipped per the pre-existing `files: ["dist", "README.md", "CHANGELOG.md",
+"docs"]` allowlist - carried unchanged from v0.7, not a v0.8-introduced
+defect. `UNEXPECTED_PACKED_FILES: NONE`. `PACKAGE_DRY_RUN: PASS`,
+`PACKAGE_CONTENT_AUDIT: PASS`, `REQUIRED_VIEWER_PACKAGE_ASSETS: PASS`.
+
+### 16.2 Local actual tarball smoke
+
+Built at `.my-dev-kit-workflow/v0.8/prerelease-readiness/pack/`
+(`npm pack` with explicit destination `cwd`). SHA-256 (pre-correction
+candidate, superseded by the CI-authoritative hash in §13.3 after the
+correction commit):
+`c5dfb7f93ddc90b984e22b2cae03e36c9bfe96d6875812f238b2c02b3291978a` (initial);
+recomputed after the security/build-reproducibility fix and reran the local
+packed-viewer smoke clean (§13.2). Installed into
+`.my-dev-kit-workflow/v0.8/prerelease-readiness/consumer/` via
+`scripts/ci/runPackedViewerSmoke.mjs` itself (which performs this install/
+verify/run sequence): package identity, `bin`, `dist/viewer/**` all
+resolved correctly from the consumer's own `node_modules`, never this
+repository's `src/`/`dist/`. `--version`, `--help`, `view --help` all
+correct. Viewer launched and passed the full local smoke assertion list
+(§13.2). `LOCAL_PACKED_CANDIDATE_PATH`:
+`.my-dev-kit-workflow/v0.8/prerelease-readiness/pack/my-frontend-observer-0.7.0.tgz`.
+`LOCAL_CLEAN_CONSUMER: PASS`, `LOCAL_INSTALLED_CLI: PASS`,
+`LOCAL_INSTALLED_VIEWER: PASS`.
+
+The CI candidate job's tarball (§13.3) is the authoritative cross-platform
+candidate; this local tarball is corroborating evidence only, per task
+policy.
+
+## 17. Package version invariant
+
+Checked before candidate freeze, after CI PASS, and immediately before this
+report's commit - all three times: `package.json` version, `package-lock.json`
+version, and `package-lock.json` `packages[''].version` were all `0.7.0`.
+Unchanged throughout this entire stage.
+
+## 18. Repository hygiene
+
+Both commits (`55299e5`, `d8eb0fc`) staged only their exact intended files
+(never `git add -A`); `git diff --check` was run before each (only benign
+LF/CRLF line-ending warnings, no real whitespace errors); `git status
+--short` showed no untracked pollution before either commit. No tarball,
+log, npm cache, consumer install, Chromium profile, or CI-downloaded
+artifact was ever staged. `REPOSITORY_POLLUTION_CHECK: PASS`.
+
+## 19. Release-state invariant
+
+No npm publication, no git tag, no GitHub Release, no push to `master`, no
+version bump occurred at any point in this stage. The only remote push was
+the `validation/v0.8-pre-release-readiness` branch (twice: initial push, then
+a fast-forward to the corrected candidate) - readiness infrastructure only,
+never merged, never tagged.
+
+## 20. Remaining non-blocking risks
+
+- `X-Content-Type-Options`/CSP headers are not set on viewer responses
+  (§10.9) - low risk given the loopback-only, same-origin, no-third-party-
+  content design; worth a focused follow-up but not blocking.
+- Several devDependencies (and `typescript`, a major version behind) are
+  stale but not security-required or EOL (§11) - deferred per "do not churn
+  dependencies for cosmetic freshness."
+- `scripts/dev/*.mjs` (5 files) were not proven dead but also not
+  independently re-verified as still-invoked by any documented workflow in
+  this stage; kept with justification (§15.2, ROT-3) rather than removed.
+- The CI Linux job resolved a newer Node 24 patch (v24.20.0/v24.19.0) than
+  this session's local Windows Node (v24.11.0); all are within the declared
+  `>=24` range and no incompatibility was observed, but the workflow does
+  not separately test the single newest stable Node line beyond its pinned
+  `'24'` (§12) - unchanged from the pre-existing CI architecture, not a
+  regression introduced here.
+
+None of these rise to a blocking finding under this stage's PASS criteria.
+
+## 21. Final local validation (before candidate freeze, restated)
+
+Rerun immediately before the corrected candidate commit (`d8eb0fc`) and
+again confirmed clean after: `npm run typecheck`, `npm run lint`, `npm test`
+(1157 tests), `npm run build`, `npm run check:docs`, `npm run test:browser`
+(178 tests, stable across three consecutive full reruns), `npm run
+test:security` (80 + 70 tests), `npm pack --dry-run --json`, `git diff
+--check`. All passed.
+
+## 22. Verdict
+
+**`PASS_READY_FOR_RELEASE_PREP`**
+
+Entry-gate audit passed; source-checkout validation passes; security
+validation passes with one real finding found and fixed within this stage
+(SEC-1, symlink media escape) and no remaining blocking finding; code-rot
+audit completed with one text fix and one test-robustness fix, no blocking
+finding; dependencies have no blocking unsupported/security issue (0
+findings after the `vitest` patch); package dry-run and local packed smoke
+pass; CI produced exactly one candidate tarball, SHA-256 verified identical
+on every platform; Windows, Linux, and macOS all pass, including the v0.8
+packed viewer and its PWA/server-down hard gate; pre-v0.8 packed workflows
+remain valid on the same candidate; the one reproducible CI failure cycle
+was root-caused and corrected (not silently retried); the one genuine local
+flake was diagnosed and fixed, not ignored; package version remains `0.7.0`
+throughout; no publication/version-bump/tag/release action occurred.
+
+`NEXT_STAGE_READINESS`: **`READY_FOR_V08_RELEASE_PREP`**