@getarbiter/cli 0.5.0

package/dist/templates/claude/rules/50-batch-execution.md

@@ -0,0 +1,75 @@
+# Batch Execution Contract
+
+## Principle
+
+Parallel agents are powerful but dangerous when they edit shared state concurrently. This rule defines when parallelism is safe.
+
+## Allowed: Read-Only Parallel Agents
+
+Spawn multiple agents concurrently only when ALL of the following are true:
+
+- **Read-only**: agents only read files, grep, search, or list — no writes
+- **File-discovery**: agents locate paths, gather facts, or summarize content
+- **No shared output**: agents do not write to the same file or directory
+- **No dependencies**: agents do not depend on each other's results to proceed
+
+Examples of safe parallel work:
+
+- Search for all usages of a symbol across the codebase
+- Read multiple independent files to gather facts
+- Run read-only analysis scripts on separate subsystems
+
+## Prohibited in Parallel Agents
+
+Never spawn parallel agents that:
+
+- **Edit or write files** — concurrent edits cause conflicts and lost work
+- **Commit to git** — commit ordering is non-deterministic; history corrupts
+- **Install or modify dependencies** — package-lock divergence is unrecoverable
+- **Create branches or tags** — race conditions in git ref creation
+- **Delete files or directories** — no recovery from concurrent deletes
+
+## Carve-out: Worktree-Isolated Parallel Execution (ADR-103)
+
+The prohibitions above target parallel agents sharing ONE working tree. A parallel
+agent is exempt from the edit/commit/branch prohibitions only when ALL of the following
+conditions hold — each is necessary, and any miss voids the exemption:
+
+1. **Dedicated worktree** — the agent operates in its own git worktree opened via
+   `arbiter worktree open` (or `/wt-open`). What prevents the ref race is git itself:
+   `git worktree add -b` creates the branch atomically and refuses one that exists.
+   (The `.arbiter/.lock` taken during open guards the open-log write, not branch
+   creation — ADR-103 D1.)
+2. **Distinct branch per agent** — no two parallel agents ever share a branch.
+3. **Disjoint file-sets** — the file-sets the agents will touch are declared disjoint
+   in a plan manifest (wave-drain Phase 1) before dispatch.
+
+Still prohibited even under the carve-out:
+
+- **Installing or modifying dependencies** (`package.json` / lockfiles) — a solo,
+  serial lane only; lockfile divergence across worktrees is unrecoverable.
+- **Editing the main working tree** — workers write only inside their own worktree.
+- **Creating tags** — tags are repo-global refs; no worktree isolation applies.
+
+Lock discipline under the carve-out (ADR-103 §4): `arbiter gate-exec` is a **leaf**
+operation — it acquires only the gate flock and is never invoked while `.arbiter/.lock`
+is held, so the one BLOCKING lock is never taken underneath a file lock. Total
+acquisition order: gate-lock ≺ worktree-lock ≺ wave-claim.
+
+## Anti-Rot Checklist
+
+Before spawning parallel agents, verify:
+
+- [ ] Each agent's task is read-only or produces output to a distinct, non-overlapping path
+- [ ] No agent modifies shared state (git index, lockfiles, shared dirs)
+- [ ] Results are aggregated by the orchestrator AFTER all agents complete
+- [ ] If any agent needs to write, serialize it — run agents sequentially instead
+
+## Recovery
+
+If parallel agents collide (conflicting edits, broken lockfile, corrupted state):
+
+1. Abort all in-flight agent operations
+2. Run `git status` to assess damage
+3. Restore from last clean commit (`git stash` or `git restore`)
+4. Re-run the work sequentially

package/dist/templates/claude/rules/55-brainstorm-terminal-state.md

@@ -0,0 +1,44 @@
+---
+title: 'Brainstorm Terminal-State Rule'
+doc_version: '1.0.0'
+status: active
+last_review: '2026-06-07'
+owner: ''
+canonical_id: ''
+tags: ['audience/agent', 'audience/dev', 'kind/internal']
+related: []
+---
+
+# Brainstorm Terminal-State Rule
+
+Brainstorming is a divergence phase, not an implementation phase. Its output is a
+decision, captured durably — never code.
+
+## The Contract
+
+A brainstorm session has exactly one terminal state:
+
+1. A committed design doc under `docs/design/<topic-slug>.md`, and
+2. A GitHub issue that captures the decision.
+
+Once both exist, the session **STOPS**. It never flows into implementation in the
+same turn.
+
+## Hard Stops
+
+While a brainstorm is active (marker `.arbiter/brainstorm-active` present), do NOT:
+
+- Begin implementation or edit source files
+- Create branches or commits for the feature
+- Run `/task` to advance into build
+
+The `post-brainstorm-stop` hook enforces this: it blocks `/task` until the marker
+is explicitly cleared (`rm .arbiter/brainstorm-active`) or the marker auto-expires
+after 24 hours.
+
+## Why
+
+Separating "decide what to build" from "build it" keeps decisions reviewable before
+code is written, prevents half-explored designs from hardening into the codebase,
+and gives every implementation a tracked issue to anchor against. Implementation
+begins only after a human picks up the issue with `/task #<issue-number>`.

package/dist/templates/claude/rules/60-incidental-capture.md

@@ -0,0 +1,43 @@
+# Incidental-Capture Rule
+
+While doing task X, you will notice debt, smells, and risks that live OUTSIDE X's
+scope. Each one is real and must not be lost — but acting on it inside X corrupts
+the diff, dilutes the review, and breaks the one-task-one-change contract.
+
+## The Contract
+
+When you notice an out-of-scope finding while working task X, your ONLY in-band
+action is to capture it:
+
+```bash
+arbiter note "<finding>" --kind <dup|smell|risk|debt> --severity <low|med|high> --file <path> --line <n>
+```
+
+Capture is the TERMINAL action for that finding during this task. Once noted, you
+return to X immediately.
+
+## Hard Stops
+
+For a finding that is out of scope for the current task, do NOT:
+
+- Fix it (no edit to address it — capture only)
+- Branch for it or widen the current task's diff to accommodate it
+- Open an issue inline, refactor "while you're here", or chase it down a rabbit hole
+
+The note lands in a per-agent JSONL spool at `.arbiter/findings/<shard>.jsonl`
+(ephemeral, gitignored — drained downstream, never committed).
+
+## Composes With
+
+- **Root-cause discipline** — a smell INSIDE the current diff is fixed or recorded
+  as tech-debt, not merely noted. `arbiter note` is for findings OUTSIDE the current
+  diff.
+- **Tech-debt** — a finding that warrants a tracked, durable follow-up is promoted
+  to `arbiter task record-tech-debt`; `arbiter note` is the lightweight first capture,
+  drained and triaged later.
+
+## Why
+
+A noticed-but-unrecorded finding is a finding lost. Separating "see it" from "fix
+it" keeps each task's diff minimal and reviewable, prevents scope creep, and turns
+every passing observation into durable signal instead of an abandoned good intention.

package/dist/templates/claude/rules/75-impact-vault-reading.md

@@ -0,0 +1,43 @@
+# Impact-First Editing Rule
+
+Before you change a module, know what depends on it. arbiter already emits a
+dependency graph and an `/impact` analysis skill — but nothing makes you _read_ it
+before editing. A change made blind to its blast radius is how a "small fix" silently
+breaks three callers you never opened.
+
+## The Contract
+
+Before editing a module that is **shared, core, or reached by more than one caller** —
+and always before a change that touches **2+ files** — first establish its blast radius:
+
+```
+/impact <symbol-or-file>
+```
+
+`/impact` is **graph-first**: when the optional `graphify` knowledge graph
+(`graphify-out/graph.json`) is present and fresh, it answers from the precomputed
+dependency edges — deterministic, no-LLM, ~1000x cheaper than loading every grep hit.
+When the graph is absent or the symbol is not in it, it **falls back to ripgrep**, so
+you always get an answer. Reading the graph is never required for the gate to pass — but
+it is the cheapest way to avoid an out-of-scope break.
+
+Record the result in the plan: the upstream callers and downstream dependents the change
+reaches, and which of them this edit must keep working. The plan's `files:` manifest
+should cover them — if `/impact` surfaces a dependent outside the manifest, widen the
+plan or capture it with `arbiter note`, do not edit it incidentally.
+
+## What This Is NOT
+
+- A hard gate — this is **advisory**. It blocks nothing; it directs attention. It
+  composes with the `pre-edit-plan-anchor` hook (which enforces the plan) and the
+  incidental-capture rule (which keeps out-of-scope dependents out of the diff).
+- A requirement to install `graphify` — arbiter never requires a graph tool. The skill
+  degrades to ripgrep with no loss of correctness, only of cheapness.
+- Applicable to a one-line edit in a leaf file with no dependents — judgment, not
+  ceremony.
+
+## Why
+
+The blast radius of a change is knowable _before_ you make it, and arbiter already paid
+to compute it. Reading it first turns "I think this is isolated" into "I verified what
+this reaches" — the difference between a reviewed change and a hopeful one.

package/dist/templates/claude/rules/90-exec-protocol.md.ejs

@@ -0,0 +1,40 @@
+# Execution Protocol
+
+## Branch Enforcement
+
+Before any file edit:
+1. Run `git branch --show-current`
+2. If on `main` → stop and create a task branch first — edits on `main` bypass every review and gate artifact that anchors to a task branch
+3. Branch must start with `task/` — e.g., `task/#123-description`
+
+## Execution Flow
+
+1. Read AGENTS.md (invariants + governance)
+2. Create task branch if not on one
+3. Plan before editing (3+ file changes → outline first)
+4. Run `/ship #NNN` — the single orchestration entrypoint (auto-sequences plan → review → gate → merge)
+5. Implement with TDD (test first) — `/ship` drives each phase; `/task` subcommands for recovery only
+6. Run `node scripts/check-all.mjs L1` before commit
+7. Run `node scripts/check-all.mjs L2` before push
+
+## Gate Commands
+
+```bash
+node scripts/check-all.mjs L1   # fast: lint + format + unit tests
+node scripts/check-all.mjs L2   # full: L1 + coverage + integration
+```
+
+## Stop Conditions
+
+- Gate fails after two focused attempts → STOP, report blockers
+- INV violation found → STOP, do not bypass
+- Orphan TODO found → fix before proceeding
+- Symptom patch over a known smell (duplicate-of-existing-helper, missed extraction) without `arbiter task record-tech-debt` → STOP
+
+## Root-Cause Discipline (CANON-22)
+
+When a change touches code that the duplication (jscpd), complexity, or dead-code gates flag:
+
+- **Fix the root cause** in the smelly/duplicated code you touch — extract the shared helper, simplify the over-complex function, delete the dead branch.
+- **OR** run `arbiter task record-tech-debt` with an explicit rationale (why the root-cause fix is out of scope now) before proceeding.
+- A symptom-only patch layered over a known smell — duplicating a helper that already exists, widening a function already over the complexity ceiling — is a stop condition, not a tradeoff. The duplication ratchet (Lehman entropy) blocks any net increase regardless of intent.

package/dist/templates/claude/rules/95-closer-mode.md

@@ -0,0 +1,45 @@
+---
+title: 'CLOSER Mode (A11)'
+doc_version: '1.0.0'
+status: active
+last_review: '2026-07-06'
+owner: ''
+canonical_id: ''
+tags: ['audience/agent', 'audience/dev', 'kind/internal']
+related: []
+---
+
+# CLOSER Mode (A11)
+
+Empirical failure mode across multiple AI-driven repos (2026-07): agents burn hours
+_discovering_ work (spawning tech-debt issues, refactoring adjacent code) instead of
+_closing_ it — discovery is cheap and visible, the residual 10% (merge, red gate,
+conflict) is hard. This rule fixes the mode, not the hope.
+
+**Trigger:** the task enters its closing phase (post-implementation, pre-merge —
+`arbiter task advance --to close`), or a human invokes it on stuck work.
+
+## The 7 rules
+
+1. **Single named target.** No switching to a different file/bug/issue mid-close.
+2. **No discovery.** Opening new issues, or refactoring beyond the minimal diff, is
+   FORBIDDEN. Findings go on a PARKING list — one line, no action. This includes
+   deleting a colleague's untracked file to make a format/lint check pass — report the
+   obstruction instead of removing the evidence.
+3. **Discovery is the failure mode.** Closing is the only success metric while this
+   rule is active.
+4. **Two strikes.** The same error surviving 2 fix attempts requires a 5-line
+   root-cause writeup before a 3rd attempt, or the item is declared BLOCKED and the
+   agent moves to the next one.
+5. **Pre-existing failures are the blocker.** A red gate or failing check on the branch
+   is this task's responsibility, not an excuse to skip it.
+6. **Done = merged + evidence.** A completion claim is never made from a green local
+   run alone — it requires the PR merged (or gate green with a recorded evidence
+   artifact) on the current tree.
+7. **Never end on a promise.** Foreground-wait on PR/gate checks (e.g.
+   `gh pr checks <n> --watch`) — a background "monitor" cannot actually wake a stalled
+   agent. End the turn on the report, not on "I'll check back."
+
+**PARKING list convention:** append findings to `.arbiter/findings/<task-id>.jsonl`
+(one line per finding, no code changes) rather than opening an issue or fixing them
+inline — see `arbiter note`.

package/dist/templates/claude/settings.json.ejs

@@ -0,0 +1,165 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/hooks.mjs PreToolUse:Bash",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/hooks.mjs 'PreToolUse:Edit|Write'",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Task|Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/hooks.mjs 'PreToolUse:Task|Agent'",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/hooks.mjs PostToolUse:Bash",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/hooks.mjs 'PostToolUse:Edit|Write'",
+            "timeout": 90
+          }
+        ]
+      }<% if (governanceLevel !== 'L1') { %>,
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/hooks.mjs PostToolUse:ExitPlanMode",
+            "timeout": 3
+          }
+        ]
+      }<% } %>
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/hooks.mjs PostToolUseFailure:Bash",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/hooks.mjs PreCompact",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/hooks.mjs SubagentStop",
+            "timeout": 5
+          }
+        ]
+      }
+    ]<% if (governanceLevel !== 'L1') { %>,
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/hooks.mjs UserPromptSubmit",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/hooks.mjs Stop",
+            "timeout": 5
+          }
+        ]
+      }
+    ]<% } %>
+  },
+  "permissions": {
+    "allow": [
+      "Bash(git *)",
+      "Bash(./scripts/*)"<% if (buildTool === 'npm') { %>,
+      "Bash(npm run *)",
+      "Bash(npx *)",
+      "Bash(node *)"<% } %><% if (buildTool === 'cargo') { %>,
+      "Bash(cargo *)"<% } %><% if (buildTool === 'gradle') { %>,
+      "Bash(./gradlew *)",
+      "Bash(gradle *)"<% } %><% if (buildTool === 'maven') { %>,
+      "Bash(mvn *)"<% } %><% if (buildTool === 'go') { %>,
+      "Bash(go *)",
+      "Bash(golangci-lint *)"<% } %><% if (buildTool === 'pip') { %>,
+      "Bash(python *)",
+      "Bash(pip *)",
+      "Bash(pytest *)",
+      "Bash(ruff *)",
+      "Bash(uv *)"<% } %>,
+      "Bash(gh *)",<% if (buildTool === 'bun') { %>
+      "Bash(bun run arbiter *)",<% } %>
+      "Bash(arbiter *)"
+    ],
+    "deny": [
+      "Bash(rm -rf /*)",
+      "Bash(sudo:*)",
+      "Bash(git push --force)",
+      "Bash(*ARBITER_GATE_BYPASS*)",
+      "Bash(*ARBITER_PLAN_BYPASS*)",
+      "Bash(*ARBITER_SKIP_PLAN_REVIEW*)",
+      "Bash(*ARBITER_SKIP_TDD*)",
+      "Bash(*ARBITER_SKIP_GATE_MARKER*)",
+      "Bash(*ARBITER_SSOT_BYPASS*)",
+      "Bash(*ARBITER_PREPUSH_BYPASS*)",
+      "Bash(*ARBITER_PREPUSH_SKIP*)",
+      "Bash(*ARBITER_NO_EVIDENCE*)",
+      "Bash(*ARBITER_SKIP_DOCS*)",
+      "Edit(.arbiter/evidence/**)",
+      "Edit(.arbiter/gate-pass.json)",
+      "Edit(.arbiter/status.json)"
+    ]
+  }
+}

package/dist/templates/claude/skills/architect-review/SKILL.md.ejs

@@ -0,0 +1,82 @@
+---
+name: architect-review
+description: Use when introducing new modules, adding external dependencies, or making structural changes that cross module boundaries. On-demand architecture review.
+title: "Architect Review"
+doc_version: "1.0.0"
+status: active
+last_review: "2026-05-20"
+owner: ""
+canonical_id: ""
+tags: ['audience/agent', 'audience/dev', 'kind/internal']
+related: []
+---
+
+# Architect Review
+
+## Use When
+
+- New module / component creation
+- External dependency added
+- Cross-module communication change<% if (language === 'java') { %>
+- New package under the main source root
+- New entity, repository, or Flyway migration
+- New port interface or adapter type<% } %><% if (language === 'typescript') { %>
+- New top-level directory under `src/`
+- New shared utility or cross-cutting concern
+- Import boundary violation (importing from a sibling module's internals)<% } %>
+
+## Skip When
+
+- Bug fixes within existing patterns
+- Test-only changes
+- Documentation-only changes
+- UI/style-only changes with no domain impact
+
+When skipping, output:
+```
+[architect-review — SKIPPED]
+Skip criterion applied: <criterion>
+```
+
+## Review Checklist
+
+### Structure<% if (language === 'java') { %>
+- Does the new code follow the existing package structure?
+- Are new classes in the correct layer (controller / service / repository / domain)?
+- Does it avoid cross-layer imports (e.g., domain importing from infrastructure)?<% } %><% if (language === 'typescript') { %>
+- Does the new code follow the existing directory structure?
+- Does it avoid importing from a module's internal files directly?
+- Is the module boundary well-defined (clear public API)?<% } %>
+- Is the change backwards-compatible?
+- Does it introduce any circular dependencies?
+
+### Dependencies
+- Is the new dependency necessary?
+- Is it actively maintained?
+- Does it overlap with an existing dependency?
+
+### Testability
+- Can the new module be tested in isolation?
+- Does it require a running external system to test?
+
+### Observability
+- Does it log at appropriate levels?
+- Are errors surfaced with enough context?
+
+## Output Format
+
+```markdown
+## Architect Review
+
+**Change:** <brief description>
+**Classification:** Breaking / Non-breaking / Additive
+
+**Structure:** Strong / Adequate / Needs Attention
+**Dependencies:** Strong / Adequate / Needs Attention
+**Testability:** Strong / Adequate / Needs Attention
+
+**Concerns:**
+- <concern 1>
+
+**Recommendation:** Proceed / Proceed with conditions / Redesign
+```

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

@@ -0,0 +1,86 @@
+---
+name: brainstorming
+description: Structured brainstorming skill — explore solution space, produce design doc and GH issue, then STOP. No auto-implementation.
+argument-hint: '[topic or problem description]'
+title: 'Brainstorming Skill'
+doc_version: '1.0.0'
+status: active
+last_review: '2026-05-20'
+owner: ''
+canonical_id: ''
+tags: ['audience/agent', 'audience/dev', 'kind/internal']
+related: []
+---
+
+# Brainstorming Skill
+
+Activate when the user asks to brainstorm, explore options, think through a design, or gather ideas before implementation.
+
+## Entry
+
+When this skill is invoked:
+
+1. Write `.arbiter/brainstorm-active` to signal an active brainstorm session:
+   ```bash
+   mkdir -p .arbiter && touch .arbiter/brainstorm-active
+   ```
+2. Proceed to the brainstorming process below.
+
+## Process
+
+### Step 1 — Frame the problem
+
+Restate the problem in one sentence. Identify constraints, non-goals, and success criteria.
+
+### Step 2 — Generate options (minimum 3)
+
+For each option:
+
+- **Name**: a short label
+- **Approach**: 2–4 sentences
+- **Tradeoffs**: pros and cons relative to the others
+- **Fit**: how well it satisfies the constraints
+
+### Step 3 — Recommend
+
+State your recommended option and the primary reason. Note any conditions that would make a different option preferable.
+
+### Step 4 — Design doc
+
+Write a short design document covering:
+
+- Problem statement
+- Chosen approach
+- Key decisions and rejected alternatives
+- Open questions
+
+Save to `docs/design/<topic-slug>.md`.
+
+### Step 5 — Create GitHub issue
+
+Create a GH issue capturing the design decision:
+
+```bash
+gh issue create --title "design: <topic-slug>" --body "$(cat docs/design/<topic-slug>.md)"
+```
+
+## Terminal State (MANDATORY)
+
+**STOP after Step 5.** Do NOT:
+
+- Begin implementation
+- Edit source files
+- Create branches or commits
+- Run `/task`
+
+The brainstorm session ends when the design doc exists and the issue is created. Implementation begins only after the user explicitly clears the marker:
+
+```bash
+rm .arbiter/brainstorm-active
+```
+
+Until the marker is cleared, the `post-brainstorm-stop` hook blocks `/task` commands with an error citing this file path.
+
+## Exit
+
+After the user clears the marker (or it auto-expires after 24h), the session is ready for `/task #<issue-number>` to begin implementation.

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

@@ -0,0 +1,39 @@
+---
+name: clean-code
+description: Gate-map for code quality — which gate mechanically enforces each limit (jscpd/knip/madge/complexity/ratchet). Use when reviewing code quality or before adding code that might duplicate or over-complicate.
+title: "Clean Code"
+doc_version: "1.0.0"
+status: active
+last_review: "2026-05-20"
+owner: ""
+canonical_id: ""
+tags: ['audience/agent', 'audience/dev', 'kind/internal']
+related: []
+---
+
+# Clean Code
+
+This skill is a **gate-map, not a lecture.** Every limit below is mechanically enforced — the gate is the source of truth. When in doubt, run the gate; don't argue the principle.
+
+## Limits → enforcing gate
+
+| Concern | Limit | Enforced by |
+| --- | --- | --- |
+| **DRY / duplication** | clones below threshold; no copy-paste | `jscpd` (CANON-22) + debt ratchet — no net increase (Lehman entropy) |
+| **Complexity (KISS)** | cyclomatic ≤ 10 per function | `eslint` complexity rule + debt ratchet |
+| **No dead code (YAGNI)** | no unused files/exports | `knip` |
+| **No cycles** | no circular imports | `madge --circular` |
+| **No bloat** | file / LOC ceilings | bloat ratchet + debt ratchet |
+
+## When a gate fires
+
+Fix the **root cause** — extract the shared helper, simplify the function, delete the dead branch — or run `arbiter task record-tech-debt` with a rationale. A symptom patch over a flagged smell is a stop condition (see `90-exec-protocol.md` → Root-Cause Discipline). Juergens'09: an *inconsistent* clone (duplicated, then edited in one copy only) is a latent bug — dedup before it diverges.
+
+## Naming & extraction (review heuristic — not gated)
+
+- Names reveal intent: verb+noun functions (`getUserById`); `is`/`has`/`can` booleans; no cryptic abbreviations.
+- Repeated block → **extract function**. Long `if/else` on a type → polymorphism. One-liner wrapper that adds no clarity → **inline**. Complex expression → **extract variable**.<% if (language === 'java') { %>
+- **Java:** `Optional` over null returns; `final` for invariant fields; no raw generics; records for data carriers.<% } %><% if (language === 'typescript') { %>
+- **TypeScript:** no `any` (use `unknown` and narrow — enforced by the `check-no-any` hook, INV-04); `const` over `let`; discriminated unions over nullable fields.<% } %><% if (language === 'go') { %>
+- **Go:** errors are values — handle explicitly; interfaces defined consumer-side; short names for short scopes.<% } %><% if (language === 'python') { %>
+- **Python:** PEP 8 names; type hints on signatures; comprehensions over manual loops; dataclasses for data carriers.<% } %>