my-frontend-observer 0.4.0 → 0.5.0

package/docs/COMMANDS.md

@@ -362,6 +362,168 @@ node dist/cli.js compare `
   --config-file .\comparison-config.json
 ```
 
+## `approve-baseline`
+
+**Current status: shipped as part of the published `my-frontend-observer@0.5.0`
+package.** Frontend contract schema is `1.0.0`, independent of the
+observation (`1.2.0`) and comparison (`1.0.0`) schemas.
+
+`my-frontend-observer approve-baseline` is the *only* baseline-approval
+operation in the observer — approval is never inferred from a successful
+comparison or evaluation, and no command automatically supersedes or selects
+a baseline. It explicitly approves and persists one already-authored
+`PersistentBaselineContract` against the observation it claims to approve:
+
+```text
+my-frontend-observer approve-baseline --observation <observation-artifact-root> --contract-file <json-file> --output <directory>
+```
+
+Required:
+
+- `--observation <path>` — root directory of the persisted observation
+  artifact this baseline claims to approve (read through the existing
+  observation-artifact reader).
+- `--contract-file <json-file>` — local JSON file containing one raw
+  `PersistentBaselineContract` (no wrapper field). As with `--config-file`,
+  only file readability/JSON-validity/non-array-object-root is checked here;
+  every structural rule (artifact kind, schema version, clause shape) is
+  enforced by the existing frozen domain validator.
+- `--output <directory>` — portable, relative output location for the
+  baseline artifact.
+
+Before persisting, the application layer verifies the contract's frozen
+`sourceObservation` reference (`observationId`, `requestId`, `producer`,
+`observationSchemaVersion`) actually matches the supplied observation
+artifact's stable identity — approving a baseline against an unrelated
+observation is rejected, even if both artifacts are individually valid. Any
+`supersedesBaselineId` already authored in the contract is preserved exactly
+as supplied; this command never discovers a prior baseline, infers
+supersession, or deletes anything.
+
+On success the command prints exactly:
+
+```text
+Baseline: <baseline-id>
+State: approved
+Artifact: <baseline-artifact-root>
+Clauses: <count>
+Supersedes: <baseline-id|none>
+```
+
+and exits `0`. It exits nonzero for invalid CLI syntax, an unreadable/
+malformed/structurally-invalid contract file, a `PerChangeContract` passed
+where a baseline is expected, a source-observation mismatch, an existing
+artifact collision (baseline identities are never overwritten), or a failed
+artifact write.
+
+## `save-change-contract`
+
+**Current status: shipped as part of the published `my-frontend-observer@0.5.0`
+package.**
+
+`my-frontend-observer save-change-contract` validates and persists one
+already-authored `PerChangeContract` so it can later be evaluated — this is
+persistence only, never approval:
+
+```text
+my-frontend-observer save-change-contract --contract-file <json-file> --output <directory>
+```
+
+Required:
+
+- `--contract-file <json-file>` — local JSON file containing one raw
+  `PerChangeContract` (no wrapper field).
+- `--output <directory>` — portable, relative output location for the
+  change-contract artifact.
+
+Domain/application validation rejects a `PersistentBaselineContract` passed
+here, malformed clauses, an unsupported authored category, an authored
+`category: "unexpected"` (the derived-only fifth classification can never be
+authored as a permission), and invalid tolerance/mode fields — none of this
+is duplicated in CLI code. Any `supersedesBaselineClauseIds` already
+authored on a clause is preserved exactly; resolving those references
+against a particular baseline remains `evaluate-contract`'s responsibility.
+
+On success the command prints exactly:
+
+```text
+Change contract: <contract-id>
+Artifact: <contract-artifact-root>
+Clauses: <count>
+Supersedes baseline clauses: <count>
+```
+
+and exits `0`. It exits nonzero for invalid CLI syntax, an unreadable/
+malformed/structurally-invalid contract file, a persistent baseline contract
+passed here, an existing artifact collision, or a failed artifact write.
+
+## `evaluate-contract`
+
+**Current status: shipped as part of the published `my-frontend-observer@0.5.0`
+package.** Frontend contract evaluation artifact schema is `1.0.0`, its own
+independent family.
+
+`my-frontend-observer evaluate-contract` executes the canonical Batch 2
+evaluator against already-persisted evidence/contracts and persists the
+result:
+
+```text
+my-frontend-observer evaluate-contract --before <observation-artifact-root> --after <observation-artifact-root> --comparison <comparison-artifact-root> --baseline <baseline-contract-artifact-root> --change <per-change-contract-artifact-root> --output <directory> [--enforce]
+```
+
+Required:
+
+- `--before <path>` / `--after <path>` — root directories of the persisted
+  before/after observation artifacts.
+- `--comparison <path>` — root directory of the already-persisted comparison
+  artifact for that before/after pair.
+- `--baseline <path>` — root directory of the already-approved baseline
+  contract artifact.
+- `--change <path>` — root directory of the already-persisted per-change
+  contract artifact.
+- `--output <directory>` — portable, relative output location for the
+  evaluation artifact.
+
+Options:
+
+- `--enforce` — makes a `FAIL` verdict produce a nonzero process exit
+  status. A `FAIL` evaluation is always persisted and printed identically
+  with or without this flag; `--enforce` changes only the process exit code
+  — never evaluation identity, contents, or persistence.
+
+**`evaluate-contract` never launches a browser, never re-resolves targets,
+and never recomputes comparison or relationship evidence** — it reads the
+already-persisted before/after observations and comparison exactly as given
+(through the existing observation-artifact reader and a new comparison
+reader) and calls the canonical `evaluateFrontendContract` exactly once.
+
+A `FAIL` verdict (a found regression or unsatisfied contract clause) is a
+successful, persisted evaluation outcome — not an execution error. On
+success (evaluation constructed and persisted, verdict `PASS`, or verdict
+`FAIL` without `--enforce`), the command prints exactly:
+
+```text
+Evaluation: <evaluation-id>
+Verdict: <PASS|FAIL>
+Artifact: <evaluation-artifact-root>
+Clauses: <total-clause-result-count>
+Unexpected: <unexpected-change-count>
+Enforced: <yes|no>
+```
+
+and exits `0`; with `--enforce` and verdict `FAIL`, it prints the same
+result and exits nonzero. It exits nonzero and persists nothing for invalid
+CLI syntax or an unreadable/malformed/incoherent source artifact (evaluation
+could not even be constructed) — distinct from a legitimate persisted `FAIL`.
+
+The evaluation artifact directory contains `manifest.json` only — no
+screenshot is copied. Operational `--before`/`--after`/`--comparison`/
+`--baseline`/`--change`/`--output` paths never enter the persisted
+`evaluationRequestId` or any other semantic field; two semantically
+identical evaluations invoked from different filesystem locations share the
+same `evaluationRequestId` even though each execution gets a fresh
+`evaluationId`.
+
 ## Foundation commands
 
 - `npm install` — install dependencies (includes the `playwright` runtime

package/docs/CONTRACTS.md

@@ -2,7 +2,7 @@
 
 ## Current contracts
 
-The observation artifact contract is published as `my-frontend-observer@0.4.0`
+The observation artifact contract is published as `my-frontend-observer@0.5.0`
 and proven both from the source checkout and from the packed npm tarball,
 on Windows, Linux, and macOS. The observation schema is `1.2.0` (see "v0.2
 target contract" and "v0.3 scroll scenario contract" below):
@@ -250,6 +250,175 @@ The public entry point is `my-frontend-observer compare --before <root>
 --after <root> --output <directory> [--config-file <json-file>]` (see
 `docs/COMMANDS.md`) - comparison itself never launches a browser.
 
+## v0.5 frontend contract and evaluation (shipped as part of this release)
+
+Downstream of the v0.4 observation/comparison/relationship evidence above,
+`src/domain/frontendContracts.ts` freezes the v0.5 contract/change-scope
+model, `src/domain/frontendContractIdentity.ts` freezes deterministic
+contract/baseline/clause identity, and `src/domain/frontendContractEvaluation.ts`
+implements the one canonical pure evaluation engine. Baseline/per-change
+contract persistence, evaluation-artifact persistence, explicit baseline
+approval, and public CLI exposure are all implemented and shipped (see
+"v0.5 contract and evaluation persistence" and "v0.5 public contract/
+evaluation commands" below).
+
+**Contract classes**: a `PersistentBaselineContract` (append/supersession-based
+history via an optional `supersedesBaselineId`) and a `PerChangeContract`
+(the allowed scope of one requested change). Both share `artifactKind:
+"my-frontend-observer/frontend-contract"` and `schemaVersion: "1.0.0"` - an
+independent family from the observation (`1.2.0`) and comparison (`1.0.0`)
+schemas; the frontend-contract schema constant happens to share the version
+string `1.0.0` with comparison's by coincidence only.
+
+**Four authored categories, one derived classification**: every per-change
+clause is authored as exactly one of `requested`, `expected-dependent`,
+`protected`, or `preserved`. `unexpected` is a fifth, *derived-only*
+classification the evaluator produces for a meaningful rendered difference no
+active clause accounts for - it can never be authored as a permission.
+
+**Bounded contract primitives**: 15 frozen `ContractPrimitive` kinds cover
+visibility, clipping, width bounds, non-overlap, relative width, vertical
+sequence, geometric fit (explicitly distinct from DOM containment),
+document-width-vs-viewport, scroll ownership, initial-viewport position,
+relationship-unchanged, and property-unchanged/increases/decreases - a closed
+vocabulary, never a generic expression language.
+
+**Contract tolerance**: `exact` / `absolute-px` / `percent`, independent of
+`ComparisonConfig.geometryTolerancePx` (which only suppresses insignificant
+comparison noise and is never contract authorization). Percent tolerance's
+denominator is the absolute before-value.
+
+**Required vs. permitted expected-dependent**: `required` clauses must occur
+compliantly to pass; `permitted` clauses accept no change or a compliant
+change, and fail only on a strictly contradictory change.
+
+**Evaluation result vocabulary**: each clause resolves to `pass` / `fail` /
+`unavailable` (with a required non-empty reason - required evidence gaps and
+an `incomparable` source comparison never fabricate a `pass`) / `conflict`
+(with at least two `conflictingClauseIds` - covers both an unresolved
+baseline/per-change contradiction and an unknown `supersedesBaselineClauseIds`
+reference). The overall verdict is `PASS` only when every clause result is
+`pass` and no unexpected change remains; otherwise `FAIL` - there is no
+partial-pass scoring.
+
+**Explicit supersession, never inferred**: a per-change clause may list
+`supersedesBaselineClauseIds` to remove specific baseline clauses from active
+evaluation. Two clauses that structurally contradict each other on the same
+(target, property) without explicit supersession produce a `conflict`, never
+a silent preference for one side.
+
+**Reuses existing v0.4 evidence directly**: the evaluator consumes an
+already-computed `ComparisonArtifact` (`differences`, `relationshipChanges`,
+`relationshipsBefore`/`relationshipsAfter`, `comparability`) and the source
+`ObservationArtifact` pair - it never re-launches a browser, re-resolves a
+target, or reimplements clipping/relationship/scroll-owner derivation.
+Unexpected-change derivation reads `ComparisonArtifact.differences` only
+(which already includes one difference per relationship change), so a single
+logical transition is never double-counted.
+
+## v0.5 contract and evaluation persistence (shipped as part of this release)
+
+Persistence consumes the frozen v0.5 domain above; it never redefines it.
+`src/artifacts/frontendContractArtifactWriter.ts`/`frontendContractArtifactReader.ts`
+persist and read both `PersistentBaselineContract` and `PerChangeContract`
+symmetrically (both already share `CONTRACT_ARTIFACT_KIND`/`CONTRACT_SCHEMA_VERSION`,
+so one writer/reader pair serves both contract classes) as
+`<outputLocation>/<baselineId|contractId>/manifest.json`, following the same
+atomic-write discipline as `artifacts/artifactWriter.ts`/`artifacts/comparisonArtifactWriter.ts`
+(sibling temporary directory, then one atomic rename; an existing directory at
+the final identity is a genuine collision and is rejected, never overwritten -
+prior baseline history is never rewritten). `src/artifacts/comparisonArtifactReader.ts`
+is a new Batch 3 addition (no comparison reader existed before) mirroring
+`artifacts/artifactReader.ts`'s discipline exactly, changing no comparison
+semantics and keeping comparison schema `1.0.0`.
+
+**Evaluation artifact envelope**: Batch 1 froze the evaluation-result
+vocabulary (`ClauseEvaluationResult`, `OverallVerdict`) but not a persistable
+envelope, so `src/domain/frontendContractEvaluationArtifact.ts` adds exactly
+that - `artifactKind: "my-frontend-observer/frontend-contract-evaluation"`,
+`schemaVersion: "1.0.0"` (its own independent family, distinct from
+observation/comparison/frontend-contract), an `evaluationId`/`evaluationRequestId`
+pair, bounded `before`/`after` source-observation references, and
+`comparisonId`/`comparisonRequestId` plus `contracts: {baselineId,
+contractId}` references - never an embedded `ObservationArtifact` or copied
+screenshot. It reuses `ClauseEvaluationResult`/`OverallVerdict`/
+`UnexpectedChangeResult` unchanged and contains no evaluation logic itself.
+`evaluationRequestId` is a deterministic function of `{baselineId,
+contractId, beforeObservationId, afterObservationId, comparisonRequestId}`
+(`frontendContractIdentity.ts#buildFrontendContractEvaluationRequestIdentity` -
+deliberately `comparisonRequestId`, not the fresh-per-execution
+`comparisonId`, so semantically identical evaluations share an identity);
+`evaluationId` reuses the existing generic `buildFrontendContractInstanceIdentity`
+unchanged. `src/artifacts/frontendContractEvaluationArtifactWriter.ts`/
+`frontendContractEvaluationArtifactReader.ts` persist/read it with the same
+atomic-write discipline as above.
+
+**Application seam**: `src/application/frontendContractEvaluationService.ts#evaluateAndPersist`
+calls the existing pure `evaluateFrontendContract` exactly once and - only
+for a structurally constructible result, whether the verdict is `PASS` or
+`FAIL` - persists exactly one evaluation artifact; an `{ok: false}` evaluator
+result (evidence could not be constructed into an evaluation at all) is never
+persisted as a fabricated artifact. `evaluateAndPersistFromArtifactRoots` is
+the future-CLI-facing wrapper: it reads two observations through the existing
+`readObservationArtifact` (never a second observation reader), the
+comparison and the two contracts through the readers above, then delegates
+to `evaluateAndPersist` exactly once.
+
+## v0.5 public contract/evaluation commands (shipped as part of this release)
+
+Three public commands expose the persistence/evaluation contract above (see
+`docs/COMMANDS.md` for exact flags/output/exit behavior, not duplicated
+here):
+
+- `approve-baseline` → `frontendContractPersistenceService.ts#approveAndPersistBaseline`
+  → validates a `PersistentBaselineContract` and its `sourceObservation`
+  coherence against a supplied observation artifact → persists via
+  `frontendContractArtifactWriter.ts`. The only baseline-approval act in the
+  observer.
+- `save-change-contract` → `frontendContractPersistenceService.ts#persistPerChangeContract`
+  → validates a `PerChangeContract` (rejecting a baseline contract, an
+  authored `unexpected` category, or any other structural violation) →
+  persists via the same writer. Persistence only, never approval.
+- `evaluate-contract` → `frontendContractEvaluationService.ts#evaluateAndPersistFromArtifactRoots`
+  → `evaluateFrontendContract` exactly once → `frontendContractEvaluationArtifactWriter.ts`
+  exactly once. `--enforce` affects only the process exit status for an
+  already-persisted `FAIL` verdict.
+
+No command infers baseline approval or supersession automatically - not
+`compare`, not a `PASS` evaluation, not any artifact writer.
+
+This full command sequence is proven against real Chromium observations (not
+hand-constructed artifacts) - see "v0.5 real-browser workflow proof" below.
+
+## v0.5 real-browser workflow proof (shipped as part of this release)
+
+`tests/browser/cliFrontendContracts.test.ts` and
+`scripts/dev/builtCliFrontendContractsBrowserSmoke.mjs` drive the complete
+`observe` → `approve-baseline` → `save-change-contract` → `observe` →
+`compare` → `evaluate-contract` sequence against a real disposable local HTTP
+fixture and real Chromium, proving two scenarios:
+
+- a fully successful contract change - a real observed navigation-width
+  decrease and workspace-width increase, both satisfying their authored
+  `requested`/`expected-dependent` clauses, an unchanged `protected` rail
+  width, and an unclipped `preserved` navigation - overall `PASS`;
+- the "milestone signature" failure - the same locally successful requested
+  change (navigation shrinks, workspace expands, both still `pass`)
+  co-occurring with a genuine `protected` right-rail width regression (a real
+  `resized` comparison difference) and a genuine `preserved` navigation
+  clipping regression (a real `clipping-changed` difference, `not-clipped` →
+  `clipped`) - overall `FAIL`.
+
+Both scenarios confirm: `--enforce` changes only the process exit status
+(`0` without it, nonzero with it) for the identical persisted
+`evaluationRequestId`/`clauseResults`; every source observation and
+comparison artifact is byte-identical before and after evaluation; the
+evaluation directory contains `manifest.json` only (no copied screenshot);
+and no operational filesystem path is ever serialized into a persisted
+manifest. This is real-browser evidence layered on top of the CLI-level
+proof in `tests/unit/cliFrontendContracts.test.ts` and the Chromium-free
+`scripts/dev/builtCliFrontendContractsSmoke.mjs` - it does not replace them.
+
 ## Approved v0.1 design inputs
 
 The historical greenfield scaffold plan recorded these v0.1 design decisions:
@@ -269,7 +438,10 @@ the file layout: there is no separate `evidence.json` - page/target evidence
 is embedded directly inside `manifest.json`.
 
 Comparison and relationship contracts belong to v0.4, and canonical
-change-scope contracts belong to v0.5. Bounded agent-context plus ecosystem
-integration contracts move to v0.6, followed by the text/config-driven
+change-scope contracts belong to v0.5 - see "v0.5 frontend contract and
+evaluation" above for the full shipped contract model, identity, evaluation
+engine, persistence, baseline approval, and CLI exposure.
+Bounded agent-context plus ecosystem integration contracts move to v0.6,
+followed by the text/config-driven
 coding-agent review contract in v0.7. Viewer and annotation contracts follow in
 v0.8 and v0.9 and converge with the existing workflow in v0.10.

package/docs/CURRENT_STATE.md

@@ -1,8 +1,9 @@
 # Current State
 
-The project is published at package version `0.4.0` (roadmap v0.4, Layout
-Relationships, Dependency Evidence, and Before/After Comparison; observation
-schema `1.2.0`; comparison schema `1.0.0`).
+The project is published at package version `0.5.0` (roadmap v0.5,
+Executable Frontend Contracts and Explicit Change Scope; observation schema
+`1.2.0`; comparison schema `1.0.0`; frontend contract schema `1.0.0`;
+evaluation artifact schema `1.0.0`).
 
 ## Greenfield foundation established
 
@@ -314,15 +315,96 @@ evidence, comparison persistence, and public `compare` CLI are all
 implemented, exercised end-to-end, packed-validated cross-platform, and
 released.
 
+v0.5 frontend contract model, identity, and evaluation engine are released
+as part of `0.5.0`: `src/domain/frontendContracts.ts` (persistent baseline /
+per-change contract types, the four authored change-scope categories plus
+the derived `unexpected` classification, the 15-primitive bounded
+vocabulary, contract tolerance, and the clause-result/overall-verdict
+vocabulary), `src/domain/frontendContractIdentity.ts` (deterministic
+contract/baseline/clause identity), and
+`src/domain/frontendContractEvaluation.ts#evaluateFrontendContract`
+(the one canonical pure evaluator: active-baseline/supersession calculation,
+bounded conflict detection, per-category clause evaluation, difference-to-
+scope matching, unexpected-change derivation, and overall PASS/FAIL) - all
+covered by focused unit tests. Observation schema stays `1.2.0`, comparison
+schema stays `1.0.0`.
+
+v0.5 contract and evaluation persistence are also released as part of
+`0.5.0`: `src/artifacts/frontendContractArtifactWriter.ts`/`frontendContractArtifactReader.ts`
+(symmetric baseline/per-change contract persistence, atomic write, no
+overwrite of existing history), `src/artifacts/comparisonArtifactReader.ts`
+(new - no comparison reader existed before this batch; comparison schema
+still `1.0.0`), `src/domain/frontendContractEvaluationArtifact.ts` (minimal
+additive persisted envelope around the frozen evaluation-result vocabulary,
+its own independent schema family `1.0.0`) with
+`src/artifacts/frontendContractEvaluationArtifactWriter.ts`/`...Reader.ts`,
+and `src/application/frontendContractEvaluationService.ts#evaluateAndPersist`/
+`evaluateAndPersistFromArtifactRoots` (calls `evaluateFrontendContract`
+exactly once, persists exactly one evaluation artifact for both `PASS` and
+`FAIL` verdicts, never persists a fabricated artifact when evaluation
+construction itself fails). `evaluateFrontendContract` itself is unmodified.
+
+v0.5 public contract/baseline-approval/evaluation CLI is also released as
+part of `0.5.0`:
+`approve-baseline` (the only baseline-approval act - explicit only, never
+inferred from `compare` or a `PASS` evaluation; verifies the contract's
+`sourceObservation` matches the supplied observation before persisting),
+`save-change-contract` (persistence only), and `evaluate-contract`
+(evaluates already-persisted before/after/comparison/baseline/change
+evidence exactly once and persists exactly one evaluation artifact;
+`--enforce` makes a `FAIL` verdict exit nonzero without changing the
+verdict, its identity, or its persisted content - a `FAIL` without
+`--enforce` still exits `0`). `src/application/frontendContractPersistenceService.ts`
+adds the two new thin application seams (`approveAndPersistBaseline`,
+`persistPerChangeContract`); `src/cli.ts` gained no browser or artifact-
+writer import. Covered by `tests/unit/cliFrontendContracts.test.ts` and the
+Chromium-free `scripts/dev/builtCliFrontendContractsSmoke.mjs` dev smoke.
+Observation schema `1.2.0`; comparison schema `1.0.0`; frontend contract
+schema `1.0.0`; evaluation artifact schema `1.0.0` - no schema was bumped
+to add this CLI.
+
+v0.5 proved the complete public contract workflow (`observe` →
+`approve-baseline` → `save-change-contract` → `observe` → `compare` →
+`evaluate-contract`) against real Chromium observations, not hand-constructed
+artifacts: a fully successful contract change (all clauses `pass`, overall
+`PASS`), and the "milestone signature" case - a locally successful requested
+change (navigation shrinks, workspace expands, both real and both `pass`)
+coexisting with a genuine protected-property regression (real right-rail
+`resized` difference) and a genuine preserved-invariant regression (real
+`clipping-changed` difference, `not-clipped` → `clipped`) - producing overall
+`FAIL`. Both scenarios are covered by `tests/browser/cliFrontendContracts.test.ts`
+(real Chromium, via `tests/fixtures/server.ts`'s new `/contract` route) and by
+the built-CLI dev smoke `scripts/dev/builtCliFrontendContractsBrowserSmoke.mjs`
+(the built `dist/cli.js`, not the imported `runCli()`, against its own
+disposable local HTTP fixture). Both confirm `--enforce` behavior (`FAIL`
+persists and exits `0` without it, exits nonzero with it, identical
+`evaluationRequestId` and `clauseResults` in both cases), full source
+observation/comparison immutability, no screenshot copied into the
+evaluation artifact, and no operational filesystem path leaked into any
+persisted manifest.
+
+The packed-readiness coverage gap this left (`V0_5_READINESS_VALIDATION_GAP_EXISTS`)
+was corrected and proven cross-platform before release:
+`scripts/ci/runPackedObservationSmoke.mjs` also exercises the installed
+packed candidate's `approve-baseline`/`save-change-contract`/
+`evaluate-contract` commands against real installed-candidate `observe`/
+`compare` evidence, proving the same successful-change and milestone-
+signature scenarios through the installed tarball rather than the source
+checkout. v0.5 pre-release readiness passed on the validation branch
+`validation/v0.5-pre-release` (GitHub Actions run `31727856546`, one shared
+hash-verified candidate tarball on Windows, Linux, and macOS - see
+`docs/CI_CD.md` for full evidence) before the version `0.5.0` release below.
+
 ## Not implemented
 
-- v0.5+ frontend contracts/change scope (baseline approval, requested/
-  protected/preserved change scope, PASS/FAIL verdicts), source ownership,
-  my-dev-kit runtime/static integration, orchestrator/lab product
-  integration, viewer, and annotation all remain unimplemented.
+- v0.5 baseline-selection/discovery policy (the caller must supply which
+  baseline to approve/evaluate against; there is no "find the current
+  baseline" command), source ownership, my-dev-kit runtime/static
+  integration, orchestrator/lab product integration, viewer, and annotation
+  all remain unimplemented.
 
 ## Next target
 
-v0.1-v0.4 are implemented, validated, and released (`0.1.0`, `0.2.0`,
-`0.3.0`, `0.4.0`). v0.5 (Executable Frontend Contracts and Explicit Change
-Scope) is next.
+v0.1-v0.5 are implemented, validated, and released (`0.1.0`, `0.2.0`,
+`0.3.0`, `0.4.0`, `0.5.0`). v0.6 (Bounded Agent Context and Native
+my-dev-kit Ecosystem Integration) is next.

package/docs/DEVELOPMENT.md

@@ -21,9 +21,9 @@ npm run check:docs
 npm pack --dry-run
 ```
 
-`npm test` runs the fast unit suite only (`tests/unit/`, currently 176
+`npm test` runs the fast unit suite only (`tests/unit/`, currently 515
 passing tests). `npm run test:browser` runs the real-Chromium integration
-suite (`tests/browser/`, currently 88 passing tests) against deterministic
+suite (`tests/browser/`, currently 120 passing tests) against deterministic
 local fixtures under `tests/fixtures/` and requires the Chromium binary
 above to be installed first; it is kept out of `npm test` because it
 launches a real browser and is slower.
@@ -114,13 +114,61 @@ before and after the comparison ran. Run it locally after `npm run build`:
 node scripts/dev/builtCliCompareSmoke.mjs
 ```
 
-Unlike `scripts/ci/runPackedObservationSmoke.mjs`, none of these three dev
+`scripts/dev/builtCliFrontendContractsSmoke.mjs` is the v0.5 equivalent,
+added alongside the `approve-baseline`/`save-change-contract`/
+`evaluate-contract` command implementations (shipped as part of the
+published `0.5.0` package - see `docs/CURRENT_STATE.md`). Unlike the other dev smokes, it needs no Chromium
+at all: it hand-writes deterministic, schema-`1.2.0`-valid observation
+manifests directly to a temporary directory (preserving the public
+observation artifact contract without a real browser capture), then runs
+the built `dist/cli.js` for `compare`, `approve-baseline`,
+`save-change-contract`, and `evaluate-contract` - twice for the final
+step, once without `--enforce` and once with it, against the same
+milestone-signature contract (requested navigation shrink = pass, expected
+workspace expansion = pass, protected right-rail width = fail, preserved
+unclipped navigation = fail, overall = `FAIL`). It validates both exit
+codes (`0` without `--enforce`, nonzero with it), that both invocations
+persist byte-for-byte semantically identical evaluation evidence
+(`evaluationRequestId` and `clauseResults` equal), that the evaluation
+directory contains `manifest.json` only, that no operational filesystem
+path leaked into either persisted evaluation manifest, and that every
+source observation/comparison/contract artifact remains unmodified. Run it
+locally after `npm run build`:
+
+```powershell
+node scripts/dev/builtCliFrontendContractsSmoke.mjs
+```
+
+`scripts/dev/builtCliFrontendContractsBrowserSmoke.mjs` is the v0.5 Batch 5
+real-browser equivalent, added alongside
+`tests/browser/cliFrontendContracts.test.ts`. Unlike the Chromium-free
+`scripts/dev/builtCliFrontendContractsSmoke.mjs` above, this one launches a
+real disposable local HTTP fixture and real Playwright Chromium, then drives
+the built `dist/cli.js` through the complete `observe` → `approve-baseline`
+→ `save-change-contract` → `observe` → `compare` → `evaluate-contract`
+sequence twice: once against a candidate whose served content produces a
+fully successful contract change (all clauses `pass`, overall `PASS`), and
+once against a candidate that reproduces the milestone-signature failure - a
+real observed navigation clipping regression and a real observed right-rail
+width regression alongside an otherwise-successful requested/expected-
+dependent change (overall `FAIL`). It validates the same `--enforce`
+exit-code/identity behavior, screenshot-free evaluation directory, source
+immutability, and path-privacy properties as the Chromium-free smoke, but
+against genuine rendered geometry instead of hand-constructed artifacts. Run
+it locally after `npm run build` (Chromium must already be installed):
+
+```powershell
+node scripts/dev/builtCliFrontendContractsBrowserSmoke.mjs
+```
+
+Unlike `scripts/ci/runPackedObservationSmoke.mjs`, none of these five dev
 smokes is wired into any CI workflow or is a release gate - they are
 source-checkout development evidence only, proving the built CLI's
-`--targets-file`/`--scroll-scenario-file`/`compare` behavior without
-installing a packed tarball or requiring cross-platform infrastructure.
-None is part of the published package. Cross-platform packed validation of
-both the v0.1-v0.3 observation behavior and the v0.4 `compare` command is
-`scripts/ci/runPackedObservationSmoke.mjs`'s responsibility (see
-`docs/CI_CD.md`) - the same script, against the same single candidate
-tarball per platform.
+`--targets-file`/`--scroll-scenario-file`/`compare`/frontend-contract
+command behavior without installing a packed tarball or requiring
+cross-platform infrastructure. None is part of the published package.
+Cross-platform packed validation of the v0.1-v0.5 observation/compare/
+contract behavior is `scripts/ci/runPackedObservationSmoke.mjs`'s
+responsibility (see `docs/CI_CD.md`) - the same script, against the same
+single candidate tarball per platform, now including the v0.5 contract/
+evaluation CLI.

package/docs/PROJECT_OVERVIEW.md

@@ -17,19 +17,25 @@ The responsibility split is stable:
 
 v0.1, Runtime Observation Foundation; v0.2, Stable Semantic Targets and
 Region Identity; v0.3, Runtime Scrolling, Overflow, and Visibility Behavior;
-and v0.4, Layout Relationships, Dependency Evidence, and Before/After
-Comparison, are released, published to npm (current version `0.4.0`,
-observation schema `1.2.0`, comparison schema `1.0.0`) and validated as a
-packed npm tarball in a clean consumer environment across Windows, Linux,
-and macOS: a real `observe` CLI command launches Chromium, enforces
-loopback-only safety, captures bounded page/target evidence via legacy
-CSS-shorthand targets, structured semantic `--targets-file` targets, or a
-bounded `--scroll-scenario-file` runtime scroll scenario
-(`window-scroll-by` or `target-scroll-by`), and persists one portable local
-artifact; a real `compare` CLI command reads two already-persisted
-observation artifacts and derives before/after layout-relationship and
-difference evidence without launching a browser - see
-`docs/CURRENT_STATE.md` for the implementation summary. v0.5–v0.10 remain
+v0.4, Layout Relationships, Dependency Evidence, and Before/After
+Comparison; and v0.5, Executable Frontend Contracts and Explicit Change
+Scope, are released, published to npm (current version `0.5.0`, observation
+schema `1.2.0`, comparison schema `1.0.0`, frontend contract schema `1.0.0`,
+evaluation artifact schema `1.0.0`) and validated as a packed npm tarball in
+a clean consumer environment across Windows, Linux, and macOS: a real
+`observe` CLI command launches Chromium, enforces loopback-only safety,
+captures bounded page/target evidence via legacy CSS-shorthand targets,
+structured semantic `--targets-file` targets, or a bounded
+`--scroll-scenario-file` runtime scroll scenario (`window-scroll-by` or
+`target-scroll-by`), and persists one portable local artifact; a real
+`compare` CLI command reads two already-persisted observation artifacts and
+derives before/after layout-relationship and difference evidence without
+launching a browser; and the public `approve-baseline`/`save-change-contract`/
+`evaluate-contract` commands turn a persistent baseline contract plus a
+per-change contract (requested/expected-dependent/protected/preserved scope,
+plus the derived-only `unexpected` classification) into one canonical
+`PASS`/`FAIL` evaluation, proven against real Chromium observations - see
+`docs/CURRENT_STATE.md` for the implementation summary. v0.6–v0.10 remain
 future and unimplemented.
 
 The revised dependency path reaches practical coding-agent use before graphical

package/docs/QUICKSTART.md

@@ -30,6 +30,11 @@ Once you have two such artifacts, `node dist/cli.js compare --before
 between them without launching a browser again - see
 [COMMANDS.md](COMMANDS.md#compare) for details.
 
+You can then approve a baseline, save a per-change contract, and evaluate a
+candidate change against them plus the observation/comparison evidence
+above - see [COMMANDS.md](COMMANDS.md#approve-baseline) for the exact flags
+and [WORKFLOWS.md](WORKFLOWS.md) for the full flow.
+
 To validate the repository itself instead:
 
 ```powershell