@fateforge/xpedition-cli 1.0.0

package/.agent/CLI-SPEC.md

@@ -0,0 +1,1073 @@
+# Agent-Facing CLI Design Spec
+
+
+This document defines the machine contract a CLI must honor when called by an AI agent. The goal: agents can call it reliably, parse it reliably, recover and retry reliably, and never block or mis-write in a non-interactive setting.
+
+## 1. Core rules
+
+1. stdout is the contract: emit a single valid JSON document by default; no logs, progress, prompts, or color codes mixed in.
+2. stderr is the side channel: progress, warnings, debug, and error explanations all go to stderr.
+3. Machine-first: default `--format json`; `text` is for humans only; `raw` is for raw bytes, logs, diffs passed through verbatim.
+4. Non-interactive safe: write operations must not wait on keyboard input; use `--dry-run` + `--confirm <token>`.
+5. Deterministic: same input produces the same output structure; field names, field order, and schema version stay stable.
+6. Least surprise: queries don't change state; a write with no valid confirm token must fail rather than proceed.
+7. Recoverable: error codes, exit codes, and `retryable` must be stable enough for an agent to decide retry, back off, or ask the user.
+
+## 2. Global flags
+
+| Flag | Meaning |
+|------|---------|
+| `--format json/text/raw` | Output format, default `json` |
+| `--json` | Compatibility alias for `--format json`; not recommended for new calls |
+| `--fields <a,b,c>` | Return only selected fields, reduces tokens (query commands) |
+| `--compact` | Compact JSON output, strips redundant whitespace (query commands) |
+| `--dry-run` | Simulate a write, return a change preview and `confirm_token` |
+| `--confirm <token>` | Carry the dry-run token to actually execute the write |
+| `--quiet` | Suppress progress/prompts on stderr, never suppress errors |
+
+`update` is a **single command, not a write with a confirm gate** (see §14): a
+bare `update` performs the whole self-update in one call. It may add
+tool-specific flags such as `--target-version` or `--channel`, and it keeps
+`--check` and `--dry-run` as **optional read-only** flags, but it does NOT take
+`--confirm <token>` — self-update is exempt from the §7 write gate.
+
+Format responsibilities:
+
+- `json`: structured machine output, the default, and the only format recommended for agents.
+- `text`: human-readable, may change, must not be parsed programmatically.
+- `raw`: unwrapped bytes / log / diff, passed through verbatim, no JSON envelope.
+
+## 3. Unified output envelope
+
+Success and failure share one shape. The agent only needs to check `ok` first.
+
+Success:
+
+```json
+{
+  "ok": true,
+  "schema_version": "1.0",
+  "data": {},
+  "meta": {
+    "duration_ms": 0
+  }
+}
+```
+
+Failure:
+
+```json
+{
+  "ok": false,
+  "schema_version": "1.0",
+  "error": {
+    "code": "E_NOT_FOUND",
+    "message": "human readable message",
+    "details": {},
+    "retryable": false
+  },
+  "meta": {
+    "duration_ms": 0
+  }
+}
+```
+
+Conventions:
+
+- Every JSON response must include `ok` and `schema_version`.
+- `data` is always the command's business payload; do not hoist business fields to the envelope top level.
+- `error.code` is a stable semantic enum, prefixed with `E_`.
+- `error.message` is for humans; agents should not parse it.
+- `error.details` holds structured context; must be redacted.
+- `error.retryable` tells the agent whether it may back off and retry automatically.
+- `meta.duration_ms` records command execution time. `meta` is always emitted on
+  every response (success and error); do not mark it `omitempty`, since
+  `duration_ms: 0` is a valid value the agent should always be able to read.
+- `meta.notices[]` (optional) MAY carry ambient operational notices — currently
+  the update-available notice — read **only from the local cache**, never via a
+  network call. Each notice has a `severity` (`info` | `warning`).
+  Omit the field when there is nothing to report. See §14.
+- A breaking schema change must bump the `schema_version` major version.
+
+### 3.1 Canonical machine contract (`contract.json`) — single source, enforced
+
+The prose in §3/§6/§11 has a machine-readable twin: **`contract/contract.json`**,
+maintained **only** in this template repo and the single source of truth for the
+fields every tool shares. It encodes the envelope key sets, the `E_*` ↔ exit ↔
+`retryable` table, the self-description required keys, naming convention,
+pagination/batch shapes, and the `_untrusted` key.
+
+- **One source, vendored copies, no drift.** A tool does not hand-author these.
+  It vendors `contract.json` (and the `.agent` specs) pinned to a spec tag in
+  `.agent/SPEC_VERSION`, regenerates a per-language module (`contract_gen.{go,py}`)
+  from it via `scripts/gen-contract.js`, and a fail-closed CI guard
+  (`scripts/check-spec.js`) keeps both byte-identical to `template@<pin>` and the
+  generated module in sync with `contract.json`. Editing the contract happens in
+  the template; tools bump the pin and run `scripts/sync-spec.js`.
+- **Core is frozen; features extend, never redefine.** `error_codes.core` is
+  identical in every tool (this is what makes exit-code/retryable behavior
+  portable). A tool's unique error codes live in `contract-ext.json` and are
+  validated: an ext code is `E_*`, must declare `{exit, retryable}`, must not
+  shadow a core code, and exit `9` is reserved for human-action codes
+  (`E_HUMAN_REQUIRED`, `E_2FA_REQUIRED`). This is how the contract stays uniform
+  while supporting tool-specific fields.
+- **Enforcement calibration.** Envelope keys, the error-code table, `meta` keys,
+  and the `schema_version` value are matched **exactly**. Self-description blocks
+  (`reference` / `context` / `doctor` / `changelog` / `update`) must contain the
+  **required** canonical keys but may add tool-specific ones — so a unique feature
+  command is never blocked, only the shared surface is pinned. A runtime
+  conformance test (per tool) asserts actual command output against
+  `contract.json`.
+
+## 4. stdout / stderr rules
+
+- In `json` mode, stdout may contain only one JSON document, or NDJSON for explicitly streaming commands.
+- stderr may carry progress, warnings, and diagnostics.
+- On error in `json` mode, the failure envelope is that single JSON document on stdout — agents always parse stdout and check `ok`, never scrape stderr. stderr may add human-readable explanation.
+- `--quiet` may only suppress non-error info on stderr.
+- No banners, prompts, progress bars, or color codes before/after the JSON on stdout.
+- stdout / stderr are always **UTF-8 encoded, no BOM**, newline `\n`, so agents parse reliably across platforms (especially Windows).
+
+## 5. Streaming output (NDJSON)
+
+Large output, log streams, subscription streams, and per-item batch results use NDJSON. Each line must be an independent valid JSON object — easy to consume streaming, low memory, interruptible:
+
+```jsonl
+{"ok":true,"schema_version":"1.0","type":"item","data":{}}
+{"ok":true,"schema_version":"1.0","type":"item","data":{}}
+{"ok":true,"schema_version":"1.0","type":"summary","data":{"count":2}}
+```
+
+Conventions:
+
+- Normal queries use a single JSON envelope by default.
+- Use NDJSON only when the command is explicitly a log / stream / subscribe / batched-stream.
+- NDJSON lines must include `ok`, `schema_version`, `type`.
+- The final line should use `type: "summary"`.
+- True binary or plain-text passthrough goes through `--format raw`, not wrapped into one giant JSON.
+
+## 6. Exit code table
+
+| Code | Meaning | Agent behavior |
+|------|---------|----------------|
+| 0 | Success | continue |
+| 1 | Generic error | read the error envelope to decide |
+| 2 | Argument/usage error | don't retry, fix args |
+| 3 | Resource not found | don't retry |
+| 4 | Permission/auth/config failure | don't retry, surface credentials or permission |
+| 5 | Confirmation required but token missing | run dry-run for a token, then retry |
+| 6 | Precondition conflict or invalid token | re-read state, then retry |
+| 7 | Retryable transient error (network/rate-limit/server) | back off and retry |
+| 8 | Timeout | back off and retry |
+| 9 | Human action required (see §16.3, optional) | relay to the user, run `resume` once done |
+
+Error codes and exit codes must align:
+
+- `E_USAGE` / `E_VALIDATION` -> 2
+- `E_NOT_FOUND` -> 3
+- `E_AUTH` / `E_FORBIDDEN` / `E_CONFIG` -> 4
+- `E_CONFIRMATION_REQUIRED` -> 5
+- `E_CONFLICT` -> 6
+- `E_NETWORK` / `E_RATE_LIMITED` / `E_SERVER` -> 7
+- `E_TIMEOUT` -> 8
+- `E_INTEGRITY` -> 1 (release integrity failure: missing/invalid signature or checksum mismatch; **non-retryable**, see §14)
+- `E_IO` -> 1 (local filesystem failure: disk full, file locked, partial write; non-retryable, needs an environment fix; see §14 update replace stage)
+- `E_INTERRUPTED` -> 130 (operation cancelled by signal/user, SIGINT = 128+2; retryable — staged work leaves nothing half-applied, see §14)
+- `E_HUMAN_REQUIRED` -> 9 (optional, only when §16.3 is enabled)
+
+When the failure comes from an upstream HTTP call, map the status onto the
+taxonomy so the agent can tell failure modes apart from `error.code` +
+`retryable` — do NOT collapse every 4xx into `E_NETWORK`:
+
+- `401` -> `E_AUTH`
+- `403` -> `E_FORBIDDEN`
+- `404` -> `E_NOT_FOUND`
+- `408` -> `E_TIMEOUT` (retryable)
+- `409` -> `E_CONFLICT`
+- `429` -> `E_RATE_LIMITED` (retryable)
+- `5xx` -> `E_SERVER` (retryable)
+- connection refused / DNS / reset -> `E_NETWORK` (retryable)
+
+Map by the upstream's own error TYPE/status where available, not by sniffing
+the human-readable message text (substring matching misclassifies messages that
+merely contain words like "not found"). Keep this mapping in ONE function so the
+status->code->exit contract cannot drift between the output layer and the
+command layer. Codes that are declared but never reachable should be annotated
+as reserved so an agent does not plan for a branch that cannot occur.
+
+## 7. Write flow (dry-run -> confirm)
+
+A write command must first support `--dry-run`, returning a preview and a token:
+
+```json
+{
+  "ok": true,
+  "schema_version": "1.0",
+  "data": {
+    "preview": {
+      "changes": [
+        {
+          "action": "delete",
+          "resource": "mail",
+          "id": "123",
+          "before": {},
+          "after": null
+        }
+      ]
+    },
+    "confirm_token": "ct_9f2a...",
+    "expires_at": "2026-06-05T12:00:00Z"
+  },
+  "meta": {
+    "duration_ms": 0
+  }
+}
+```
+
+The second step carries the token to execute:
+
+```bash
+tool resource delete --id 123 --confirm ct_9f2a...
+```
+
+Confirm-token conventions:
+
+- The token must bind a hash of the operation content: command path, args, target resource ID, calling account, permission context.
+- The hash must be keyed (HMAC) with a machine-local secret (e.g. `~/.<tool>/confirm.secret`, created on first use, `0600`), so a token cannot be fabricated by recomputing a public hash — it must come from a real `--dry-run` on the same machine.
+- When a resource version is available, also bind it (version, etag, changekey, or updated_at) to prevent state drift.
+- The token must expire; `expires_at` is ISO 8601 UTC.
+- On expiry, changed args, or changed target state, execution returns `E_CONFLICT`, exit code 6.
+- With no token, return `E_CONFIRMATION_REQUIRED`, exit code 5.
+- dry-run must not cause external side effects, but may read state to build the preview.
+
+## 8. Query, pagination, and field selection
+
+Query commands support, by default:
+
+- `--fields <a,b,c>`: return only selected fields; when dotted paths are supported, declare it in reference.
+- `--compact`: strip JSON whitespace.
+- `--limit`: cap the number of returned items.
+- `--cursor` or `--offset`: pagination cursor or offset.
+
+Suggested pagination shape:
+
+```json
+{
+  "items": [],
+  "count": 0,
+  "next_cursor": null,
+  "has_more": false
+}
+```
+
+For offset-based upstreams, echo `offset` and return an explicit `next_offset`
+(the value to pass next, present only while `has_more` is true) so the agent
+pages deterministically instead of re-deriving `offset + count`:
+
+```json
+{
+  "items": [],
+  "count": 0,
+  "offset": 0,
+  "next_offset": 20,
+  "has_more": true
+}
+```
+
+When a list is silently capped (e.g. an auto-paginate ceiling), surface
+`truncated: true` rather than returning a short list that looks complete.
+
+Conventions:
+
+- All IDs are strings, even if numeric underneath.
+- All times are ISO 8601 UTC.
+- List order must be stable; declare the default sort in reference.
+- Query commands must not fall into an interactive prompt just because an optional filter is missing.
+
+### 8.1 Server-side filters over client-side faking
+
+Prefer pushing a filter to the upstream over post-filtering a page client-side. A
+filter applied after pagination silently undercounts: it looks complete but only
+reflects the fetched page. If the upstream gained a filter in a known version, map
+the flag to it and record the minimum version (reference + compatibility doc)
+rather than emulating it; if you must filter locally, page the full set first and
+say so.
+
+### 8.2 Heavy sub-resources are separate, structured, and projectable
+
+A sub-resource whose size is unbounded (a diff, a log, an artifact, a full file
+body) is its own command, never inlined into a list. The cheap, bounded summary
+(counts, paths, stats) belongs on the list; the heavy payload is fetched on demand
+for the specific item the agent chose. Return it **structured** (e.g. a diff as
+per-file entries, not one opaque blob) so `--fields` can project it down to an
+inventory (paths + line counts) without shipping the payload. This makes the
+agent's token cost a choice, not a surprise — no bespoke truncation protocol
+required.
+
+### 8.3 Multi-scope queries fan out under the batch contract
+
+When a read spans many containers (projects in a group, every project in the
+instance), resolve the scope to a concrete set and fan out as a client-side loop
+(§15, class B): one external command, exactly one scope selector, results
+aggregated with each item annotated by its source container. A container that
+fails to scan is reported in the result (e.g. `projectErrors[]` / `scope` /
+`projectsScanned`), never silently dropped, and a single failure must not abort
+the rest. Aggregating bounded metadata across containers is safe; never aggregate
+an unbounded sub-resource (§8.2) across the whole set. An instance-wide scope that
+only makes sense for one actor (all of a user's commits) must be bound to that
+actor and fail closed otherwise, so a bare unbounded scan is impossible.
+
+## 9. Idempotency and concurrency safety
+
+Write commands should support idempotent semantics where possible:
+
+- Create-type commands should support `--request-id` or `--idempotency-key`. Where the upstream
+  honors an idempotency header (e.g. GitLab's `Idempotency-Key`), forward it; bind the key into the
+  confirm scope so the token matches only that key.
+- Retrying the same idempotency key must not create duplicate resources.
+- Update/delete commands should record the target resource version during dry-run.
+- If a version change is detected at confirm time, return `E_CONFLICT`.
+- **Confirm tokens are single-use.** Once a token has been accepted to execute a write, record its
+  fingerprint (e.g. under `~/.<tool>/confirm-consumed.json`, pruned by expiry) and reject any replay
+  with `E_CONFLICT` ("token already used; re-run `--dry-run`"). This gives agents safe-retry: a
+  confirmed write that times out cannot be blindly re-sent — the retry is rejected and re-running
+  `--dry-run` reveals the now-current state. This is the universal safe-retry mechanism for upstreams
+  that expose no resource version to bind. Mark consumed BEFORE the write executes (a crash mid-write
+  conservatively blocks the replay rather than risking a duplicate). A storage failure must degrade
+  gracefully and never block the write.
+- Batch writes should return per-item results; don't hide other items' status because one failed.
+
+Suggested batch-write result:
+
+```json
+{
+  "results": [
+    {
+      "id": "1",
+      "ok": true,
+      "action": "deleted"
+    },
+    {
+      "id": "2",
+      "ok": false,
+      "error": {
+        "code": "E_NOT_FOUND"
+      }
+    }
+  ],
+  "summary": {
+    "ok_count": 1,
+    "error_count": 1
+  }
+}
+```
+
+## 10. Sensitive data and auditing
+
+- password, token, secret, authorization header, cookie must not appear in stdout, stderr, error.details, or the audit log.
+- dry-run previews must redact sensitive fields.
+- reference/context/doctor must not leak plaintext credentials.
+- context may report whether credentials exist, but only as a boolean or redacted summary.
+- The audit log should record command path, redacted args, calling account, time, exit code, duration.
+- `--quiet` must not disable auditing.
+
+## 11. Self-description commands (reference / context / doctor / changelog)
+
+### reference
+
+Declares the tool's capabilities, commands, params, output schema, error codes, and permission levels, so an agent understands the tool first.
+
+Each command's `output_schema` MUST be machine-usable, not a stub. Use a string label that
+resolves to an entry in a top-level `schemas` catalog: `{ "shape": "object"|"array", "fields":
+[...], "untrusted_fields": [...] }`, with the field list enumerated from the command's actual
+returned data (the flatten structs / `*ToMap` builders) and `untrusted_fields` listing the
+attacker-controllable keys. Each command SHOULD also carry `examples`: one runnable invocation
+(write commands show the `--dry-run` then `--confirm` pair, dangerous commands include
+`--dangerous`). A guard test SHOULD assert every leaf command resolves to a non-empty schema and has
+at least one example, so `reference` cannot silently regress to a stub.
+
+```json
+{
+  "ok": true,
+  "schema_version": "1.0",
+  "data": {
+    "tool": "tool-name",
+    "version": "1.0.0",
+    "release_readiness": {
+      "level": "beta",
+      "fcc_required": true,
+      "fcc_status": "verified",
+      "mock_upstream_required": true,
+      "mock_upstream_status": "verified",
+      "live_smoke_required_for_stable": true,
+      "live_smoke_status": "missing",
+      "reason": "Stable requires recorded live smoke/E2E evidence.",
+      "required_evidence": [
+        "functional_contract_coverage_100",
+        "mock_upstream_contract_tests",
+        "recorded_live_smoke_for_stable"
+      ]
+    },
+    "commands": [
+      {
+        "path": "resource delete",
+        "type": "write",
+        "description": "Delete a resource",
+        "params": [
+          {
+            "name": "id",
+            "type": "string",
+            "required": true,
+            "multiple": false
+          }
+        ],
+        "output_schema": "deleted_resource",
+        "examples": [
+          "<tool> resource delete <id> --dry-run --compact",
+          "<tool> resource delete <id> --confirm <confirm_token> --compact"
+        ]
+      }
+    ],
+    "schemas": {
+      "deleted_resource": {
+        "shape": "object",
+        "fields": ["id", "status"],
+        "untrusted_fields": []
+      }
+    },
+    "exit_codes": {}
+  },
+  "meta": {
+    "duration_ms": 0
+  }
+}
+```
+
+`release_readiness` is the machine-readable release gate. It must appear in
+`reference` for every AI-native CLI:
+
+- `level`: `stable`, `beta`, or `unpublishable`.
+- `stable`: FCC is 100%, mock upstream/contract tests cover external behavior,
+  and at least one recorded live smoke/E2E run exists for the release candidate.
+- `beta`: FCC is 100% and mock upstream/contract tests exist, but live
+  smoke/E2E evidence is missing or explicitly not available yet.
+- `unpublishable`: any public behavior lacks command-level coverage, or mock
+  upstream/contract tests cover only happy paths while failure/auth/pagination/
+  empty/rate-limit behavior remains untested.
+- `fcc_status`, `mock_upstream_status`, and `live_smoke_status` use
+  `verified`, `missing`, `not_applicable`, or `unknown`; `stable` may not use
+  `missing` or `unknown` for any required item.
+- `required_evidence[]` names the evidence an agent or release script should
+  inspect before trusting the level.
+
+### context
+
+Reports the current runtime, config, target, and credential status.
+
+```json
+{
+  "ok": true,
+  "schema_version": "1.0",
+  "data": {
+    "env": "prod",
+    "account": "user@example.com",
+    "config": {},
+    "credentials": {
+      "configured": true
+    }
+  },
+  "meta": {
+    "duration_ms": 0
+  }
+}
+```
+
+### doctor
+
+Environment and risk check-up; each item gives an actionable fix.
+
+```json
+{
+  "ok": true,
+  "schema_version": "1.0",
+  "data": {
+    "checks": [
+      {
+        "check": "auth",
+        "status": "pass",
+        "fix": null
+      },
+      {
+        "check": "network",
+        "status": "fail",
+        "fix": "set HTTP_PROXY or check VPN"
+      },
+      {
+        "check": "release_readiness",
+        "status": "warn",
+        "fix": "record live smoke/E2E evidence before declaring stable"
+      }
+    ]
+  },
+  "meta": {
+    "duration_ms": 0
+  }
+}
+```
+
+`doctor` must include `check: "release_readiness"` with the same release level
+reported by `reference`. Use `pass` for `stable`, `warn` for intentional `beta`,
+and `fail` for `unpublishable` or for a declared `stable` state with missing
+evidence. The check should include an actionable `fix` when the status is not
+`pass`.
+
+### changelog
+
+Reports **what changed between versions** so an agent that just self-updated can refresh its knowledge instead of reusing stale patterns. This is the time-axis complement to `reference` (which describes current capabilities).
+
+```bash
+tool changelog                    # all version changes
+tool changelog --since 1.0.3      # only versions newer than 1.0.3
+```
+
+```json
+{
+  "ok": true,
+  "schema_version": "1.0",
+  "data": {
+    "current_version": "1.1.0",
+    "since": "1.0.3",
+    "entries": [
+      {
+        "version": "1.1.0",
+        "date": "2026-06-07",
+        "changes": {
+          "added": [
+            "..."
+          ],
+          "changed": [
+            "..."
+          ],
+          "fixed": []
+        }
+      }
+    ]
+  },
+  "meta": {
+    "duration_ms": 0
+  }
+}
+```
+
+Conventions:
+
+- **Single source of truth**: `changelog` output is derived from `CHANGELOG.md` (embedded into the binary at build time by `## [version]` section); no separate data maintained. Same source as release notes.
+- `--since <version>` returns only entries strictly newer than that version, for an agent that "last saw version X" to pull the delta.
+- Change categories follow Keep a Changelog: `added` / `changed` / `fixed` / `deprecated` / `removed` / `security`.
+- After a successful self-update, the tool should hint the agent to run `changelog --since <old version>` (see §14).
+
+## 12. Command design conventions
+
+1. Use the shortest command that completes a clear task; reduce combinatorial complexity.
+2. Query commands support `--fields` and `--compact` by default to cut tokens.
+3. Write commands must support `--dry-run` and `--confirm`.
+4. Naming uses `<noun> <verb>` or `<verb> <noun>` style, consistent across the tool.
+5. Don't require agents to parse help text; `--help` is for humans, machine capability is exposed via `reference`.
+6. All times ISO 8601 UTC; all IDs strings.
+7. On failure, return a structured error rather than a half-finished success payload.
+8. Avoid ambiguous params; booleans are flags, enums are bounded choices.
+
+## 13. Functional contract coverage and release gate
+
+Functional Contract Coverage (FCC) is the release blocker: every public behavior
+an agent can rely on must have automated command-level test coverage. Numeric
+line or branch coverage is useful engineering telemetry, but it is secondary and
+must not be used as a substitute for missing functional contract tests.
+
+A public functional contract is anything declared in:
+
+- `README.md` / `README_zh.md`, `SKILL.md`, or Skill reference pages;
+- `tool reference`, `--help`, `context`, `doctor`, `changelog`, or `update`
+  output;
+- JSON envelope fields, command output schemas, global flags, error codes, exit
+  codes, retryability, and stdout/stderr behavior;
+- documented config/env variables, credential handling, write safety, update
+  verification, Skill sync, and `_untrusted` security guarantees.
+
+Required coverage for each public command or contract:
+
+- success path;
+- missing/invalid arguments;
+- missing config, missing auth, or permission failure when applicable;
+- upstream API failure, network failure, rate limit, or timeout when applicable;
+- JSON envelope shape, output schema, exit code, and stderr/stdout boundary;
+- non-interactive behavior: no prompts, no blocking, and write commands use
+  `--dry-run` -> `--confirm <token>`;
+- regression test for every bug fix that changes observable behavior.
+
+What `FCC = 100%` means:
+
+- every command/flag/output/error behavior listed in the public contract is
+  mapped to at least one automated test, or explicitly marked non-applicable;
+- command-level tests validate the CLI boundary, not just internal helpers;
+- broad generated code, version constants, build metadata, or unreachable
+  platform guards may be excluded from numeric coverage, but not from FCC if
+  they are documented public behavior;
+- a release cannot be tagged while known FCC gaps remain;
+- `fcc_status: "verified"` must be machine-backed by an enumeration guard
+  test: enumerate every leaf command from live `reference` output and assert
+  each one is invoked by at least one command-level test. The guard skips
+  while the status is honestly declared `missing`, and fails if the claim is
+  flipped to `verified` without the coverage (the template ships this guard).
+
+CI should run the unit and command-level suites for every PR. Numeric coverage
+thresholds may ratchet upward over time per repository, but the release standard
+is absolute: public functional contracts must be covered.
+
+### Release readiness levels
+
+Release readiness is deliberately stricter than "tests pass":
+
+- **Stable**: FCC is 100%; mock upstream/contract tests cover success,
+  validation, config/auth/permission failures, upstream/network/rate-limit/
+  timeout failures, empty results, pagination, output schema, exit codes, and
+  stdout/stderr boundaries; at least one live smoke/E2E run has been recorded
+  for the release candidate.
+- **Beta**: FCC is 100% and mock upstream/contract tests meet the same
+  behavioral breadth, but recorded live smoke/E2E evidence is missing or the
+  project explicitly declares that live E2E is not available yet.
+- **Unpublishable**: any public command/flag/output/error behavior lacks
+  command-level coverage, or mock upstream tests only cover happy paths.
+
+`reference.release_readiness` and `doctor.checks[]` are the machine-readable
+surface for this gate. A repository may choose not to publish `beta` artifacts,
+but it must not describe itself as `stable` without the live evidence above.
+
+## 14. Versioning and compatibility
+
+- `schema_version` is the output schema version, not the tool version.
+- A breaking schema change bumps the major version, e.g. `1.x` -> `2.0`.
+- Non-breaking added fields may keep the major version.
+- Deprecated fields should keep a compatibility window and be marked deprecated in reference.
+- Compatibility aliases may exist but should not be the recommended usage in new docs.
+- Agents should rely on `reference`, not `--help` or README.
+
+### Version negotiation (tool version ↔ Skill expectation)
+
+A Skill is a snapshot of the capabilities the day it was written; once the binary version drifts, things misalign: a Skill written for v1.1 against a v1.0 binary will silently call commands that don't exist.
+
+- The tool must report its own version: `tool --version` and `context.data.version`.
+- The Skill declares a minimum compatible version in frontmatter (see SKILL-SPEC `requires.min_version`).
+- `doctor` should include a check "does the current version meet the declared minimum"; if not, give a `fix` (upgrade command), status `fail`.
+
+### Self-update and Skill-sync loop
+
+For tools with `self-update`, after a successful update they **must close both
+refresh loops**:
+
+1. the binary/package is current;
+2. every bundled Agent Skill directory is current, with the same end state as
+   running `npx skills add <repo> -y -g`.
+
+The user-facing Skill install command stays `npx skills add ...`; the binary
+must not expose a separate `install-skill` command. During update, however, the
+tool owns the full lifecycle and must either sync every Skill directory under
+`skills/` — running `npx skills add <repo> -y -g` does exactly that, and syncing
+only `skills/<tool>/` would leave a tool's other Skills (SKILL-SPEC §7) behind —
+or return an explicit `skill_sync_status` and `skill_sync_command`
+that the agent can execute before using new behavior.
+
+Single-command update contract (no leaf commands, no confirm token):
+
+- A bare `update` performs the whole update in ONE call: resolve the latest (or
+  `--target-version`) release, verify its integrity, replace the binary/package,
+  then sync the Skill directories. Self-update is a single-target, non-destructive,
+  self-verifying operation, so it is **exempt from the §7 `--dry-run → --confirm
+  <token>` write gate** — the safety guarantee is the in-process signature
+  verification below, not an agent's review of a preview. There are no `update`
+  leaf subcommands.
+- **Install-method dispatch — drive the manager, don't just print the command.**
+  "Replace the binary/package" means reaching the upgraded end state in that one
+  call for *every* install method, not only standalone binaries:
+  - **Standalone binary** (the tool owns the file): download → in-process Sigstore
+    signature verify → checksum → atomic in-place swap; `signature_status:
+    "verified"`.
+  - **Package-manager-managed install** (npm / Go / Homebrew — the manager owns the
+    file): the tool MUST NOT mutate the managed file in place (that desyncs the
+    manager's metadata) and MUST NOT merely return the command for the user to run.
+    It DRIVES the manager — it executes the install command on the user's behalf
+    (e.g. `npm install -g <pkg>@<version>`), then syncs the Skill, reaching the same
+    end state with `status: "updated"`. Integrity on this path is the package
+    manager's own (registry integrity/provenance), so `signature_status` is
+    `not_checked`; the new version takes effect on the next invocation. Detection
+    must be robust (don't misclassify a standalone binary as managed); a failed
+    manager invocation reports the error with `binary_replaced: false` and the
+    exact command to run manually.
+- `update --check` is an OPTIONAL read-only probe: report current/target
+  versions, install method, whether an update is available, whether Skill sync is
+  supported, and signature/checksum availability. It changes nothing.
+- `update --dry-run` is an OPTIONAL read-only preview of the same changes
+  (binary/package update, Skill sync, verification plan). It issues NO token and
+  is never a required step before `update`.
+- `update` is idempotent: when already on the latest (or requested) version it
+  returns `ok` with a no-op result, so an agent may call it freely. This no-op
+  check MUST run before any package-manager command; an already-current install
+  must not re-run `npm`, `go`, `pip`, `brew`, or an equivalent manager.
+- Successful and no-op `update` results describe the final post-command state,
+  not the pre-install comparison. After a successful install, `data` carries
+  `previous_version`, `current_version`, `target_version`, `update_available`,
+  `signature_verified`, `signature_status`, `skill_sync_status`, and enough
+  verification metadata for the agent to audit what happened. `current_version`
+  MUST equal `target_version`, and `update_available` MUST be `false`. In a
+  no-op result, `current_version` and `target_version` are also equal and
+  `update_available` is `false`.
+- If the binary/package updates but Skill sync fails, return partial success
+  (`ok: false`, `binary_replaced: true`) with `target_version`,
+  `update_available: false`, and `skill_sync_command`; the agent must not use
+  newly documented behavior until the Skill sync has completed.
+
+Version notification contract:
+
+- `update --check` actively checks the latest release and refreshes the local
+  update notice cache.
+- `doctor` may actively check with a short timeout; network failure must not
+  make `doctor` fail by itself.
+- `context` and `--help` only read the local cache and must not contact remote
+  registries or GitHub.
+- The cached notice MAY also be attached to **every command's `meta.notices`**,
+  read **only from the local cache** (no network; cost is one local file read).
+  Business commands surface the cached notice — they never actively check / phone
+  home. Omit `meta.notices` when the cache has nothing to report.
+- After a successful install, partial success after the binary/package commit,
+  or an idempotent no-op at the target/latest version, the tool MUST clear or
+  suppress any cached `update_available` notice for that installed target before
+  later commands can attach `meta.notices`. An update command's own response must
+  not carry a stale notice that says the just-installed target is still available.
+- When an update is available, the notice carries `type: "update_available"`,
+  `severity`, current/latest versions, install method, `recommended_command`,
+  release URL when known, checked-at timestamp, and machine-readable next steps.
+  It appears in active-check command `data` (`context` / `doctor` / `update
+  --check`) and, read-only from cache, in any command's `meta.notices`. Text/help
+  output may append one concise hint.
+- **Severity grading** — computed at check time from the embedded CHANGELOG delta
+  between the running version and the latest, and stored in the cache so the
+  cached `meta.notices` carries the right level:
+  - `info` (default): routine patch/minor with no security entry.
+  - `warning`: the changelog delta since the running version contains a
+    `security` entry, OR the latest crosses a **major** version (first semver
+    component increased) — i.e. likely security-relevant or breaking.
+
+Release verification baseline:
+
+- **Mandatory signature verification, no skip path**: the binary self-update path
+  MUST verify the Sigstore signature on `checksums.txt` in-process, then verify
+  the archive SHA256 against it. A missing signature bundle, a signature that does
+  not verify, or a checksum mismatch all fail closed — there is no "can't verify,
+  proceed anyway" degradation. The whole chain surfaces `E_INTEGRITY` (exit 1,
+  non-retryable): a forged or corrupt release is not a transient blip to retry.
+- **Verifier embedded, no user-environment dependency**: verification happens
+  inside the tool binary (Go via `sigstore-go`, Python inside the frozen binary
+  via `sigstore`) with **no external cosign** and nothing pre-installed on the
+  machine. The TUF trust root is bootstrapped from the library's embedded
+  `root.json`, not fetched on first-use trust (TOFU).
+- **New bundle format**: the signing side produces a Sigstore protobuf bundle
+  (`checksums.txt.sigstore.json`) via `cosign sign-blob --new-bundle-format`, which
+  the in-process verifier consumes; the legacy cosign bundle format is not accepted.
+- **Identity binding**: verifiers bind the certificate SAN to this repo's tagged
+  release workflow (`…/release.yml@refs/tags/v*`, anchored `^…$`) and validate the
+  GitHub OIDC issuer. When the target tag is known, pin the exact identity (stronger
+  than a regexp).
+- **Cross-language parity**: Go binaries and Python frozen binaries follow the same
+  self-update contract — download archive → in-process signature verify → checksum
+  → replace binary. Package managers do not own integrity.
+- Update results carry `signature_status` (`verified` on success; any failure exits
+  via the error envelope) and `signature_verified` (true only when in-process
+  Sigstore verification actually ran and succeeded). Never imply checksum
+  verification is a signature.
+
+- After `update` succeeds, return `previous_version` and `current_version` in `data`.
+- Also hint in the result: `run "changelog --since <previous_version>" to see what changed`.
+- Agent convention: after self-update, before continuing, read `changelog --since <old version>` (see the SKILL-SPEC recipe).
+
+Failure and interruption contract:
+
+Single-command `update` runs as staged work — discover → download → verify
+signature → verify checksum → replace binary → sync Skill — with exactly one
+atomic commit point. The invariant that makes every failure message honest:
+
+- Everything BEFORE the binary swap touches only a temp dir; any failure or
+  interruption there leaves the installed binary untouched and fully usable
+  (`current_version` unchanged, `binary_replaced: false`).
+- The swap itself is atomic. On Windows a running executable can be renamed but
+  not overwritten, so the verified `<bin>.new` is moved into place by renaming the
+  in-use binary aside to `<bin>.old`, then renaming `<bin>.new` onto the real path
+  — the new binary is in place at once, `binary_replaced: true`, and the next
+  invocation runs the new version (no restart needed). The displaced `<bin>.old`
+  cannot be deleted while the old process is still running, so it is left in place
+  and cleaned up by the next `update`, which re-verifies any staged artifact from
+  scratch — a leftover is never trusted. On non-Windows the swap is a same-filesystem rename
+  of the verified binary into place. A crash mid-swap leaves either the old or the
+  new binary, never a hybrid.
+- Skill sync runs AFTER the swap and is independently replayable.
+
+So the tool can always determine — and MUST always report — its post-failure
+state. Every update failure envelope carries, in `error.details` (or `data` on
+partial success): `stage`
+(`discover|download|verify_signature|verify_checksum|replace|skill_sync`),
+`current_version`, `binary_replaced`, and `skill_sync_status`.
+
+Classify the failure by the agent's next action, not by the raw cause:
+
+| Stage | Failure | code / exit | retryable | Post-state | Message must say |
+|-------|---------|-------------|-----------|------------|------------------|
+| discover / download | network / timeout / rate-limit | `E_NETWORK` / `E_TIMEOUT` / `E_RATE_LIMITED` → 7,8 | true | old version, no change | "transient — re-run `update`, it is idempotent" |
+| verify_signature / verify_checksum | missing/invalid signature, identity mismatch, checksum mismatch | `E_INTEGRITY` → 1 | **false** | old version, install refused | "integrity failure — do NOT retry, stop and report" |
+| replace | permission / disk full / file locked | `E_FORBIDDEN` / `E_CONFIG` / `E_IO` → 4,1 | false (needs fix) | old version (atomic not committed) | the concrete fix, then re-run |
+| skill_sync (post-swap) | npx missing / network | partial success (`ok:false`, `binary_replaced:true`) | true | binary NEW, Skill OLD | "binary at vX; run `<skill_sync_command>`, then `changelog --since <prev>`" |
+| any | user/signal interrupt (SIGINT) | `E_INTERRUPTED` → 130 | true | per the stage invariant above | what actually happened + the safe next step |
+
+Interruption (Ctrl-C / SIGTERM):
+
+- Trap the signal, unwind the current stage to a clean state, and STILL emit the
+  terminal JSON envelope on stdout before exiting non-zero — an interrupted agent
+  must receive a parseable terminal state, never a bare killed process.
+- Always clean the temp dir on interrupt; a partial download must never be
+  trusted by a later run (re-download + re-verify always).
+- The message depends on the interrupted stage: before the swap → "cancelled, no
+  change, still on `<current>`"; during the atomic swap → report old-or-new
+  truthfully; after the swap during Skill sync → partial success with
+  `skill_sync_command`.
+
+Three rules the messages must never break:
+
+1. Never misstate the version: every terminal envelope states the version the
+   tool is actually running now.
+2. Never let an agent retry an integrity failure: `E_INTEGRITY` is
+   `retryable: false` and verbally distinct from any network failure — a forged
+   release is not a transient blip to loop on.
+3. Never call a partial a success: binary replaced but Skill not synced is
+   partial success with `skill_sync_command`, not `ok: true`.
+
+## 15. Batch operations
+
+Many write workflows need to act on a batch of objects in one call (close many issues, send to many openids, run one SQL across many instances). A batch command is still **one** agent-facing command with **one** envelope, **one** confirm token, and **one** aggregated result — never a loop the agent has to drive. The contract below is identical whether the batch is served by a native upstream bulk endpoint (class A) or by a client-side loop (class B); the agent must not be able to tell which.
+
+### 15.1 Plural inputs
+
+- Batch targets use a plural flag: `--ids`, `--symbols`, `--instances`, `--openids`, etc.
+- Each plural flag accepts both **comma-separated** (`--ids 1,2,3`) and **repeatable** (`--ids 1 --ids 2 --ids 3`) forms; the two are equivalent and may be mixed.
+- A single value degrades gracefully: `--ids 1` is a valid batch of one, same envelope as a batch of many. Where a singular flag (`--symbol`) already exists, keep it as a compatibility alias of the plural and declare it deprecated in reference; do not run two divergent code paths.
+- De-duplicate targets before executing and preserve input order in the result `items[]` so the agent can zip results back to inputs deterministically.
+- An empty target list is a usage error (`E_VALIDATION`, exit 2), not a silent no-op.
+
+### 15.2 Dry-run summary for a batch
+
+`--dry-run` on a batch returns **what will happen to N objects** before any write, plus a single `confirm_token` that covers the whole batch:
+
+```json
+{
+  "ok": true,
+  "schema_version": "1.0",
+  "data": {
+    "preview": {
+      "action": "close",
+      "total": 3,
+      "targets": ["1042", "1043", "1044"],
+      "changes": [
+        { "action": "close", "resource": "issue", "id": "1042" },
+        { "action": "close", "resource": "issue", "id": "1043" },
+        { "action": "close", "resource": "issue", "id": "1044" }
+      ]
+    },
+    "confirm_token": "ct_9f2a...",
+    "expires_at": "2026-06-15T12:00:00Z"
+  },
+  "meta": { "duration_ms": 0 }
+}
+```
+
+- The preview must state the operation and the full target set, so a human or agent can audit the blast radius before confirming.
+- The token binds the **whole resolved target set** (plus command path, args, account, permission context per §7), so adding or removing a target invalidates it with `E_CONFLICT`.
+
+### 15.3 One confirm token covers the whole batch, consumed once
+
+- A single `--confirm <token>` from the batch dry-run authorizes the entire batch; the agent does not confirm per item.
+- The token is **single-use** exactly as in §9: it is fingerprinted and marked consumed before the write runs, and any replay is rejected with `E_CONFLICT` ("token already used; re-run `--dry-run`"). This reuses each repo's existing single-consumption confirm infrastructure — batch adds no new token mechanism.
+- On a partial batch failure the token stays consumed; the agent re-runs `--dry-run` (which now resolves to the still-pending targets) rather than replaying the old token.
+
+### 15.4 Dangerous batches: `--dangerous` two-step gate
+
+Irreversible or high-blast-radius batches — bulk `delete`, MR `merge`, mass send / broadcast — require an extra gate **on top of** dry-run → confirm:
+
+- The command must be invoked with `--dangerous`; without it the command fails with `E_CONFIRMATION_REQUIRED` (exit 5) even when a valid confirm token is present.
+- This is a two-step human-intent gate: `--dangerous` declares intent, the confirm token authorizes the specific resolved batch. Both are required; neither alone executes.
+- Reference marks these commands `dangerous: true`, and their `examples[]` show the `--dangerous` form.
+- Tools may layer stricter local policy on a dangerous batch (e.g. per-item confirm, default `--continue-on-error false`, or night-time dry-run-only); such overrides must be declared in reference, not hidden.
+
+### 15.5 Per-item aggregated result, no whole-batch rollback
+
+Batch results aggregate per item. A partial failure does **not** roll back succeeded items:
+
+```json
+{
+  "ok": true,
+  "schema_version": "1.0",
+  "data": {
+    "items": [
+      { "target": "1042", "ok": true },
+      { "target": "1043", "ok": true },
+      {
+        "target": "1044",
+        "ok": false,
+        "error": { "code": "E_NOT_FOUND", "retryable": false }
+      }
+    ],
+    "summary": { "total": 3, "succeeded": 2, "failed": 1 }
+  },
+  "meta": { "duration_ms": 0 }
+}
+```
+
+- Each `items[]` entry carries `target` (the input identifier — `id`, `symbol`, `instance`, …; use the natural key, not an array index), `ok`, and on failure `error` with the same `{ code, retryable }` taxonomy as the top-level envelope (§6).
+- `summary` always reports `{ total, succeeded, failed }`. The counts must equal the item tally.
+- Top-level `ok` is `true` when the batch executed and produced a result, even with per-item failures; per-item status lives in `items[]`. Reserve top-level `ok: false` for a batch that could not run at all (bad args, auth, no targets). Do not hide other items' status because one failed (consistent with §9).
+- `--continue-on-error` controls whether the batch keeps going after the first item failure; **default `true`** (best-effort, finish the batch). Set `--continue-on-error false` to stop at the first failure — already-applied items stay applied (no rollback), and `summary` reflects only attempted items, with the unattempted remainder reported (e.g. `skipped`) so the agent can resume. Dangerous batches may flip the default to `false`; declare it in reference.
+
+### 15.6 Upstream caps: client-side auto-chunking
+
+When the native bulk endpoint has a per-call limit, the command splits the batch into chunks and submits them sequentially, presenting a single command to the agent:
+
+- Known caps: Jira `/issue/bulk`, agile `backlog/issue` and `sprint/{id}/issue` ≤ 50; WeChat openid batches ≤ 100, mass-send openid lists per upstream limit. The command must chunk to the cap; it must not pass a too-large batch straight through and let the upstream 400.
+- Chunking is invisible in the contract: still one envelope, one `confirm_token`, one aggregated `items[]`/`summary` across all chunks.
+- A chunk-level failure is mapped back onto the affected `items[]`; one failed chunk does not fail the whole command (subject to `--continue-on-error`).
+- Keep the chunk size in one shared helper per tool so the cap cannot drift between commands sharing an endpoint.
+
+### 15.7 A/B classes, one external contract
+
+- **Class A** uses a native upstream bulk endpoint (true server-side batch, possibly atomic per the upstream).
+- **Class B** loops client-side over single-target calls because no native bulk exists.
+- The external contract is identical for both: plural inputs, dry-run summary, single confirm token, dangerous gate, aggregated `items[]`/`summary`, and `--continue-on-error`. The agent cannot and need not tell A from B.
+- Atomicity is **not** part of the external contract. A class-B (or capped, chunked class-A) batch must not claim upstream atomicity; where the upstream genuinely is non-atomic or order-unstable, say so in the output schema / reference rather than implying a transaction.
+
+### 15.8 Self-description for batch commands
+
+Every batch command carries a real `output_schema` and runnable `examples[]` (per §11):
+
+- The schema declares the `items[]` shape (`target`, `ok`, `error{code,retryable}`) and the `summary{total,succeeded,failed}` shape, with attacker-controllable keys listed in `untrusted_fields` (`_untrusted`).
+- `examples[]` show the plural-input dry-run then confirm pair; dangerous batches include `--dangerous`.
+- These must pass the reference guard (non-empty schema + at least one example per leaf command) and count toward FCC (§13) like any other public behavior.
+
+## 16. Optional patterns (enable as needed)
+
+These three patterns are **not for everyone**: implement them if your tool needs them, ignore them otherwise — zero overhead. They let the spec scale with tool complexity — a simple tool stays light, a complex tool need not reinvent the wheel. Each is marked "when applicable."
+
+### 16.1 Credential lifecycle (when tokens expire)
+
+**When applicable**: credentials are not static but expire / need refresh — OAuth access_token (WeChat Official Account ~2h), cookie / session (Xiaohongshu), temporary STS credentials, etc. Tools with static username/password skip this section.
+
+- Beyond "is it configured," `context.data.credentials` should report **validity and expiry** (redacted):
+
+  ```json
+  {
+    "credentials": {
+      "configured": true,
+      "valid": true,
+      "expires_at": "2026-06-07T12:00:00Z",
+      "refreshable": true
+    }
+  }
+  ```
+
+- When a token is expired and cannot auto-refresh, the operation returns `E_AUTH` (exit 4), with `details` indicating re-auth is needed.
+- Tools that can auto-refresh should do so **transparently**, not bothering the agent; degrade to `E_AUTH` only if refresh fails.
+- `doctor` adds a `check: "credentials"` item; for near-expiry give `warn` + a renew `fix`.
+- Refresh tokens and secrets are always redacted — never in stdout / stderr / details.
+
+### 16.2 Async job lifecycle (long jobs: submit -> poll -> fetch result)
+
+**When applicable**: the operation can't return a result synchronously — async SQL execution / approval (Archery), bulk send, scrape/crawl jobs, large exports. Commands that return results synchronously skip this section.
+
+- The submit command returns a `job_id` and status immediately, without blocking:
+
+  ```json
+  {
+    "ok": true,
+    "schema_version": "1.0",
+    "data": {
+      "job_id": "job_abc123",
+      "status": "pending",
+      "poll": "tool job status --id job_abc123",
+      "result": "tool job result --id job_abc123"
+    },
+    "meta": { "duration_ms": 12 }
+  }
+  ```
+
+- Status queries return a stable enum: `pending` / `running` / `succeeded` / `failed` / `cancelled`, with progress (e.g. `progress`, `eta_seconds`).
+- Result and status are fetched separately: after `succeeded`, use the `result` command to pull data (large results via NDJSON / `--format raw`).
+- A `failed` result uses the standard error envelope; `retryable` indicates whether the whole job can be retried.
+- Submission of a write-type long job still goes through `dry-run → confirm`; the `job_id` is created only after confirm.
+
+### 16.3 Human-in-the-loop checkpoints (when a human must scan / solve captcha / approve)
+
+**When applicable**: a step mid-flow must be completed by a human — QR login / captcha (Xiaohongshu), approver sign-off (Archery), secondary confirmation. Fully automated tools skip this section.
+
+- When stuck at a human step, **don't block, don't guess** — return a dedicated signal so the agent hands off to the user:
+
+  ```json
+  {
+    "ok": false,
+    "schema_version": "1.0",
+    "error": {
+      "code": "E_HUMAN_REQUIRED",
+      "message": "Scan the QR code to continue",
+      "details": { "action": "scan_qr", "resume": "tool login resume --id sess_1", "qr_path": "/tmp/qr.png" },
+      "retryable": false
+    },
+    "meta": { "duration_ms": 30 }
+  }
+  ```
+
+- `E_HUMAN_REQUIRED` uses exit code `9` (added beyond the existing 0–8; not reusing `4`, to distinguish "bad credentials" from "waiting on a human action").
+- `details.action` is a stable enum describing what the human must do; `details.resume` gives the command to continue after the human is done.
+- Agent convention: on `E_HUMAN_REQUIRED` → relay `message` and the required action to the user → wait for them → run `resume`; do not auto-retry.
+
+## 17. Design checklist
+
+> Items marked `(optional)` only apply when the corresponding optional pattern is enabled.
+
+- [ ] Default `--format json`
+- [ ] stdout contains only valid JSON / NDJSON, no pollution
+- [ ] Logs and progress all go to stderr
+- [ ] Success/failure share one envelope, with `ok` and `schema_version`
+- [ ] `error` has semantic `code`, `details`, `retryable`
+- [ ] Exit codes tiered and consistent with `retryable`
+- [ ] Write commands have the dry-run / confirm-token loop
+- [ ] Confirm token binds operation args, account, permission context, resource version
+- [ ] Provides `reference` / `context` / `doctor`
+- [ ] Provides `changelog [--since]`, same source as CHANGELOG/release-notes
+- [ ] Tool reports its own version (`--version` and `context.version`)
+- [ ] `reference` reports `release_readiness`, and `doctor` checks it
+- [ ] (with self-update) `update` is a single command (no leaf subcommands, no confirm token); `--check` / `--dry-run` are optional read-only
+- [ ] (with self-update) release integrity is verified, and signature status is explicit
+- [ ] (with self-update) syncing every Skill directory under `skills/` is part of the update result
+- [ ] (with self-update) post-update returns previous/current version and hints to read changelog
+- [ ] (with self-update) every update failure/interruption envelope carries `stage` + `current_version` + `binary_replaced` + `skill_sync_status`; `E_INTEGRITY` is non-retryable; binary-replaced-but-Skill-unsynced is partial success, not `ok`
+- [ ] (with self-update) SIGINT/SIGTERM is trapped, leaves nothing half-applied, and still emits the terminal JSON envelope
+- [ ] Query commands support `fields` / `compact`
+- [ ] List commands support pagination or explicitly state none is needed
+- [ ] Batch commands take plural inputs (`--ids`/`--symbols`/…), comma-separated or repeatable, single value degrades
+- [ ] Batch dry-run summarizes the full target set; one confirm token covers and is consumed once for the whole batch
+- [ ] Dangerous batches (delete / merge / mass-send) require the `--dangerous` two-step gate
+- [ ] Batch results aggregate `items[].{target,ok,error{code,retryable}}` + `summary{total,succeeded,failed}`, no whole-batch rollback, `--continue-on-error` default true
+- [ ] Capped upstream bulk auto-chunks client-side under one command; A/B classes share one external contract; batch commands ship real `output_schema` + `examples`
+- [ ] Functional Contract Coverage is 100% for public README / Skill / reference / help / context / doctor / changelog / update behavior
+- [ ] Stable releases have recorded live smoke/E2E evidence; otherwise the tool declares `beta`
+- [ ] All times ISO 8601 UTC
+- [ ] All IDs strings
+- [ ] Secrets redacted end to end
+- [ ] Schema changes have a versioning/compat policy
+- [ ] stdout/stderr are UTF-8 without BOM
+- [ ] (optional · expiring tokens) `context`/`doctor` report credential validity and expiry; refresh failure degrades to `E_AUTH`
+- [ ] (optional · long jobs) submit returns `job_id` + status enum, status/result separated
+- [ ] (optional · human needed) stuck human steps return `E_HUMAN_REQUIRED` (exit 9) + `resume`, no auto-retry