my-frontend-observer 0.4.0 → 0.5.0

package/docs/RELEASE.md

@@ -1,18 +1,25 @@
 # Release
 
-`v0.4.0` is published to npm as `my-frontend-observer`, validated on
+`v0.5.0` is published to npm as `my-frontend-observer`, validated on
 Windows, Linux, and macOS as an installed packed-tarball consumer prior to
 publication (covering the legacy CSS-shorthand `--target` path, the
 structured semantic `--targets-file` path, the bounded
 `--scroll-scenario-file` `window-scroll-by`/`target-scroll-by` runtime
-scroll scenario path, and the installed `compare` command's comparable and
-incomparable cases). No project license has been declared yet; that
-decision remains open for a later explicit task.
+scroll scenario path, the installed `compare` command's comparable and
+incomparable cases, and the installed `approve-baseline`/
+`save-change-contract`/`evaluate-contract` frontend contract commands -
+including both a fully successful contract change and the milestone-
+signature failure, with `--enforce` exit-status behavior). No project
+license has been declared yet; that decision remains open for a later
+explicit task.
 
-Observation, comparison, and package version remain separate: package
-version is `0.4.0`; observation schema is `1.2.0` and comparison schema is
-`1.0.0`, neither of which changes automatically with the package version.
+Observation, comparison, frontend contract, evaluation artifact, and package
+version all remain separate: package version is `0.5.0`; observation schema
+is `1.2.0`, comparison schema is `1.0.0`, frontend contract schema is
+`1.0.0`, and evaluation artifact schema is `1.0.0` - none of which changes
+automatically with the package version.
 
-Prior releases: `v0.3.0` (Runtime Scrolling, Overflow, and Visibility
-Behavior), `v0.2.0` (Stable Semantic Targets and Region Identity), `v0.1.0`
-(Runtime Observation Foundation) - see `CHANGELOG.md`.
+Prior releases: `v0.4.0` (Layout Relationships, Dependency Evidence, and
+Before/After Comparison), `v0.3.0` (Runtime Scrolling, Overflow, and
+Visibility Behavior), `v0.2.0` (Stable Semantic Targets and Region
+Identity), `v0.1.0` (Runtime Observation Foundation) - see `CHANGELOG.md`.

package/docs/ROADMAP.md

@@ -94,6 +94,12 @@ Planning must settle comparability and tolerance semantics.
 
 ## v0.5 — Executable Frontend Contracts and Explicit Change Scope
 
+Current status: released as `0.5.0`, published to npm and validated as a
+packed npm tarball in a clean consumer environment on Windows, Linux, and
+macOS (observation schema `1.2.0`, comparison schema `1.0.0`, frontend
+contract schema `1.0.0`, evaluation artifact schema `1.0.0`). See
+`docs/CURRENT_STATE.md` for the implementation summary.
+
 Objective/problem: prevent a requested local fix from silently breaking an
 approved region or invariant. Required capabilities are baseline invariants,
 requested/expected-dependent/protected/preserved classifications, explicit

package/docs/SECURITY.md

@@ -37,12 +37,24 @@ comparison, and writes one local comparison `manifest.json`
 as JSON only and is never executed (no `eval`, no dynamic code loading from
 a manifest).
 
+## Frontend contracts (`approve-baseline`/`save-change-contract`/`evaluate-contract`, shipped as part of the published `0.5.0` package)
+
+These three commands introduce no new browser or network surface:
+`src/application/frontendContractPersistenceService.ts` and
+`src/application/frontendContractEvaluationService.ts` import nothing from
+`src/browser/` and never launch Chromium. `approve-baseline` and
+`save-change-contract` validate and persist a local JSON contract file
+(parsed as JSON only, never executed); `evaluate-contract` reads
+already-persisted local observation/comparison/contract artifacts and runs
+the pure `evaluateFrontendContract` function. None of the three navigates,
+re-observes a target, or contacts a network resource.
+
 ## Not yet addressed
 
 Certificate-failure-specific handling, permission-prompt-specific handling
 (Chromium's default deny-all applies; no permission is ever explicitly
 granted), and any non-loopback/remote browsing mode remain unimplemented and
-out of scope. `my-frontend-observer@0.4.0` is published to npm, and a
+out of scope. `my-frontend-observer@0.5.0` is published to npm, and a
 pre-release readiness CI workflow (Windows/Linux/macOS packed-candidate
 validation) already exists (see `docs/CI_CD.md`); these are no longer future
 decisions. Those facts do not expand the security scope above: remote

package/docs/WORKFLOWS.md

@@ -11,9 +11,9 @@ install dependencies (npm install; npx playwright install chromium)
 → validate documentation (npm run check:docs)
 ```
 
-## Current observation workflow (published as 0.4.0)
+## Current observation workflow (published as 0.5.0)
 
-The real `observe` workflow, part of the published `my-frontend-observer@0.4.0`
+The real `observe` workflow, part of the published `my-frontend-observer@0.5.0`
 package, accepts target configuration through either of two input paths,
 plus one optional runtime scroll scenario:
 
@@ -62,10 +62,10 @@ temporary consumer directory outside the repository, on Windows, Linux, and
 macOS (`scripts/ci/runPackedObservationSmoke.mjs`) - the same workflow,
 independent of the source checkout.
 
-## Current comparison workflow (published as 0.4.0)
+## Current comparison workflow (published as 0.5.0)
 
 **Current status: shipped as part of the published `my-frontend-observer@0.4.0`
-package.** This is a separate workflow from the observation workflow above -
+package (unchanged in `0.5.0`).** This is a separate workflow from the observation workflow above -
 it consumes two already-persisted observation artifacts rather than
 producing one, and it never launches a browser:
 
@@ -110,12 +110,69 @@ fixture (`scripts/dev/builtCliCompareSmoke.mjs`), and packed-tarball
 validation of the installed `compare` command
 (`scripts/ci/runPackedObservationSmoke.mjs` - see `docs/CI_CD.md`).
 
+## Current frontend contract workflow (published as 0.5.0)
+
+This is a text/config-driven workflow layered downstream of the two
+workflows above - it does not replace them, and it is not yet the complete
+v0.7 coding-agent workflow (no bounded agent context, no automatic
+baseline selection, no CLI-level approval policy beyond the explicit
+`approve-baseline` act):
+
+```text
+observe before
+observe after
+compare
+        ↓
+approve baseline (approve-baseline --observation <before-root>
+  --contract-file <PersistentBaselineContract.json> --output <dir>)
+        ↓
+save per-change contract (save-change-contract
+  --contract-file <PerChangeContract.json> --output <dir>)
+        ↓
+evaluate contract (evaluate-contract --before <root> --after <root>
+  --comparison <root> --baseline <root> --change <root> --output <dir>
+  [--enforce])
+        ↓
+persisted evaluation artifact (schema 1.0.0, its own independent family):
+  clause results (pass/fail/unavailable/conflict), unexpected changes,
+  overall PASS/FAIL
+```
+
+`approve-baseline` is the only baseline-approval act; a successful `compare`
+or a `PASS` evaluation never approves or supersedes a baseline
+automatically. `evaluate-contract` never launches a browser and never
+recomputes comparison/relationship evidence - it calls the canonical
+`evaluateFrontendContract` exactly once against the supplied evidence and
+persists exactly one evaluation artifact, whether the verdict is `PASS` or
+`FAIL`. `--enforce` affects only the process exit status for a `FAIL`
+verdict, never the persisted evidence itself.
+
+This is exercised by `runCli()`-level tests
+(`tests/unit/cliFrontendContracts.test.ts`), a built `node dist/cli.js`
+smoke that needs no Chromium
+(`scripts/dev/builtCliFrontendContractsSmoke.mjs`), a real-Chromium
+end-to-end test (`tests/browser/cliFrontendContracts.test.ts`), and a
+real-Chromium built-CLI smoke
+(`scripts/dev/builtCliFrontendContractsBrowserSmoke.mjs` - see
+`docs/DEVELOPMENT.md`). The real-browser coverage proves both a fully
+successful contract change and the "milestone signature" failure (a locally
+successful requested change coexisting with a genuine protected-property
+regression and a genuine preserved-invariant regression) against actual
+rendered geometry, not hand-constructed artifacts. It is also part of
+packed-tarball validation: `scripts/ci/runPackedObservationSmoke.mjs`
+exercises the installed candidate's `approve-baseline`/`save-change-contract`/
+`evaluate-contract` commands against real installed-candidate `observe`/
+`compare` evidence, proven on Windows, Linux, and macOS (see
+`docs/CI_CD.md`).
+
 ## Future workflows
 
 ```text
 stable targets and bounded runtime behavior
 → relationships and before/after comparison (released - see above)
-→ safe-change contracts
+→ safe-change contracts (contract model, evaluation, persistence, and CLI
+  released as 0.5.0 - see above; baseline approval remains a single explicit
+  command, not a policy engine)
 → bounded agent context plus runtime/static ecosystem integration
 → text/config-driven coding-agent change review
 → interactive viewer
@@ -123,6 +180,6 @@ stable targets and bounded runtime behavior
 → full visual human–LLM workflow
 ```
 
-Safe-change contracts (v0.5+) and everything after remain unimplemented. The
-v0.7 coding-agent workflow must work without the v0.8 viewer or v0.9
-annotation system.
+Bounded agent context, ecosystem integration, and everything after remain
+unimplemented. The v0.7 coding-agent workflow must work without the v0.8
+viewer or v0.9 annotation system.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "my-frontend-observer",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Local-first browser runtime evidence producer",
   "type": "module",
   "repository": {