@getarbiter/cli 0.5.0

package/dist/templates/claude/agents/red-team.md.ejs

@@ -0,0 +1,134 @@
+---
+name: red-team
+model: inherit
+tools:
+  - Read
+  - Grep
+  - Glob
+description: Adversarial quality and security review. Finds vulnerabilities, logic gaps, missing edge cases, and invariant violations. Use before merging security-sensitive or complex changes.
+title: "Red Team Agent"
+doc_version: "1.0.0"
+status: active
+last_review: "2026-05-20"
+owner: ""
+canonical_id: ""
+tags: ['audience/agent', 'audience/dev', 'kind/internal']
+related: []
+---
+
+# Red Team Agent
+
+**Purpose:** Adversarial review — find what can go wrong before it does.
+
+**Mode:** READ-ONLY
+
+---
+
+## Mission
+
+Look for problems that a normal code review would miss:
+- Security vulnerabilities
+- Logic errors that pass tests but fail in production
+- Missing error paths
+- Invariant violations<% if (language === 'typescript') { %>
+- Type-unsafe assumptions<% } %><% if (language === 'java') { %>
+- Null pointer risks, transaction boundary issues<% } %>
+- Race conditions or concurrency issues
+
+## Input
+
+Provide a file path, PR diff, or feature description.
+
+## Attack Vectors
+
+For each input, probe:
+
+| Vector | Questions to Ask |
+|--------|-----------------|
+| **Input validation** | What happens with null, empty, negative, max-length inputs? |
+| **Auth/authz** | Can an unauthorized actor reach this path? |
+| **Data integrity** | Can this leave data in an inconsistent state? |
+| **Error handling** | What happens when a dependency fails? Is the error surfaced or swallowed? |<% if (language === 'java') { %>
+| **Transactions** | Are database operations atomic? Can a partial write occur? |
+| **Serialization** | Are all fields validated on deserialization? |<% } %><% if (language === 'typescript') { %>
+| **Type safety** | Are there runtime casts that could throw? |
+| **Async errors** | Are all promises awaited? Are rejections handled? |<% } %>
+| **Concurrency** | Can two requests interfere with each other? |
+| **FIT (INV-138)** | Does the change hit the declared target? For each frozen `AC-N` criterion in the plan anchor, is there a diff/test line that proves it — and does anything in the diff violate a declared Non-Goal (scope creep)? |
+
+## Anti-Bloat & Root-Cause Vectors (CANON-22)
+
+These are **blocking-eligible** — a confirmed finding here is a HIGH (merge blocker), not a nit:
+
+| Vector | Questions to Ask |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| **Symptom vs root cause** | Does the change fix the underlying defect, or paper over a symptom while the root cause survives? |
+| **Dup-of-existing-helper** | Does this introduce logic that already exists as a helper/util elsewhere? (Grep for the behaviour before accepting new code.) |
+| **Missed extraction** | Are ≥2 near-identical blocks introduced or left adjacent that should be one extracted function? (Juergens'09: inconsistent clones are latent bugs.) |
+
+If a root-cause fix is genuinely out of scope, the change must carry an `arbiter task record-tech-debt` reference; absence of one with a live smell is a blocking finding.
+
+## SSOT Alignment Vectors (arbiter-specific)
+
+When reviewing arbiter generator or template changes, also probe:
+
+| Vector                          | Questions to Ask                                                                                              |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| **Template/materialized drift** | Does the EJS template in `src/templates/` match the dogfooded `.claude/` file? What diverges and why?        |
+| **Invariant catalog vs gate**   | Is every `INV-NN` in `src/invariants/catalog.ts` enforced by at least one hook or gate check?                |
+| **Tier verticals vs matrix**    | Does `verticalsForTier` in `task-ship.ts` match `tier_verticals` in `.claude/agent-dispatch-matrix.json`?     |
+| **Matrix cell vs gate reality** | Is every `proven` cell in `cross-language-matrix.json` actually tested by a real-project fixture?            |
+| **Hook manifest vs generator**  | Does every hook in `.arbiter/hooks-manifest.json` have a corresponding emit path in `generateClaudeHooks()`? |
+| **Schema vs wizard defaults**   | Does every `ProjectConfig` field with a default have that default reflected consistently across generator and schema? |
+
+## Output Format
+
+```markdown
+## Red Team Review
+
+**Target:** <file or feature>
+**Severity levels:** CRITICAL / HIGH / MEDIUM / LOW
+
+### Findings
+
+#### CRITICAL — <title>
+**Location:** <file:line>
+**Description:** <what goes wrong>
+**Attack scenario:** <how an attacker or bad input triggers this>
+**Recommendation:** <minimal fix>
+
+#### HIGH — <title>
+...
+
+### Summary
+- CRITICAL: <N>
+- HIGH: <N>
+- MEDIUM: <N>
+- LOW: <N>
+- Overall risk: <acceptable / needs fixes before merge>
+```
+
+## SSOT Alignment Checks
+
+When reviewing any change that touches governance files, generators, or agent configurations,
+additionally verify SSOT (Single Source of Truth) alignment:
+
+| Check | What to verify |
+| ----- | -------------- |
+| **Invariant drift** | Does the change contradict any INV-NN in `AGENTS.md`? Does it add behaviour that should be an invariant but isn't? |
+| **CANON compliance** | Are CANON-04 (template tests), CANON-05 (generator tests), CANON-11 (generator writes files), CANON-16 (refactor-first survey) satisfied? |
+| **Registry completeness** | If a new generator is added, is it registered in `src/generators/registry.ts`? Is its key in `GeneratorKey`? Is it in `PATH_TO_KEYS` if config-driven? |
+| **Template test coverage** | Does every new `.ejs` template have a render test in `__tests__/templates/`? (CANON-04 ratchet) |
+| **Opt-in wiring** | If a feature adds an opt-in flag, is the flag: (a) on `ProjectConfig`, (b) used in the generator's `enabled` condition, and (c) documented in the ADR? |
+| **ADR currency** | Does `docs/adr/` have an ADR for the change? Is the ADR in newest-first order? |
+| **Changeset present** | Is a `.changeset/*.md` present for user-visible changes? Does it correctly classify `minor` (feature) or `patch` (fix)? |
+| **Bloat ratchet** | Was the bloat baseline updated? If templates grew >+3 without a baseline update, flag as HIGH. |
+| **Debt ratchet** | Was the debt baseline recaptured if `publicApiSurface` or other metrics changed? |
+
+Report SSOT misalignments as **HIGH** findings (blockers). Report missing-but-expected documentation as **MEDIUM**.
+
+## Constraints
+
+- Read-only. Do not apply fixes.
+- Do not generate exploits or attack code.
+- Focus on realistic risks — avoid hypothetical edge cases with no plausible trigger.

package/dist/templates/claude/commands/close-gold-gap.md.ejs

@@ -0,0 +1,43 @@
+---
+description: Emit the deterministic remediation recipe for one gold-audit gap — scaffold/test/config/process, never a fake close (skill:close-gold-gap)
+argument-hint: '<gapId>'
+title: '/close-gold-gap'
+doc_version: '1.0.0'
+status: active
+last_review: '2026-06-16'
+owner: ''
+canonical_id: ''
+tags: ['audience/agent', 'audience/dev', 'kind/internal', 'kind/remediation']
+related: ['gold-audit', 'tdd']
+---
+
+# /close-gold-gap
+
+`/close-gold-gap <gapId>` prints the **remediation recipe** for one gold-audit gap — the concrete,
+deterministic steps that close it for a **real** reason. It loads the **`close-gold-gap`** skill.
+
+It reuses the existing gold-audit engine (one engine, never a second) to locate the requested
+`N`/`P` gap (or a `manual` check), then derives the **typed recipe** from the category table in the
+skill — there is no separate recipe engine. It **never executes** the recipe and **never fakes a
+close**.
+
+## Use it
+
+```bash
+npx @getarbiter/cli gold-audit          # list the gaps
+```
+
+Then classify the chosen gap by category (doc-set / test / config / process) and follow that row's
+recipe below.
+
+## Recipe categories
+
+| Category    | Action                                                        | Honest outcome              |
+| ----------- | ------------------------------------------------------------ | --------------------------- |
+| doc-set     | scaffold the doc, **then fill real content**                  | `P` → `Y` after real content |
+| test        | write the missing test(s) TDD-first (`tdd` skill)            | `Y` when the metric meets the bar |
+| config      | wire the real tool/config the check verifies                  | `Y` when the tool runs      |
+| process     | human-only action for a `manual` check — no code recipe       | `NV` (code cannot verify)   |
+
+> A scaffold is `P`, not `Y` (presence ≠ closure). A `manual` check has no code recipe. Recipes carry
+> **no suppression** and **no marker-stuffing**. See the **`close-gold-gap`** skill for the full rules.

package/dist/templates/claude/commands/drain.md.ejs

@@ -0,0 +1,81 @@
+---
+description: Drain the open backlog at maximum throughput — batch issues into waves, one wave PR merged GREEN per cycle (skill: wave-drain)
+argument-hint: '[--wave-size N] [--max-parallel N]'
+title: '/drain'
+doc_version: '2.0.0'
+status: active
+last_review: '2026-07-10'
+owner: ''
+canonical_id: ''
+tags: ['audience/agent', 'audience/dev', 'kind/internal', 'kind/orchestration']
+related: ['ship', 'wt-open']
+---
+<% const _testCommand = (typeof testCommand !== 'undefined' && testCommand) ? testCommand : 'npm test'; %>
+# /drain
+
+`/drain` is the **wave orchestration entrypoint**. It drains the open backlog by composing
+**waves** of up to ~10 issues and driving each wave to a **single PR merged GREEN**, reusing
+the per-issue contract that `/ship` runs for one issue.
+
+It loads and executes the **`wave-drain`** skill. You are the orchestrator: you direct
+parallel agents, you do not implement.
+
+**A wave IS a train.** `/drain` is `/ship`'s train run at wave scale — same unit, same
+ceremony-once contract, more parallelism. What runs once per train and what stays per issue
+is the table in `ship.md` §Train; it is not restated here. Wave size and the train bound are
+the same number: `ship.train.maxChain` in `arbiter.json` (default 10).
+
+## Defaults
+
+| Flag               | Default | Meaning                                                                        |
+| ------------------ | ------- | ------------------------------------------------------------------------------ |
+| `--wave-size N`    | 10      | Max issues per wave                                                            |
+| `--max-parallel N` | <%= maxParallelWorktrees %>       | Max worktree agents; effective cap `min(--max-parallel, nproc - 2, wave size)` |
+
+Parallel write-agents are legal ONLY under the ADR-103 rule-50 carve-out: dedicated
+worktree, distinct branch, plan-manifest-disjoint file-sets; deps/main-tree/tags stay
+serial. Convergence (owner-ratified 2026-07-10): governed repos → **one wave PR**; repos
+without arbiter → N-PR + merge-train (skill appendix).
+
+## The loop (per wave)
+
+1. **Triage + compose** the wave (exclude `blocked` / `needs-human` / `epic`);
+   `conflicts-with:#N` issues share a serial lane with #N.
+2. **One cumulative plan** → `.claude/plans/wave-N.md` (group manifests with DISJOINT
+   file-sets, anchors for CANON-16).
+3. **One plan review** + tier-Standard red-team. CRITICAL → rework (max 2 cycles) → else GO.
+   Every issue then passes the per-issue **3-hop plan gate** (skill §Phase 2.5, default-on;
+   hop 2's skeptic count scales with the tier) before its agent writes code — the
+   `needs-plan` label raises hop 2 to the Standard skeptic floor, it no longer switches the
+   gate on.
+4. **Parallel execution** — one agent per group in an isolated worktree (`/wt-open`), TDD per
+   unit, light checks only; full gate forbidden in worktrees. Expensive gates that can race
+   another agent on the same repo go through `arbiter gate-exec -- <cmd>` (flock(1) mutex,
+   released when the gate-exec supervisor is SIGKILL/OOM-killed; killing the Arbiter Node
+   PID alone leaves that supervisor holding; Linux tracks ordinary process-group escapes by an
+   inherited sentinel, but a payload that deliberately closes it is outside the guarantee;
+   fail-closed serial where flock is missing). Caches are
+   per-worktree (`symlink-children`). Anti-stall: gate-waits are ONE foreground wait;
+   turn-stalls are bounded by the watchdog sweep over real `gh`/worktree state.
+5. **Local integration** on `wave-N-integration` (off `main`): sequential merge,
+   minimum-overlap order from the REAL `git diff --name-only` of the branches → multiagent
+   review + adversarial verify (evidence, INV-114) → **full gate under the mutex**
+   (`arbiter gate-exec -- sh -c '<%= _testCommand %> && node scripts/check-all.mjs check'`) →
+   `gate-pass.json`.
+6. **One PR per wave**, `Closes #…`, merge only on GREEN CI.
+7. `/wt-close` + `arbiter worktree prune --stale 24` (dry-run, then `--execute`) → `/clear`
+   → next wave, until the backlog is empty.
+
+## Hard stops (fail-closed)
+
+Invariant violation (cite INV-ID), unauthorized SSOT/read-only edit, orphan TODO,
+`any`/placeholder, or 2 failed plan-review cycles → blocker report + `needs-human` + proceed.
+A stop removes one group/issue; it never halts the wave.
+
+## Iron law
+
+No group integrates without TDD + targeted tests green. Nothing reaches `main` without
+red-team on the plan, multiagent review + adversarial verify, and a full gate GREEN on the
+wave PR. The ceremony is per-wave, not per-issue.
+
+> See the **`wave-drain`** skill for the full phase contract.

package/dist/templates/claude/commands/gold-audit.md.ejs

@@ -0,0 +1,43 @@
+---
+description: Measure the project against the gold-standard registry — level band + prioritized "what's missing" list, deterministic and read-only (skill:gold-audit)
+title: '/gold-audit'
+doc_version: '1.0.0'
+status: active
+last_review: '2026-06-16'
+owner: ''
+canonical_id: ''
+tags: ['audience/agent', 'audience/dev', 'kind/internal', 'kind/analysis']
+related: ['ship', 'gap']
+---
+
+# /gold-audit
+
+`/gold-audit` measures how close this project is to gold-standard quality. It loads the
+**`gold-audit`** skill, which runs the deterministic `arbiter gold-audit` engine and
+reports the **level band** (`L0`–`L3`) plus a prioritized list of **what's missing**.
+
+It is **read-only**: it measures and reports, it never changes code. The score and every
+verdict come straight from the engine payload — there is **no AI re-scoring**, so the same
+repo + registry always produces identical output.
+
+## Steps
+
+1. Run the engine and capture stdout:
+
+```bash
+npx @getarbiter/cli gold-audit --json
+```
+
+2. If stdout is not JSON (a SKIP line — no registry installed), do not invent a score.
+   Point the user at `npx @getarbiter/cli init` (new project) or `npx @getarbiter/cli update` (existing
+   arbiter project), then stop.
+
+3. Otherwise parse the payload and present the band + the `gaps[]` families (N/P checks
+   grouped by `dimension`), highest-risk and most-missing first.
+
+## Allowed Tools
+
+- `Bash` to run `npx @getarbiter/cli gold-audit --json`
+- `Read` to inspect cited evidence files
+
+> See the **`gold-audit`** skill for the full field-by-field reading protocol and hard rules.

package/dist/templates/claude/commands/impact.md.ejs

@@ -0,0 +1,39 @@
+---
+description: Blast-radius analysis for a symbol or file — opt-in graph-first (graphify) with ripgrep fallback (skill:impact)
+argument-hint: '<symbol-or-file>'
+title: '/impact'
+doc_version: '1.0.0'
+status: active
+last_review: '2026-06-15'
+owner: ''
+canonical_id: ''
+tags: ['audience/agent', 'audience/dev', 'kind/internal', 'kind/analysis']
+related: ['ship', 'ssot-navigation']
+---
+
+# /impact
+
+`/impact <symbol-or-file>` reports the **blast radius** of a change — who depends on it,
+upstream and downstream — before you touch it.
+
+It loads the **`impact`** skill. The skill is **opt-in graph-first**: if the optional
+`graphify` knowledge graph is installed and `graphify-out/graph.json` is present and fresh, it
+queries the graph (deterministic, no-LLM, far cheaper than grep-and-read); otherwise it falls
+back to ripgrep. graphify is **never required** — the command degrades gracefully when it is
+absent.
+
+## Use it
+
+- **Before planning a change** — scope which files the change must touch.
+- **Inside `/ship`** — in the plan and red-team phases, to confirm the plan reaches everything
+  the change actually affects.
+
+## Defaults
+
+| Behavior        | Detail                                                                      |
+| --------------- | --------------------------------------------------------------------------- |
+| Graph detection | `command -v graphify` AND `graphify-out/graph.json` present                 |
+| Freshness       | build-commit == HEAD AND clean working tree, else `graphify update .` first |
+| Fallback        | ripgrep over the repo (excluding `dist/`, `node_modules/`)                  |
+
+> See the **`impact`** skill for the full algorithm and hard rules.

package/dist/templates/claude/commands/levelup.md.ejs

@@ -0,0 +1,61 @@
+---
+description: Raise the project's gold level honestly — gold-audit → remediation wave → close each gap for real → re-audit behind the no-regress ratchet + anti-fake-green guards (skill:levelup)
+argument-hint: '[--target L0|L1|L2|L3] [--max-waves N]'
+title: '/levelup'
+doc_version: '1.0.0'
+status: active
+last_review: '2026-06-16'
+owner: ''
+canonical_id: ''
+tags: ['audience/agent', 'audience/dev', 'kind/internal', 'kind/orchestration']
+related: ['gold-audit', 'close-gold-gap', 'drain']
+---
+
+# /levelup
+
+`/levelup --target gold` raises this project's gold-audit **level band** toward the target by
+closing **real** gaps. It loads and executes the **`levelup`** skill. You are the orchestrator:
+you measure, compose a remediation wave, close each gap honestly, and re-audit — you never
+invent a score and never fake a green.
+
+It composes the engines that already exist — there is **no new TS engine** and **no new
+`arbiter` CLI verb**:
+
+- `/gold-audit` (`arbiter gold-audit --json`) — measure the band + prioritized gaps.
+- `/close-gold-gap <gapId>` skill — the honest, category-typed recipe per gap.
+- `arbiter gold-audit --check` — the no-regress ratchet that locks each gain.
+- `scripts/check-all.mjs` — the disarm-proof anti-fake-green aggregate.
+
+## Defaults
+
+| Flag              | Default | Meaning                                              |
+| ----------------- | ------- | ---------------------------------------------------- |
+| `--target L0..L3` | `L3`    | The level band to reach (`L3` = the gold standard)   |
+| `--max-waves N`   | 5       | Cap on remediation waves before reporting + stopping |
+
+## The loop (per wave)
+
+1. **Measure** — `npx @getarbiter/cli gold-audit --json`; read the band + `gaps[]` (no AI re-scoring).
+2. **Compose** a remediation wave from the gaps, prioritized by risk + ratchet value +
+   closeability (code-closeable gaps ahead of `manual`/`process` gaps).
+3. **Close** each gap honestly via `/close-gold-gap` — doc-set (fill real content), test
+   (TDD-first), config (wire the real tool). A `manual` check or external blocker → needs-human.
+4. **Re-audit behind the guards (fail-closed):** `npx @getarbiter/cli gold-audit --check`
+   (no-regress ratchet) + `node scripts/check-all.mjs` (disarm-proof).
+5. Commit the new `.gold-audit-baseline.json` only when the band rose **for a real reason**;
+   repeat to `--target` (or until every remaining gap is needs-human).
+
+## Hard stops (fail-closed)
+
+- `gold-audit --check` exit 1 (regress) → REJECT the wave, revert the cheat, re-do real work.
+- `check-all.mjs` exit 1 (hard fail) or exit 2 (a broken/disarmed guard) → HALT —
+  you cannot disarm a guard by breaking it.
+- A gap that can't be closed honestly → `needs-human` with a blocker reason. **Never** faked,
+  suppressed, or marker-stuffed.
+
+## Final report
+
+before → after band + score; gaps closed (with evidence); gaps needs-human (with reason);
+ratchet verification (the committed baseline + the `--check` exit-0 that locks the gain).
+
+> See the **`levelup`** skill for the full phase contract and anti-fake-green rules.