@jevitate/cli 0.1.0 → 0.3.0

package/skills/jevitate-test-campaign/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: jevitate-test-campaign
+description: Plan and run an end-to-end release test campaign of a whole web app with jevitate: preflight, a jobs-to-be-done catalog, discovery runs → draft Journeys, journey-anchored adversarial/exploratory missions, full-stack evidence, triage by exit code, verify-fix and regressions, budgets, CI suites and the release gate. Use to test a release or "the whole app" across many user jobs. For one run, use that tool's skill.
+---
+
+A campaign is many bounded runs, chosen on purpose and read honestly. An untargeted sweep from the
+landing page stays shallow (a handful of states near the entry pages) and never reaches the core
+jobs. Anchor everything on the jobs users actually do. Load `jevitate-explore`,
+`jevitate-run-journey`, `jevitate-verify-fix` and `jevitate-ci-check` for the flags of each step.
+
+## 0. Targets and environments
+
+- Test a non-production environment the human has authorized: a local dev server, a preview or a
+  staging build. Name each in `.jevitate/environments.json` so Journeys run with `--env <name>`.
+- Iterate on a dev or debug build (hot reload makes frontend fixes cheap). Timing findings there
+  are advisory. Run the final round on the compiled release build before the gate, and leave load
+  testing (`jevitate-load-test`) to a release-like environment.
+- Never point a sweep at a database other test work is using. Seed or reset it (`--fixtures`, or an
+  operator `--before`/`--after` hook) so runs don't pollute each other.
+
+## 1. Preflight (stop on any failure)
+
+- `jevitate ai status --json`: the keys must be accepted live, not just present.
+- One tiny `--real` goal run proves the model path end to end before you queue an hour of runs.
+- One Playwright storageState per persona (kept under `~/.jevitate/`, never committed). Check each
+  still logs in: a quick goal run per persona with `--storage-state <file>` and a `--success`
+  check on a page only that persona sees. Use `--save-storage-state` on the same file when the app
+  rotates refresh tokens.
+- Target health: the start URL answers and the backend is up. A dead target makes every run
+  `inconclusive`, which tells you nothing.
+
+## 2. Build the job catalog first
+
+List every user job from the app's routes, API surface and product docs: persona, job, and the
+signal that proves it worked. Write one goal spec per job (template below): the outcome only,
+never the click path; independent `--success` checks (page or network state); preconditions;
+whether it mutates state; and a run order (jobs that create data run before jobs that use it).
+A job you can't write a checkable `--success` for is too vague. Split it or narrow it.
+
+## 3. Discovery: one goal run per job
+
+For each job, as the right persona, with no scripted path:
+
+```bash
+jevitate explore-author-journey --url <start-url> --goal "<outcome only>" --success "<check>" --id <job-id> --name "<job>" --storage-state <persona-file> --real --json
+```
+
+- Reached: an UNPROMOTED draft Journey is written. Promotion is a human decision. List the drafts
+  and ask the human to review and run `jevitate journey promote <id>`. Never promote yourself.
+- Stuck, detour, `exhausted` or `inconclusive`: that is a finding about the job itself
+  (discoverability, UX, a broken step), not only a crash. Log it in the register.
+- A question rather than a task ("how many seats does the plan allow?") is a find-out run: a
+  `--goal "find out …; report the answer"` with no `--success`, read-only by default.
+
+## 4. Journey-anchored missions (where most defects are)
+
+Defects cluster mid-flow: a verification step, a checkout, a half-finished build. Start missions
+from a promoted Journey's key intermediate states, not the landing page. The Journey's prefix is
+replayed in the mission's OWN browser context (page, form contents and session kept), then the
+mission takes over on the live page:
+
+```bash
+jevitate journey anchors <journey-id> --json   # the named states worth exploring from, with suggested probes
+jevitate explore --from-journey <journey-id> --at-step <anchor|n> --param <k=v> --env <env> --strategy adversarial --storage-state <persona-file> --max-actions 60 --evidence-video --real --json
+```
+
+- `--at-step` takes an anchor name (from `metadata.anchors`) or a 1-based step number. Only the
+  prefix's own `--param`s are required. `--strategy` may be goal, coverage, exploratory,
+  adversarial or usability (`--feature`, `--repeat`, `--persona` and `--actor` are refused).
+- A prefix that no longer replays ends the run `inconclusive` with `failure.kind: "journey-stale"`
+  (exit 2): the Journey drifted. Fix or re-author it; never fall back to a bare `--url`.
+- Results and findings carry `branch: {journeyId, step, anchor}`: the exact point they came from.
+- `--at-step all` (or `anchors`) sweeps every step: each in a fresh session restored by
+  `--fixtures`, `--max-actions` split evenly per step, one deduped report naming each defect's steps.
+- `verify-fix` and regressions replay such a finding THROUGH the Journey prefix (re-supply secret
+  params with `--param`); a stale prefix is `inconclusive` (`journey-stale`), never `fixed`.
+- `--strategy adversarial` attacks the anchor: replaying a one-time code, swapping a tenant id
+  mid-flow, a double submit at checkout, an expired share link, skipping a step-up (the anchor's
+  `probes` list what to try). `--strategy exploratory` follows newly revealed controls from there.
+  `--strategy usability --goal "<job>" --app-class <class>` critiques the job (`jevitate-ux-review`).
+- `--persona <name=storageState>` (repeatable, without `--from-journey`) runs the same mission per
+  role and diffs them; a 403 for one and 200 for another is a candidate authorization finding.
+- `--invariants <file>` turns app rules ("Saved means stored") into code-decided defects. Lint
+  them first: `jevitate invariants validate <files...> --url <url>`.
+
+Sweep many anchors with a campaign (template below): discovery replays each job's whole Journey (a
+stale one skips its missions), then every anchored mission runs in order with the spec's
+`fixtures` restore around each run, and ONE deduped report comes back (each defect lists the
+Journey steps it branched from):
+
+```bash
+jevitate campaign run .jevitate/campaign/campaign.json --real --json
+```
+
+An invalid spec is refused with every problem listed (exit 64). Shell `before`/`after` restore
+hooks in the spec run only with `--allow-shell-hooks`, and only when the human asked for them.
+
+## 5. A small untargeted pass, plus non-journey attacks
+
+Keep one `--strategy coverage --scope app` run per persona to find orphan and dead-end screens.
+Attacks that no Journey reaches (direct API authorization, forged or reordered webhooks,
+cross-tenant requests, session fixation across hosts) are scripted by the operator; record what
+was tried in the register, so the gate can show they were covered.
+
+## 6. Full-stack evidence on every run
+
+Tail the backend while the browser runs, so each finding carries its server-side cause:
+`--log-source docker:<container>` (or `file:<path>`), `--log-defect error`, and
+`--log-correlation-header <name>` when the app propagates a request id. Matching log lines are
+redacted and attached to the step that caused them. Add `--evidence-video` (a captioned clip per
+defect) or `--screenshots`, and link the files from the issue.
+
+## 7. Triage by exit code, then collect before fixing
+
+`0` clean · `1` defects found · `2` inconclusive (proved nothing: never a pass; fix the budget,
+session or check and rerun) · `3` hang · `4` intermittent · `64` refused, nothing ran. Report the
+outcome you got. Never round it up.
+
+1. Collect: a campaign's own `campaign.md` is already one deduped list; across campaigns and
+   ad-hoc runs, `jevitate report --target <origin> --since <campaign-start> --json` dedupes every run
+   into one defect list. Keep one register (template below) tagged by layer and severity.
+2. Fix: frontend fixes under the hot-reload dev server, rechecked at once; backend fixes batched
+   into one rebuild.
+3. Prove: `jevitate verify-fix --result <run>.result.json --fingerprint <fp> --replays 3 --json` for
+   every finding. Only `fixed` counts. Then `jevitate ledger add <run>.result.json <fp> --json` and,
+   when the human asks, `jevitate regression capture --from <run>.json --result <run>.result.json --fingerprint <fp> --id <id> --json`.
+4. Re-sweep the jobs the fixes touched, and compare: `jevitate diff <runA> <runB> --json`.
+
+## 8. Budgets and machine limits
+
+- Every run has a cap: `--max-actions` (and `--max-decisions` for model-driven runs). Start at
+  40–60 per mission; raise it only for a run that ended `exhausted` on a real job.
+- Run missions one at a time. Check free memory before each; a browser killed by the OOM killer
+  reads as `crashed`, not as an app defect.
+- Mark paid controls with `--paid <pattern>` so retries and hang replays never repeat them. Never
+  add `--allow-destructive` or `--allow-writes` unless the human asked.
+
+## 9. CI: promoted Journeys + a check suite
+
+Put every promoted Journey, the invariants, the key goals and a few anchored missions in a suite,
+and gate with `jevitate check --suite <suite.json> --target-build <sha> --json` (MCP `run_check`;
+see `jevitate-ci-check`). Tag the release candidate's clean run as a baseline:
+`jevitate baseline tag <name> <runs...>`. In CI, exit 1 fails the build, and exit 2 or 64 is a
+broken check, never green.
+
+## 10. The gate
+
+Release only when: every job in the catalog has a promoted Journey that passes; every finding is
+`fixed` by verify-fix (with a ledger entry or regression); the final round ran on the release
+build; and no `inconclusive` run was counted as a pass. Anything short of that, report it as open.
+
+## Templates
+
+Job spec (one per job, `.jevitate/campaign/jobs.json`) — the catalog you plan from:
+
+```json
+[{
+  "id": "invite-teammate",
+  "persona": "admin",
+  "storageState": "~/.jevitate/sessions/admin.json",
+  "goal": "invite a new teammate by email and see them listed as pending",
+  "success": ["textIncludes:role=table|Pending", "responseStatus:POST /api/invites=2xx"],
+  "preconditions": ["an org with a free seat"],
+  "mutates": true,
+  "order": 3
+}]
+```
+
+Anchors live on the promoted Journey itself (`metadata.anchors`, listed by `jevitate journey anchors <id>`):
+
+```json
+"anchors": [{ "name": "invite-form", "step": 4, "description": "the filled invite form", "probes": ["double submit", "invite into another org id"] }]
+```
+
+Campaign spec (`.jevitate/campaign/campaign.json`, for `jevitate campaign run`):
+
+```json
+{
+  "version": 1,
+  "name": "release-candidate",
+  "env": "staging",
+  "fixtures": "restore.json",
+  "maxRuns": 40,
+  "maxActions": 60,
+  "jobs": [
+    { "id": "invite-teammate", "journey": "invite-teammate", "storageState": "~/.jevitate/sessions/admin.json",
+      "params": { "email": "new@example.test" }, "anchors": ["invite-form"], "strategies": ["adversarial", "exploratory"] },
+    { "id": "checkout", "journey": "checkout", "anchors": ["payment", 6], "strategies": ["adversarial"], "maxActions": 40 }
+  ]
+}
+```
+
+Issue register (one row per deduped finding, `.jevitate/campaign/register.md`):
+
+```text
+| fingerprint | job | layer (fe/be) | severity | outcome | evidence | status (open/fixed/verified) | regression |
+```
+
+## What you must never do
+
+- Never promote a Journey, approve an inbox item or capture a regression on your own. Ask.
+- Never count `inconclusive`, `intermittent` or a single clean replay as passing.
+- Never widen `--allow` beyond what the human authorized, and never test production.

package/skills/jevitate-ux-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jevitate-ux-review
-description: Produce ranked, cited, advisory usability findings for a flow — offline over a saved Recording (`jevitate ux <recording> --app-class`) or live over an authorized target (`jevitate explore --strategy usability --goal --app-class`). Use when a human wants a UX/usability critique of a journey, not a pass/fail functional test. Findings are advisory and never gate a run.
+description: Produce ranked, cited, advisory usability findings (preview) for a flow — offline over a saved Recording (`jevitate ux <recording> --app-class`, MCP `ux_review`) or live on an authorized target (`jevitate explore --strategy usability --goal --app-class`, MCP `run_exploration`). Use when the user wants a UX or usability critique, not a pass/fail test. Findings are advisory and never gate a run.
 ---
 
 You produce a UX review: ranked, cited, evidence-anchored usability findings for
@@ -9,22 +9,40 @@ fails a run or a build. Every finding is calibrated to an app class (a consumer
 signup and an internal admin tool are held to different bars) and cites a rubric
 item; the platform structurally cannot emit an uncited finding.
 
+PREVIEW (0.2.0): these findings are a preview feature. The independent quality
+grader is not yet calibrated across apps, and how findings are grouped/deduped
+is still being redesigned (issues #133, #198). `report.preview` is `true` and
+`report.headline` says so; tell the human this is a preview, not a finished
+verdict.
+
 ## Two modes — pick by what you have
 
 - OFFLINE, over a saved Recording — `jevitate ux <recording.json> --app-class
-  <class> [--persona <p>] [--job "<text>"] [--out <dir>] --json`. Analyzes a
+  <class> [--persona <p>] [--job "<text>"] [--out <dir>] [--min-confidence <n>]
+  [--show <labels>] --real --json`. Analyzes a
   Recording you already captured (e.g. from `jevitate-record` or a successful
   `jevitate explore`). It launches no browser. `--app-class` is REQUIRED
-  (e.g. `consumer`, `admin`, `internal`); `--job` sharpens relevance.
+  (e.g. `consumer`, `admin`, `internal`); `--job` sharpens relevance. It reads
+  the artifacts next to `<stem>.recording.json` automatically: the live
+  usability run's evidence sidecar `<stem>.evidence.json` (the screens as
+  analyzed plus the run signals), `<stem>.result.json` or
+  `<stem>.transcript.json`, and `<stem>.screens/`. With the sidecar, offline
+  review reproduces the live run's findings. Without it, `report.evidenceCaveats`
+  names what could not be checked. `--evidence` and `--result` override the
+  discovered files.
 - LIVE, against an authorized target — `jevitate explore --strategy usability
   --url <authorized-url> --goal "<the job>" --app-class <class> [--allow
-  <origin>] [--secret <value>] [--max-actions <n>] --real --json`. Drives the
+  <origin>] [--secret <value>] [--max-actions <n>] [--min-confidence <n>]
+  [--show <labels>] --real --json`. Drives the
   exploration loop toward the job (Jev makes the browsing decisions, not you)
   and reviews each observed screen against the rubric as it goes. Needs a
   gateway: `--real` (live, after `jevitate ai setup`) or `--fake-ai` (a
   deterministic pipeline smoke that will NOT produce a real review). No
   selection fails closed.
 
+Over MCP: `ux_review` is the offline mode (`recording`, `appClass`, …); `run_exploration`
+with `strategy: "usability"` is the live mode. Usability is not a queueable mission strategy.
+
 Prefer OFFLINE when a Recording already exists — it is cheaper, deterministic,
 and touches no live site. Use LIVE only when there is no Recording and the human
 authorized the target.
@@ -43,21 +61,93 @@ authorized the target.
   authorized. Pass real secrets/PII via `--secret` so they stay out of every
   model call.
 
+## Filtering what is shown
+
+- `--min-confidence <0..1>` (also `JEVITATE_UX_MIN_CONFIDENCE`, or `ux.minConfidence` in
+  `~/.jevitate/config.json`; default 0.3): findings below it are suppressed.
+- `--show <labels>` (also `JEVITATE_UX_SHOW`, or `ux.show` in the config): an
+  opt-in filter on the quality grade. The grades are `actionable`,
+  `relevant-minor`, `generic` and `wrong`. The default shows ALL grades. The
+  grader is not calibrated (no held-out, multi-rater kappa ≥ 0.4 off its tuning
+  app), so it labels findings and does not hide them. Each finding carries its
+  grade in `quality`, and `report.qualityFiltered` says whether a filter was
+  applied. `--show actionable,relevant-minor` restores the old filter.
+- `--max-findings-per-page <n>` (also `JEVITATE_UX_MAX_FINDINGS_PER_PAGE`, or
+  `ux.maxFindingsPerPage` in the config; default 5): caps findings per route,
+  highest-confidence first (0.2.0, issue #198 interim — a full redesign is
+  tracked there). The rest are counted in `report.suppressed` as
+  `per-page-cap`, never dropped silently.
+- Nothing is dropped silently: every suppressed candidate is counted in
+  `report.suppressed`. Change a filter only when the human asks, and say which
+  filter you changed.
+
 ## Reading the result
 
-- The report is a set of findings, each with a `severity` (`info` | `minor` |
-  `major`), a rubric `citation` (`source` + `ref`), and redacted evidence refs
-  pointing at the screen/control it is about. Rank your summary by severity and
-  lead with the `major` findings.
-- Report findings as ADVISORY recommendations, with their citations — never as
-  defects that block shipping, and never restate a finding without the rubric
-  citation the tool attached (the citation is what makes it more than an
-  opinion).
+- Lead with `report.headline`. It gives the findings grounded in observed run
+  behavior, the heuristic-only count in the appendix, and "N suppressed (by
+  rubric item: …)".
+- `report.findings` holds only findings with behavioral evidence:
+  - run signals (tier `signal`): a hung request, a stuck job still offered
+    again, a duplicate write or create, a failed submit with no or only generic
+    error copy, a repeated assistant reply, an inert control, an internal id,
+    or a URL whose page shows another route's content. Each cites its steps,
+    requests, text and screenshot in `signal`.
+  - rubric findings grounded in the friction the run hit on that screen: a
+    backtrack, a retry, a dead end, a long wait, an error, an abandoned field,
+    or the goal not reached. `journeyEvidence` gives the kind and step range.
+  - Their `severity` and `impact` come from the observed impact on the job:
+    `blocked` > `slowed` > `confused`. Findings on the same friction point are
+    collapsed into one, with the others listed in `contributing`.
+- `report.heuristicAppendix` holds rubric findings with no observed friction.
+  They are screen-level heuristics only, capped at `info`. Mention them as an
+  appendix, never as the review's findings.
+- Each finding is specific and grounded:
+  - `observation`: what is wrong, naming the control, label or text, relative to
+    the job.
+  - `userImpact`: what it costs the user.
+  - `recommendation`: a concrete change to that control or text.
+  - `controls` and `quotes`: the implicated controls and verbatim on-screen text.
+    Independent code checked that both exist on the screen.
+  - `evidenceRefs`: only those controls, not every control on the page.
+  - `route`, `screenId`, `occurrences` and `screenIds`: where it was seen. The
+    same item on the same route and controls is one finding with a count.
+  - `severity` (`info` | `minor` | `major`) and a rubric `citation` (`source` +
+    `ref`).
+  - `quality`: the independent grader's label and its confidence.
+  - `confidence` with its `confidenceBasis`: violation × applicability ×
+    grounding × agreement. Quote the observation and recommendation; don't
+    paraphrase them into generic heuristic advice.
+  - `contributing` (0.2.0, issue #198 interim): DIFFERENT rubric items that
+    fired on the SAME control on the SAME route are collapsed into one
+    finding — the highest-confidence one leads, the rest are listed here with
+    their own `rubricItemId`, `citation`, `observation` and `occurrences`. Read
+    it as "these principles all flagged the same thing", not as noise to
+    ignore — mention the other principles when it matters.
+- Rank your summary the way the report does: by `impact`, then severity. Lead
+  with what blocked the job.
+- `report.suppressed` counts what was not shown: `byReason`, `byRubricItem` and
+  `byRubricItemRoute`. The reasons are:
+  - `ungrounded`: named no control or text.
+  - `rejected-evidence`: cited a control or text that is not on the screen.
+  - `not-confirmed`: the specifics step found no concrete violation.
+  - `below-min-confidence`
+  - `quality-policy`: a grade outside an explicit `--show` filter.
+  - `per-page-cap` (0.2.0, issue #198 interim): the route already has
+    `--max-findings-per-page` findings shown; this one ranked lower.
+  Say how many were suppressed. `clean: true` only happens with zero findings
+  AND zero suppressed, so never describe a report with suppressions as "no
+  issues".
+- `coverage.notApplicable` lists items whose rubric precondition did not hold,
+  for example choice overload on a 2-control screen. Those items are evaluated,
+  not skipped.
+- Report findings as ADVISORY recommendations, with their citations. They are
+  never defects that block shipping. Never restate a finding without the rubric
+  citation the tool attached; the citation is what makes it more than an opinion.
 - An analysis that FAILED (`E_UX_ANALYSIS`) is a real failure to surface
-  honestly — never fabricate a clean "no issues found" report from a failed run.
-  Offline review over a bare Recording is coverage-limited (it sees only what
-  the Recording captured — no live a11y tree, no runtime contrast); say so when
-  the Recording is thin, rather than implying the flow is fully vetted.
+  honestly. Never fabricate a clean "no issues found" report from a failed run.
+  Offline review over a bare Recording is coverage-limited: it sees only what
+  the Recording captured, with no live a11y tree and no runtime contrast. When
+  the Recording is thin, say so rather than implying the flow is fully vetted.
 
 ## What you must never do
 

package/skills/jevitate-verify-fix/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: jevitate-verify-fix
+description: Reproduce a jevitate finding by its fingerprint and prove a fix (`jevitate verify-fix`, MCP `verify_fix`); attach evidence (`--evidence-video` clips, `--record-video` before/after, `--screenshots`); keep findings re-checkable (`jevitate ledger`); lock a bug in as a committed regression (`jevitate regression capture|run`). Use after a run reports a defect, when fixing one, or when a PR needs proof a bug is gone. Not for finding new bugs (jevitate-explore).
+---
+
+Every finding jevitate reports has a stable `fingerprint` and its own reproduction: the Recording
+and the step to replay up to. Your job is to replay it, read the verdict literally, and attach
+the evidence. No model decides any of these verdicts.
+
+## Reproduce or verify a fix
+
+- CLI: `jevitate verify-fix --result <run>.result.json --fingerprint <fp> [--replays 3] --json`.
+  The result file is `<stem>.result.json` beside the run's Recording (under `.jevitate/logs/<date>/`
+  by default). The fingerprint is from the result's `defects[]` (or `hangs[]`).
+- MCP: `verify_fix({ id, fingerprint, replays?, recordVideo?, screenshots?, storageState? })`,
+  where `id` is the result stem (e.g. `adversarial-2026-09-23T00-00-00-000Z`) or a finished
+  `queue_exploration` missionId.
+- Verdicts and exit codes: `fixed` (0, the signal was absent on every replay) · `still-reproduces`
+  (1) · `inconclusive` (2, a replay couldn't reach the step, e.g. a missing session or a changed
+  page) · `intermittent` (4, it fired on some replays) · 64 (unusable input). Only `fixed` means
+  fixed. A single clean replay isn't evidence, so never lower `--replays` below 3 to make a check
+  pass.
+- An authenticated app needs `--storage-state <file>` (a path, never cookie contents), or the
+  target's session in `~/.jevitate/targets.json`. A finding recorded at a viewport or device
+  replays at that emulation. `--viewport`/`--device` that differ are refused unless
+  `--allow-emulation-override` is passed.
+
+## Evidence for a PR or an issue
+
+- At discovery, add `--evidence-video` to `jevitate explore` (or `mission queue`). Each defect
+  (up to 5) then gets a captioned clip of its minimal repro with the failing step marked by the
+  real signal, plus before and at screenshots, under `<run>.evidence/<fingerprint>/`. The result
+  gets `defects[].evidence`, and the issue drafts link to them.
+- At fix time, `jevitate verify-fix ... --record-video` writes the before/after pair:
+  `evidence.before` (the run's own clip) and `evidence.after` (a captioned replay now, ending on the
+  verdict).
+- `--screenshots [screens|steps|<dir>]` writes masked screenshots and an `index.md`. It works on
+  `explore`, `verify-fix`, `journey run` and `mission queue`.
+- Secrets are masked in pixels. A capture whose mask can't be proven isn't written
+  (`screenshotsSkipped`/`captureSkips` say why). Report that. Never work around it.
+- Link to the files. GitHub's API can't upload media, so commit them under `.jevitate/` or
+  publish them as CI artifacts.
+
+## Keep it re-checkable: the ledger
+
+Run output under `.jevitate/logs/` is pruned by retention. To re-check a finding months later:
+
+- `jevitate ledger add <run>.result.json <fp> [--ticket JEV-123] --json` stores the repro material
+  (no sessions, no page text) in `.jevitate/regressions/ledger/<fp>.json`. Commit it with the fix.
+- After that, `jevitate verify-fix <fp> --json` works without `--result`, and
+  `jevitate ledger verify [--ticket JEV-123] --json` re-checks every entry. It exits with the worst
+  verdict. An empty match is exit 2 ("nothing verified"), never a pass.
+- Over MCP, the `ledger` tool takes `add`/`list`/`verify` as its action.
+
+## Lock it in: a committed regression
+
+- `jevitate regression capture --from <run>.json --result <run>.result.json [--fingerprint <fp>]
+  --id <id> --json` replays the failure `--attempts` times (default 3) and commits
+  `<id>.recording.json` and `<id>.meta.json` to `.jevitate/regressions/`. A failure that doesn't
+  reproduce every time is labeled flaky and isn't committed. It captures a failed goal `--success`
+  check (minimized), an app-caused failed action, a failed network check, a declared-invariant
+  violation, or a Recording whose last `expect` fails.
+- A hard-signal fingerprint (HTTP 5xx, a hang, a server-log defect) is refused (64) with a pointer
+  to `ledger add`/`verify-fix`. To make one a regression, declare the rule it breaks as an
+  invariant (`--invariants`) and capture the invariant violation.
+- `jevitate regression run <id> [--env <name>] --json` exits 1 (`reproduces`) while the bug is
+  there and 0 (`fixed`) once it's gone. An existing `--id` is refused unless `--force` is passed.
+  Only overwrite when the human asks.
+- MCP: `regressions` with `action: "capture"` or `action: "run"`.
+
+## What you must never do
+
+- Never report `inconclusive` or `intermittent` as fixed, and never retry until you happen to get a
+  clean replay.
+- Never edit a result file, a ledger entry or a committed regression to change a verdict.
+- Never capture or commit a regression the human didn't ask for. Recommend it and say why.