@kirrosh/zond 0.22.0 → 0.26.0

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

@@ -0,0 +1,114 @@
+---
+name: zond-seed
+description: |
+  Agent-orchestrated auto-seed: create the fixtures a deep audit needs from
+  what the API itself offers, so CRUD depth stops being gated by hand-seeded
+  `{{account}}`/`{{customer}}`/… ids. Use when `prepare-fixtures` reports
+  `unseededRoots`, when `db diagnose` shows `cascade_skips`, or the user asks
+  to "seed fixtures", "create test data", "un-skip the CRUD chains", "raise
+  depth". YOU reason (read the API graph, author create-bodies, order them,
+  read the 4xx and fix it); zond only EXECUTES (POST + capture id into
+  `.env.yaml`). Sibling `zond` runs the full audit; hand back to it once
+  fixtures are seeded.
+allowed-tools: [Read, Write, Edit, Bash(zond *), Bash(bunx zond *)]
+---
+
+# zond-seed — agent-orchestrated fixture creation
+
+The m-24 endgame: an autonomous seed loop where the DECISION is yours and the
+EXECUTION is zond's. This is **not** a revert of ARV-336 (the blind recursive
+cascade zond removed — 1% success on Stripe). The difference is the feedback
+loop: you read the spec + resource graph, author a create-body, POST it, and
+when the server says 400 you read *why* and fix the body. That is exactly why
+it works where the heuristic engine failed.
+
+## Iron rules (read once, apply always)
+
+- **You reason, zond executes.** You author every create-body and pick the
+  order; zond only POSTs and captures the returned id. Never ask zond to
+  "figure out" a body — that heuristic engine was deleted (ARV-336, m-24) and
+  must not grow back. There is no `zond seed` command by design.
+- **No blind cascade — one create at a time, with a feedback loop.** POST a
+  body, read the response. On 4xx, read the error message, revise the *specific*
+  field it names, retry. Cap at **~3 attempts per resource**, then mark it
+  un-seedable and move on. Never fire a chain of creates without reading each
+  reply.
+- **Seed only what the API can self-serve.** Fixtures needing external input —
+  KYC-verified accounts, verified bank accounts, webhook signing secrets,
+  paid-plan / SCIM / TOS-gated resources, or ids that only exist after a real
+  event (`issue_id`, `file_id`, `integration_id`) — are **reported, not
+  invented** (pairs with `prepare-fixtures` `unseededRoots` and ARV-349/350).
+  Guessing a value here just 422s and lies about coverage. Hand those to the
+  **`warm-up-target`** skill, which warms them via the target's own SDK/CLI.
+- **Live + throwaway/sandbox + cleanup only.** Never seed against production or
+  shared data. Confirm `base_url` is a sandbox/test account first. Track every
+  id you create and DELETE it at the end (or seed inside a disposable account /
+  Stripe test-clock). If you cannot guarantee cleanup, ask before creating.
+- **Honor prose exclusion.** Specs document mutual exclusion in `description`,
+  not machine-readable `oneOf` (Stripe: "You may only specify one of A, B").
+  If a 400 says that, drop one member and retry (folded from ARV-347).
+
+## Inputs — what to seed
+
+| Signal | Command | Field |
+|---|---|---|
+| Chain-heads gating suites | `zond prepare-fixtures --api <name> --json` | `summary.fixtureGaps.unseededRoots[]` |
+| Empty captures from last run | `zond db diagnose --json` | `cascade_skips[].capture_var` |
+| Dependency order | `apis/<name>/.api-resources.yaml` | each resource's `fkDependencies` |
+| Body schema + last server reply | `zond api annotate dump --seed-bodies --with-last-attempt --api <name>` | `seed_body`, `last_attempt` |
+
+`unseededRoots` is your worklist. `fkDependencies` gives the order: a resource
+whose FK points at another must be created *after* its parent (parent id is
+captured first, then referenced). Sort parent-before-child yourself; skip
+cycles and resources whose only dep is external input.
+
+**miss-no-list `candidates` (ARV-382):** when prepare-fixtures can't confidently
+derive the owner list for a fixture var, the item carries a `candidates[]` of
+plausible GET/list endpoints (ranked by structural proximity; deprecated ones
+marked `(deprecated)`). zond does NOT pick — that's your call: `zond request`
+the top candidate, read a record, `zond fixtures add <var>=<id>`. An empty
+`candidates` (and no owner) is an honest dead-end: no listable source exists —
+create the resource or obtain the id from a parent flow.
+
+## The loop
+
+For each root, parent-first:
+
+1. **Author the body.** `zond api annotate dump --seed-bodies --with-last-attempt`
+   gives the schema, a rationale, and `last_attempt` (what zond last POSTed and
+   how the server replied). Fill required fields with real-looking values;
+   reference already-captured parents as `{{parent_var}}`.
+
+2. **Create + capture** — one command, deterministic:
+   ```bash
+   zond request POST /v1/accounts --api <name> \
+     --body '{"type":"custom","country":"US","capabilities":{...}}' \
+     --json-path id --capture account
+   ```
+   On 2xx zond writes `account=<id>` into `apis/<name>/.env.yaml` (with a
+   `.bak` backup) and prints `captured account=<id>`. On non-2xx it writes
+   nothing and prints `--capture account skipped — … status=400 …`.
+
+3. **Feedback on failure.** Read the response body. Common fixes:
+   - "Missing required field X" → add X.
+   - "You may only specify one of A, B" → drop one (prose exclusion).
+   - "Invalid <field>" / 422 on an id → the value is external-input; stop
+     retrying this root and mark it un-seedable.
+   Revise the `--body`, retry. Cap ~3 attempts.
+
+4. **Cascade.** Once a parent id is captured, its children unblock — their
+   `{{parent_var}}` now resolves. Walk down the dependency chain.
+
+5. **Verify.** Re-run `zond prepare-fixtures --api <name> --json` — the roots
+   you seeded should drop out of `unseededRoots`.
+
+## Cleanup & report
+
+- DELETE every id you created (reverse order — children first), or confirm the
+  seed account is disposable.
+- Report: **seeded** (var → id), **un-seedable** (var → reason: external input
+  / gated / no create endpoint). The un-seedable list is the honest ceiling —
+  hand it to the user; do not paper over it with invented values.
+
+Hand back to `zond` for the full audit once depth is unblocked. Measure the
+lift: test coverage before vs after seeding.

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

@@ -0,0 +1,272 @@
+---
+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.
+- **Never read raw response bodies past 8 KB.** The diagnose envelope
+  truncates by default; to see full bodies, bundle the run instead
+  (`zond report bundle <id> --no-body-cap`) — only when 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.endpoints[]` (action under `findings[].evidence.recommended_action`) | 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. Besides
+status transitions, the payload carries `.data.body_changes[]` (ARV-339) —
+per-test field-level response-shape diff (`added` / `removed` /
+`type_changed`), i.e. how the contract moved even where status stayed green.
+Each change carries `scope` (ARV-352): `container` = response envelope /
+pagination skeleton (real drift), `element` = a field inside a collection
+item (path crosses `[]`). On list/log endpoints two runs return DIFFERENT
+objects, so `element`-scoped changes are schema-of-union variance across the
+re-sampled set — NOT contract drift. `summary.bodyChangesContainer` /
+`bodyChangesElement` split the count so you can tell "12 field diffs, all
+element-scope on /v1/events" (data variance) from real envelope drift.
+
+## 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
+zond db diagnose --report yaml       # same payload as YAML (ARV-338) — for run snapshots you keep/diff as text
+# ARV-380: aggregate by_recommended_action across a run SET (same --union
+# vocabulary as `zond coverage`) instead of looping per run and merging:
+zond db diagnose --union session --json                # all runs in the active session
+zond db diagnose --union since:2h --api <name> --json  # runs in a time window (scoped to a collection)
+zond db diagnose --union runs:263,266,269 --json       # an explicit run-id set
+```
+
+The shape (relevant fields only):
+
+```jsonc
+{
+  "ok": true,
+  "data": {
+    "run_id": 42,
+    "summary": { "passed": 18, "failed": 7, "errored": 1 },
+    "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
+      }
+    ]
+  }
+}
+```
+
+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` — unresolved variables / broken base_url. Point at
+   `.env.yaml` and the failing `request_url` values (unresolved
+   `{{var}}` placeholders are visible right in them).
+5. `fix_fixture` — `prepare-fixtures` miss-* or inconclusive-baseline
+   from mass-assignment. Run `zond prepare-fixtures --api <name> --apply`
+   (single-pass); fill any remaining gaps by hand (`fixtures add` /
+   editing `.env.yaml`). 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/`. Prefer re-running `zond generate
+   --api <name>` so newer generation applies (e.g. ARV-38 default-string),
+   or refine `.api-resources.yaml` hints when the body shape can't be
+   inferred. If you DO hand-edit the YAML, delete its `# Auto-generated`
+   header so regenerate preserves it (ARV-361) — otherwise a re-run
+   regenerates it; `--force` overwrites even header-stripped files.
+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.
+
+### Shortcut: `by_recommended_action` envelope (ARV-101/ARV-228)
+
+`zond db diagnose --json` ships a pre-aggregated envelope keyed by the
+`recommended_action` enum so triage agents skip the `jq | group_by`
+step. Each bucket carries up to 5 examples with full request context
+(method, path, status, trimmed reason) — enough to render the output
+template below without re-fetching `failures[]`.
+
+Shape (extracted from `.data.by_recommended_action`):
+
+```jsonc
+{
+  "fix_auth_config": {
+    "count": 4,
+    "examples": [
+      {
+        "suite": "github-smoke",
+        "test": "GetNotifications",
+        "method": "GET",
+        "path": "/notifications",
+        "status": 401,
+        "reason": "expected 200, got 401"
+      }
+      // … up to 5 entries
+    ]
+  },
+  "report_backend_bug": { "count": 12, "examples": [ … ] }
+}
+```
+
+Iterate the priority order in the table above (`report_backend_bug` →
+`fix_test_logic`); for each present key, `count + examples` is enough
+to build the per-bucket section. Fall back to `failures[]` only when
+you need details outside the example slice (full response body, the
+6th example, etc).
+
+## 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.
+
+### Cross-phase double-emit (ARV-358)
+
+A single backend defect surfaces in more than one phase stream, so a naive
+HIGH count over-reports. The `checks` phase (`30-checks.ndjson`, e.g.
+`not_a_server_error`) and the `stateful` phase (`40-stateful.ndjson`, e.g.
+`cursor_boundary_fuzzing`) can both flag the *same* endpoint 5xx — that's
+one defect counted 3–4×. zond does NOT dedup this for you: the check_ids
+differ, so collapsing them is a "same root cause" judgment (attribution),
+which is your job, not the tool's. When counting, **group by `(method,
+path, status)` across phase streams**, not by raw finding count — one
+`GET /v1/billing/alerts → 500` is one defect even if it appears 4 times.
+
+## 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 — request_url resolved to "/v1/projects"
+    next: edit apis/<name>/.env.yaml → base_url
+📥 fix_fixture  ×<n>
+  · {{audience_id}} unresolved
+    next: zond prepare-fixtures --api <name>  (reports the gap; fill it via `fixtures add` / .env.yaml)
+📜 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. Look for unresolved `{{var}}`
+  in `request_url` first; if none, the run hit a fatal early failure —
+  `zond db run <id> --status 500 --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.