@dailephd/my-frontend-observer 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+Future development.
+
+## 0.9.1 - 2026-09-21
+
+Hardened PWA security-acceptance reproducibility as a maintenance release.
+
+- Hardened the PWA server-down HARD GATE from fresh test-owned state, removing
+  hidden dependence on prior test order and persistent Chromium profile state.
+- Corrected the false-ready service-worker predicate and separately proved
+  active registration and current-client control.
+- Proved shell-cache readiness, `/api/` exclusion from Cache Storage,
+  origin-server unavailability, offline shell reload, and stale-evidence
+  absence.
+- Added permanent `npm run test:pwa-hard-gate` and integrated it into
+  `npm run test:security`.
+- No production PWA behavior, schema, or dependency changed.
+
 ## 0.9.0 - 2026-09-21
 
 v0.9, Human Visual Annotation and Design-Intent Capture. Structured visual

package/README.md

@@ -1,6 +1,6 @@
 # my-frontend-observer
 
-## Common project workflow (v0.9.0)
+## Common project workflow (v0.9.1)
 
 ```powershell
 my-frontend-observer init --url http://127.0.0.1:3000 --target app=#app
@@ -17,9 +17,10 @@ my-frontend-observer view
 `1`, `2`, or `3` for `PASS`, `FAIL`, `REVIEW_REQUIRED`, or `BLOCKED`.
 Canonical hashes remain available in viewer details and persisted provenance,
 but are not normal workflow command inputs. The existing low-level commands
-remain supported. v0.9.0 is the current published release.
+remain supported. v0.9.1 is the current published release.
 
-v0.9.0 adds the structured visual annotation workflow described below.
+v0.9.1 is a maintenance release that hardens independent PWA security-gate
+validation without changing production PWA behavior.
 
 `my-frontend-observer` is the local-first rendered browser/runtime evidence
 producer in the my-dev-kit ecosystem. Its durable product purpose is defined
@@ -28,8 +29,9 @@ composition is documented in the [my-dev-kit ecosystem guide](https://github.com
 
 ## Current status
 
-`v0.9.0`, Human Visual Annotation and Design-Intent Capture, is the current
-published release. It builds on `v0.8.1`, Project Workflow CLI and
+`v0.9.1`, PWA Hard-Gate Isolation and Reproducible Security Acceptance, is the
+current published release. It preserves the `v0.9.0` Human Visual Annotation
+and Design-Intent Capture release and builds on `v0.8.1`, Project Workflow CLI and
 Human-Readable Evidence Aliases, `v0.8.0`, Interactive Local Observation
 Viewer, and `v0.7.0`, End-to-End Coding-Agent Frontend Change
 Review, `v0.6.0`, Bounded Agent Context and Native my-dev-kit Ecosystem
@@ -347,7 +349,7 @@ Planning authorities:
   intent and responsibility boundaries.
 - [Project Milestones](docs/PROJECT_MILESTONES.md): complete ordered capability
   design and cross-milestone rules.
-- [ROADMAP](docs/ROADMAP.md): version-level requirements; v0.1-v0.9.0 are
+- [ROADMAP](docs/ROADMAP.md): version-level requirements; v0.1-v0.9.1 are
   released; v0.10 remains future.
 - [Current State](docs/CURRENT_STATE.md): retained scaffold and release state.
 

package/docs/CI_CD.md

@@ -1,6 +1,27 @@
 # CI/CD
 
-CI interprets `check` as PASS `0`, FAIL `1`, REVIEW_REQUIRED `2`, or BLOCKED `3`. The released package is `@dailephd/my-frontend-observer@0.9.0`; its CLI remains `my-frontend-observer`. Packed readiness installs one exact tarball and runs `runPackedViewerSmoke.mjs` as the single project/viewer smoke owner for `init`, `capture`, bounded `check --json` REVIEW_REQUIRED and unchanged-contract FAIL-to-PASS, alias-aware project `view`, and viewer security. `runPackedObservationSmoke.mjs` remains the lower-level legacy observation smoke.
+CI interprets `check` as PASS `0`, FAIL `1`, REVIEW_REQUIRED `2`, or BLOCKED `3`. The released package is `@dailephd/my-frontend-observer@0.9.1`; its CLI remains `my-frontend-observer`. Packed readiness installs one exact tarball and runs `runPackedViewerSmoke.mjs` as the single project/viewer smoke owner for `init`, `capture`, bounded `check --json` REVIEW_REQUIRED and unchanged-contract FAIL-to-PASS, alias-aware project `view`, and viewer security. `runPackedObservationSmoke.mjs` remains the lower-level legacy observation smoke.
+
+## Gate isolation invariant
+
+Cross-platform/full-suite success does not by itself prove that a security or
+acceptance gate is independent. Any test explicitly labeled `HARD GATE`,
+`SECURITY GATE`, or `ACCEPTANCE GATE` must also be able to run from fresh
+state without relying on earlier test order, a previously warmed service-worker
+cache, a persistent browser profile from an earlier run, or another test's
+server/evidence setup.
+
+v0.9.1 applies this rule to the PWA server-down
+hard gate. `npm run test:pwa-hard-gate` runs that gate by itself. It is a
+separate required proof in addition to the normal full-file execution in
+`npm run test:browser` and `npm run test:security`.
+
+`npm run test:security` now ends with `npm run test:pwa-hard-gate`. The
+`candidate` job in `.github/workflows/pre-release-readiness.yml` already runs
+`npm run test:security`, so release-readiness candidate validation receives
+the isolated gate automatically. The workflow YAML did not need to change. The
+released v0.9.1 suite contains the corrected isolated gate. No production PWA
+regression was found.
 
 A GitHub Actions pre-release readiness workflow exists at
 `.github/workflows/pre-release-readiness.yml` (triggered manually via

package/docs/COMMANDS.md

@@ -783,7 +783,7 @@ the annotation workflow. The rest of this section describes the inspection
 surface, which is unchanged.
 
 **Current status: viewer behavior is released as package
-`@dailephd/my-frontend-observer@0.9.0`.** Starts one
+`@dailephd/my-frontend-observer@0.9.1`.** Starts one
 loopback-only Node viewer server and serves the same React + TypeScript +
 Vite application to a normal browser or an installed Progressive Web App.
 `--root` is used as a bounded, read-only evidence-discovery root: the server

package/docs/CURRENT_STATE.md

@@ -1,6 +1,6 @@
 # Current State
 
-v0.9.0 is released and published as `@dailephd/my-frontend-observer@0.9.0`.
+v0.9.1 is released and published as `@dailephd/my-frontend-observer@0.9.1`.
 v0.9 (Human Visual Annotation and Design-Intent Capture) adds structured visual
 annotation to the project-aware viewer. It passed integrated real-Chromium
 acceptance and final exact-candidate pre-release readiness on Windows, Linux
@@ -12,8 +12,10 @@ repository also holds a deterministic demo and four tutorial scenarios for
 v0.9, recorded by the external `@dailephd/my-dev-kit-lab@0.4.9` tool. See
 "v0.9 status" below.
 
-The project is published at package version `0.9.0` (roadmap v0.9, Human
-Visual Annotation and Design-Intent Capture; observation schema `1.2.0`;
+The project is published at package version `0.9.1` (roadmap v0.9.1, PWA
+Hard-Gate Isolation and Reproducible Security Acceptance; the preceding v0.9
+release was Human Visual Annotation and Design-Intent Capture; observation
+schema `1.2.0`;
 comparison schema `1.0.0`; frontend contract schema `1.0.0`; evaluation
 artifact schema `1.0.0`; bounded-agent-context schema `1.0.0`;
 external-reference schema `1.0.0`; visual annotation schema `1.0.0`). v0.9.0
@@ -22,6 +24,71 @@ evidence schema version. v0.8.1 did not change any canonical evidence schema
 version either; see "v0.8 status" below for the final, complete v0.8 viewer
 state.
 
+## v0.9.1 maintenance status
+
+Status: released and published as `@dailephd/my-frontend-observer@0.9.1`.
+No production code changed.
+
+Result of the implementation:
+
+1. The original failure was reproduced. Selected alone, the hard gate failed at
+   the offline reload with `net::ERR_CONNECTION_REFUSED`.
+2. Root cause, part one: the old readiness check was
+   `registration?.active !== undefined`. While the worker was still installing,
+   `active` was `null` and the page had no controller. Because
+   `null !== undefined` is true, the check passed and the server was closed
+   before the worker controlled the page or finished precaching.
+3. Root cause, part two: the gate shared a server, evidence root, and a fixed
+   persistent Chromium profile with earlier tests. In normal file order those
+   tests had already activated a controlling worker, which hid the defect.
+4. The hard gate now owns a fresh evidence root, viewer server, temporary
+   persistent profile, and BrowserContext. No PWA test uses the fixed
+   `.my-dev-kit-workflow` profile any more.
+5. The gate proves service-worker activation (`registration.active !== null`)
+   and current-page control (`navigator.serviceWorker.controller !== null`)
+   as separate facts.
+6. It proves the app shell is in the Workbox precache and that no `/api/`
+   request is in Cache Storage.
+7. It proves the server is down with a direct Node-side request before the
+   offline reload.
+8. After the reload, the shell renders, the evidence list shows its explicit
+   unavailable state, and the previously visible evidence identity is absent.
+9. `npm run test:pwa-hard-gate` runs the gate alone. `npm run test:security`
+   now ends with it. It passes repeatedly, and the full PWA file, browser suite,
+   and security suite pass.
+10. Production PWA behavior is unchanged.
+
+Evidence: `docs/reports/v0.9.1-batch1-pwa-hard-gate-isolation.md` and
+`docs/reports/v0.9.1-batch2-hard-gate-validation-integration.md`.
+
+The historical planning background follows.
+
+A post-release test-isolation defect has been identified in
+`tests/browser/pwaHardening.test.ts`. The PWA server-down test labeled
+`HARD GATE` passes in the normal full-file/full-suite execution but fails
+when selected independently with Vitest `-t`. The current test shares a
+persistent Chromium context/profile with earlier tests, and its own setup proves
+that a service-worker registration is active without independently proving all
+of the state the server-down experiment needs: that the current page is
+controlled, that the application shell is actually precached, and that no
+historical profile/cache state was inherited.
+
+This is currently classified as a test-isolation defect, not a demonstrated
+production PWA regression. The released safety contract remains unchanged:
+application-shell caching may keep the viewer shell available while evidence
+and media remain server-backed, and stale evidence must never be presented as
+current after the server is unavailable. No production PWA code change is
+authorized unless a corrected fresh-state hard-gate experiment first
+demonstrates a real runtime failure.
+
+The completed v0.9.1 maintenance patch was governed by the frozen implementation
+plan `docs/plans/v0.9.1-implementation-plan.md`. It made the hard gate own fresh
+disposable evidence/server/browser-profile state, explicitly prove service-worker
+control and shell/API cache preconditions, explicitly prove the server is
+unavailable before the offline reload, and add an isolated execution gate so the
+same test passes by itself as well as inside the full browser and security
+suites.
+
 v0.8 (Interactive Local Observation Viewer) is fully implemented, tested,
 formally cross-platform/security validated, and released. All eight v0.8
 implementation batches, the hardened documentation/implementation-

package/docs/DEVELOPMENT.md

@@ -1,7 +1,7 @@
 # Development
 
-The released v0.9.0 package is published as
-`@dailephd/my-frontend-observer@0.9.0` (CLI `my-frontend-observer`). It keeps
+The released v0.9.1 package is published as
+`@dailephd/my-frontend-observer@0.9.1` (CLI `my-frontend-observer`). It keeps
 the v0.8.1 project workflow and adds structured visual annotation.
 
 The v0.8.1 workflow is exercised through unit and real-Chromium tests. Project fixtures use `init`, `capture baseline`, and `check`; coding-agent consumers use bounded `check --json`. `tests/browser/projectCheckWorkflow.test.ts` covers REVIEW_REQUIRED, contract FAIL-to-PASS, reference FAIL/PASS/BLOCKED, incomparable BLOCKED, current history, and contained acceptance paths. `scripts/ci/runPackedViewerSmoke.mjs` is the single installed-package viewer/project-workflow smoke owner: it repeats REVIEW_REQUIRED and unchanged-contract FAIL-to-PASS before alias-aware viewer proof. Run the full unit, browser, security, build, documentation, and packed-consumer validations before release readiness.
@@ -38,6 +38,36 @@ first; it is kept out of `npm test` because it launches a real browser and
 is slower. Exact counts drift as the suite grows - run the commands above
 for the current numbers rather than trusting this document.
 
+## Hard/security/acceptance gate isolation
+
+Tests explicitly designated `HARD GATE`, `SECURITY GATE`, or
+`ACCEPTANCE GATE` must be independently reproducible. A passing full suite is
+not sufficient evidence if the gate itself only succeeds because another test
+ran first or because a prior run left browser/cache/filesystem state behind.
+
+For browser-based gates, the gate must own or explicitly establish every
+precondition material to its claim. That includes disposable evidence state,
+servers, browser profiles/contexts, service-worker control, relevant cache
+state, and cleanup. Fixed persistent profiles must not be used as hidden
+fixtures for a hard acceptance claim.
+
+v0.9.1 applies this rule to the PWA server-down safety proof in
+`tests/browser/pwaHardening.test.ts`. The hard gate owns its evidence root,
+viewer server, temporary Chromium profile, and context. It must pass when
+selected alone and must also continue to pass in the complete browser and
+security suites.
+
+Run the gate by itself with:
+
+```powershell
+npm run test:pwa-hard-gate
+```
+
+Run this command when working on PWA, service-worker, viewer-server, or
+security behavior. It must pass on its own, not only after other tests have
+run. `npm run test:security` also runs it after the rest of the security
+suite. See `docs/plans/v0.9.1-implementation-plan.md`.
+
 ROADMAP v0.1 and Project Milestone 1 require browser-level validation once the
 observation capability is planned and implemented. Static checks must not later
 be substituted for that required browser evidence. `npm run test:browser` is

package/docs/PROJECT_MILESTONES.md

@@ -1719,6 +1719,34 @@ Implementation status: implemented and released as `0.9.0`. The milestone
 design below is unchanged and remains the capability authority. Milestone 10
 remains future.
 
+### v0.9.1 maintenance acceptance note
+
+v0.9.1 is a bounded maintenance patch over Milestone 9 rather than a new
+capability milestone. A post-release PWA hard-gate test-isolation defect was
+found: the server-down safety test can pass only after earlier tests have
+prepared persistent service-worker/cache state. No production PWA regression has
+been demonstrated.
+
+The durable acceptance rule added by this maintenance patch is broader than the
+single PWA test: any test explicitly designated `HARD GATE`, `SECURITY GATE`,
+or `ACCEPTANCE GATE` must be able to establish its own prerequisites and pass
+when selected independently from fresh state. Such a gate must not rely on
+another test running first, a fixed browser profile, historical cache state, or
+test ordering. For browser gates, owned servers, evidence roots, browser
+profiles, contexts, and other state must be scoped and cleaned up explicitly.
+
+The v0.9.1 correction is test/validation work unless the corrected isolated
+experiment demonstrates a genuine product failure. In that case the work must
+stop and be reclassified before production semantics change. The concrete
+implementation details live in
+`docs/plans/v0.9.1-implementation-plan.md`; the Milestone 9 product capability
+design below remains unchanged.
+
+Status: the maintenance invariant is implemented and released in v0.9.1 for the PWA hard gate, which
+now passes alone through `npm run test:pwa-hard-gate` and inside the full
+browser and security suites. No genuine product failure was found. Release of
+v0.9.1 is released and published.
+
 ### Objective
 
 Add visual human intent to the already working Milestone 7 coding-agent/reference workflow through the Milestone 8 viewer.

package/docs/PROJECT_OVERVIEW.md

@@ -1,8 +1,9 @@
 # Project Overview
 
-The repository contains the complete v0.9.0 release, published as
-`@dailephd/my-frontend-observer@0.9.0` under the MIT license. It adds
-structured visual annotation to the v0.8.1 project workflow (`init`,
+The repository contains the complete v0.9.1 release, published as
+`@dailephd/my-frontend-observer@0.9.1` under the MIT license. It hardens
+independent PWA security acceptance while preserving the structured visual
+annotation added to the v0.8.1 project workflow (`init`,
 `capture`, `check`, project-aware `view`).
 
 `my-frontend-observer` is the rendered browser/runtime evidence producer in
@@ -32,7 +33,7 @@ v0.6, Bounded Agent Context and Native my-dev-kit Ecosystem Integration;
 v0.7, End-to-End Coding-Agent Frontend Change Review; v0.8, Interactive
 Local Observation Viewer; v0.8.1, Project Workflow CLI and Human-Readable
 Evidence Aliases; and v0.9, Human Visual Annotation and Design-Intent Capture,
-are released and published to npm. The current package version is `0.9.0` as
+are released and published to npm. The current package version is `0.9.1` as
 `@dailephd/my-frontend-observer` (observation schema `1.2.0`, comparison schema
 `1.0.0`, frontend contract schema `1.0.0`, evaluation artifact schema `1.0.0`,
 bounded-agent-context schema `1.0.0`, external-reference schema `1.0.0`,
@@ -96,7 +97,7 @@ artifact identifiers during ordinary use. Existing low-level commands remain
 supported. The frozen plan is
 `docs/plans/v0.8.1-cli-usability-patch-plan.md`.
 
-The latest published release is v0.9.0. v0.9 adds structured
+The latest published release is v0.9.1. v0.9 added structured
 visual annotation to the project-aware viewer for both runtime observations and
 external references. People draw marks, explicitly associate them, and confirm
 structured intent. Selected confirmed runtime intent can become a normal
@@ -110,6 +111,16 @@ The repository-owned deterministic demo and its four tutorial scenarios
 `@dailephd/my-dev-kit-lab@0.4.9` tool) passed final cross-platform readiness
 with the release. They are release support and documentation, not product
 behavior, and they are not shipped in the npm package.
+
+The v0.9.1 maintenance release hardens the
+PWA server-down hard acceptance test so the gate is reproducible from a fresh
+browser profile and fresh test-owned state. PWA hard/security acceptance no
+longer depends on prior test order or persistent browser state, and
+`npm run test:security` now also runs the gate by itself through
+`npm run test:pwa-hard-gate`. This was a test-isolation correction, not a
+production PWA defect. No production behavior changed. The frozen concrete plan
+is `docs/plans/v0.9.1-implementation-plan.md`.
+
 v0.10 remains future and unimplemented and completes the visual human-LLM
 workflow on top of the v0.9 annotation model and v0.8.1 high-level acceptance
 surface.
@@ -167,6 +178,12 @@ Repository-local authorities and navigation:
   gates, and validation expectations for v0.9. It is planning authority only;
   the v0.9 implementation state is recorded in CURRENT_STATE.md and the
   `reports/v0.9-*.md` reports.
+- [plans/v0.9.1-implementation-plan.md](plans/v0.9.1-implementation-plan.md)
+  freezes the bounded maintenance plan for independent PWA hard-gate
+  reproduction, fresh browser-profile ownership, explicit service-worker/cache
+  precondition proof, and isolated-gate validation. It does not authorize a
+  production PWA change unless the corrected experiment demonstrates a real
+  product defect.
 - [reports/v0.9-architecture-retrieval.md](reports/v0.9-architecture-retrieval.md)
   preserves the bounded current-source retrieval that grounded the v0.9 plan.
 

package/docs/RELEASE.md

@@ -1,7 +1,8 @@
 # Release
 
-`v0.9.0` (Human Visual Annotation and Design-Intent Capture) is released and
-published to npm as `@dailephd/my-frontend-observer`. The release adds
+`v0.9.1` (PWA Hard-Gate Isolation and Reproducible Security Acceptance) is
+released and published to npm as `@dailephd/my-frontend-observer`. This
+maintenance release adds
 structured visual annotation of runtime observations and external references
 to the project-aware viewer, selected promotion of confirmed runtime intent
 into canonical change contracts, and selected materialization of confirmed
@@ -14,7 +15,7 @@ independently from the npm package version.
 
 Observation, comparison, frontend contract, evaluation artifact,
 bounded-agent-context, external-reference, visual annotation, and package
-version all remain separate: package version is `0.9.0`; observation schema is
+version all remain separate: package version is `0.9.1`; observation schema is
 `1.2.0`, comparison schema is `1.0.0`, frontend contract schema is `1.0.0`,
 evaluation artifact schema is `1.0.0`, bounded-agent-context schema is
 `1.0.0`, external-reference schema is `1.0.0`, and visual annotation schema is

package/docs/ROADMAP.md

@@ -1,7 +1,10 @@
 # Roadmap
 
-v0.9 status: released as v0.9.0 and published to npm as
-`@dailephd/my-frontend-observer@0.9.0`. v0.10 remains future work.
+v0.9.1 status: released and published to npm as
+`@dailephd/my-frontend-observer@0.9.1`. It is a bounded maintenance patch that
+corrects the PWA hard-gate test-isolation defect discovered after the v0.9.0
+release. No production PWA regression has been demonstrated. v0.10 remains
+future work.
 
 This is a version-level specification, not an implementation checklist.
 Concrete steps and sequencing are designed only when a version begins, after
@@ -890,6 +893,55 @@ seven implementation prompts, and batch gates live in
 version-level decisions above plus current repository inspection; this roadmap
 intentionally does not duplicate batch-by-batch instructions.
 
+## v0.9.1 — PWA Hard-Gate Isolation and Reproducible Security Acceptance
+
+Current status: released as `0.9.1`. The concrete implementation plan remains
+frozen in `docs/plans/v0.9.1-implementation-plan.md`.
+This patch is maintenance work over the released v0.9.0 codebase and does not
+change the v0.9 product capability model.
+
+Objective/problem: make the PWA server-down hard acceptance proof genuinely
+self-contained. The released test in `tests/browser/pwaHardening.test.ts`
+passes in the normal full-file/full-suite order but fails when selected alone
+because it can inherit service-worker/cache state from earlier tests and from a
+fixed persistent Chromium profile. That is a test-isolation defect. It is not
+evidence that the released PWA serves stale evidence or otherwise violates the
+runtime safety contract.
+
+Required capabilities: the hard gate must create and own fresh disposable
+evidence state, a fresh viewer server, a fresh persistent Chromium profile, a
+fresh BrowserContext, and its page; independently establish service-worker
+registration and activation; prove that the current page is controlled by the
+worker; prove the application shell needed for offline reload is precached;
+prove `/api/` evidence responses are absent from Cache Storage; prove live
+evidence is visible before shutdown; prove the server/network is actually
+unavailable after shutdown; reload from the precached shell; then prove an
+explicit unavailable state is shown and previously fetched evidence is absent.
+All owned resources must be cleaned up even on failure.
+
+Constraints and contracts: the hard/security acceptance experiment must not
+depend on another `it()`, test order, a previously warmed Cache Storage, or a
+profile retained under `.my-dev-kit-workflow`. Tests explicitly designated
+`HARD GATE`, `SECURITY GATE`, or `ACCEPTANCE GATE` must be independently
+runnable from fresh state. The dedicated isolated hard-gate command and the
+normal full browser/security suites must exercise the same product behavior.
+
+Exclusions: no production PWA/service-worker semantic change is authorized
+merely to make the test green; no new user-facing feature, evidence schema,
+CLI command, package dependency, tutorial behavior, or v0.10 capability belongs
+in this patch. If the corrected clean-state experiment exposes a genuine
+runtime defect, implementation must stop and reclassify the work as a product
+defect before changing production behavior.
+
+Acceptance: the PWA hard gate passes when run by itself from a fresh process and
+fresh temporary profile, passes in the complete `pwaHardening.test.ts` file,
+and passes in the normal browser/security validation chain. The test must prove
+its own service-worker control, shell-cache, API-cache-exclusion, network-down,
+and stale-evidence-absence prerequisites rather than infer them from another
+test. Temporary browser profiles and evidence roots must be removed after both
+success and failure. Release-readiness validation must preserve the v0.9.0
+product/package behavior while proving the stronger test-isolation invariant.
+
 ## v0.10 — Full Visual Human–LLM Frontend Change Workflow
 
 Objective/problem: complete the visual communication branch by combining the

package/docs/WORKFLOWS.md

@@ -764,7 +764,7 @@ external-reference services.
 
 ## Current release workflow
 
-The published package is `@dailephd/my-frontend-observer@0.9.0`; install it
+The published package is `@dailephd/my-frontend-observer@0.9.1`; install it
 with npm and use the `my-frontend-observer` CLI. The ordinary workflow is
 `init`, `capture baseline`, `check baseline`, then `view`. Existing sections
 below retain the historical low-level and viewer workflows for compatibility.