my-frontend-observer 0.3.0 → 0.5.0

package/docs/ARCHITECTURE.md

@@ -3,7 +3,7 @@
 ## Current scaffold architecture
 
 The current repository is one published TypeScript ESM package
-(`my-frontend-observer@0.3.0`):
+(`my-frontend-observer@0.5.0`):
 
 - `src/cli.ts` is the real, thin `observe` command entry point (argument
   parsing/output only).
@@ -45,8 +45,8 @@ Playwright or the filesystem-write path directly. Batch 6 closed the
 remaining real-Chromium coverage gap (a genuine navigation failure, distinct
 from a readiness timeout or a pre-launch safety rejection) and validated the
 packed npm tarball end to end in a clean consumer environment, independent
-of the source checkout. There is still no controlled-scroll/comparison
-behavior.
+of the source checkout. At the end of the v0.1 implementation there was no
+controlled-scroll or comparison behavior.
 
 ## Current v0.2 architecture (released/current architecture)
 
@@ -108,6 +108,176 @@ is still one canonical `observe()` application use case and one artifact
 writer; `scrollScenarioEvidence` is simply one more optional field on the
 same `ObservationArtifact`.
 
+## Current v0.4 architecture (released/current architecture)
+
+v0.4 adds one new downstream pipeline that consumes `ObservationArtifact`
+values rather than producing them - it never adds a second browser lifecycle,
+target resolver, or observation engine:
+
+```text
+ObservationArtifact before  ObservationArtifact after
+        \                          /
+         `--------.       .-------'
+                    \     /
+              artifact reader (src/artifacts/artifactReader.ts)
+                       ↓
+              comparability evaluation (src/domain/comparisonEngine.ts)
+                       ↓
+    canonical relationship derivation, called for each side independently
+              (src/domain/relationships.ts#deriveLayoutRelationships)
+                       ↓
+              canonical comparison derivation
+              (src/domain/comparisonEngine.ts#compareObservations)
+                       ↓
+                ComparisonArtifact
+                       ↓
+    atomic comparison writer (src/artifacts/comparisonArtifactWriter.ts)
+
+CLI `compare`
+        ↓
+application service only (src/application/comparisonService.ts)
+        ↓
+[reader → domain comparison → writer, as above]
+```
+
+`src/domain/relationships.ts` froze the layout-relationship contract and
+implements the one canonical pure derivation,
+`deriveLayoutRelationships(observation, options?)`: horizontal/vertical
+order, area overlap, relative width, geometric fit, vertical sequencing,
+page-width fit/exceeds, and a standalone `deriveTargetClipping(record)` -
+all computed only from an already-captured `ObservationArtifact`'s own
+`targetEvidence`/`pageEvidence`, never from a second browser query. DOM
+containment is read directly from the existing v0.2 `TargetContainment`
+evidence rather than re-derived, and stays a distinct concept from
+geometric fit.
+
+`src/domain/comparisonEngine.ts` implements the one canonical pure
+before/after engine, `compareObservations(before, after, config?)`:
+validates both source artifacts, evaluates comparability *before* any
+rendered difference is calculated, calls `deriveLayoutRelationships` once
+per side with the same tolerance, and derives target/page differences and
+relationship changes. `src/artifacts/comparisonArtifactWriter.ts` persists
+the result atomically (sibling temp directory, then one rename) as
+`<outputLocation>/<comparisonId>/manifest.json` only - no screenshot is
+copied; the manifest's `before`/`after` references point back to the
+source observations' own `screenshot.path`. `src/application/
+comparisonService.ts` is the one application-layer seam: `compareAndPersist`
+takes two in-memory `ObservationArtifact`s and does exactly one comparison
+plus exactly one persist; `compareAndPersistFromArtifactRoots` is a thin
+wrapper that additionally reads both sides from disk via the existing
+`src/artifacts/artifactReader.ts#readObservationArtifact` reader (itself
+just a `manifest.json` parse plus the same `isValidObservationArtifact`
+structural gate the writer uses).
+
+`src/cli.ts` gained one new top-level command, `compare`
+(`--before`/`--after`/`--output`/`--config-file`), implemented with the same
+thin-CLI-boundary discipline as `observe`: `parseCompareArgs` handles only
+argument shape/duplication, an optional `loadComparisonConfigFile` reads and
+validates only file readability/JSON-validity/non-array-object-root (exactly
+like `--targets-file`/`--scroll-scenario-file`), and the command body calls
+`compareAndPersistFromArtifactRoots` exactly once. **The CLI's comparison
+path never launches Chromium** - `src/cli.ts` imports nothing from
+`src/browser/` or `src/artifacts/` (it only reaches persistence and artifact
+reading indirectly, through the application-layer seam above), matching the
+same import-boundary discipline already enforced for `observe`.
+
+## Current v0.5 architecture (released/current architecture)
+
+v0.5 adds one new downstream layer that consumes `ComparisonArtifact` values
+(plus the source `ObservationArtifact` pair) rather than producing them - no
+new browser lifecycle, target resolver, or comparison engine is added:
+
+```text
+ObservationArtifact before + after
+              ↓
+existing v0.4 comparison/relationship pipeline (unchanged)
+              ↓
+        ComparisonArtifact
+              ↓                                PersistentBaselineContract
+              |                                          +
+              `------------------------→   PerChangeContract
+                                                          ↓
+                        canonical contract evaluation
+                        (src/domain/frontendContractEvaluation.ts#evaluateFrontendContract)
+                                                          ↓
+                        clause results + unexpected changes + overall PASS/FAIL
+```
+
+`src/domain/frontendContracts.ts` froze the contract/change-scope type,
+constant, and structural-validator vocabulary (Batch 1); `src/domain/
+frontendContractIdentity.ts` froze deterministic contract/baseline/clause
+identity in the same canonicalize+sha256(+opaque-nonce) style as `src/domain/
+comparisonIdentity.ts`. `src/domain/frontendContractEvaluation.ts#evaluateFrontendContract`
+(Batch 2) is the one canonical pure evaluation entry point: it validates its
+five inputs (before/after `ObservationArtifact`, `ComparisonArtifact`,
+`PersistentBaselineContract`, `PerChangeContract`) are structurally coherent
+and mutually consistent, calculates the active baseline clause set after
+explicit supersession, detects bounded structural conflicts, evaluates every
+active clause via the frozen 15-primitive vocabulary against the existing
+`ComparisonArtifact`/`ObservationArtifact` evidence (never re-deriving
+clipping/relationship/scroll-owner facts), classifies unaccounted-for
+`ComparisonArtifact.differences` entries as `unexpected`, and derives one
+overall `PASS`/`FAIL` verdict. It performs no I/O, launches no browser, and
+persists nothing - `src/domain/frontendContractEvaluation.ts` itself remains
+untouched by the persistence layer below (Batch 3).
+
+Batch 3 adds the persistence/application boundary around this frozen domain,
+without redefining it:
+
+```text
+        ComparisonArtifact (read via new src/artifacts/comparisonArtifactReader.ts)
+              +
+PersistentBaselineContract / PerChangeContract
+(read/written via src/artifacts/frontendContractArtifactReader.ts / ...Writer.ts)
+              ↓
+src/application/frontendContractEvaluationService.ts#evaluateAndPersist
+              ↓
+    evaluateFrontendContract()  [called exactly once, unmodified]
+              ↓
+src/domain/frontendContractEvaluationArtifact.ts
+    (minimal additive persisted envelope around the frozen result)
+              ↓
+src/artifacts/frontendContractEvaluationArtifactWriter.ts
+    (atomic write, exactly once on a structurally constructible result)
+```
+
+`evaluateAndPersistFromArtifactRoots` is the CLI-facing wrapper, reading
+before/after observations through the existing `readObservationArtifact` (no
+second observation reader), the comparison and both contract classes
+through the new readers, then delegating to `evaluateAndPersist` exactly
+once - mirroring `application/comparisonService.ts#compareAndPersistFromArtifactRoots`'s
+own thin-wrapper shape.
+
+Batch 4 exposes this through the same thin-CLI boundary already established
+by `observe`/`compare`:
+
+```text
+src/cli.ts (argument parsing, JSON-file-shape checks, help/output formatting,
+            exit-code selection only)
+        ↓
+src/application/frontendContractPersistenceService.ts#approveAndPersistBaseline
+src/application/frontendContractPersistenceService.ts#persistPerChangeContract
+src/application/frontendContractEvaluationService.ts#evaluateAndPersistFromArtifactRoots
+        ↓
+domain validators (isValidPersistentBaselineContract / isValidPerChangeContract)
++ artifact readers/writers (Batch 3)
++ evaluateFrontendContract() (Batch 2, unmodified)
+```
+
+Three new top-level commands - `approve-baseline`, `save-change-contract`,
+`evaluate-contract` - each parse only CLI-syntax concerns (duplicate/missing
+flags, JSON-file readability/parseability/object-root shape) and delegate to
+exactly one application-layer call; `src/cli.ts` imports no artifact writer/
+reader module and no browser code, matching the existing `observe`/`compare`
+import-boundary discipline exactly. `approveAndPersistBaseline` adds the one
+new coherence check Batch 3 did not need: verifying a baseline contract's
+frozen `sourceObservation` reference actually matches the supplied
+observation artifact before persisting - explicit approval only, never
+inferred from a `compare` or `evaluate-contract` result. `--enforce` on
+`evaluate-contract` is applied only after evaluation and persistence have
+already completed; it selects the process exit status for an already-final
+`FAIL` result and is never part of any identity or persisted field.
+
 ## Planned v0.1 architecture constraints
 
 v0.1 planning must preserve these approved boundaries without treating module

package/docs/CI_CD.md

@@ -67,3 +67,79 @@ observations. This was proven on `validation/v0.3-pre-release`
 hash-verified candidate tarball (SHA-256
 `da6cbc18a98d005b84a2f12c06f5c01d390006b53c02176a6c9cdc6d9b9d24d0`) - the
 release candidate for `v0.3.0`.
+
+## v0.4 readiness coverage
+
+The packed-candidate readiness gap that previously existed for the v0.4
+`compare` public command - identified during the v0.4 implementation/
+documentation audit as `V0_4_READINESS_VALIDATION_GAP_EXISTS` - has been
+closed: `scripts/ci/runPackedObservationSmoke.mjs` now also installs the
+candidate tarball, observes a deterministic before/after fixture through
+the installed `observe`, and runs the installed `compare` against both
+resulting artifacts, asserting (through the *installed package's own*
+exported `isValidComparisonArtifact`/`isValidObservationArtifact`, resolved
+from the consumer's own `node_modules` rather than the source checkout):
+comparison artifact kind/schema `1.0.0`, a `comparable` result with a real
+`moved`+`resized` target difference and a real relationship-family
+transition (`does-not-overlap`→`overlaps` and `left-of`→
+`horizontally-overlapping` simultaneously - the same pair the v0.4
+relationship-family matching regression concerns), an explicit
+`--config-file` non-causal dependency-evidence result, an `incomparable`
+result (differing viewport) with the expected blocking comparability
+reason and no fabricated ordinary differences, comparison-manifest path
+privacy (no absolute operational path leakage), retained (never copied)
+before/after screenshot references, a `manifest.json`-only comparison
+directory, and byte-identical source-observation manifests/screenshots
+before and after comparing - on every platform in the matrix, using the
+same single hash-verified candidate tarball as the legacy/semantic/scroll
+observations. This preserves every pre-existing v0.1-v0.3 packed
+observation proof unchanged and adds the v0.4 proof additively, in the same
+script and the same candidate, per the established same-candidate
+architecture (no second `npm pack`, no per-platform rebuild).
+
+## v0.5 readiness coverage
+
+The packed-readiness coverage gap identified during the v0.5 implementation-
+completeness audit as `V0_5_READINESS_VALIDATION_GAP_EXISTS` - the packed
+candidate smoke exercised `observe`/`compare` but not `approve-baseline`/
+`save-change-contract`/`evaluate-contract` - has been **corrected locally**:
+`scripts/ci/runPackedObservationSmoke.mjs` now also installs the same
+candidate tarball, observes a deterministic navigation/workspace/rail
+fixture through the installed `observe`, and drives the complete installed
+`approve-baseline` → `save-change-contract` → `observe` (candidate) →
+`compare` → `evaluate-contract` sequence, proving both a fully successful
+contract change (overall `PASS`, `--enforce` still exits `0`) and the
+milestone-signature failure (a locally successful requested/expected-
+dependent change alongside a real protected right-rail regression and a
+real preserved navigation-clipping regression, overall `FAIL`) - including
+`--enforce` producing a nonzero exit for the identical `FAIL` evidence
+(`evaluationRequestId` and `clauseResults` unchanged), full source
+observation/comparison/contract-artifact immutability, no copied
+screenshots, and no repository-root artifact leakage. All product behavior
+under test is invoked through the installed tarball's own executable, never
+imported from the source checkout. This addition is exercised in every
+existing matrix lane (`windows-latest`, `ubuntu-latest`, `macos-latest`)
+because all three already invoke this same script against the same
+candidate tarball - no workflow YAML change was required.
+
+This correction has since been proven cross-platform on the validation
+branch `validation/v0.5-pre-release`, first tested at commit
+`90255a9175503664f3e65d4114ee205176b7040a`: GitHub Actions run
+[`31727856546`](https://github.com/dailephd/my-frontend-observer/actions/runs/31727856546)
+passed completely - the candidate job (Linux, Node 24) and all three
+`matrix-smoke` lanes (`windows-latest` Node v24.18.1, `ubuntu-latest` Node
+v24.19.0, `macos-latest` Node v24.18.0) - using one shared candidate
+tarball, `my-frontend-observer-0.4.0.tgz`, SHA-256
+`9533a53e475614cd80a29dfa8b0f85e533e3ad736596579f559479e90e78941a`,
+independently hash-verified by each of the three matrix lanes before any of
+them ran the smoke (no lane built its own tarball). Every lane's
+`smoke-summary.json` reported byte-identical v0.5 evidence: the installed
+candidate's `approve-baseline`/`save-change-contract`/`evaluate-contract`
+`--help` all present, a real successful contract change (overall `PASS`,
+`--enforce` exits `0`), and the real milestone-signature failure (requested/
+expected-dependent `pass`, protected/preserved `fail`, overall `FAIL`,
+identical `evaluationRequestId`/`clauseResults` with `--enforce` exiting `1`
+and without it exiting `0`), plus source-artifact immutability, no copied
+screenshot, no path leakage, and no repository-root leakage - alongside
+every pre-existing v0.1-v0.4 packed observe/compare/scroll assertion, still
+passing unchanged on all three platforms.

package/docs/COMMANDS.md

@@ -225,6 +225,305 @@ persists honestly - typically as `partial` - carrying the same
 `target-missing`/`target-ambiguous`/`browser-evidence-unavailable` diagnostic
 that any other unresolved configured target would produce.
 
+## `compare`
+
+**Current status: shipped as part of the published `my-frontend-observer@0.4.0`
+package.** Comparison schema is `1.0.0`, independent of and never reused for
+the observation schema (`1.2.0`).
+
+`my-frontend-observer compare` (or `node dist/cli.js compare` from a source
+checkout) reads two already-persisted observation artifacts and derives
+before/after evidence purely from their existing content:
+
+```text
+my-frontend-observer compare --before <observation-artifact-root> --after <observation-artifact-root> --output <directory> [options]
+```
+
+Required:
+
+- `--before <path>` — root directory of the "before" persisted observation
+  artifact (the directory containing its `manifest.json`, as produced by
+  `observe`).
+- `--after <path>` — root directory of the "after" persisted observation
+  artifact.
+- `--output <directory>` — portable, relative output location for the
+  comparison artifact (same contract as `observe --output`).
+
+Options:
+
+- `--config-file <json-file>` — loads a comparison configuration directly
+  (no wrapper field): `{ "geometryTolerancePx": <0-10>,
+  "expectedDependencies": [...] }`. Without it, `geometryTolerancePx`
+  defaults to `0.5` CSS px with no declared dependencies. As with
+  `--targets-file`/`--scroll-scenario-file`, `--config-file` only validates
+  file readability, JSON validity, and a non-array object root; every
+  semantic rule (tolerance bounds, dependency property/direction
+  vocabulary, dependency source marker) is enforced by the same domain
+  validator the comparison engine itself uses.
+- `--help` — show `compare` usage.
+
+**Comparison never launches a browser.** It reads two manifests through the
+existing observation-artifact reader, runs the pure comparison engine, and
+persists a portable `manifest.json` — no navigation, no target
+re-resolution, no Chromium process.
+
+On success the command prints exactly:
+
+```text
+Comparison: <comparison-id>
+State: <comparable|comparable-with-warnings|incomparable>
+Artifact: <comparison-artifact-root>
+Differences: <count>
+Relationship changes: <count>
+Diagnostics: <count>
+```
+
+and exits `0` — **including when `State` is `incomparable`**: comparison
+determining that two observations should not be treated as equivalent
+frontend states is itself a successful outcome, not a failure. The command
+exits nonzero only for invalid CLI syntax, an unreadable/malformed/
+structurally-invalid source artifact, invalid comparison configuration, or
+a failed artifact write.
+
+### Comparability
+
+Before any rendered difference is calculated, the engine evaluates whether
+the two observations are comparable at all:
+
+- **Hard incompatibilities** (force `incomparable`): different logical page
+  URL, different viewport, different browser engine, or a mismatched scroll
+  scenario configuration (no scenario vs. a scenario, or two different
+  scenario configurations).
+- **Warnings** (still `comparable-with-warnings`, comparison proceeds):
+  different producer package version, different browser version, or a
+  changed/added/removed configured target.
+- **Unassessed dimensions** the observer does not yet model (theme,
+  authenticated state, application state) are always recorded, never
+  silently claimed identical.
+
+An `incomparable` result still persists a structurally valid
+`ComparisonArtifact`: the comparability reasons are recorded, and ordinary
+rendered differences/relationship changes stay empty rather than fabricated.
+
+### Difference and relationship evidence
+
+For a `comparable`/`comparable-with-warnings` result, the manifest's
+`differences` and `relationshipChanges` arrays carry structured before/
+after evidence: appeared/disappeared targets (only for a stable target name
+configured on both sides — a target added/removed from configuration is
+recorded separately as a `configurationChanges` entry, never fabricated as
+appeared/disappeared), moved/resized targets, visibility changes, clipping
+changes, actual dimensional overflow changes, DOM containment changes,
+page-size changes, scroll-owner changes, and layout-relationship
+transitions (e.g. `does-not-overlap` → `overlaps`, or
+`document-width-fits-viewport` → `document-width-exceeds-viewport`) reused
+verbatim from the same canonical relationship engine `observe` output feeds
+Batch 2's `deriveLayoutRelationships`.
+
+### Explicit dependency evidence (non-causal)
+
+`--config-file`'s `expectedDependencies` lets you declare an expected
+layout relationship such as "`navigation.width` decreases →
+`workspace.width` increases" using only the frozen `x`/`y`/`width`/`height`
+property vocabulary and `increase`/`decrease`/`change`/`unchanged`
+direction vocabulary. Each declaration is evaluated independently against
+the two observations and persists exactly one outcome: `consistent`,
+`not-observed`, `contradictory-to-declaration`, or `unavailable`. **The
+observer never infers a dependency from co-change, and never emits a
+causal claim, a PASS/FAIL verdict, or a change-contract decision** — v0.4
+produces comparison evidence; whether that evidence satisfies some
+contract is v0.5+ scope.
+
+### Path privacy
+
+`--before`, `--after`, `--config-file`, and `--output` are operational
+filesystem input only. None of them affect `comparisonRequestId`, and none
+of them are written into the persisted manifest — the manifest instead
+retains logical source references (`observationId`, `requestId`,
+`producer`, `observationSchemaVersion`, and the source `screenshot.path`).
+Two semantically identical observation/config pairs read from different
+filesystem locations produce the same `comparisonRequestId`; each execution
+still gets a fresh `comparisonId`.
+
+### Source observations remain immutable
+
+Comparison is read-only with respect to its inputs: it never modifies
+either source observation's `manifest.json` or `screenshot.png`, and it
+never copies screenshot bytes into the comparison directory — the
+comparison artifact directory contains `manifest.json` only.
+
+Example:
+
+```powershell
+node dist/cli.js compare `
+  --before observations/<before-id> `
+  --after observations/<after-id> `
+  --output comparisons `
+  --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