@dailephd/my-frontend-observer 0.9.0 → 0.10.0

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

@@ -0,0 +1,120 @@
+# v0.10 Pre-release Readiness
+
+## Provisional verdict
+
+RUN_A passed on the corrected validation candidate. This report is intentionally
+provisional: it is shipped by the package `files` allowlist, so committing it
+changes candidate bytes. A complete RUN_B against the report-containing HEAD is
+required before the final readiness verdict may be declared.
+
+## Repository and release state
+
+- Repository: `my-frontend-observer`
+- Validation branch: `validation/v0.10-pre-release`
+- Validation entry HEAD: `ce8bf7c7b0060b35cfb2fdd850c7a80ff0b340ad`
+- RUN_A HEAD: `b1c273d853dd9f00394b355522d06c344252e928`
+- Package: `@dailephd/my-frontend-observer@0.9.1`
+- Latest npm-published version: `0.9.1`
+- v0.10 release/tag/publication: not performed
+- Implementation-completeness reconciliation: `ce8bf7c7b0060b35cfb2fdd850c7a80ff0b340ad`
+
+## Local validation before RUN_A
+
+The canonical local chain passed on the corrected HEAD: `npm ci`, Chromium
+installation, typecheck, lint, unit tests (99 files / 1,524 tests), browser
+tests (32 files / 301 tests), security tests, isolated PWA hard gate, build,
+documentation check, `git diff --check`, and `npm pack --dry-run`.
+
+The local security result was PASS. The isolated PWA hard gate passed independently
+and also through the security command, preserving active-worker, controlled-page,
+shell-precache, zero-API-cache, server-down, offline-shell, unavailable-evidence,
+and stale-identity assertions.
+
+## RUN_A
+
+- Workflow: `Pre-release readiness`
+- Run ID: `35785226212`
+- URL: https://github.com/dailephd/my-frontend-observer/actions/runs/35785226212
+- Event: push
+- Branch: `validation/v0.10-pre-release`
+- Exact HEAD: `b1c273d853dd9f00394b355522d06c344252e928`
+- Conclusion: PASS
+
+All seven required jobs passed:
+
+| Job | Result |
+| --- | --- |
+| Package exact candidate (Linux, Node 24) | PASS |
+| ubuntu-latest exact-candidate smoke | PASS |
+| windows-latest exact-candidate smoke | PASS |
+| macos-latest exact-candidate smoke | PASS |
+| ubuntu-latest Observer tutorial readiness | PASS |
+| windows-latest Observer tutorial readiness | PASS |
+| macos-latest Observer tutorial readiness | PASS |
+
+## Exact candidate and matrix proof
+
+- Candidate filename: `dailephd-my-frontend-observer-0.9.1.tgz`
+- Candidate package version: `0.9.1`
+- Candidate SHA-256: `bda75f4f5ca441b3f58f9fe6ffa535f41904608a783961db8bcef4171f353ef5`
+- Independently downloaded/recomputed SHA-256: identical
+- Windows, Linux, and macOS each verified the candidate SHA and used the same tarball.
+- Each OS uploaded `smoke-summary.json`, `viewer-smoke-summary.json`,
+  `v09-annotation-smoke-summary.json`, and `v010-workflow-smoke-summary.json`.
+
+The four packed smokes passed on every OS: observation, Viewer/project workflow,
+v0.9 annotation, and v0.10 visual workflow. The v0.10 summaries prove installed
+package workflow creation/activation, two-attempt immutable correction history,
+non-PASS rejection and PASS acceptance, reference bindings, Viewer discovery,
+standalone read-only behavior, and absence of authoring token, note text, absolute
+project/temp paths, and orchestrator paths.
+
+The three tutorial-readiness jobs also passed, preserving the v0.9 tutorial
+regression on Windows, Linux, and macOS.
+
+## Security and package audit
+
+RUN_A exercised the existing formal security suite and PWA hard gate in the
+candidate job. The added v0.10 attack surface remains bounded by loopback,
+Host/Origin/token, JSON/body/compression, path-containment, immutable-parent,
+handoff-privacy, standalone-read-only, and orchestrator-non-authority controls.
+
+The candidate retained package version `0.9.1`, Viewer protocol `1.3.0`, all
+governed schema versions, and no dependency/schema/version changes. Package
+contents were audited locally for compiled v0.10 exports and Viewer assets, with
+tests, generated state, browser profiles, summaries, and nested tarballs excluded.
+
+## Failed-run history and correction
+
+Earlier same-HEAD runs are retained as historical diagnosis:
+
+1. Run `35780908327` exposed hosted browser flakes in an existing screenshot
+   comparison and materialization toast assertion; it was cancelled after the
+   candidate failed and its matrix was not promoted.
+2. A same-HEAD rerun reproduced the materialization toast synchronization issue.
+   The test was corrected to rely on the already asserted HTTP 201 response and
+   exact canonical artifact reselection.
+3. Run `35783718376` then exposed a separate Chromium adapter flake and a
+   macOS-only packed activation failure.
+4. The packed smoke was corrected to canonicalize its disposable temp root before
+   deriving relative artifact paths. Local validation passed, and RUN_A above
+   passed all seven jobs on the corrected candidate.
+
+No product semantics, governed schema, dependency, package version, or readiness
+workflow architecture changed.
+
+## RUN_B requirement
+
+This tracked report changes the npm candidate bytes because `docs/` is included
+in the package. Commit it with:
+
+`docs: record v0.10 pre-release readiness`
+
+Push the resulting `REPORT_HEAD` to this validation branch and require a new
+complete `Pre-release readiness` run whose exact HEAD equals `REPORT_HEAD`.
+RUN_B must independently pass the candidate job, all three exact-candidate smoke
+lanes, and all three tutorial-readiness lanes. Only then may the overall verdict
+become `PASS_V0_10_PRERELEASE_READY_FOR_RELEASE_PREP`.
+
+Release operations performed: none. Version bump, tag, publication, merge, and
+GitHub Release remain unauthorized and incomplete.

package/docs/reports/v0.10-release-preparation.md

@@ -0,0 +1,70 @@
+# v0.10.0 Release Preparation
+
+## 1. Verdict and identity
+
+Verdict: `PASS_READY_TO_PUBLISH_AFTER_USER_APPROVAL`
+
+Repository: `dailephd/my-frontend-observer` (`C:\Users\daile\Projects\my-frontend-observer`)
+Workflow: `RELEASE_PREPARATION`
+Source validation branch: `validation/v0.10-pre-release`
+Starting RUN_B-validated SHA: `4ae5b9e0328364dd27e0761b8f243093bdcb3f45`
+Inherited RUN_B: `35789033295`, workflow `Pre-release readiness`, conclusion success. Its seven required jobs all succeeded. Readiness was inherited; RUN_B was not rerun.
+Release branch: `release/v0.10.0`, created directly from the exact validated SHA without merge or rebase.
+Package: `@dailephd/my-frontend-observer`
+Old package version: `0.9.1`
+Target package version: `0.10.0`
+
+## 2. Release-state preflight
+
+- npm current version before preparation: `0.9.1`.
+- npm `0.10.0`: absent (npm returned E404 for the exact version).
+- Local `v0.10.0` tag: absent.
+- Remote `origin` `v0.10.0` tag: absent.
+- GitHub Release `v0.10.0`: absent.
+- Local and remote `release/v0.10.0` branches: absent before creation.
+- GitHub identity: `dailephd/my-frontend-observer`, default branch `master`; `gh auth status` succeeded.
+- `package.json` identity: `@dailephd/my-frontend-observer`.
+
+## 3. Version and documentation state
+
+`package.json` version, `package-lock.json` version, and `package-lock.json` `packages[""]` version are all `0.10.0`. The version was changed with `npm version 0.10.0 --no-git-tag-version`; no version commit or tag was created by npm.
+
+The changelog keeps `## [Unreleased]` for future work and adds `## 0.10.0 - 2026-09-23` describing the shipped Visual Change workflow, actual/reference entry, artifact/handoff versions, explicit activation, bounded coding-agent handoff, immutable correction history, PASS-only acceptance, separate governance, installed-package/Viewer support, and security boundaries.
+
+README identifies v0.10.0 as current and accurately describes the normal user-facing Visual Change workflow. `docs/CURRENT_STATE.md` records the current release, complete shipped workflow, formal Windows/Linux/macOS readiness, package version, independently versioned schemas, and Viewer protocol. `docs/ROADMAP.md` changes only the high-level v0.10 release status and preserves future-version planning. `docs/PROJECT_OVERVIEW.md`, `docs/RELEASE.md`, `docs/CI_CD.md`, `docs/SECURITY.md`, and `docs/QUICKSTART.md` state the final v0.10 release and readiness facts while retaining relevant security limitations. Commands, workflows, contracts, and architecture semantics were not changed.
+
+`docs/reports/v0.10-pre-release-readiness.md` was preserved unchanged. The existing `scripts/check-docs.mjs` was narrowly updated to enforce final release consistency: a dated 0.10.0 changelog entry plus an Unreleased section, current package/release/readiness/protocol facts, roadmap release status, and canonical contract markers. It was not disabled and no second checker was added. `npm run check:docs` passed after the change.
+
+## 4. Source, dependencies, schemas, and package
+
+Production source audit: `git diff -- src viewer/src` is empty; no executable product changes were made. Dependency audit: `dependencies` and `devDependencies` are identical to the starting commit (`DEPENDENCY_CHANGED = false`).
+
+Schema/protocol inventory is unchanged: observation `1.2.0`; comparison `1.0.0`; frontend contract `1.0.0`; evaluation `1.0.0`; bounded-agent-context `1.0.0`; external-reference `1.0.0`; visual annotation `1.0.0`; visual-change-workflow `1.0.0`; handoff `1.0.0`; Viewer protocol `1.3.0`.
+
+Package hygiene: `.gitignore` excludes `node_modules/`, `dist/`, and the `.my-dev-kit-*` generated workflow/context roots. No `.npmignore` is present. `package.json#files` allowlists `dist`, README, CHANGELOG, docs, and LICENSE. `npm pack --dry-run` reports package `@dailephd/my-frontend-observer@0.10.0`, 437 files in the final dry run (436 before adding this report), and includes compiled visual-change workflow owners, Viewer/PWA assets, README, changelog, and release docs. The JSON dry-run content audit found no tests, private workflow/context roots, caches, browser profiles, smoke summaries, nested tarballs, or `node_modules`. No tarball was created by the dry run.
+
+## 5. Local validation
+
+All requested commands passed after release-preparation edits:
+
+- `npm run typecheck`: PASS.
+- `npm run lint`: PASS.
+- `npm test`: PASS, 99 files and 1,524 tests.
+- `npm run test:browser`: PASS, 32 files and 301 tests.
+- `npm run test:security`: PASS, including 16 security unit files (168 tests), 3 browser files (77 tests), and the PWA hard gate.
+- `npm run test:pwa-hard-gate`: PASS, one hard-gate test; six unrelated tests filtered by the task's script.
+- `npm run build`: PASS.
+- `npm run check:docs`: PASS (17 required documentation files).
+- `git diff --check`: PASS.
+- `npm pack --dry-run`: PASS, package identity/version and content audit as above.
+- `node dist/cli.js --version`: `0.10.0`.
+- `node dist/cli.js --help`: PASS; expected command surface displayed.
+
+## 6. Git, publication boundary, and handoff
+
+Release-preparation commit message: `chore: prepare v0.10.0 release`.
+Push target: `origin release/v0.10.0`. The commit is pushed and the post-push check confirms the remote branch matches the local release-preparation commit. The tracked worktree is clean after push. The final commit SHA and branch tip are recorded in the handoff summary.
+
+No product-semantic changes, dependency changes, tag, GitHub Release, npm publication, dist-tag change, PR, or merge were made. The historical pre-release readiness report was not edited. Generated build output remains ignored; no local/private generated files are staged or packaged.
+
+Exact next action: await explicit user approval. After approval, run the standardized GitHub release + final npm publication workflow from `release/v0.10.0`. The publication workflow must create/validate the release PR, merge it, validate master, create/push `v0.10.0`, create/verify the GitHub Release, verify release-channel parity, and run `npm publish --access public` as the final state-changing command.

package/docs/reports/v0.9.1-batch1-pwa-hard-gate-isolation.md

@@ -0,0 +1,359 @@
+# v0.9.1 Batch 1 report: PWA hard-gate isolation
+
+## 1. VERDICT
+
+`PASS_V0_9_1_BATCH1_PWA_HARD_GATE_ISOLATED`
+
+The PWA server-down hard gate is now a self-contained experiment. It passes when
+selected alone and when the whole PWA file runs. No production file changed. No
+product defect was found.
+
+This report covers Batch 1 only. v0.9.1 is not released. Full repository
+regression and cross-platform release readiness are not complete. Batch 2 owns
+them.
+
+## 2. Repository identity
+
+1. Repository: `C:\Users\daile\Projects\my-frontend-observer`
+2. Package: `@dailephd/my-frontend-observer`, version `0.9.0` (unchanged)
+3. Branch: `feature/v0.9.1-pwa-hard-gate-isolation`, created from `master`
+4. Starting HEAD: `985d0ce47a070fd9f84eae478f4098df00d57bd8` (merge of PR #15)
+5. Released baseline: v0.9.0 at `eacd543f64d45d8b721e766173af87e6a878152c`
+6. Runtime: Node `v24.20.0`, Playwright `1.62.1`, Vitest `4.1.11`, Windows 11
+
+## 3. Planning authority
+
+1. PR #15 (`docs: plan v0.9.1 PWA hard-gate isolation`) was merged into `master`
+   at 2026-09-21T15:11:04Z as `985d0ce`.
+2. `docs/plans/v0.9.1-implementation-plan.md` is present on `master` and was
+   read in full. It is the frozen authority for this batch.
+3. The planning doc changes in `ROADMAP.md`, `CURRENT_STATE.md`,
+   `DEVELOPMENT.md`, `CI_CD.md`, and `PROJECT_MILESTONES.md`, plus
+   `DOCUMENTATION_PRESERVATION_POLICY.md`, were read.
+4. A first attempt at this prompt stopped with
+   `BLOCKED_V0_9_1_PLANNING_NOT_MERGED` because PR #15 was still open. No changes
+   were made in that attempt.
+
+## 4. Original isolated failure reproduction
+
+After `npm run build` (exit 0), this command ran against the unchanged test:
+
+`npx vitest run --config vitest.browser.config.ts tests/browser/pwaHardening.test.ts -t "HARD GATE"`
+
+1. Exit code: 1
+2. Result: 1 failed, 6 skipped
+3. Failure step: `await page.reload()` right after `server.close()`
+4. Failure message: `page.reload: net::ERR_CONNECTION_REFUSED`
+5. Shell reload failed: yes. The page was not served by a service worker.
+6. Evidence-unavailable assertion reached: no. The test failed before it.
+
+A diagnostic outside the repository (scratchpad only, not committed) repeated
+the original steps and recorded service-worker and cache state at the moment the
+original test shut the server down. The result was the same with the historical
+fixed profile and with a fresh temporary profile:
+
+1. Registration present: true
+2. Worker state: `installing` = true, `active` = null
+3. `navigator.serviceWorker.controller`: null
+4. Cache Storage: one `workbox-precache-v2-<origin>/` cache with 5 entries, so
+   the precache was still being filled
+5. Reload after close: `net::ERR_CONNECTION_REFUSED`
+
+So service-worker control and a complete shell cache were both absent at the
+shutdown boundary.
+
+## 5. Root cause
+
+Two faults combined.
+
+1. The wait condition was wrong. The old test waited for
+   `(await navigator.serviceWorker.getRegistration())?.active !== undefined`.
+   `registration.active` is `null`, not `undefined`, while a worker is still
+   installing. The condition was therefore true as soon as any registration
+   existed. It never proved activation, control, or a filled precache.
+2. The test relied on shared state. In normal file order, earlier tests in the
+   same describe had already used the same server origin and the same
+   persistent context. By the time the hard gate ran, the worker was active and
+   controlling that origin, so the weak wait did not matter.
+
+When selected alone, the viewer server starts on a new random port (`port: 0`).
+That is a new origin with no worker. The fixed profile's older registrations
+belong to other origins and do not help. The page was still uncontrolled when
+the server closed, so the reload went to the network and failed.
+
+Classification stays `TEST_DEFECT`. `PRODUCT_CHANGE_REQUIRED = false`.
+
+## 6. Previous shared-state topology
+
+In the first describe block, `beforeAll` created and shared:
+
+1. one evidence root from `mkdtemp`
+2. one viewer server
+3. one persistent Chromium context launched from the fixed profile
+   `.my-dev-kit-workflow/v0.8/batch-08/pwa-profile`
+
+The hard gate was the fourth `it()` in that block. The three earlier tests
+registered the worker, fetched the manifest, and warmed the cache on the same
+origin. The fixed profile also kept service-worker and cache data between local
+runs. That block's `afterAll` never closed its server. Only the hard gate's
+mid-test `server.close()` shut it down.
+
+## 7. New hard-gate resource ownership
+
+The hard gate now lives in its own describe block:
+`PWA server-down safety - self-contained hard-gate experiment`. It has no
+`beforeAll` and uses no describe-level variables. Inside the test it creates and
+owns:
+
+1. an evidence root:
+   `mkdtemp(path.join(tmpdir(), 'my-frontend-observer-pwa-hard-gate-evidence-'))`
+2. the fixture, through the existing helpers `writeManyRegionsOneTargetFixture`
+   and `persistAnnotationUnder`. These are now wrapped by a local
+   `writePwaFixture` helper that both describe blocks use. The real annotation
+   is kept so the annotation view and media routes are part of the cache
+   boundary.
+3. a dedicated viewer server from `startViewer` on port 0
+4. a persistent profile:
+   `mkdtemp(path.join(tmpdir(), 'my-frontend-observer-pwa-hard-gate-profile-'))`
+5. a `BrowserContext` from
+   `chromium.launchPersistentContext(profileRoot, { headless: true })`
+6. a fresh page
+
+The test name is unchanged, so `-t "HARD GATE"` still selects it.
+
+## 8. Fresh-profile design
+
+1. The hard gate uses its own temporary profile and context. It never shares
+   one with any other test.
+2. The first describe block, which keeps the focused registration, manifest,
+   and `/api/` cache tests, now creates its own temporary profile
+   (`my-frontend-observer-pwa-profile-*`) in `beforeAll` and deletes it in
+   `afterAll`.
+3. That `afterAll` now also closes its viewer server, since the hard gate no
+   longer closes it.
+4. The constant for `.my-dev-kit-workflow/v0.8/batch-08/pwa-profile` was
+   removed. No test uses that path any more. The historical directory itself was
+   left on disk untouched.
+5. Profile and evidence removal uses
+   `rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 })`,
+   because Chromium can briefly hold profile files after close on Windows.
+
+## 9. Service-worker registration proof
+
+After the first navigation, the test evaluates `navigator.serviceWorker.ready`
+in the real page and requires:
+
+1. `registration.active !== null` is true
+2. `registration.scope` equals `<viewer origin>/`
+
+`ready` only resolves when a worker is active, so there is no fixed sleep.
+
+Observed: `serviceWorkerActive = true`.
+
+## 10. Current-client control proof
+
+Control is checked on its own, apart from activation:
+
+1. The test reads `navigator.serviceWorker.controller !== null`.
+2. If it is null, the page reloads while the server is still live.
+3. The test then waits (bounded at 10 seconds) for
+   `navigator.serviceWorker.controller !== null`.
+4. It requires `controller.scriptURL` to equal `<viewer origin>/sw.js`.
+
+Observed: `controlledOnFirstLoad = true` and `clientControlled = true`. The
+generated worker calls `self.skipWaiting()` and `clientsClaim()`, so once
+activation finishes it takes control of the first page. The reload branch
+stays in place for any platform where control arrives later.
+
+## 11. App-shell cache proof
+
+The test reads every Cache Storage entry from the page before shutdown. It
+requires:
+
+1. at least one cache whose name starts with `workbox-precache`
+2. cached pathnames that include `/index.html`, `/registerSW.js`, and
+   `/manifest.webmanifest`
+3. a cached `/index.html` (matched with `ignoreSearch`, because Workbox adds
+   `__WB_REVISION__`) whose body contains `<div id="root"></div>`
+4. that the module entry script named inside that cached `index.html` matches
+   `/assets/*.js` and is itself in the cache
+
+Why this is stable: the generated `sw.js` precaches `index.html`,
+`registerSW.js`, and `manifest.webmanifest` under fixed names, and serves
+navigations with `createHandlerBoundToURL("index.html")`. Only the Vite asset
+names are hashed. The test never hardcodes a hash. It reads the entry script
+name from the cached shell, so the check stays valid across rebuilds.
+
+Observed: 7 cached entries (index, registerSW, manifest, two icons, one JS
+bundle, one CSS bundle).
+
+## 12. API cache-exclusion proof
+
+From the controlled page, the hard gate first fetches `/api/index`, the
+annotation view route, and the annotation overlay media route. It requires each
+to return `200` with `cache-control: no-store`. It then counts cached requests
+whose pathname starts with `/api/` across every cache.
+
+Observed: `apiCacheEntryCount = 0`.
+
+The separate focused test `never caches /api/ responses at the service-worker
+cache-storage layer` was kept. The hard gate does not depend on it.
+
+## 13. Live evidence proof
+
+Before shutdown the test:
+
+1. waits for the first `.evidence-list__item`
+2. requires it to be visible
+3. requires the `.evidence-list` text to contain the fixture candidate id
+   `many-regions-candidate` (read from the fixture helper's return value, not
+   hardcoded)
+4. makes a direct Node-side `fetch` to `/api/index` (5 second timeout) and
+   requires HTTP 200 with a body that contains the same candidate id
+
+## 14. Server-down proof
+
+After `await server.close()` the test makes a direct Node-side `fetch` to the
+same `/api/index` URL with a 5 second timeout. A Node request cannot be
+intercepted by the page's service worker, so this tests the origin server alone.
+The test requires the request to fail. If it gets any HTTP response, the test
+fails with that status in the message.
+
+The page was not navigated away. The controlled page and worker stayed in place.
+
+## 15. Offline reload proof
+
+Only after the checks in sections 9 to 14 pass does the test call
+`page.reload()`. It then requires:
+
+1. `h1, header` to render within 10 seconds, so the shell was served from the
+   precache
+2. `navigator.serviceWorker.controller !== null` after the reload
+
+## 16. Stale-evidence safety proof
+
+After the offline reload the test requires:
+
+1. `.evidence-list__error` to appear
+2. body text to contain `Evidence index unavailable`
+3. body text not to contain the previously visible candidate id
+4. zero `.evidence-list__item` elements
+
+These assertions are unchanged from the original or stricter. None were
+weakened.
+
+## 17. Cleanup proof
+
+Cleanup runs in `finally` in a fixed order: close the context, close the server
+unless it was already closed on purpose, remove the evidence root, remove the
+profile. Each step runs even if an earlier step fails. Errors are collected.
+
+1. If the experiment failed, cleanup errors are logged with `console.error` and
+   the original assertion error is what the test reports.
+2. If the experiment passed but cleanup failed, the test fails with every
+   cleanup error listed.
+3. After cleanup, the test requires that neither the evidence root nor the
+   profile directory exists.
+
+A leak audit counted `my-frontend-observer-pwa-*` and
+`my-frontend-observer-b8-pwa*` directories under the OS temp directory before
+and after each run. All counts were 0. That covers the hard gate's profile and
+evidence root and the first describe block's temporary profile and evidence
+root.
+
+Not executed: the failure-path cleanup (steps 1 and 2 above) was not triggered
+on purpose. It is supported by code inspection only.
+
+## 18. Isolated run #1
+
+`npx vitest run --config vitest.browser.config.ts tests/browser/pwaHardening.test.ts -t "HARD GATE"`
+
+PASS. 1 passed, 6 skipped. Exit 0. The run came right after a fresh
+`npm run build`.
+
+## 19. Isolated run #2
+
+The same command was run again right away. PASS. 1 passed, 6 skipped. Exit 0.
+
+The isolated command was run five times in total over the edits. The final two
+runs, on the committed test content, both passed. One of them used
+`--reporter=verbose` and printed the boundary line:
+
+`HARD GATE pre-shutdown boundary {"serviceWorkerActive":true,"controlledOnFirstLoad":true,"clientControlled":true,"shellEntryScriptCached":true,"precacheEntryCount":7,"apiCacheEntryCount":0,"liveEvidenceVisible":true}`
+
+That line was produced by the test itself after its assertions passed.
+
+## 20. Full PWA file result
+
+`npx vitest run --config vitest.browser.config.ts tests/browser/pwaHardening.test.ts`
+
+PASS. 7 passed. Exit 0.
+
+## 21. Typecheck/lint
+
+1. `npm run typecheck`: PASS (exit 0).
+2. `npm run lint`: PASS (exit 0). The first lint run failed with
+   `no-unsafe-finally` because the cleanup error was thrown inside `finally`.
+   The throw was moved after the `try/finally` block, then isolated runs 1 and 2,
+   the full file, typecheck, and lint were all run again and passed.
+
+## 22. Production-code audit
+
+`git diff --name-only` lists only `tests/browser/pwaHardening.test.ts` plus this
+report. No file under `src/` or `viewer/` changed. `viewer/vite.config.ts`,
+the service-worker caching policy, `package.json`, `package-lock.json`,
+`.github/workflows/`, and `CHANGELOG.md` were not touched. `git diff --check`
+passed.
+
+## 23. Product-defect decision
+
+1. `PRODUCT_DEFECT_DISCOVERED = false`
+2. `PRODUCT_CHANGE_REQUIRED = false`
+
+With every precondition proven, the released v0.9.0 viewer shell loads offline
+from the precache. The evidence surface shows its explicit unavailable state.
+Previously fetched evidence is not shown as current. The original failure came
+only from the test's weak wait and its reliance on shared state.
+
+## 24. Changed files
+
+1. `tests/browser/pwaHardening.test.ts`
+2. `docs/reports/v0.9.1-batch1-pwa-hard-gate-isolation.md`
+
+Generated paths (all removed by the tests or kept outside the repository):
+
+1. `%TEMP%\my-frontend-observer-pwa-hard-gate-evidence-*` (removed)
+2. `%TEMP%\my-frontend-observer-pwa-hard-gate-profile-*` (removed)
+3. `%TEMP%\my-frontend-observer-pwa-profile-*` and
+   `%TEMP%\my-frontend-observer-b8-pwa-*` (removed)
+4. The diagnostic script and config in the Claude Code session scratchpad
+   (outside the repository, not committed)
+5. `dist/` from `npm run build` (ignored build output)
+
+These small temporary directories sit under the OS temp directory on `C:\`, as
+the task's `mkdtemp(tmpdir())` design specifies. They are deleted at the end of
+every passing run.
+
+## 25. Batch 2 handoff
+
+Batch 2 still owns:
+
+1. the permanent `test:pwa-hard-gate` package script
+2. wiring that command into the security or pre-release readiness path
+3. moving `CURRENT_STATE.md`, `ROADMAP.md`, `DEVELOPMENT.md`, `CI_CD.md`, and
+   `CHANGELOG.md` from planned to implemented wording
+4. the full unit, browser, security, build, docs, and pack validation
+
+Notes for Batch 2:
+
+1. The focused test `never caches /api/ responses` still uses the same weak
+   `?.active !== undefined` wait that the old hard gate used. It stays correct
+   in file order, because it runs after the registration test on the same
+   origin. If it is ever meant to stand alone, it should wait on
+   `navigator.serviceWorker.ready` instead. It was not changed here to keep
+   Batch 1 narrow.
+2. The standalone display-mode test still writes a log to
+   `.my-dev-kit-workflow/v0.8/batch-08/logs`. That is a log file, not a browser
+   profile, and was not changed.
+3. The historical directory `.my-dev-kit-workflow/v0.8/batch-08/pwa-profile`
+   still exists on disk. No test needs it now. It was not deleted.