@kirrosh/zond 0.26.1 → 0.27.0

package/src/cli/commands/init/templates/skills/zond.md

@@ -1,861 +0,0 @@
----
-name: zond
-description: |
-  Primary skill for any zond work. Loads on workspace touch
-  (`apis/<name>/`, `.env.yaml`, `.api-fixtures.yaml`) AND on intent —
-  full API audit, "find bugs", "raise coverage", "test the whole API",
-  contract-drift check, schema-drift detection, post-deploy regression,
-  case study, single-flow scenario authoring, fixture pack. Hand off to
-  `zond-checks` for depth-check reference / SARIF / stateful invariants,
-  to `zond-triage` for "what broke in the last run".
-allowed-tools: [Read, Write, Edit, Bash(zond *), Bash(bunx zond *), Bash(sqlite3 *)]
----
-
-# zond — Primary skill
-
-CLI-only. Run `zond --version` first; if missing:
-`curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh`.
-
-For depth-check reference (the catalog of conformance / security /
-stateful checks, SARIF output, m-20 invariants) — see `zond-checks`.
-For triage of a failing run — see `zond-triage`.
-
-## Iron rules (read once, apply always)
-
-- **NEVER read raw OpenAPI** with Read/cat/grep. The workspace has
-  pre-built artifacts (catalog/resources/fixtures) — use those. Drop
-  into `apis/<name>/spec.json` only when probe-class authoring needs
-  full schemas.
-- **NEVER `curl` or `wget`** — use `zond request <method> <url> --api <name>`
-  for ad-hoc HTTP so it lands in the run DB and respects auth. Never
-  shell-substitute the token by hand (`$(yq …)` is blocked by the sandbox).
-  `--body '{…}'` always sends `application/json`. For form-encoded APIs
-  (Stripe v1, classic webforms) pass `--form` — zond URL-encodes the
-  JSON body. Auto-detect from spec: if `requestBody.content` in
-  `.api-catalog.yaml` declares only `application/x-www-form-urlencoded`,
-  use `--form`; mixed content-types → pick by `Content-Type` header you
-  want to test.
-- **NEVER hardcode tokens** — put them in `apis/<name>/.secrets.yaml`
-  (auto-gitignored), reference from `.env.yaml` as `@secret:auth_token`.
-  Plain `${SHELL_VAR}` references also work. Tests read the resolved
-  value as `{{auth_token}}`.
-- **NEVER read `.secrets.yaml` directly.** Use `zond doctor --api <name> --json`
-  — reports `set | unset` and value length only. To WRITE / rotate a secret
-  use `zond secrets set <key> <value> --api <name>` (writes a `.bak`, never
-  echoes the value, auto-strips a pasted `Bearer ` prefix — pass `--literal`
-  to keep it verbatim).
-- **NEVER edit `.api-*.yaml`** (catalog / resources / fixtures) by hand —
-  regenerated by `zond refresh-api`. `.api-resources.local.yaml` IS the
-  hand-editable / annotate-target overlay; safe to edit.
-  `.api-schema.local.yaml` is the response-schema overlay (ARV-176) —
-  written by `refresh-api --merge-schema`, also survives refresh; edit by
-  re-merging a `patch.schema.json`, not by hand. `.env.yaml` values are
-  editable (see ARV-114).
-- **NEVER invent endpoints.** Only use entries from `.api-catalog.yaml`.
-- **NEVER run destructive ops on a shared / production org without
-  `--dry-run` first.** Probes, `prepare-fixtures --apply`, `cleanup` hit
-  live APIs and can delete user data. `--dry-run` once → inspect → drop
-  the flag.
-- **NEVER share triage artefacts** outbound without `--redact-identity`.
-  Secret-redaction is on by default; identity values (org/member slugs,
-  real ids) need the extra flag.
-- **NEVER report cleanup failure as an API bug.** POST 200 → DELETE 5xx
-  is *probably* a fixture-isolation issue (orphan accumulation, race).
-  Re-run with `--no-cleanup` or isolated namespace before filing.
-- **`recommended_action: report_backend_bug` / 5xx → STOP** in interactive
-  mode (surface the request/response, get a decision; never `expect:`-mask).
-  In autonomous / loop / audit-sweep mode (no user-in-the-loop), log to
-  `api-bugs-<NN>.md`, continue the sweep — bailing on bug #1 forfeits #2..N.
-- **CRUD-run ≥80% 401/403 / `permission_denied` → `env_issue`, not bug.**
-  Token scope issue. Confirm via `zond db diagnose <run-id> --json`
-  (401/403 dominate `by_recommended_action`); do not generate
-  case-studies, do not `expect:`-mask.
-- **MUST run `zond doctor --api <name> --missing-only` before generating
-  fixtures or touching `.env.yaml`** — identifies unfilled keys early.
-- **`prepare-fixtures` is single-pass, never POST-creates, and never
-  harvests values** (ARV-362) — it verifies existing fixtures and reports
-  unfilled vars as gaps. Which record/field fills a slot is your call:
-  fill fixtures by hand (`fixtures add` / editing `.env.yaml`).
-
-## Workspace artifact model
-
-After `zond add api <name> --spec <path|url>`, `apis/<name>/` contains:
-
-```
-spec.json                    ← dereferenced OpenAPI (machine source)
-.api-catalog.yaml            ← endpoint index (method, path, params)
-.api-resources.yaml          ← CRUD chains + FK deps (auto)
-.api-resources.local.yaml    ← overlay: extensions + annotate output (hand-edit OK; appears after first `zond api annotate apply` — or create by hand to use as overlay)
-.api-fixtures.yaml           ← MANIFEST: required vars + descriptions (read-only)
-.env.yaml                    ← VALUES: variable values (user / prepare-fixtures writes)
-.secrets.yaml                ← raw secret values (auto-gitignored)
-.identity.yaml               ← non-secret identifying values (gitignored)
-tests/                       ← generated/handwritten suites
-scenarios/                   ← handwritten flow suites
-probes/                      ← probe-emitted suites
-```
-
-### Manifest vs values (the #1 source of confusion)
-
-**`.api-fixtures.yaml` = the list of vars this API needs (manifest).
-`.env.yaml` = their values.**
-
-| Op | Touches manifest? | Touches env? |
-|---|---|---|
-| `zond add api` / `refresh-api` | rebuilds | seeds skeleton |
-| `zond generate` | extends (adds new `{{vars}}` discovered) | does **not** modify |
-| `zond prepare-fixtures` | reads | writes values |
-| `zond fixtures add` / `import` | reads | writes values (manual) |
-| user editing | never | always |
-
-- `{{var}}` in a generated test but NOT in `.api-fixtures.yaml` is a
-  bug in the manifest builder / generator. Don't "fix" it by adding to
-  `.env.yaml`.
-- A key in `.env.yaml` but NOT in `.api-fixtures.yaml` is shadow —
-  `prepare-fixtures` warns `not in manifest, ignored`.
-- "Generate should sync `.env.yaml`" is a rejected design (decision-7,
-  m-17).
-
-### Manual fixture-bootstrap (you fill every value)
-
-ARV-362: `prepare-fixtures` **reports** FK gaps — it never harvests a
-value. Every fixture is filled by hand: read the gap (empty list → create
-a record first; non-empty → pick a value; 404/403 → auth/drift), then
-supply it. Vendor-dashboard ids (Stripe `cus_*`, GitHub PR numbers,
-Sentry issue ids) have no list endpoint at all — same hand-off:
-
-| Input you have | Command |
-|---|---|
-| Concrete id values | `zond fixtures add <var>=<id> [--validate] --apply` |
-| Curl from devtools / dashboard | `pbpaste \| zond fixtures import --from-curl --apply` (URL is matched against spec paths to extract `{var}` bindings) |
-
-`--validate` GETs the spec's read-by-id endpoint and classifies the
-fixture as `live` / `stale` / `unknown` so dead ids don't silently
-break later runs (ARV-32). Both commands write to `apis/<name>/.env.yaml`
-with a `.env.yaml.bak` backup.
-
-### When to read which file
-
-| To know… | Read |
-|---|---|
-| What endpoints exist | `.api-catalog.yaml` |
-| How resources chain (CRUD, FK, ETag) | `.api-resources.yaml` |
-| What vars are needed and why | `.api-fixtures.yaml` |
-| What var values are set | `.env.yaml` |
-| Annotation overlay (seed_body, lifecycle, pagination, readback_diff) | `.api-resources.local.yaml` |
-| Full request/response schema (only when needed) | `spec.json` |
-
-## --json envelope (uniform across commands)
-
-```jsonc
-{
-  "ok": true|false,
-  "command": "<name>",
-  "data": { /* command-specific */ },
-  "warnings": ["..."],
-  "errors": [{ "code": "ZondErrorCode", "message": "...", "details": {} }],
-  "exit_code": 0|1|2
-}
-```
-
-Route on `errors[].code`, not message. Stdout discipline: `--json`
-emits only the envelope on stdout; progress/hints to stderr.
-
-`--json` ≠ `--report json`. `--json` wraps the **command result**;
-`--report json` wraps the **test-run artefact**. `zond run` doesn't
-accept `--json` — use `--report json`.
-
-## Entry points — pick by intent
-
-| User asked… | Start at |
-|---|---|
-| "smoke this API", "quick first pass", "demo / CI gate" | `zond audit --api <name>` (safe-mode breadth pass — no live mutations) |
-| "audit this API", "test the whole API", "raise coverage", "deep pass" | walk Phase 0–9 — audit covers smoke; depth (stateful, security, learn-apply) needs phase-level decisions |
-| "full live audit against sandbox", "include mass-assignment/security probes" | `zond audit --api <name> --live --with-mass-assignment --with-security` (REQUIRES throwaway/sandbox account) |
-| "find bugs", "test for 5xx", "probe sweep" | Phase 0 → Phase 7 (Probes) |
-| "security only / SSRF / CRLF" | Phase 7.2 directly with `--dry-run` first |
-| "deep depth-checks", "SARIF", "stateful invariants" | Hand off → `zond-checks` |
-| "what broke in last run", "diagnose run X" | Hand off → `zond-triage` |
-| "write a test for X flow", "smoke this checkout" | Phase S (Scenarios) |
-| "what vars does this API need" | `zond doctor --api <name> --json` |
-| "share results", "case study" | Phase 9 (Share) |
-| "workspace looks messy" | `zond clean --api <name>` (dry-run → `--force`) |
-
-## Phase 0 — Orient
-
-```bash
-zond doctor --api <name> --json                 # gaps + freshness
-```
-
-Then read the three artifacts (NOT the raw spec):
-
-```bash
-cat apis/<name>/.api-catalog.yaml | head -80
-cat apis/<name>/.api-resources.yaml
-cat apis/<name>/.api-fixtures.yaml
-```
-
-If doctor reports stale → `zond refresh-api <name>`.
-
-## Phase 1 — Fixture pack
-
-`zond prepare-fixtures` is **single-pass and deterministic**: it walks
-`.api-resources.yaml`, hits each owner list/read endpoint, and **reports**
-which FK vars are unfilled (empty list → create one first; non-empty →
-pick a value; 404/403 → auth/drift). It does **not** POST-create resources
-and (ARV-362) **never harvests a value** — which record/field fills a slot
-is your judgment. Fill every gap by hand (`fixtures add` / `.env.yaml`).
-
-```bash
-zond prepare-fixtures --api <name>            # report gaps (never writes values)
-zond prepare-fixtures --api <name> --apply    # only unsets stale ids under --refresh; never harvests
-zond prepare-fixtures --api <name> --refresh  # = --verify --apply: drop (unset) stale 404 ids → you refill
-```
-
-It also scans the generated suites and reports two named gap buckets
-(warnings in text, `summary.fixtureGaps` in `--json`) — report only, no
-values invented, no auto-seed (ARV-349/350):
-- **`unseededRoots`** — required manifest vars that are empty, referenced by
-  a suite, and seeded by no step (e.g. `{{account}}` created in `crud-accounts`
-  but referenced uncaptured in `persons-crud`). These are chain-heads: one id
-  un-skips a whole dependent CRUD suite. Fix these first.
-- **`undefinedVars`** — suite `{{vars}}` no manifest entry, capture, or param
-  produces (`{{bank_code}}`, `{{tax_id}}`). Supply by hand.
-
-To fill `unseededRoots` autonomously — author create-bodies, POST them, and
-capture the returned ids — hand off to **`zond-seed`** (agent reasons, zond
-executes via `request … --capture`). It seeds only what the API self-serves
-and reports external-input gaps honestly.
-
-When a var stays UNSET after `--apply`, read the per-target reason in the
-output, then fill the gap directly:
-
-| Input you have | Command |
-|---|---|
-| Concrete id values | `zond fixtures add <var>=<id> [--validate] --apply` |
-| Curl from devtools / dashboard | `pbpaste \| zond fixtures import --from-curl --apply` |
-| Nothing yet (empty list) | Create the resource in the product UI / via API, then harvest its id with `fixtures add` |
-
-Common reasons a var stays UNSET (all fixed outside prepare-fixtures):
-- empty list on the target account — no record exists to harvest;
-- the id lives only in a vendor dashboard (Stripe `cus_*`, GitHub PR
-  numbers, Sentry issue ids) with no discoverable list endpoint;
-- the value is gated outside the API path (email verify / paid plan /
-  SCIM / TOS limits). Document the gap; don't loop.
-
-Editing `.env.yaml` by hand is the sanctioned fallback when the CLI
-cannot harvest a value (write-only ingest endpoints, SDK-only ids,
-slugs that live in user's project config). Touch values only — never
-add keys not in `.api-fixtures.yaml`.
-
-### Dynamic value functions in `.env.yaml` (ARV-190, m-21)
-
-Stale hardcoded UUIDs / dates / idempotency keys pin existing rows or
-expire mid-run. Use `#(funcName)` / `#(funcName(args))` references —
-evaluated at load time, stable within one run:
-
-| Token | Resolves to | Use for |
-|---|---|---|
-| `#(uuid)` | fresh UUID v4 (same value across all references in this run) | Idempotency-Key, request id |
-| `#(uuidStable(<seed>))` | deterministic UUID from seed (sha-256 shaped as v4) | reproducible tests |
-| `#(today)` | `YYYY-MM-DD` (UTC) | expiry-from dates |
-| `#(todayPlus(N))` | today + N days (N may be negative) | expires_at, valid_until |
-| `#(now)` | ISO 8601 timestamp | created_at hints |
-| `#(unix)` | seconds since epoch | epoch timestamps |
-| `#(alphanumeric(N))` | N random `[a-z0-9]` chars (default 8) | one-shot tokens |
-| `#(env:VAR)` | `process.env.VAR` (alias for `${VAR}`) | secrets passed through |
-
-```yaml
-# apis/foo/.env.yaml
-idempotency_key: "#(uuid)"          # same uuid across every step in this run
-trial_expires:   "#(todayPlus(30))"  # 30 days from now
-request_id:      "req-#(uuid)"       # embedded; shares uuid with above
-```
-
-Resolution order: `${ENV}` → `#(...)` → `@secret:` → `@identity:`. Dynamic
-functions run BEFORE secret/identity refs so a secret value that happens to
-contain `#(...)` stays opaque (no double-expansion). Per-run cache means
-`#(uuid)` referenced twice in the same `.env.yaml` returns the same value
-— critical for idempotency-replay flows.
-
-## Phase 2 — Annotate (NEW, m-20 / ARV-187)
-
-**Critical**: zond itself does NOT call any LLM. The flow is
-**dump → agent fills YAML → apply**. The agent (you) generates the
-overlay; zond validates and writes it into `.api-resources.local.yaml`.
-
-`zond api annotate` has 6 dump-subcommands (one per aspect). Pick what
-your downstream check needs:
-
-| Aspect | Dump produces | Feeds into |
-|---|---|---|
-| `--seed-bodies` | request-body schema per resource | all stateful checks (create-body overlay) |
-| `--readback` | create+read pair (write-shape vs read-shape) | `cross_call_references` ignore_fields, write_to_read_map |
-| `--idempotency` | header candidates | `idempotency_replay` (header, scope, body_hash_fields) |
-| `--pagination` | list-endpoint cursor/page detection | `pagination_invariants` (type, cursor_param) |
-| `--lifecycle` | action-endpoint candidates per resource | `lifecycle_transitions` (states, transitions) |
-| `--resources` | orphan endpoints not in resource graph | `.api-resources.local.yaml` extensions |
-
-**Workflow** (for ANY aspect):
-
-```bash
-# 1. Dump — emits JSON slices on stdout. Restrict scope with --only.
-zond api annotate dump --api <name> --seed-bodies --only r1,r2 > /tmp/dump.json
-
-# 2. Agent reads the dump and writes a YAML response file (see format below).
-
-# 3. Apply — dry-run first (diff), then --yes to write.
-zond api annotate apply --api <name> --seed-bodies --input /tmp/out.yaml          # dry-run + diff
-zond api annotate apply --api <name> --seed-bodies --input /tmp/out.yaml --yes    # write
-```
-
-YAML response format — a top-level list of entries, each one resource:
-
-```yaml
-- resource: <name>
-  seed_body:                              # (--seed-bodies)
-    content_type: application/x-www-form-urlencoded
-    body:
-      amount: 1000
-      currency: usd
-  rationale: 'why this shape'             # optional, helps future review
-  confidence: high                        # high|medium|low — optional
-```
-
-Same shape for `readback_diff`, `idempotency`, `pagination`,
-`lifecycle` blocks (see `zond-checks` for the per-aspect schemas).
-
-**When to annotate**: run dump+apply BEFORE Phase 6 (stateful checks)
-for any production API. Without annotation, stateful checks fall back
-to defaults and miss API-specific quirks (custom pagination params,
-non-standard lifecycle field names, write-only fields in create body).
-
-**For Stripe-style form-encoded APIs**: `--seed-bodies` is the single
-biggest win — the create-body overlay it produces lets stateful checks
-POST valid resources instead of 400-ing on schema-derived random bodies.
-
-### Agent-in-the-loop annotate (dump → write → apply, ARV-187 / 277 / 278-282)
-
-zond does NOT infer annotations. YOU (the agent) read the spec slice and
-write the overlay; zond only dumps raw material and validates/merges what
-you produce.
-
-```bash
-# 1. Dump the raw material for a resource — spec slice + expected YAML
-#    shape + (for seed-bodies) the last N seed-POST attempts so you see
-#    the error progression, not just the current 400 (ARV-277/278).
-zond api annotate dump --api <name> --seed-bodies --only <res> \
-  --with-last-attempt --history 5
-
-# 2. YOU write the overlay: read the dumped slice + attempt history,
-#    reason about the required create body / pagination / lifecycle /
-#    idempotency, and produce one YAML doc per resource. Edit
-#    .api-resources.local.yaml directly OR emit a file for apply.
-
-# 3. Apply — zond validates your YAML (zod), renders a diff, and (with
-#    --yes) merges. With --gap-fill-only (ARV-281) your response can ONLY
-#    add missing fields — already-set blocks are protected from overwrite.
-zond api annotate apply --api <name> --seed-bodies --input agent-out.yaml --gap-fill-only --yes
-
-# 4. Refresh fixtures — drop (unset) stale (404) ids so they resurface as
-#    gaps; refill them by hand / `fixtures add` (discover never harvests).
-zond prepare-fixtures --api <name> --refresh
-```
-
-## Phase 3 — Generate tests
-
-```bash
-zond generate apis/<name>/spec.json --output apis/<name>/tests [--tag <spec-tag>] [--uncovered-only]
-zond check tests apis/<name>/tests
-```
-
-`generate` fills bodies with typed generators (`{{$randomString}}` etc.).
-Format-strict APIs reject many — that's a **test-fix**, not a backend bug.
-Pair with Phase 1 fixtures + Phase 2 annotation.
-
-Required FK / reference body fields (`*_id`, unresolved `*Code` like
-`sequenceTypeCode`) are wired to `{{fixture}}` refs (ARV-45) — canonicalised
-(`sequence_type_code`) and listed in `.api-fixtures.yaml` as `source: body-fk`.
-Fill their real values once in `.env.yaml`; no more hand-editing generated
-tests. Blank fixture → the var is unbound and dependent tests skip.
-
-If a CRUD chain you expected is missing, run
-`zond generate <spec> --explain` — diagnostic table shows every POST
-endpoint with verdict (no GET-by-id, non-`{id}` item param,
-trailing-slash mismatch, …).
-
-## Phase 4 — Spec-lint (hygiene, separate workflow)
-
-```bash
-zond lint --api <name>                           # 0 network requests
-zond lint --api <name> --json | jq '.data.stats'
-# Equivalent: `zond check spec --api <name>`
-```
-
-ARV-255 (m-21 pivot): **spec-lint is hygiene, not security or
-contract.** It runs separately from `zond audit` / `zond probe` /
-`zond checks run` — those produce the security/reliability/contract
-report, lint stays out of that pile.
-
-Severity capped at **LOW / INFO** by design:
-- LOW: real spec violations (format mismatch in example, missing
-  path-param format, response without schema).
-- INFO: style and documentation gaps (additionalProperties missing,
-  naming, missing examples).
-
-No HIGH/MEDIUM ever — static analysis has no runtime evidence, so the
-severity matrix forbids escalation. `--strict` opts back into a
-non-zero exit when any LOW lands.
-
-## Phase 5 — Run (sanity → smoke → CRUD)
-
-Wrap multi-run sweeps in a session so `/runs` shows one row:
-
-```bash
-zond session start --label "smoke + probes"
-zond run apis/<name>/tests --tag sanity --report json                              # 5.1 sanity
-zond run apis/<name>/tests --safe --report json                                    # 5.2 smoke (GET-only)
-zond run apis/<name>/tests --tag crud,setup --validate-schema --report json        # 5.3 full CRUD
-zond run apis/<name>/tests --tag positive --include 'path:^/emails'                # 5.4 narrow
-zond session end
-```
-
-**Always pass `--validate-schema` for CRUD** — contract drift is
-invisible without it. `schema_violation` failures are real backend bugs;
-treat them like 5xx.
-
-**After any `zond run` with failures → delegate to `zond-triage`.** Do
-NOT parse `runs/run-NN.json` with `jq` by hand. The triage skill reads
-`zond db diagnose --json` (which already buckets by `recommended_action`
-in `data.by_recommended_action`, ARV-228) and routes by closed enum —
-re-implementing that logic with prose heuristics drifts. Only fall back
-to manual CLI queries when the failure is outside the example slice.
-
-Rate limit: `zond run` defaults to an adaptive limiter (no-op until
-`RateLimit-*` headers appear). Pass `--rate-limit <N>` for a hard cap;
-`--sequential` for old binaries.
-
-**Long runs**: `zond run` shows a periodic progress line on stderr when
-stdout/stderr is a TTY (`zond: [42s] 234/10927 steps (2%), 230 req, ~30
-req/s, ETA ~5m`) — overwrites itself in place. Suppressed by `--quiet`
-and on non-interactive output. For huge probe-suites (e.g. GitHub spec
-→ ~10k probes under `--rate-limit 30` = 6+ min), this signals "alive,
-not hung". `zond probe static` itself prints a scale-warning block with
-ETA-at-rate-limit estimates and a `--max-per-endpoint K` sampling hint
-when `totalProbes ≥ 2000`.
-
-**Hard cap on requests**: pass `--max-requests N` to cap outgoing HTTP
-calls across the whole run. Remaining steps short-circuit to `skip` with
-`error: "max-requests-cap-reached"`. Each `retry_until` attempt counts as
-one request. Useful for sampling huge probe runs (`--max-requests 500`)
-and for CI time-boxing.
-
-`--all`: fold every `apis/<name>/tests/` dir into one `runs.id` per
-invocation (CI shape). CI context (commit_sha, branch, trigger=ci)
-auto-stamped from env vars.
-
-### Spec-drift learning tail (`--learn`)
-
-After the initial CRUD run, **always** close with `--learn` /
-`--learn-apply`. R09 measured a 28% → 58% pass-coverage jump from this
-phase alone.
-
-```bash
-zond run apis/<name>/tests --learn                            # detect (read-only)
-zond run apis/<name>/tests --learn-apply --learn-target test  # rewrite expect.status
-zond run apis/<name>/tests --learn-apply --learn-target drifts # allowlist in tolerated-drifts.yaml
-```
-
-**Caveat — `--learn-apply test` weakens assertions, not the code.**
-Diff `apis/<name>/tests/*.yaml` + `tolerated-drifts.yaml` after every
-apply; treat unexpected widenings as a review-blocker.
-
-## Phase 6 — Stateful checks (m-20)
-
-After Phase 2 annotation is applied, run the cross-call invariants.
-See `zond-checks` for per-check semantics.
-
-```bash
-zond checks run --api <name> --check stateful --report ndjson --live   # CRUD create-chains need --live
-```
-
-**Safe by default (ARV-299)**: without `--live`, `checks run` skips the
-stateful CRUD create-chains (`ensure_resource_availability`,
-`use_after_free`) — they'd POST real resources. Read-only stateful checks
-(pagination, observation-mode lifecycle, cross-call GET diff) still run.
-Add `--live` **only against a throwaway/sandbox account** to exercise the
-create-chains.
-
-`--check stateful` expands to the state-machine set (ARV-325):
-- `cross_call_references` — POST→GET drift (uses readback_diff overlay)
-- `idempotency_replay` — bit-identical replay on `Idempotency-Key`
-- `pagination_invariants` — `?limit=N` + `?after=last_id` non-overlap
-- `lifecycle_transitions` — declared state-machine validity
-- `use_after_free`, `ensure_resource_availability` — CRUD lifecycle
-- `cursor_boundary_fuzzing` — list-cursor edge values
-- `webhooks` (recipe-based, see `docs/recipes/webhook-receiver.md`)
-
-`ignored_auth` / `open_cors_on_sensitive` are **not** part of the alias —
-they're auth/security checks that roughly triple run time on wide APIs.
-Run them by explicit id: `--check ignored_auth,open_cors_on_sensitive`.
-
-**Iron rule**: don't run `--check stateful` without prior `api annotate`
-review. Defaults catch the obvious; quirks need declared config.
-
-## Phase 7 — Proactive bug hunting (probes)
-
-```bash
-zond probe static --api <name>                # validation + methods (defaults; generator, always safe)
-zond probe mass-assignment --api <name> --live --emit-tests apis/<name>/probes/mass-assignment
-zond probe security ssrf,crlf,open-redirect --api <name> --live \
-  --emit-tests apis/<name>/probes/security
-zond run apis/<name>/probes --report json
-```
-
-**Safe by default (ARV-299)**: `probe mass-assignment` / `probe security`
-without `--live` plan only (no live attack payloads) — same as `--dry-run`.
-Add `--live` **only against a throwaway/sandbox account** to send probes.
-`probe static` just generates suites, so it's always safe.
-
-Flag: 5xx on null/empty/wrong-type body → missing validation. 2xx on
-undeclared method → contract drift. `is_admin: true` echoed in response
-→ HIGH from mass-assignment.
-
-**Body-FK auto-discovery** — `mass-assignment` resolves required
-`*_id`/`*_slug`/`*_uuid`/`*_key` fields by hitting sibling list endpoints.
-If digest still says "unresolved body FKs:" — add to `.env.yaml` manually.
-
-**Auto-path-FK** — same logic for path params (`{domain_id}`/`{webhook_id}`).
-Cached per run. Pass `--no-discover` to opt out.
-
-### 7.1 — Manual mass-assignment catch-up
-
-`mass-assignment` digest splits findings: HIGH / MED / LOW /
-INCONCLUSIVE (no valid body — fixture problem) / INCONCLUSIVE-5XX
-(baseline crashed — already in validation-probe). Sweep INCONCLUSIVE
-with `--emit-template`:
-
-```bash
-zond probe mass-assignment --api <name> --emit-template "POST:/<resource>" \
-  --output apis/<name>/probes/mass-assignment/<resource>.yaml
-```
-
-Emits `create → verify → cleanup` chain pre-filled with classic vectors
-(`is_admin`, `role`, `owner_id`). If a privileged field survives the
-round-trip GET → **HIGH**, file via `report bundle --include case-study`.
-
-### 7.2 — Security probes
-
-```bash
-zond probe security ssrf,crlf --api <name> --dry-run         # first run: which (endpoint, field) — same as default --safe
-zond probe security ssrf,crlf,open-redirect --api <name> --live   # send, sandbox only
-```
-
-**Targeting** (two filters; an endpoint must pass BOTH to be planned):
-
-1. **Has a JSON request body** — GET-only routes are skipped with
-   `no-body`. The probes work by mutating a body field, so read-only
-   endpoints have nothing to attack.
-2. **Has ≥1 field name matching the requested class detectors** — if
-   no field matches, the endpoint is skipped with `no-matched-field`.
-
-Field autodetection: SSRF (`*_url`/`webhook`/`callback`/`format: uri`),
-CRLF (`subject`/`*_prefix`/`name`), open-redirect (`redirect`/`next`).
-
-If `--dry-run` reports `0 planned / 0 skipped / 0 total` with a narrow
-`--include`, the scope likely captured only GET routes — broaden the
-filter or drop `--include` to see the per-endpoint skip reasons. With
-no `--include`, the dry-run shows `no-body` / `no-matched-field` next
-to each skipped endpoint so the gap is obvious.
-
-Baseline-OK request first; if baseline ≠ 2xx → `INCONCLUSIVE-BASELINE`,
-attacks skipped (kills 5×404 noise on scope-locked endpoints).
-
-Verdict: HIGH (5xx OR payload echoed in 2xx — stored injection),
-LOW (2xx, no echo — verify side-effects manually), OK (4xx).
-
-**Cleanup is state-aware**: PUT/PATCH does `GET` → snapshot → attack →
-restore. POST falls back to `DELETE` with eventual-consistency retry.
-Restore failures → `## ⚠️ Cleanup failures` at top of digest.
-
-CI exit: non-zero on HIGH > 0 OR `cleanup.error > 0`.
-
-### 7.3 — Post-probe hygiene
-
-```bash
-zond prepare-fixtures --api <name> --refresh    # drop stale FK ids
-zond cleanup --orphans                           # retry DELETE for ~/.zond/orphans/
-```
-
-Skip only with `probe security --isolated` (isolated mode never attacks
-seeded-fixture endpoints).
-
-## Phase 8 — Coverage + spec drift
-
-```bash
-zond coverage --api <name> --union session                  # default: dual-metric (test + audit)
-zond coverage --api <name> --union since:1h                 # last hour
-zond coverage --api <name> --union tag:smoke                # tag-filtered
-zond coverage --api <name> --scope audit --union session    # only "did zond touch the API"
-zond coverage --api <name> --scope test  --union session    # legacy single block
-zond coverage --api <name> --fail-on-coverage 50            # CI gate (gates pass-coverage)
-```
-
-**Dual-metric output (ARV-265).** `zond coverage` prints two blocks side-by-side by default:
-
-- **test-coverage** — runs produced by `zond run` only (`run_kind` ∈ {regular, probe}). Has two sub-metrics:
-  - `pass-coverage`: endpoint had a passing 2xx (strict; CI gate via `--fail-on-coverage`)
-  - `hit-coverage`: endpoint received any response (loose; breadth proxy)
-  Three-bucket JSON: `covered2xx`, `coveredButNon2xx`, `unhit`.
-- **audit-coverage** — any HTTP touch from any producer (`zond run` + `checks run` + `probe` + `request` + `prepare-fixtures`). Use this to answer "did the scan reach the API at all?" — typical safe-mode runs without `zond run` still report >50% on a 1k-endpoint spec from `checks run` alone.
-
-Source breakdown (`--scope audit` text or `data.audit_coverage.by_source` JSON):
-
-```
-audit-coverage: 619/1184 endpoints (52%, 1500 HTTP touches)
-  by source:
-    check     619 endpoints, 1500 events
-    regular     0 endpoints,    0 events
-    probe       0 endpoints,    0 events
-    request     3 endpoints,    3 events
-```
-
-Producers opt out via `ZOND_CHECKS_PERSIST=0`.
-
-**Quality signals to gate CI on** (not raw pass-coverage):
-
-| Signal | Command |
-|---|---|
-| Contract drift | `checks run --phase coverage` HIGH count == 0 |
-| Stateful invariants | `checks run --check stateful` HIGH count == 0 |
-| Auth / Authz / injection | `probe security` HIGH count == 0 |
-| Mass-assignment | `probe mass-assignment` HIGH count == 0 |
-| Response conformance | `run --validate-schema` `schema_violation` == 0 |
-| Drift allowlist review | `git diff apis/<name>/tolerated-drifts.yaml` |
-
-## Phase 9 — Share findings
-
-```bash
-zond report export <run-id>                                # default: triage/<api>/run-<id>/
-zond report bundle 135..142 -o triage/sweep/               # all artefacts (default): case-study + export + diagnose + index.md
-zond report bundle <run-id> --include case-study,diagnose  # subset only (drop export)
-zond report bundle --session <id> -o triage/session/       # group by session
-```
-
-Bodies > 8 KB truncated by default; `--no-body-cap` to keep full.
-Existing files at `--output` auto-rotate to `<stem>-vN.<ext>`;
-`--overwrite` to silence. **Always pass `--redact-identity` for
-outbound sharing** (secret-redaction is on by default; identity slugs
-need the extra flag).
-
-Offer this proactively after a run surfaces `definitely_bug`
-(5xx / schema violation / mass-assignment 2xx). Skip for `env_issue` /
-`quirk`.
-
-## One-shot smoke audit — `zond audit`
-
-**`zond audit` is the breadth pass, not "full audit".** It covers the
-*smoke + coverage* slice — prepare-fixtures → generate → probe static
-→ session-wrapped run on tests+probes → coverage → `audit-report.html`.
-Depth (stateful checks, security probes against R18 evidence-gates,
-m-20 annotate, `--learn-apply` iteration) is the **skill's job, not
-audit's**: those stages need decisions audit can't make
-(annotate-before-stateful, scoping after auth-cluster, evidence
-preconditions). Use audit for: CI smoke, demo, "first 5 minutes on a
-new API". For a real depth campaign, walk Phase 0–9 from this skill.
-
-```bash
-zond audit --api <name> --dry-run                       # print stage plan
-zond audit --api <name>                                  # safe mode (default) — no live probes
-zond audit --api <name> --live --with-mass-assignment --with-security   # full live pipeline (throwaway/sandbox only)
-zond audit --api <name> --out reports/audit-<name>.html
-```
-
-**ARV-264 safe vs live decision matrix.** Default is `--safe` (implicit;
-no flag needed). `--live` is the opt-in for traffic that mutates the
-target API.
-
-| Concern | `--safe` (default) | `--live` |
-|---|---|---|
-| `prepare-fixtures` mode | single-pass path-FK discovery (GET) | same — single-pass, never POST-creates |
-| `probe mass-assignment` | skipped even if `--with-mass-assignment` set, with a warning | runs when `--with-mass-assignment` set |
-| `probe security` (SSRF/CRLF/redirect) | skipped even if `--with-security` set, with a warning | runs when `--with-security` set |
-| `probe static` (validation+methods) | always runs — pure spec walk, no live traffic | same |
-| `run tests / probes` | runs against the live API but only generated GET-shape suites by default | same |
-
-**Pre-flight warnings (printed before any subprocess fires):** missing
-`auth_token` when the spec declares securitySchemes (probes will skip
-with 401 and the report will read misleadingly green); no
-securitySchemes declared in the spec (open API or incomplete spec —
-auth-related checks will skip).
-
-**Rule of thumb.** Unknown-scope PAT against a production API → `--safe`
-(default). Throwaway account / sandbox tenant → `--live` is fine. Never
-run `--live` against shared/production data on first contact.
-
-Each stage prints `==> Stage N/M: <name>` and a completion line
-`└─ OK · Ns` / `FAIL (exit K) · Ns` / `SKIPPED (reason)`. Exit 1 if
-any non-coverage stage failed.
-
-`generate` skipped via mtime when `tests/` is fresher than `spec.json`
-(pass `--force` to override).
-
-**Session reuse (ARV-65)**: if `.zond/current-session` is already set
-when audit starts (i.e. user ran `zond session start` first), audit
-reuses that session — `session-start` and `session-end` stages skip
-with reason `reusing active session <id>`. The user's session stays
-active after audit returns; runs inside audit are stamped with the
-outer `session_id` and roll up under the user's `coverage --union
-session` later.
-
-ARV-158: when any run inside the audit session has failures, the
-generated `audit-report.html` embeds a "Failures by run" section with
-collapsible `<details>` per run — `by_recommended_action` buckets +
-first example (method, path, status, reason) + concrete drill-down
-commands (`zond db diagnose --run-id N --json`, `zond report export
-N`). Triage starts from the rendered HTML; you only fall back to CLI
-queries when you need fields outside the example slice.
-
-When NOT to use audit: narrow asks ("fix run X", "why this endpoint
-500s") — walk phases.
-
-## Phase S — Single-flow scenarios
-
-When the user wants to verify one specific flow (not breadth):
-
-```bash
-zond doctor --api <name>                                 # confirm fixtures
-# write apis/<name>/scenarios/<flow-slug>.yaml directly (no scaffold cmd)
-zond session start --label "<short reason>"
-zond run apis/<name>/scenarios/<flow>.yaml --report json
-zond session end
-```
-
-YAML grammar (zond runner format — NOT Postman / OpenAPI shape):
-
-```yaml
-name: cancel-pending-order
-tags: [scenario, orders]
-base_url: "{{base_url}}"
-headers: { Authorization: "Bearer {{auth_token}}" }
-tests:
-  - name: create order
-    POST: /workspaces/{{ws_id}}/orders
-    json: { amount: 100, currency: USD }
-    expect:
-      status: 201
-      body:
-        id: { capture: order_id }
-        status: { equals: pending }
-  - name: cancel
-    POST: /orders/{{order_id}}/cancel
-    expect: { status: 200 }
-  - name: verify cancelled
-    GET: /orders/{{order_id}}
-    expect:
-      status: 200
-      body: { status: { equals: cancelled } }
-  - name: cleanup
-    DELETE: /orders/{{order_id}}
-    always: true                                          # runs even on prior failure
-    expect: { status: [200, 204, 404] }
-```
-
-Grammar:
-- HTTP verb is a top-level key on the step (`GET:`, `POST:`, …).
-- Body: `json: {...}` / `form: {...}` / `multipart:` / `text:`.
-- Captures: `expect.body.<field>: { capture: <var> }`.
-- Assertions: `equals`, `type`, `exists`, `matches`, `gt`/`lt`,
-  `length*`, `each`, `contains_item`, `set_equals`, `oneOf`.
-- `expect.status`: number or array. `oneOf` / `anyOf` string forms NOT
-  supported — pass an array directly.
-- `always: true` — runs on prior failure (cleanup).
-- `skip_if: "{{var}} =="` — skip when fixture var unset.
-- Generators: `{{$randomEmail}}`, `{{$uuid}}`, `{{$randomString}}`,
-  `{{$randomInt}}`, `{{$randomIsoDate}}`. Full list:
-  `zond reference random-helpers`.
-
-Hand-crafted scenarios are for **bug repro / post-deploy smoke /
-verifying a fix** — small focused work. For breadth, use Phase 3
-(generate) and the full audit chain.
-
-## Diagnose failures
-
-```bash
-zond db runs --limit 5 --json
-zond db diagnose <run-id> --json              # grouped by root_cause
-zond db run <id> --status 500 --json
-zond db compare <idA> <idB> --json            # regression diff + field-level body diff (.data.body_changes[], ARV-339)
-zond db run <id> --report yaml                # run snapshot as YAML (ARV-338) — keep/diff as text
-```
-
-> **db --json envelope shape** (consistent across siblings): the array
-> always lives under `data.<plural>`, not directly under `data`.
-> `db runs` → `.data.runs[]`, `db collections` → `.data.collections[]`,
-> `db run <id> --status …` → `.data.results[]`. Top-level totals on runs
-> are at `runs[].total/passed/failed`, not under a `.summary` wrapper.
-
-`recommended_action` enum (closed):
-- `report_backend_bug` — STOP, surface to user
-- `fix_test_logic` — edit the YAML
-- `fix_auth_config` / `fix_network_config` / `fix_env` — config issues
-- `fix_spec` — edit OpenAPI (from `check spec`)
-- `fix_fixture` — fill `.env.yaml` (from `prepare-fixtures` miss-* or
-  inconclusive mass-assignment baseline)
-- `update_spec` — status-drift from `--learn`
-
-`cascade` failures collapse under root cause — fix upstream, not
-individually.
-
-### Fixing 4xx from stub generators (`fix_test_logic`)
-
-When body rejected on format (400/422 + "expected ..."):
-
-1. Read failure: `zond db run <id> --status 422 --json`.
-2. **Fixture pack first** — if it's a FK id / verified resource /
-   constrained enum, add to `.env.yaml` (Phase 1).
-3. **Typed generator** — swap `{{$randomString}}` for matching format
-   helper.
-4. **Hardcoded literal** — when typed generators fail (regex too strict).
-5. **Runtime captures** — for resources the test creates (capture from
-   prior `create_*` step or `setup: true` suite). For pre-existing FKs,
-   prefer step 2.
-
-For deep triage of a specific failing run → hand off to `zond-triage`.
-
-## Auth / environments
-
-- `apis/<name>/.env.yaml` is both auth and fixture pack — any key
-  interpolatable as `{{key}}`. Auto-gitignored.
-- Login-flow tokens: `setup: true` suite captures vars that propagate
-  to later suites in the same run.
-- `zond run --env <name>` loads `.env.<name>.yaml`. Discovery walks up
-  to workspace root; deeper files override shallower.
-
-## File lifecycle
-
-Everything zond writes is tracked in `.zond/manifest.json` with
-sha256-at-write. Files whose hash no longer matches are **skipped**
-on clean (user edits stay safe). Re-running a generator overwrites
-the entry — manual edits to generator-owned files are lost on
-regenerate; promote them to a separate suite first.
-
-```bash
-zond clean --api <name>                     # dry-run: lists what would be removed
-zond clean --api <name> --force             # delete (preserves probes/)
-zond clean --api <name> --probes --force    # also probe suites
-zond clean --all --force                    # nuclear
-```
-
-Triage outputs default to
-`triage/<api>/<run-id>/<command>-<ts>.<ext>`. Don't pass `--output`
-unless the user has a specific destination.
-
-## When to hand off
-
-- "deep depth-checks", "SARIF", "boundary coverage", "stateful
-  invariants details", "annotate aspect XYZ" → `zond-checks`
-- "what failed in last run", "why is it red", "case study from run X"
-  → `zond-triage`
-
-If the user is mid-workflow in one of those, don't restart from here.