@kirrosh/zond 0.22.0 → 0.23.0

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

@@ -0,0 +1,397 @@
+---
+name: zond-checks
+description: |
+  Schemathesis-style depth checks for an API — conformance + security
+  probes that go beyond YAML smoke tests. Use when the user asks for:
+  "deep audit", "find spec drift", "test edge cases", "boundary value
+  coverage", "find security bugs", "broken auth check", "use-after-free",
+  "SARIF for code scanning", "GitHub Code Scanning report", "stateful
+  invariants", "cross-call drift", "idempotency replay", "pagination
+  consistency", "lifecycle state machine". For a full generated test
+  pipeline + scenarios + audit chain, hand off to `zond`. For triage
+  of a failing run, use `zond-triage`.
+allowed-tools: [Read, Bash(zond *), Bash(bunx zond *), Bash(jq *), Bash(sqlite3 *)]
+---
+
+# zond-checks — Depth checks (conformance + security)
+
+CLI-only skill. Use *after* a YAML smoke run passes — depth checks
+exercise contract drift, malicious input rejection, broken auth, and
+soft-deleted resource leaks against a live API.
+
+The catalog is fixed and self-describing — list it before running so
+the user sees what they'll get:
+
+```bash
+zond checks list                 # registered checks (id, severity, expected)
+zond checks list --json          # same, machine-readable
+```
+
+## When to use
+
+| User asks | Run |
+|---|---|
+| "deep audit", "find edge cases" | `zond checks run --api <name>` |
+| "boundary value coverage" | `... --phase coverage` |
+| "find security bugs", "broken auth" | `... --check ignored_auth,use_after_free,ensure_resource_availability` |
+| "is GET returning what POST accepted?", "cross-call drift" | `... --check cross_call_references` (m-20) |
+| "does the API honor Idempotency-Key?", "two-POST replay" | `... --check idempotency_replay` (m-20) |
+| "are paginated lists consistent?", "duplicates across cursor pages" | `... --check pagination_invariants` (m-20) |
+| "does cancel/archive land the resource in the declared state?", "state-machine" | `... --check lifecycle_transitions` (m-20) |
+| "do captured webhook events match spec.webhooks shape?" | `zond probe webhooks --event-log events.jsonl` (m-20) — recipe: docs/recipes/webhook-receiver.md |
+| "schemathesis-style strict mode" | `... --strict-405 --strict-401` (m-18) |
+| "SARIF for GitHub Code Scanning" | `... --report sarif --output zond.sarif` |
+| "stream findings to a pipeline" | `... --report ndjson \| jq -c '.'` |
+| "scan large API faster" | `... --workers auto` (or `--workers 8`) |
+
+### Strict-mode флаги (m-18)
+
+- **`--strict-405`** — `unsupported_method` принимает только 405 (вместо
+  pragmatic 401/403/404/405). Mirror schemathesis V4 default. Включай
+  когда target — backend, где политика «undeclared method → 405»
+  обязательна (RFC 9110 compliance).
+- **`--strict-401`** — `ignored_auth` no-auth/bogus_auth требует ровно 401
+  (вместо любого 4xx). Включай для проверки точности auth-rejection policy.
+
+Pragmatic режим (default) — реалистичный для production API'ев где gateway
+часто возвращает 404 на undeclared method или 403 на missing auth.
+
+## Iron rules
+
+- **NEVER hand-roll these checks in YAML.** The catalog encodes
+  schemathesis V4 semantics 1-to-1 — replicating them in YAML drifts
+  silently. `zond checks run` is the single source of truth.
+- **NEVER run `--check stateful` without prior `api annotate` review.**
+  m-20 stateful checks (cross_call_references, idempotency_replay,
+  pagination_invariants, lifecycle_transitions) read `.api-resources.local.yaml`
+  for per-API quirks (custom pagination param, non-standard lifecycle
+  field, write-only ignore_fields). Defaults catch the obvious; running
+  on defaults alone misses API-specific drift. See **Phase pre-0** below.
+- **NEVER ignore `--bootstrap-cleanup-failed`.** Stateful security
+  checks (`ignored_auth`, `use_after_free`, `ensure_resource_availability`)
+  produce false positives on stale data. If the previous run's
+  cleanup failed, pass the flag — they skip with a warning instead.
+- **Auth headers are auto-derived from `--api <name>` `.env.yaml`**
+  (`auth_token` → `Authorization: Bearer …`, `api_key` → `X-API-Key`).
+  Add explicit ones with `--auth-header 'Name: value'` (repeatable).
+
+## Phase pre-0 — Annotation (mandatory for `--check stateful`)
+
+> **Heads-up for `pagination_invariants`:** only cursor-style pagination
+> is implemented in this milestone (`cursor`/`next`-token responses).
+> APIs with `type: page` / `type: offset` (GitHub, Linear, Resend, …)
+> are accepted by `annotate apply` but the check short-circuits with
+> "type not implemented" — annotating page-based pagination has **no
+> runtime effect**, skip the dump+apply step for those resources.
+
+m-20 stateful checks rely on per-resource config in
+`.api-resources.local.yaml` (overlay that survives `refresh-api`).
+`zond api annotate` is the canonical authoring path: zond emits raw
+spec slices, **agent (you) writes the YAML**, zond validates and
+applies. **zond itself does NOT call any LLM** — agent is the LLM, zond
+is the dumb-tool.
+
+Six dump aspects (one per check class):
+
+```bash
+zond api annotate dump --api <name> --seed-bodies   > /tmp/seed.json
+zond api annotate dump --api <name> --readback      > /tmp/readback.json
+zond api annotate dump --api <name> --idempotency   > /tmp/idem.json
+zond api annotate dump --api <name> --pagination    > /tmp/pag.json
+zond api annotate dump --api <name> --lifecycle     > /tmp/life.json
+zond api annotate dump --api <name> --resources     > /tmp/orphans.json  # optional: new CRUD resources from orphans
+```
+
+Restrict scope with `--only r1,r2,r3` on any dump.
+
+Agent reads each dump and writes a YAML response file (top-level list
+of entries — see per-check schemas below for the block shape).
+Optional `rationale` and `confidence: high|medium|low` per entry help
+future review.
+
+Apply — dry-run first (renders diff + conflicts), then `--yes` to write:
+
+```bash
+zond api annotate apply --api <name> --readback --input /tmp/readback.yaml         # dry-run
+zond api annotate apply --api <name> --readback --input /tmp/readback.yaml --yes   # write
+zond api annotate apply --api <name> --readback --input /tmp/readback.yaml --yes --force  # overwrite conflicts
+```
+
+Conflicts: when an existing field already has a value, apply keeps
+existing by default (renders `! field: (conflict — kept existing; pass
+--yes to overwrite)`). Pass `--force` to overwrite.
+
+**Recommended pre-stateful sweep on a new API:**
+
+```bash
+zond api annotate dump --api <name> --seed-bodies > /tmp/seed.json    # for prepare-fixtures --seed
+zond api annotate dump --api <name> --readback    > /tmp/readback.json # for cross_call_references
+zond api annotate dump --api <name> --pagination  > /tmp/pag.json     # for pagination_invariants
+zond api annotate dump --api <name> --lifecycle   > /tmp/life.json    # for lifecycle_transitions
+zond api annotate dump --api <name> --idempotency > /tmp/idem.json    # for idempotency_replay
+# … agent generates YAML files for each …
+zond api annotate apply --api <name> --seed-bodies --input /tmp/seed.yaml --yes
+zond api annotate apply --api <name> --readback   --input /tmp/readback.yaml --yes
+zond api annotate apply --api <name> --pagination --input /tmp/pag.yaml --yes
+zond api annotate apply --api <name> --lifecycle  --input /tmp/life.yaml --yes
+zond api annotate apply --api <name> --idempotency --input /tmp/idem.yaml --yes
+```
+
+Each block's YAML format is documented under the per-check section below.
+
+## Reading findings
+
+Every finding carries a closed-enum `recommended_action` so the agent
+can route without parsing free-form messages:
+
+| `recommended_action` | What to do |
+|---|---|
+| `report_backend_bug` | Server returned 5xx / accepted invalid auth / leaked deleted resource. File a backend ticket; do not "fix" the test. |
+| `fix_spec` | Server's behaviour is reasonable but spec doesn't predict it. Update `apis/<name>/spec.json` (or upstream OpenAPI) and `zond refresh-api`. |
+| `tighten_validation` | Server accepted a body that violates the schema. Backend should reject earlier (400/422). |
+| `add_required_header` | Spec marked a header `required: true`; server didn't enforce it. Either enforce it or relax the spec. |
+| `fix_auth_config` | Auth-related failure. Check `apis/<name>/.env.yaml` (`auth_token`, `api_key`) — never log the value. |
+| `fix_network_config` | Transport-level error (timeout / DNS / refused). Verify `base_url` and reachability before re-running. |
+| `wontfix_known_limitation` | Known accepted gap. Don't retry, don't file a bug. |
+
+Triage by `recommended_action` first, then by severity. HIGH/CRITICAL
+gates exit-code 1; LOW/MEDIUM is informational.
+
+## Output formats
+
+```bash
+zond checks run --api myapi --json                 # one envelope: findings[] + summary
+zond checks run --api myapi --report sarif --output zond.sarif
+                                                    # SARIF v2.1.0 for github/codeql-action/upload-sarif@v3
+zond checks run --api myapi --report ndjson | jq -c '.'   # streaming events: check_start, check_result, finding, summary
+```
+
+NDJSON event schema is published at `docs/json-schema/ndjson-events.schema.json`
+— pipe through `ajv validate` if you build a downstream consumer.
+
+## Scoping a run
+
+Long runs feel sluggish on a 200-endpoint spec. Scope down before
+broadening:
+
+```bash
+# Filter operations (regex) — same grammar as `zond generate`
+zond checks run --api myapi --include 'tag:billing,users' --exclude 'method:DELETE'
+
+# Pick a vector
+zond checks run --api myapi --mode positive       # contract verification only
+zond checks run --api myapi --mode negative       # malicious-input probes only
+
+# Pick a phase
+zond checks run --api myapi --phase coverage      # deterministic boundary values
+zond checks run --api myapi --phase examples      # default — one positive + one negative per op
+```
+
+`--allow-x00` adds the NUL byte (`\x00`) to string boundaries during
+coverage — off by default (some HTTP/JSON stacks panic on it).
+
+## Concurrency
+
+```bash
+zond checks run --api myapi --workers auto        # min(cpus, 8); usually right
+zond checks run --api myapi --workers 16          # explicit; clamped to 64
+zond checks run --api myapi --workers 8 --rate-limit 50
+                                                    # 8 workers, global 50 RPS budget
+```
+
+Workers parallelize at the *operation* level — cases inside one
+operation always run sequentially (CRUD chain ordering must be
+preserved). `--rate-limit auto` adapts from `RateLimit-*` response
+headers (RFC 9568); use it on rate-limited APIs to avoid bursting.
+
+## "0 findings" doesn't always mean "all green"
+
+The summary one-liner now ends with `(N check outcome(s) skipped: …)`
+when probes can't validate (e.g. `response_schema_conformance: no JSON
+Schema on this response branch ×2` when probes ran without auth and
+got a 4xx that the spec only declares for 2xx). Treat skipped probes
+as "not yet exercised", not "passed" — re-run with auth (or via
+`zond run --validate-schema`) to actually cover those branches.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | No HIGH/CRITICAL findings (LOW/MEDIUM may be present). |
+| 1 | At least one HIGH/CRITICAL finding — gate CI on this. |
+| 2 | CLI-input error (bad flag value, unreachable spec, etc.). |
+
+## Common combos
+
+```bash
+# Full conformance pass on staging, output SARIF for code scanning
+zond checks run --api staging --report sarif --output zond.sarif --workers auto
+
+# Just the security checks (stateful) with explicit auth
+zond checks run --api prod \
+  --check ignored_auth,use_after_free,ensure_resource_availability \
+  --auth-header 'Authorization: Bearer $TOKEN'
+
+# Coverage-phase boundary sweep, NDJSON pipe into a watcher
+zond checks run --api dev --phase coverage --report ndjson | \
+  jq -c 'select(.type == "finding") | {check, op: .finding.operation, action: .finding.recommended_action}'
+
+# Cross-call POST→GET drift only (m-20, single CRUD-chain check per resource)
+zond checks run --api stripe --check cross_call_references
+```
+
+## Cross-call drift (m-20 ARV-169)
+
+`cross_call_references` — POST resource → GET resource, diff write-shape
+vs read-shape. Surfaces fields the server silently dropped:
+
+- **state_not_persisted** — POST 2xx echoed the field, GET dropped it.
+  HIGH-signal: server lied about persisting state.
+- **write_only** — POST accepted, GET dropped. Spec-declared write-only
+  fields (passwords, etc.) are auto-filtered.
+
+Tunable per-resource in `apis/<name>/.api-resources.yaml` (или
+`.api-resources.local.yaml` overlay):
+
+```yaml
+resources:
+  - resource: customer
+    # … existing fields …
+    readback_diff:
+      ignore_fields: [metadata, livemode]      # API-quirks, suppress
+      write_to_read_map:
+        tax_id_data: tax_ids                   # write-shape → read-shape
+```
+
+Defaults already filter timestamps (`created_at`, `updated_at`), envelope
+fields (`object`, `_links`), and ETag. Per-API quirks need a yaml line.
+Authored either by hand or via the `zond api annotate dump --readback` →
+agent → `apply` flow (see **Phase pre-0** above). zond emits the
+write+read endpoint slice; agent decides `ignore_fields` /
+`write_to_read_map` and writes the YAML; zond validates + writes to
+`.api-resources.local.yaml`.
+
+## Idempotency replay (m-20 ARV-170)
+
+`idempotency_replay` — two POSTs with the same `Idempotency-Key` header.
+Server must (a) return the same resource id and (b) bit-identical response
+bodies (modulo timestamps / request-id / etag).
+
+- **duplicate_resource** — ids differ → server ignored the key. HIGH.
+- **non_bit_identical** — same id but bodies drift on non-ignored fields
+  → replay isn't truly idempotent. Surfaced in the same HIGH finding via
+  `evidence.kind`.
+
+Two ways to opt-in per resource:
+
+1. Spec declares `Idempotency-Key` as a header parameter on the create
+   endpoint → auto-detected, runs with defaults.
+2. `.api-resources.local.yaml` block (preferred — documents intent +
+   lets you tune the ignore list). Author via Phase pre-0
+   `annotate dump --idempotency` → agent → `apply`:
+
+```yaml
+resources:
+  - resource: charge
+    # … existing fields …
+    idempotency:
+      header: Idempotency-Key            # default; override for non-standard names
+      scope: endpoint                    # informational; `endpoint` | `global`
+      ignore_response_fields:            # added on top of timestamp/request_id baseline
+        - retry_after
+```
+
+Anti-FP: 429/409 on the 2nd POST → skip with cleanup. No DELETE on the
+group → finding still fires, evidence carries `cleanup_warning`.
+
+## Pagination invariants (m-20 ARV-171)
+
+`pagination_invariants` — fetch two consecutive cursor pages and assert
+the contract holds:
+
+- **duplicate_items** — an item id appears on both page A and page B
+  (off-by-one / cursor stops one short). HIGH-signal.
+- **has_more_inconsistent** — page A said `has_more=true`, but page B is
+  empty and doesn't flip to `has_more=false`. Surfaces broken end-of-list
+  signalling.
+- **partial_page_with_has_more** — page A returns fewer items than the
+  requested limit *yet* advertises `has_more=true`. Means the cursor is
+  prematurely truncating responses.
+
+Cursor-style only in this milestone (Stripe / GitHub / Resend / Linear
+pattern). `page` / `offset` / `token` declarations parse but the check
+short-circuits with a "type not implemented" reason so the yaml block
+stays a stable schema.
+
+Auto-detect: if the list endpoint declares `starting_after` / `cursor` /
+`after` / `page_token` as a query parameter, the check runs with
+defaults (`cursor_field=id`, `items_field=data|items|results`,
+`has_more_field=has_more`, `limit=2`).
+
+Per-resource yaml override (author via Phase pre-0
+`annotate dump --pagination` → agent → `apply`):
+
+```yaml
+resources:
+  - resource: customer
+    # … existing fields …
+    pagination:
+      type: cursor                   # only cursor supported today
+      cursor_param: starting_after   # Stripe-style; "after" / "cursor" / "page_token" also work
+      cursor_field: id               # field on each item that feeds the next cursor
+      has_more_field: has_more       # response field that flips on end-of-list
+      limit_param: limit             # query param for page size
+      default_limit: 2               # probe page size — small on purpose
+      items_field: data              # array container (falls back to items / results / value)
+```
+
+## Lifecycle transitions (m-20 ARV-172)
+
+`lifecycle_transitions` — declare a state machine in
+`.api-resources.yaml`, the check creates a resource and walks the
+named actions, asserting:
+
+- **undeclared_state** — observed state isn't in declared `states[]`.
+- **wrong_expected_state** — action landed the resource in a state other
+  than its declared `expected_state`.
+- **forbidden_transition** — observed (from, to) isn't in declared
+  transitions graph.
+- **state_regression_on_replay** — invoking the action a second time
+  drifted state instead of staying idempotent.
+- **double_action_5xx** — replay 5xx'd. Idempotent actions should 4xx
+  or 2xx, never crash.
+- **action_rejected** — first-call non-2xx (server-side gating). Not a
+  contract bug per se, surfaced as INCONCLUSIVE-class info.
+
+Manifest validation runs at yaml load (catches cycles, unreachable
+states, missing terminal, actions referencing undeclared states)
+before any HTTP call goes out.
+
+Author via Phase pre-0 `annotate dump --lifecycle` → agent → `apply`.
+The dump emits action-endpoint candidates (POST `/{resource}/{id}/cancel`,
+PATCH `/{resource}/{id}/status` etc.); agent decides the state machine
+graph.
+
+```yaml
+resources:
+  - resource: subscription
+    # … existing fields …
+    lifecycle:
+      field: status
+      states: [pending, active, cancelled]
+      transitions:
+        - from: pending
+          to: [active, cancelled]
+        - from: active
+          to: [cancelled]
+        - from: cancelled
+          to: []                     # terminal
+      actions:
+        cancel:
+          endpoint: POST /v1/subscriptions/{id}/cancel
+          expected_state: cancelled
+```
+
+Action endpoints accept the `{id}` placeholder (replaced with the
+captured create-id) or `{<idParam>}`. Body-less actions are the common
+case; provide `body:` only for actions that demand a request payload.

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

@@ -0,0 +1,210 @@
+---
+name: zond-triage
+description: |
+  Last-run triage. Use when the user asks "что упало в последнем run", "почему
+  красное", "что с ralph-loop'ом сделать", "summary последнего прогона",
+  "explain failures", "что мне сейчас править". Reads `recommended_action`
+  enum from `zond db diagnose`, `zond check spec`, and `zond probe <class>` JSON
+  artifacts and emits an actionable summary grouped by next-step. No LLM
+  classification — every line is routed by the enum value emitted by zond.
+allowed-tools: [Read, Bash(zond *), Bash(bunx zond *), Bash(jq *)]
+---
+
+# zond-triage — last-run summary
+
+Narrow skill: the user already has a finished run (or a recent
+`probe <class>` / `check spec` artifact) and wants to know **what failed and
+what to do next**. Sibling `zond` does the full audit + writes
+scenarios; this one only reads.
+
+## Iron rules
+
+- **Route on `recommended_action`, not on the message string.** Every zond
+  artifact stamps a closed enum: `report_backend_bug | fix_test_logic |
+  fix_auth_config | fix_network_config | fix_env | fix_spec |
+  fix_fixture | regenerate_suite | tighten_validation | add_required_header |
+  wontfix_known_limitation`. The last three (m-15 ARV-11) carry
+  depth-check findings from `zond checks run`; `regenerate_suite`
+  (m-16 ARV-42) means the failing YAML was emitted by `zond generate`
+  and editing it would be clobbered — re-run `zond generate --api
+  <name>` (or refine `.api-resources.yaml`) instead. Same triage rules
+  apply across the board: route by enum value. Group by enum, then
+  summarise. Never re-classify with prose heuristics.
+- **One actionable line per group.** The agent-directive *is* the next
+  command — don't pad with "consider checking...".
+- **`report_backend_bug` / 5xx → STOP, surface, do not edit `expect:`.**
+  Same iron rule as the parent `zond` skill.
+- **`fix_env` overrides `fix_test_logic` at the suite level.** `db
+  diagnose` already does this collapse (TASK-70/98) — trust the field
+  it returns, don't merge again client-side.
+- **Never read raw response bodies past 8 KB.** The diagnose envelope
+  truncates by default; pass `--no-body-cap` only if the user is
+  triaging body-shape bugs.
+- **Никогда не выдавать абстрактные «проверьте логи» / «уточните у
+  команды».** Если в enum-группе нет конкретного действия — пометить
+  `<TODO: clarify>` и выйти, не маскировать пустоту.
+
+## Sources & enum routing
+
+| Source | How to read | Emits `recommended_action` for |
+|---|---|---|
+| `zond db diagnose <run-id> --json` | per-failure under `data.failures[]` | every fail/error in the run |
+| `zond check spec --api <name> --json` | `data.issues[]` | every lint Issue (always `fix_spec`) |
+| `zond probe mass-assignment --json` | `data.verdicts[]` | per-endpoint verdicts (high/medium/inconclusive-5xx/inconclusive-baseline) |
+| `zond probe security --json` | counts only — read the markdown digest | high / low findings (markdown table) |
+| `zond probe static --json` | `data.files[]` (suite YAMLs to run) | findings surface only after `zond run` → routed via diagnose |
+
+`probe security` does not expose findings in `--json`; treat its
+markdown digest as the canonical source for that class and parse
+HIGH/LOW rows by hand.
+
+## Phase 1 — locate the run
+
+If the user did not name a run id, the default of `zond db diagnose`
+already targets the most recent failing run (TASK-266). Skip straight to
+Phase 2 unless you specifically need an older run:
+
+```bash
+zond db runs --limit 5 --json   # pick a non-default run id
+```
+
+If `trigger=ci`, mention the CI build in the summary. If the user said
+"после моего фикса", take the second-most-recent and pair with
+`zond db compare <prev> <curr> --json` for a regression diff.
+
+## Phase 2 — pull the diagnose envelope
+
+```bash
+zond db diagnose --json              # last failing run (default — TASK-266)
+zond db diagnose <run-id> --json     # explicit run
+zond db diagnose --latest --json     # last run, even if it passed
+```
+
+The shape (relevant fields only):
+
+```jsonc
+{
+  "ok": true,
+  "data": {
+    "run_id": 42,
+    "summary": { "passed": 18, "failed": 7, "errored": 1 },
+    "env_issue": { "scope": "suite", "affected_suites": [...], "message": "..." },
+    "failures": [
+      {
+        "suite_name": "crud-projects",
+        "test_name": "create project",
+        "failure_type": "api_error",
+        "recommended_action": "report_backend_bug",
+        "request_method": "POST",
+        "request_url": "...",
+        "response_status": 500,
+        "hint": "...",
+        "schema_hint": "..."
+      }
+    ]
+  }
+}
+```
+
+Bucket every failure by `recommended_action`. Display order (highest
+priority first):
+
+1. `report_backend_bug` — 5xx / schema_violation / mass-assignment HIGH.
+   Bug. Surface excerpt; offer `zond report bundle --include case-study`.
+2. `fix_spec` — emitted only by `zond check spec`. Edit OpenAPI source,
+   then `zond refresh-api <name>`.
+3. `fix_auth_config` — 401/403 cluster. Check `auth_token` scope (or run
+   `zond doctor --api <name> --missing-only`).
+4. `fix_env` — env_issue cluster. Print `env_issue.message` verbatim;
+   point at `.env.yaml` (path is in the envelope).
+5. `fix_fixture` — `prepare-fixtures` miss-* or inconclusive-baseline
+   from mass-assignment. Run
+   `zond prepare-fixtures --api <name> --apply [--cascade [--seed]]`. If
+   the run was post-probe and IDs may be stale, prefer
+   `prepare-fixtures --refresh` (TASK-281) and follow with `zond cleanup
+   --orphans` (TASK-278) before retrying.
+6. `fix_network_config` — connect-refused / DNS / TLS. Check `base_url`
+   reachability; `--proxy` may be needed.
+7. `regenerate_suite` (ARV-42) — 4xx (400/422) on a generator-emitted
+   suite under `apis/<name>/tests/`. Editing the YAML is wrong: the
+   next `zond audit` overwrites it. Re-run `zond generate --api <name>`
+   so newer heuristics apply (e.g. ARV-38 default-string), or refine
+   `.api-resources.yaml` hints when the body shape can't be inferred.
+8. `fix_test_logic` — 4xx (400/422) on a manually-authored suite, or any
+   leftover assertion failure not absorbed by the buckets above. Phase 4a
+   of the `zond` skill: fixture pack first, typed generator second,
+   literal third.
+
+Within each bucket, collapse by `(suite_name, response_status,
+request_method, root_cause)` and report a count + 1-2 examples. Do
+**not** dump every failure.
+
+## Phase 3 — reconcile spec / probe sources
+
+Run only what the user's question implies — don't fan out blindly.
+
+```bash
+# spec-level lint (only if user asked about spec drift / contract)
+zond check spec --api <name> --json | jq '.data.issues | group_by(.rule)'
+
+# mass-assignment digest (only if user mentioned mass-assign / privilege)
+zond probe mass-assignment --api <name> --json
+# verdicts with recommended_action != null are the actionable subset
+```
+
+For `probe security`, the digest is the source. Read the file the user
+named (or `apis/<name>/probes/security-digest.md`) and pull HIGH rows
+plus the `## ⚠️ Cleanup failures` section if present.
+
+## Output template
+
+Stay terse. Russian by default, mirror the user's language.
+
+```
+Run #<id> · <ts> · session=<id?> · trigger=<ci|manual>
+Pass <N>  Fail <M>  Error <K>  Coverage <pct>%
+
+⛔ report_backend_bug  ×<n>
+  · POST /v1/projects → 500 (×3) — TypeError: cannot read 'slug'
+    next: zond report bundle <id> --include case-study
+🛠  fix_test_logic  ×<n>
+  · POST /v1/audiences → 422 expected uuid (×2)
+    next: replace {{$randomString}} with {{$uuid}} in audiences.yaml
+🔑 fix_auth_config  ×<n>
+  · 4 suites all 401 — check auth_token scope
+    next: zond doctor --api <name> --missing-only
+🌐 fix_env  ×<n>
+  · base_url unset (env_issue.scope=run)
+    next: edit apis/<name>/.env.yaml → base_url
+📥 fix_fixture  ×<n>
+  · {{audience_id}} unresolved
+    next: zond prepare-fixtures --api <name> --apply --cascade
+📜 fix_spec  ×<n>  (from check spec)
+  · A2 missing operationId on POST /webhooks
+    next: edit spec.json → operationId, then zond refresh-api <name>
+```
+
+Skip empty buckets. If `summary.failed + summary.errored == 0`, just
+say "all green" and exit — don't invent work.
+
+## When to escalate
+
+- **Mixed recommended_action inside one suite (>3 distinct enums):**
+  the run was probably aborted mid-setup. Check `env_issue` first; if
+  not set, the run hit a fatal early failure — `zond db run <id>
+  --status 500 --first-only --json` to find it.
+- **Cleanup failures from `probe security`:** call out at the **top** —
+  this means probe mutated state it could not restore. Treat as
+  blocking; do not run more probes against the same env until the
+  user confirms manual cleanup.
+- **`recommended_action` missing on a verdict you expected to see:**
+  TASK-294 stamps it on every issue/finding emitted post-Done. If a
+  field is missing, you're probably reading a pre-TASK-294 artifact —
+  re-run the source command, don't infer.
+
+## Hand-off back to `zond`
+
+When the user wants to *act* on the summary (write a fix, file a
+report, re-run the suite), hand off to the parent `zond` skill — it
+owns the YAML edits, `zond report bundle` flow, and the re-run loop.
+This skill stops at the summary.