@getarbiter/cli 0.5.0

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

@@ -0,0 +1,58 @@
+---
+name: close-gold-gap
+description: Use when the gold-audit reports an N/P gap (or a manual check) and you want the deterministic remediation recipe — scaffold/test/config/process — that closes it for a REAL reason, never by faking it.
+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']
+related: ['gold-audit', 'tdd']
+---
+
+# Close Gold Gap
+
+Turn one gold-audit gap into a concrete, deterministic remediation **recipe** — then carry it out.
+This skill **never fakes a close**: a recipe is a plan of real work, not a shortcut to flip a verdict.
+
+## When to use
+
+After `arbiter gold-audit` reports a gap (an `N` or `P` check, or a `manual` check that a human must
+attest). Pick the gap's `id` and ask for its recipe.
+
+## Workflow
+
+1. Run the audit to list the gaps:
+
+```bash
+npx @getarbiter/cli gold-audit
+```
+
+2. Classify the gap by **category** — what does the failed check actually verify? There is no
+   separate recipe engine; the category table below **is** the recipe.
+
+3. Execute the recipe's steps yourself. Each step is typed by **category**:
+
+| Category    | What the recipe does                                                            | Honest outcome |
+| ----------- | ------------------------------------------------------------------------------ | -------------- |
+| **doc-set** | Scaffold the missing doc (`check-doc-set --generate`) **then fill real content** | `P` → `Y` only after real content |
+| **test**    | Write the missing test(s) TDD-first (loads the `tdd` skill)                      | `Y` when the real metric meets the bar |
+| **config**  | Wire the real tool/config the check verifies                                     | `Y` when the tool genuinely runs |
+| **process** | Human-only action for a `manual` check — **no code recipe**                      | `NV` (code cannot verify it) |
+
+## Anti-fake-green (hard rules)
+
+- A doc **stub** proves presence, not closure — a scaffold-only step is `P`, **never** `Y`. Fill it
+  with real content before claiming the check.
+- A `manual` check is `NV`: code cannot verify it. There is **no** code recipe — a human performs and
+  records the real-world action. Never try to make code "pass" a manual check.
+- **No suppression** — a recipe never contains `--no-verify`, `eslint-disable`, `skip`, or `ignore`.
+- **No marker-stuffing** — never write the matched `pattern`/`equals` literal as the sole action; wire
+  the behavior the check is verifying.
+
+## Re-audit
+
+After executing a recipe, re-run `npx @getarbiter/cli gold-audit` and confirm the gap flipped for a real
+reason — the genuine metric improved or real content/config now exists. If it only flipped because a
+threshold moved or a literal was pasted in, that is fake-green: revert and do the real work.

package/dist/templates/claude/skills/codebase-audit/SKILL.md.ejs

@@ -0,0 +1,88 @@
+---
+name: codebase-audit
+description: Use when running a comprehensive codebase verification. Dispatches parallel agents across disjoint scopes to check invariant compliance, dead code, test coverage gaps, and naming consistency.
+title: "Codebase Audit"
+doc_version: "1.0.0"
+status: active
+last_review: "2026-05-20"
+owner: ""
+canonical_id: ""
+tags: ['audience/agent', 'audience/dev', 'kind/internal']
+related: []
+---
+
+# Codebase Audit
+
+**Purpose:** Systematic whole-codebase verification using parallel read-only agents.
+
+## When to Use
+
+- Before a major release
+- After a large refactor
+- Periodic health checks
+- Onboarding to an unfamiliar codebase
+
+## Audit Scopes
+
+Divide the codebase into disjoint scopes and delegate each to a `codebase-scanner` agent:
+
+| Scope | What to Check |
+|-------|--------------|
+| **Dead code** | Unused exports, unreachable functions, commented-out blocks |
+| **Naming consistency** | Conventions followed (camelCase, snake_case per layer) |
+| **Test coverage gaps** | Source files without a corresponding test file |
+| **Error handling** | Unchecked errors, swallowed exceptions, missing fallbacks |<% if (language === 'typescript') { %>
+| **Type safety** | `any` usage, missing return types on public functions |<% } %><% if (language === 'java') { %>
+| **Null safety** | `null` returns without `Optional`, unchecked `get()` calls |
+| **Layer violations** | Domain importing from infrastructure, controller importing repository |<% } %>
+
+## Execution
+
+For each scope, delegate to `codebase-scanner`:
+
+```
+Delegate to codebase-scanner:
+  "Find all <scope> issues in src/"
+```
+
+Run scopes in parallel when possible.
+
+## Output Format
+
+```markdown
+## Codebase Audit Report
+
+**Date:** <date>
+**Scope:** Full / Partial (<modules>)
+
+### Dead Code
+- <file:line — description>
+
+### Naming Inconsistencies
+- <file:line — convention violated>
+
+### Test Coverage Gaps
+- <source file without test>
+
+### Error Handling Gaps
+- <file:line — description><% if (language === 'typescript') { %>
+
+### Type Safety Issues
+- <file:line — description><% } %><% if (language === 'java') { %>
+
+### Null Safety Issues
+- <file:line — description>
+
+### Layer Violations
+- <file:line — description><% } %>
+
+### Summary
+- Total issues found: <N>
+- Critical: <N>
+- Recommended actions: <list>
+```
+
+## Constraints
+
+- Read-only. No edits during audit.
+- Do not fix issues inline — create task briefs for fixes.

package/dist/templates/claude/skills/configure/SKILL.md.ejs

@@ -0,0 +1,72 @@
+---
+name: configure
+description: Use when the user wants to change arbiter.json settings (governance level, feature flags, thresholds) without re-running the full wizard.
+title: "Arbiter Configure"
+doc_version: "1.0.0"
+status: active
+last_review: "2026-05-20"
+owner: ""
+canonical_id: ""
+tags: ['audience/agent', 'audience/dev', 'kind/internal']
+related: []
+---
+
+# Arbiter Configure
+
+Modify `arbiter.json` configuration fields without re-running `arbiter init`.
+
+## Supported Paths
+
+**Feature flags** (`true` / `false`):
+- `features.debtGates`
+- `features.securityScanning`
+- `features.mutationTesting`
+- `features.contractTesting`
+- `features.suppressions`
+- `features.evidenceHarness`
+
+**AI tools** (comma-separated list: `claude`, `codex`):
+- `tools`
+
+**Thresholds** (numbers):
+- `thresholds.lineCoverage` (1–100)
+- `thresholds.branchCoverage` (1–100)
+- `thresholds.mutationScore` (1–100)
+- `thresholds.cyclomaticComplexity` (positive)
+- `thresholds.methodLength` (positive)
+- `thresholds.maxParams` (positive)
+
+## Workflow
+
+1. Ask the user which setting they want to change and the new value.
+2. Run the configure command:
+
+```bash
+<% if (tools.includes('claude')) { %>npx @getarbiter/cli configure --set <path>=<value><% } %>
+```
+
+3. If the change affects generated files, offer to run `arbiter update`:
+
+```bash
+npx @getarbiter/cli update
+```
+
+## Examples
+
+```bash
+# Disable mutation testing
+npx @getarbiter/cli configure --set features.mutationTesting=false
+
+# Raise line coverage target
+npx @getarbiter/cli configure --set thresholds.lineCoverage=90
+
+# Multiple changes at once
+npx @getarbiter/cli configure --set features.debtGates=true --set thresholds.cyclomaticComplexity=10
+
+# Change AI tools
+npx @getarbiter/cli configure --set tools=claude,codex
+```
+
+## Current Config
+
+Read the current `arbiter.json` to show the user the current values before asking what to change.

package/dist/templates/claude/skills/epic-decompose/SKILL.md.ejs

@@ -0,0 +1,86 @@
+---
+name: epic-decompose
+description: Use when breaking down a large feature (epic) into independently deliverable tasks. Produces a sequenced task list with dependencies, acceptance criteria, and size estimates.
+argument-hint: "<epic title or description>"
+title: "Epic Decompose"
+doc_version: "1.0.0"
+status: active
+last_review: "2026-05-20"
+owner: ""
+canonical_id: ""
+tags: ['audience/agent', 'audience/dev', 'kind/internal']
+related: []
+---
+
+# Epic Decompose
+
+**Purpose:** Break a large feature into independently shippable tasks.
+
+## Step 1: Understand the Epic
+
+Read the epic description carefully. Identify:
+- The user-visible outcome
+- The technical surface area (which layers are affected)
+- External dependencies (third-party APIs, migrations, infra changes)
+- Risk areas (security, performance, backwards compatibility)
+
+## Step 2: Identify Seams
+
+Find natural boundaries where the work can be split:
+- **Vertical slices** — thin end-to-end slices (preferred)
+- **Horizontal layers** — domain first, then API, then UI
+- **Data migrations** — always a separate task, run before or after code
+
+## Step 3: Sequence Tasks
+
+Order tasks by:
+1. Foundation first (data models, migrations, shared types)
+2. Core behavior second (business logic, domain layer)
+3. Integration third (API endpoints, event handlers)
+4. UI/UX last (if applicable)
+5. Cleanup/polish (dead code removal, documentation)
+
+## Step 4: Write Task Briefs
+
+For each task:
+
+```markdown
+### Task N: <title>
+
+**Goal:** <one sentence — what does this task deliver?>
+**Depends on:** Task N-1 (or "none")
+**Acceptance criteria:**
+  - [ ] <testable criterion 1>
+  - [ ] <testable criterion 2>
+**Size:** XS / S / M / L
+**Risk:** Low / Medium / High
+**Notes:** <edge cases, gotchas, open questions>
+```
+
+## Size Reference
+
+| Size | Scope |
+|------|-------|
+| XS | < 1 hour, 1-2 files |
+| S | Half day, 3-5 files |
+| M | 1-2 days, 5-10 files |
+| L | 3-5 days, 10+ files or multiple layers |
+
+Tasks larger than M should be split further.
+
+## Output Format
+
+```markdown
+## Epic: <title>
+
+**Summary:** <2-3 sentences>
+**Total tasks:** <N>
+**Estimated total:** <size>
+
+### Tasks
+<task briefs in sequence>
+
+### Open Questions
+- <question 1>
+- <question 2>
+```

package/dist/templates/claude/skills/gold-audit/SKILL.md.ejs

@@ -0,0 +1,91 @@
+---
+name: gold-audit
+description: Use when the user wants to measure how close the project is to gold-standard quality — runs the deterministic `arbiter gold-audit` engine and reports the level band plus a prioritized list of what is missing. Read-only; never changes code.
+title: "Gold Audit (measure)"
+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 (measure)
+
+**Goal:** tell the user where the project sits against the gold-standard registry —
+its level band (`L0`–`L3`), its score, and a prioritized "what's missing" list — so
+they know exactly what to close next.
+
+**Read-only.** This skill MEASURES; it never changes a single file. It runs the
+existing deterministic engine and presents the result. It does NOT re-score, re-rank,
+or "estimate" anything with the model — the verdicts come straight from the engine.
+
+---
+
+## Step 1 — Run the engine
+
+```bash
+npx @getarbiter/cli gold-audit --json
+```
+
+The CLI auto-detects the project's brownfield class and degrades gracefully when no
+registry is installed. Capture stdout as the payload.
+
+---
+
+## Step 2 — Handle the graceful fallback
+
+The engine prints a non-JSON SKIP line (it does not start with `{`) when there is no
+registry/engine installed. In that case do NOT invent a score. Tell the user the
+gold registry isn't wired up yet and point them at:
+
+```bash
+npx @getarbiter/cli init    # new project — sets up the registry + gates
+npx @getarbiter/cli update  # existing arbiter project — refreshes the generated kit
+```
+
+Then stop.
+
+---
+
+## Step 3 — Read the payload verbatim
+
+When stdout is JSON, parse it and read these fields **as-is** (no re-scoring):
+
+| Field          | Use                                                            |
+| -------------- | ------------------------------------------------------------- |
+| `level.level`  | Current band: `L0` / `L1` / `L2` / `L3`                        |
+| `level.nextLevel` / `level.toNextLevel` | Next band + how many points away    |
+| `level.brownfieldClass` | The detected class the band is keyed to              |
+| `score`        | Overall score                                                 |
+| `yCount` / `totals.checks` | Checks fully satisfied vs total                  |
+| `riskyCount`   | Count of risky (N/P on high-risk) checks                      |
+| `checks[]`     | Per-check `id` / `dimension` / `title` / `type` / `verdict` / `weight` / `evidence` |
+| `gaps[]`       | The "what's missing" families: N/P checks grouped by `dimension` |
+
+---
+
+## Step 4 — Present the level band + prioritized gaps
+
+Lead with the band, then the gap list grouped by family (`dimension`):
+
+1. **Level line** — `<level> (<brownfieldClass>) · score <score> · <toNextLevel> to <nextLevel> · Y <yCount>/<totals.checks> · RISKY <riskyCount>`.
+2. **What's missing** — iterate `gaps[]`. For each `dimension` family, list its N/P
+   checks as `<verdict> <id> <title>` with the `evidence.file`/`evidence.detail` when
+   present. These are the concrete, deterministic next actions.
+3. If `gaps[]` is empty, report that every applicable check is `Y`.
+
+Prioritize the families with the most `N` (missing entirely) and highest-risk checks
+first — but the ordering reflects the engine's verdicts, not a model opinion.
+
+---
+
+## Hard rules
+
+- **Deterministic, no AI scoring.** Same repo + same registry ⇒ identical output. The
+  level and every verdict come from the engine payload; never substitute a guess.
+- **Read-only.** Measure and report. Closing a gap is a separate, explicit action —
+  this skill never edits code, config, or docs.
+- **Graceful when absent.** No registry ⇒ point at `arbiter init` / `arbiter update`,
+  never a fabricated score.

package/dist/templates/claude/skills/impact/SKILL.md.ejs

@@ -0,0 +1,104 @@
+---
+name: impact
+description: Use when you need the blast radius of a change — "who calls X", "what breaks if I touch Y", upstream/downstream dependents of a symbol or file. Opt-in graph-first: if the optional `graphify` knowledge graph is present and fresh, query it (deterministic, no-LLM, ~1000x fewer tokens than grep-and-read); otherwise fall back to ripgrep. Never required — degrades gracefully when graphify is absent.
+argument-hint: '<symbol-or-file>'
+title: 'Impact (blast radius)'
+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: ['ssot-navigation', 'understand-code', 'ship']
+---
+
+# Impact (blast radius)
+
+**Goal:** answer "what depends on X?" — the upstream/downstream blast radius of a symbol or
+file — accurately and cheaply, before you change it.
+
+**Opt-in, graph-first.** arbiter does not require any graph tool. But if the optional
+[`graphify`](https://github.com/) knowledge graph is installed and a `graphify-out/graph.json`
+exists in the repo, this skill queries the graph **first** — it is deterministic (no LLM),
+pre-computes the dependency edges, and answers a blast-radius query in ~1000x fewer tokens than
+loading every grep hit. When the graph is absent or the symbol is not in it, the skill falls
+back to ripgrep. Either way you get an answer; the graph just makes it cheap and complete.
+
+> This is the analysis sibling of `/ship`: run `/impact` to scope a change before planning, and
+> in `/ship`'s plan/red-team phases to validate that the plan touched everything the change
+> actually reaches.
+
+---
+
+## Step 0 — Detect availability (graceful)
+
+```bash
+command -v graphify >/dev/null 2>&1 && test -f graphify-out/graph.json
+```
+
+- **Available** → continue with the graph path (Steps 1–3).
+- **Not available** → skip to **Fallback (ripgrep)**. Do NOT fail; graphify is optional. If the
+  user wants the cheap path, tell them once: install the `graphify` CLI (a `uv tool`) and run
+  `graphify update .` to build `graphify-out/`.
+
+---
+
+## Step 1 — Ensure the graph is fresh (deterministic, no-LLM)
+
+The graph is a derived artifact; it is only trustworthy when it matches the working tree.
+
+```bash
+# Stale if the recorded build commit != HEAD, or tracked code changed in the working tree.
+build_commit="$(sed -n 's/^build_commit: *//p' graphify-out/GRAPH_REPORT.md 2>/dev/null)"
+head="$(git rev-parse HEAD)"
+if [ "$build_commit" != "$head" ] || ! git diff --quiet; then
+  graphify update .            # deterministic refresh; no model involved
+fi
+```
+
+Refreshing is cheap and never asks a model anything — it re-extracts edges from source.
+
+---
+
+## Step 2 — Query the blast radius
+
+```bash
+graphify explain "<symbol>" --graph graphify-out/graph.json   # upstream + downstream dependents
+graphify path "<A>" "<B>"   --graph graphify-out/graph.json   # shortest dependency chain A→B
+```
+
+- Treat `EXTRACTED` edges (found in real code) as reliable.
+- Flag `INFERRED` edges (model-guessed at graph-build time) as "verify by hand" in any
+  review/red-team note — do not trust them blindly.
+
+---
+
+## Step 3 — Report
+
+Summarize: the changed symbol/file, its **direct** dependents, the **transitive** reach
+(modules/files), and any `INFERRED` edges that need manual confirmation. Feed this into the plan
+(which files the change must touch) and the red-team (what it might have missed).
+
+---
+
+## Fallback (ripgrep)
+
+When graphify is unavailable or returns "not in graph" (a miss), use ripgrep — correct, just
+more tokens:
+
+```bash
+rg -n --no-heading -w "<symbol>" -g '!**/dist/**' -g '!**/node_modules/**'
+```
+
+Then read the hits to separate definitions from call sites. This is the historical default and
+is always available; the graph is purely an optimization on top of it.
+
+---
+
+## Hard rules
+
+- **Optional, never fatal.** No gate, plan, or `/ship` phase may _require_ graphify. Absence ⇒
+  fall back, never error.
+- **Deterministic graph only.** Graph build/refresh (`graphify update`) is no-LLM; never "guess"
+  a blast radius and present it as graph output.
+- **Freshness before trust.** A stale graph is worse than none — always run Step 1 first.

package/dist/templates/claude/skills/levelup/SKILL.md.ejs

@@ -0,0 +1,146 @@
+---
+name: levelup
+description: Use when the user wants to raise a governed project's gold level honestly — runs /gold-audit, composes a remediation wave that closes each gap for a REAL reason via /close-gold-gap, then re-audits with the no-regress ratchet + anti-fake-green guards. The level rises only by a real verdict flip; un-closeable gaps become needs-human, never faked.
+argument-hint: '[--target L0|L1|L2|L3] [--max-waves N]'
+title: 'Level Up (raise the gold level honestly)'
+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', 'wave-drain', 'tdd', 'verification']
+---
+
+# Level Up (raise the gold level honestly)
+
+**Goal:** raise this project's gold-audit **level band** toward `--target` (default the
+top band, `L3` — the "gold" standard) by closing real gaps. Every point gained is backed by
+real config / test / doc work; the level **only** rises by a real verdict flip.
+
+**Mental model:** you are the **orchestrator**. `/levelup` does not invent a score and does
+not implement gaps by hand inline — it **measures** with `/gold-audit`, **composes a
+remediation wave** (the `/drain` fan-out shape), **closes each gap honestly** with
+`/close-gold-gap`, then **re-audits behind the ratchet + anti-fake-green guards**. It reuses
+existing engines and skills — there is **no new TS engine** and **no new `arbiter` CLI verb**.
+
+> `/gold-audit` measures (read-only). `/close-gold-gap` gives one gap its real recipe.
+> `/levelup` is the loop that ties them together and drives the band up, wave by wave.
+
+## Primitives
+
+| Primitive                                 | Role here                                                            |
+| ----------------------------------------- | -------------------------------------------------------------------- |
+| Skill `gold-audit`                        | Measure the band + the prioritized `gaps[]` (read-only, no AI score) |
+| `arbiter gold-audit --json`               | The deterministic engine payload `/gold-audit` reads                 |
+| `arbiter gold-audit --check`              | No-regress ratchet gate — locks each gain, fails on any regress      |
+| Skill `close-gold-gap`                    | The typed, honest recipe (doc-set / test / config / process) per gap |
+| Skill `wave-drain`                        | The fan-out shape for the remediation wave (groups, parallel agents) |
+| Skill `tdd`                               | Red → green → refactor for every `test`-category gap                 |
+| Skill `verification`                      | Claim-based verification before the re-audit gate                    |
+| `scripts/check-all.mjs`                   | The anti-fake-green aggregate — fail-closed disarm-proof verdict     |
+
+---
+
+## Phase 0 — Measure the starting band
+
+```bash
+npx @getarbiter/cli gold-audit --json
+```
+
+Load the **`gold-audit`** skill and read the payload verbatim — `level.level`,
+`level.nextLevel`, `score`, and `gaps[]` (the N/P checks grouped by `dimension`). Record this
+as the **before** snapshot. If the engine emits a SKIP line (no registry installed), do NOT
+invent a score: point the user at `npx @getarbiter/cli init` / `npx @getarbiter/cli update` and stop.
+
+Parse `--target` (a level band `L0`–`L3`, default the top band `L3`). If the current band is
+already `>= --target`, report "already at target" and stop.
+
+## Phase 1 — Compose a remediation wave
+
+From `gaps[]`, build a **wave** of the gaps that move the band fastest, prioritized by:
+
+1. **brownfield class + risk** — high-risk N (missing entirely) checks first;
+2. **ratchet value** — the checks whose `weight` contributes most to the next band;
+3. **closeability** — `config` / `test` / `doc-set` gaps (code-closeable) ahead of `process`
+   gaps (`manual`, `NV` — human-only, no code recipe).
+
+Partition the wave into **groups** of module-coherent gaps (the `/drain` rule: two agents
+never edit the same file concurrently). Independent groups are parallelizable.
+
+## Phase 2 — Close each gap honestly
+
+For each gap, derive its recipe and carry it out. Load the **`close-gold-gap`** skill and execute the
+recipe by **category** — the category table below **is** the recipe (no separate engine call):
+
+| Category    | Real work                                                      | Honest outcome                         |
+| ----------- | -------------------------------------------------------------- | -------------------------------------- |
+| **doc-set** | scaffold the doc, **then fill real content**                   | `P` → `Y` only after real content      |
+| **test**    | write the missing test(s) **TDD-first** (load the `tdd` skill) | `Y` when the real metric meets the bar |
+| **config**  | wire the real tool/config the check verifies                   | `Y` when the tool genuinely runs       |
+| **process** | human-only action for a `manual` check — **no code recipe**    | `NV` → routes to needs-human           |
+
+A gap that cannot be closed honestly — a `manual`/`process` check, a gap blocked on a human
+decision, or one needing an external account/service — becomes **`needs-human`** with a stated
+blocker reason. It is **NEVER** faked, suppressed, or marker-stuffed. It does not block the
+wave: the rest proceeds.
+
+## Phase 3 — Re-audit behind the ratchet + anti-fake-green guards (fail-closed)
+
+After the wave's gaps are closed, gate the gain. The level rises **only** by a real verdict
+flip — never by a moved threshold, a pasted literal, or a disabled check:
+
+```bash
+# 1. No-regress ratchet — locks the gain; exit 1 if score/Y regressed below baseline.
+npx @getarbiter/cli gold-audit --check
+
+# 2. Anti-fake-green aggregate — disarm-proof; a broken guard (exit 2) fails unconditionally.
+node scripts/check-all.mjs
+
+# 3. Re-measure the band and compare to the before snapshot.
+npx @getarbiter/cli gold-audit --json
+```
+
+**Fail-closed semantics (structural anti-fake-green):**
+
+- `gold-audit --check` exit **1** (regress) → a gap was un-closed or a real metric dropped:
+  **REJECT** the wave, revert the cheated change, re-do the real work.
+- `check-all.mjs` exit **1** (hard fail) or exit **2** (a broken/disarmed guard)
+  → **HALT** the wave. A guard you cannot trust is a stop, not a pass — you cannot disarm a
+  guard by breaking it.
+- The re-audit must show the band rose **for a real reason** (genuine metric improved, real
+  content/config now exists). A green that appears only because a literal was pasted or a
+  threshold moved is **fake-green**: revert and do the real work.
+
+Only when all three pass and the band genuinely rose do you **commit the new
+`.gold-audit-baseline.json`**, which ratchets the gain monotonically — the next wave can only
+go up from here.
+
+## Phase 4 — Repeat to target, then report
+
+Repeat Phase 1 → Phase 3 until the band reaches `--target` or no further gap can be closed
+honestly (every remaining gap is `needs-human`). Cap the loop at `--max-waves` (default 5) to
+stay bounded; if the target is not reached within the cap, report the remaining gaps and stop.
+
+Emit the **final report**:
+
+- **before → after** — starting band + score vs final band + score.
+- **gaps closed** — each `gapId`, its category, and the **evidence** (the real file/test/config
+  that flipped it `Y`).
+- **gaps needs-human** — each `gapId` with its **blocker reason** (manual check, external
+  dependency, human decision).
+- **ratchet verification** — the committed `.gold-audit-baseline.json` and the `--check`
+  exit-0 that locks the gain monotonically.
+
+## Hard rules (anti-fake-green)
+
+- **The level rises only by a real verdict flip.** Same repo + same registry ⇒ identical
+  engine verdicts; a band that "rose" without real work did not rise.
+- **Fail-closed.** A broken guard (exit 2) or a hard-fail (exit 1) **halts the wave** — never
+  `--no-verify`, never skip, never disable a guard to pass it.
+- **No fake green, ever.** No suppression (`--no-verify`, `eslint-disable`, `skip`, `ignore`),
+  no marker-stuffing (pasting the matched `pattern`/`equals` literal as the sole action), no
+  doc stub claimed as `Y`. A gap that can't be closed honestly → **`needs-human`**.
+- **No new engine, no new CLI verb.** `/levelup` is a skill + slash command; it composes
+  `arbiter gold-audit` and the `close-gold-gap` skill — it never re-implements scoring or the
+  no-regress check.