@getarbiter/cli 0.5.0

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

@@ -0,0 +1,118 @@
+---
+name: tabletop
+description: Use when the user wants a use case walked end to end the way a user lives it — narrate the journey as the persona, execute every read-only or dry-run step, compare what the docs promise against what actually happens, and record the disagreements as owned findings. Evidence only; never changes the repo.
+title: 'Tabletop (use-case exercise)'
+doc_version: '1.0.0'
+status: active
+last_review: '2026-08-29'
+owner: ''
+canonical_id: ''
+tags: ['audience/agent', 'audience/dev', 'kind/internal', 'kind/analysis']
+related: ['ship', 'gold-audit']
+---
+
+# Tabletop (use-case exercise)
+
+**Goal:** walk one concrete journey the way a user lives it and record every point where the
+documentation, the CLI, a hook, a gate or CI disagree. Tests assert expectations someone
+already had; a tabletop walks the composition and asks, at each step, whether what the doc
+says matches what happens.
+
+**Input:** a scenario slug from `docs/internal/METHOD/TABLETOP-SCENARIOS.md`, or a free-text
+use case — slugify it (`^[a-z0-9]+(-[a-z0-9]+)*$`) and supply the five fields yourself.
+
+**Evidence only.** A tabletop never modifies the repository: no edits, no commits, no
+generated files, no `--fix`, no issue opened mid-walk. A step that would write is executed
+as `--dry-run` or described and left unrun.
+
+---
+
+## Step 1 — Open the scenario
+
+State, before walking: **persona**, **starting state**, **goal**, **the docs the user would
+read** (real paths), **the exit criterion**. Pin the tree: `git rev-parse HEAD`.
+
+## Step 2 — Walk the journey in character
+
+Narrate each step in the first person as the persona — what they want, what they type, what
+they see. At every step do all three:
+
+- **(a) Execute** what is safely executable read-only or dry-run: `arbiter <cmd> --dry-run`,
+  `<cmd> --help`, rendering a template with the project's config, reading the doc the user
+  would read, running an existing check. Never a mutating command.
+- **(b) State the promise** — quote what the documentation says happens here, with
+  `path:line`.
+- **(c) Record observed vs promised** — one findings row per disagreement.
+
+A step whose behaviour cannot be executed is still walked: read the code path that would
+run, and record the observation as `not executable — read <path>`.
+
+## Step 3 — Classify every finding
+
+| column                     | value                                                           |
+| -------------------------- | --------------------------------------------------------------- |
+| `step`                     | the step number in this walk                                    |
+| `doc claim (path:line)`    | the promise, cited                                              |
+| `observed`                 | what actually happened, verbatim                                |
+| `severity`                 | `blocker` / `major` / `minor`                                   |
+| `class`                    | `phantom-command` / `doc-drift` / `missing-gate` / `ux` / `bug` |
+| `proposed permanent check` | the test or gate that would have caught it                      |
+| `owner`                    | `#NNN`, an https URL, or `fixed:<sha>` — required at major+     |
+
+- **blocker** — the journey cannot continue: a documented command does not exist, or a step
+  fails closed with no recovery.
+- **major** — the journey continues but the user is misled, or a governance promise is
+  unenforced.
+- **minor** — cosmetic, or a phrasing gap with no behavioural consequence.
+
+A tabletop is high-recall and low-precision on purpose. Over-report, then let severity and
+the owner column do the filtering.
+
+## Step 4 — Write the evidence file
+
+Write `.arbiter/evidence/tabletop/<slug>-<YYYY-MM-DD>.md` — this is the ONE file a tabletop
+creates:
+
+```markdown
+---
+scenario: greenfield-init-ts
+sha: <full sha from Step 1>
+date: 2026-08-29
+persona: TypeScript library author installing arbiter for the first time
+steps: 7
+findings:
+  blocker: 0
+  major: 1
+  minor: 2
+---
+
+# Tabletop — greenfield-init-ts
+
+<one paragraph: the journey, in the persona's words>
+
+| step | doc claim (path:line) | observed | severity | class     | proposed permanent check | owner |
+| ---- | --------------------- | -------- | -------- | --------- | ------------------------ | ----- |
+| 2    | docs/QUICKSTART.md:31 | ...      | major    | doc-drift | ...                      | #2429 |
+```
+
+The `findings` counts MUST equal the table's row counts per severity —
+`node scripts/check-tabletop-evidence.mjs` fails the build otherwise.
+
+## Step 5 — Terminate every finding
+
+- Every **blocker** and **major** ends as a filed issue (`owner: #NNN`) or a fix landed on
+  the same train (`owner: fixed:<sha>`). An unowned blocker or major fails the gate.
+- Every **behaviour** finding proposes the test or gate that would have caught it, named
+  concretely (`__tests__/…`, `scripts/check-….mjs`, a CI job) — never "add a test".
+- Report to the user: the evidence path, the counts, and the blocker list.
+
+## Hard rules
+
+- **Evidence only** — never modify the repository during a tabletop. Findings are recorded,
+  not fixed, inside the walk.
+- **Cite or drop it.** A finding without a `path:line` promise and a verbatim observation is
+  an opinion; delete the row.
+- **No invented output.** Every `observed` cell is a command's real output or a file's real
+  content. Never narrate a command you did not run.
+- **Terminate in checks.** A tabletop that produces findings but no proposed checks has
+  bought one-off recall and no regression protection.

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

@@ -0,0 +1,157 @@
+---
+name: tdd
+description: Use when implementing any feature or bugfix. Red-Green-Refactor cycle enforced. Write the failing test first, then minimal implementation.
+title: "Test-Driven Development"
+doc_version: "1.0.0"
+status: active
+last_review: "2026-05-20"
+owner: ""
+canonical_id: ""
+tags: ['audience/agent', 'audience/dev', 'kind/internal']
+related: []
+---
+
+# Test-Driven Development
+
+No production code without a failing test first — a test written after the implementation
+can only confirm what the code already does, never what it was supposed to do.
+
+## Red-Green-Refactor
+
+1. **RED** — Write one failing test for the next behavior
+2. **Verify RED** — Run the test, confirm it fails for the right reason
+3. **Record RED** — `arbiter task record-red --test-path <path>` (add `--task '#NNN'` for a
+   secondary issue on a train). It runs the test, captures the failure, and writes the
+   SHA-pinned evidence file that the `red → green` phase gate reads; advancing into `green`
+   refuses without it. A step of the loop, not a separate ceremony: a loop that stops at
+   "Verify RED" leaves the next phase gate red.
+4. **GREEN** — Write minimal code to pass
+5. **Verify GREEN** — Run all tests, all pass
+6. **REFACTOR** — Clean up without breaking tests
+
+## Test Command
+
+```bash
+<%= testCommand %>
+```
+
+## Stack: <%= language %><% if (language === 'typescript') { %>
+
+**Test runner:** vitest
+
+```typescript
+import { describe, it, expect } from "vitest";
+
+describe("feature", () => {
+  it("does the expected thing", () => {
+    // Arrange
+    // Act
+    // Assert
+    expect(result).toBe(expected);
+  });
+});
+```
+<% } else if (language === 'java') { %>
+
+**Test runner:** JUnit 5 + Mockito
+
+```java
+@ExtendWith(MockitoExtension.class)
+class FeatureTest {
+
+    @Mock
+    private Dependency dependency;
+
+    @InjectMocks
+    private Feature feature;
+
+    @Test
+    void shouldDoExpectedThing() {
+        // Arrange
+        when(dependency.call()).thenReturn(value);
+
+        // Act
+        var result = feature.execute();
+
+        // Assert
+        assertThat(result).isEqualTo(expected);
+    }
+}
+```
+<% } else if (language === 'python') { %>
+
+**Test runner:** pytest
+
+```python
+def test_does_expected_thing():
+    # Arrange
+    # Act
+    result = feature()
+
+    # Assert
+    assert result == expected
+```
+<% } else if (language === 'go') { %>
+
+**Test runner:** Go standard `testing` package
+
+```go
+func TestFeature(t *testing.T) {
+    // Arrange
+    // Act
+    got := Feature()
+
+    // Assert
+    if got != want {
+        t.Errorf("Feature() = %v, want %v", got, want)
+    }
+}
+```
+<% } else if (language === 'rust') { %>
+
+**Test runner:** Rust built-in `#[test]` + `#[cfg(test)]`
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_does_expected_thing() {
+        // Arrange
+        // Act
+        let result = feature();
+
+        // Assert
+        assert_eq!(result, expected);
+    }
+}
+```
+<% } %>
+
+## Rules
+
+- One behavior per test
+- Watch each test fail before implementing
+- Minimal code to pass — no extra features
+- Refactor only after green
+
+## Anchor to the Acceptance Criteria (INV-138)
+
+Acceptance tests derive from the issue's frozen criteria, not from your interpretation —
+writing tests from your own reading of the issue is grading your own homework.
+
+- Source of truth: the plan's `## Acceptance Criteria` block (`AC-N:` ids frozen verbatim
+  from the issue), never a live re-read of the issue.
+- Cite the id in the test title: `it('retries 3 times on 5xx (AC-1)', …)` — the reviewer's
+  FIT rubric maps each `AC-N` to the test line that proves it.
+- State the mapping in the red commit body: "tests map 1:1 to the acceptance criteria of #NNN".
+- A behavior worth implementing that maps to NO criterion means the anchor is incomplete:
+  update the plan anchor first (or capture it via `arbiter note`), don't silently widen scope.
+
+## When to Skip TDD
+
+Only with explicit user permission, and a granted skip is recorded, never tacit: note it in
+the plan (`tdd: skipped — user permission, <where granted>`) so review and verification see
+a decision instead of an omission. "This is simple" is never a reason — simplicity predicts
+typing cost, not defect rate.

package/dist/templates/claude/skills/understand-code/SKILL.md.ejs

@@ -0,0 +1,93 @@
+---
+name: understand-code
+description: Use when exploring an unfamiliar code path, tracing a feature end-to-end, or when asked "how does X work?". Structured 4-step comprehension protocol. READ-ONLY.
+argument-hint: "<module, path, or feature description>"
+title: "Understand Code"
+doc_version: "1.0.0"
+status: active
+last_review: "2026-05-20"
+owner: ""
+canonical_id: ""
+tags: ['audience/agent', 'audience/dev', 'kind/internal']
+related: []
+---
+
+# Understand Code
+
+**Mode:** READ-ONLY throughout. No edits during this skill.
+
+## Step 1: Scope Discovery
+
+Use Glob and Grep to locate relevant files:
+
+```
+Glob: src/**/*<keyword>*
+Grep: "<keyword>" in src/
+```
+
+Collect:
+- Entry point (controller, command, route handler, event listener)
+- Domain / business logic files
+- Adapter files (repository, HTTP client, external service)
+- Test files (unit + integration)
+
+## Step 2: Code Tracing
+
+Read files in dependency order:
+1. Entry point — what triggers this code path?
+2. Application layer — what orchestration happens?
+3. Domain — what business rules apply?
+4. Adapters — how does the system persist or call out?
+
+Limit: Read at most 8 files. If scope is larger, narrow the argument.<% if (governanceLevel !== 'L1') { %>
+
+## Step 3: Invariant Mapping
+
+Check which invariants apply. The registry is at `GLOBAL_INVARIANTS.md`.
+
+For each applicable INV:
+- Is it currently enforced in the code you read?
+- Are there gaps? (Note them — do NOT fix during this skill)<% } else { %>
+
+## Step 3: Contract Mapping
+
+For each function in the call chain, note:
+- Pre-conditions (what must be true before the call)
+- Post-conditions (what is guaranteed after)
+- Error paths (what can go wrong)<% } %>
+
+## Step 4: Summary Report
+
+```markdown
+## Code Understanding: <argument>
+
+**Entry Point:** <file:line — method/endpoint/event>
+
+**Call Chain:**
+  <Layer1> → <Layer2> → <Layer3>
+
+**Key Data Flow:**
+  1. <input> received at <layer>
+  2. <transformation or validation>
+  3. <persistence/response>
+
+**Domain Rules:**
+  - <rule 1>
+
+**Test Coverage:**
+  - Unit: <files or "none found">
+  - Integration: <files or "none found">
+
+**Gaps / Risks (observe only — do not fix here):**
+  - <gap 1>
+
+**Next Step:**
+  - <if debugging>: hypothesis to test first
+  - <if modifying>: safe entry point for edits
+```
+
+## Constraints
+
+- Read-only. Do not edit files.
+- Do not propose fixes — only document gaps.
+- Do not run tests or gate.

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

@@ -0,0 +1,68 @@
+---
+name: verification
+description: Use before claiming work is complete, before committing, or before creating PRs. Verify tests pass, gate passes, and no invariants are violated.
+title: "Verification Before Completion"
+doc_version: "1.0.0"
+status: active
+last_review: "2026-05-20"
+owner: ""
+canonical_id: ""
+tags: ['audience/agent', 'audience/dev', 'kind/internal']
+related: []
+---
+
+# Verification Before Completion
+
+Run this sequence before any completion claim — a claim made from memory of green output is
+the single most common agent failure mode, so every claim below is re-verified against the
+tree now, not recalled. Work through the steps in order; each depends on the previous one,
+and an unchecked box is an unfinished task, not an optional extra.
+
+## Checklist
+
+### 1. Tests
+
+```bash
+<%= testCommand %>
+```
+
+- [ ] All tests pass
+- [ ] No skipped or disabled tests added
+- [ ] New behavior has test coverage
+
+### 2. Quality Gate
+
+```bash
+node scripts/check-all.mjs L1
+```
+
+- [ ] Typecheck passes
+- [ ] Lint passes
+- [ ] Format passes
+- [ ] No orphan TODOs
+
+### 3. Invariant Check
+
+- [ ] No `any` types introduced<% if (language === 'java') { %>
+- [ ] No `.get()` without Optional check
+- [ ] No MockMvc — use RestAssured for integration tests<% } %><% if (language === 'rust') { %>
+- [ ] No `.unwrap()` calls<% } %>
+- [ ] No disabled/placeholder tests
+
+### 4. Before Push
+
+```bash
+node scripts/check-all.mjs L2
+```
+
+- [ ] Coverage threshold met
+- [ ] No dead code
+- [ ] No circular dependencies
+
+## Stop conditions
+
+Commit and push only when every box above is checked. A failing gate, a failing test, or a
+TODO without a task ID (`TODO(#NNN): ...`) stops the completion claim here: fix the root
+cause first — a claim made over a red check is false the moment it is written, and the Stop
+hook (INV-114) will reject it anyway. Report what is red and what you are doing about it
+instead of claiming done.