@kirrosh/zond 0.23.0 → 0.26.0

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

@@ -34,11 +34,9 @@ scenarios; this one only reads.
   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
+  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-группе нет конкретного действия — пометить
@@ -50,7 +48,7 @@ scenarios; this one only reads.
 |---|---|---|
 | `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 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 |
 
@@ -70,7 +68,17 @@ 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.
+`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
 
@@ -78,6 +86,12 @@ If `trigger=ci`, mention the CI build in the summary. If the user said
 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):
@@ -88,7 +102,6 @@ The shape (relevant fields only):
   "data": {
     "run_id": 42,
     "summary": { "passed": 18, "failed": 7, "errored": 1 },
-    "env_issue": { "scope": "suite", "affected_suites": [...], "message": "..." },
     "failures": [
       {
         "suite_name": "crud-projects",
@@ -97,9 +110,7 @@ The shape (relevant fields only):
         "recommended_action": "report_backend_bug",
         "request_method": "POST",
         "request_url": "...",
-        "response_status": 500,
-        "hint": "...",
-        "schema_hint": "..."
+        "response_status": 500
       }
     ]
   }
@@ -115,21 +126,24 @@ priority first):
    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).
+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 [--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.
+   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/`. 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.
+   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,
@@ -139,6 +153,42 @@ 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.
@@ -156,6 +206,18 @@ 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.
@@ -174,11 +236,11 @@ Pass <N>  Fail <M>  Error <K>  Coverage <pct>%
   · 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)
+  · 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> --apply --cascade
+    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>
@@ -190,9 +252,9 @@ 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.
+  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