@getarbiter/cli 0.5.0

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

@@ -0,0 +1,46 @@
+---
+description: Walk one use case end to end as the user would live it — execute every read-only/dry-run step, compare doc promise against observed behaviour, and record owned findings (skill:tabletop)
+title: '/tabletop'
+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
+
+`/tabletop <scenario>` runs a **tabletop exercise**: it loads the **`tabletop`** skill and
+walks one concrete journey — `greenfield-init-ts`, `ship-one-xs-issue`, or a free-text use
+case — in the persona's voice, executing what is safely executable and recording every point
+where the documentation, the CLI, a hook, a gate or CI disagree.
+
+It is **evidence only**: it never modifies the repository. Its single output is
+`.arbiter/evidence/tabletop/<slug>-<date>.md`.
+
+## Steps
+
+1. Pick the scenario from `docs/internal/METHOD/TABLETOP-SCENARIOS.md` (or slugify the
+   free-text use case) and state its persona, starting state, goal, docs and exit criterion.
+2. Pin the tree with `git rev-parse HEAD`.
+3. Walk each step in character. Execute read-only or `--dry-run` probes, quote the doc
+   promise with `path:line`, and record observed vs promised.
+4. Write the evidence file with its frontmatter and findings table, then verify it:
+
+```bash
+node scripts/check-tabletop-evidence.mjs
+```
+
+5. File or fix every `blocker` and `major` — an unowned one fails the gate — and give each
+   behaviour finding the test or gate that would have caught it.
+
+## Allowed Tools
+
+- `Bash` for read-only and `--dry-run` probes only
+- `Read` / `Grep` for the docs and code paths the user would follow
+- `Write` for `.arbiter/evidence/tabletop/<slug>-<date>.md` — and nothing else
+
+> See the **`tabletop`** skill for the severity ladder, the findings-table columns and the
+> hard rules.

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

@@ -0,0 +1,87 @@
+---
+description: Low-level task engine/CLI reference — use /ship for full orchestration
+argument-hint: '<subcommand> [options]'
+title: '/task'
+doc_version: '2.0.0'
+status: active
+last_review: '2026-06-05'
+owner: ''
+canonical_id: ''
+tags: ['audience/agent', 'audience/dev', 'kind/internal']
+related: []
+---
+<% const _backend = (typeof decompositionBackend !== 'undefined' ? decompositionBackend : null) ?? (useGitHub ? 'github' : 'markdown'); %>
+<% const _safetyNet = { XS: { planDepth: 'minimal', reviewAgentCount: 1 }, S: { planDepth: 'brief', reviewAgentCount: 1 }, Standard: { planDepth: 'full', reviewAgentCount: 2 } }; %>
+<% const _tiers = (typeof taskTiers !== 'undefined' && taskTiers) ? taskTiers : _safetyNet; %>
+<% const _collaborationMode = (typeof collaborationMode !== 'undefined' && collaborationMode) ? collaborationMode : 'peer-review'; %>
+<% const _mergeMode = (typeof mergeMode !== 'undefined' && mergeMode) ? mergeMode : 'pr-ff'; %>
+
+# /task
+
+> **Orchestration → use [`/ship`](ship.md)**. `/task` is the low-level engine/CLI behind `/ship`.
+> Use the subcommands below for recovery, manual phase control, or one-off engine calls only.
+
+Read `AGENTS.md` before using — invariants govern every phase transition.
+
+---
+
+## Subcommand reference
+
+| Subcommand | Purpose |
+|---|---|
+| `arbiter task init --id <id> --plan <path> --tier <tier>` | Seed task state (id, plan path, tier) |
+| `arbiter task advance --to <phase>` | Advance (or recover) to the target phase |
+| `arbiter task resume` | Restore context from the last cursor (`arbiter mark`) |
+| `arbiter task recover` | Repair corrupted or stale task state |
+| `arbiter task record-red --test-path <path>` | Record TDD red evidence (failing test file) |
+| `arbiter task record-tech-debt --description <d>` | File a tech-debt issue and record it |
+| `arbiter task get` | Print current task state as JSON |
+
+---
+
+## State machine
+
+Phase order: `preflight → plan → red-team-review → red → green → refactor → verification → complete`
+
+Lateral re-entry: `red-team-rework → red-team-review` (for CRITICAL red-team findings).
+
+---
+
+## Manual recovery
+
+If mid-phase or stuck, advance directly:
+
+```bash
+arbiter task advance --to <phase>
+# Examples:
+# arbiter task advance --to red          # resume from plan approval
+# arbiter task advance --to refactor     # resume after implementation
+# arbiter task advance --to verification # resume after code review
+```
+
+Do NOT use the ordered sequence to re-run all phases — that is what `/ship --advance` does.
+
+---
+
+## Tech-debt filing
+
+When you discover a pre-existing violation in code you are **not** changing (ADR violation in untouched
+code, missing enforcement, fragile abstraction requiring out-of-scope rework), file a tech-debt issue:
+
+```bash
+arbiter task record-tech-debt \
+  --description "brief finding description" \
+  --triggered-by "#NNN"   # defaults to active task from .claude/.task/status.json
+```
+
+Creates a GitHub issue labeled `tech-debt` and appends the issue number to
+`.arbiter/evidence/<task-id>/tech-debt.json`. Failure is soft (exit 0); reason is emitted to stderr.
+
+---
+
+## Gate commands
+
+```bash
+node scripts/check-all.mjs L1   # fast: lint + format + unit tests
+node scripts/check-all.mjs L2   # full: L1 + coverage + integration
+```

package/dist/templates/claude/commands/wt-close.md.ejs

@@ -0,0 +1,58 @@
+# /wt-close <task-id>
+
+Close a git worktree and optionally harvest files back to the main repo.
+
+## Lifecycle
+
+```
+wt-open #NNN [slug]          → creates worktree, writes log entry
+  work in worktree           → edit, commit, push
+wt-close #NNN [--harvest]    → reads log to find worktree path, removes it
+```
+
+`wt-close` locates the worktree by reading `.arbiter/worktree-open.log.json` written by `wt-open`. When multiple worktrees exist for the same task with different slugs, it picks the first one whose path still exists on disk.
+
+## Steps
+
+1. Parse `$ARGUMENTS` for task ID and flags.
+   - Task ID format: `#NNN` or `NNN`.
+   - Flags: `--harvest`, `--harvest-all`, `--force`, `--keep-branch`, `--no-fetch`.
+
+2. If `--harvest` or `--harvest-all` is specified, run:
+
+   ```bash
+   arbiter wt close <TASK_ID> --harvest-all
+   ```
+
+   Always use `--harvest-all` in non-interactive mode because it auto-confirms all files. `--harvest` is the interactive variant for human terminal use.
+
+3. Otherwise, run:
+
+   ```bash
+   arbiter wt close <TASK_ID>
+   ```
+
+4. Parse output:
+   - Closed path: line starting with `Worktree closed:`.
+   - Branch deletion: line starting with `Branch <name> deleted.`.
+
+5. Print a summary with harvested files, skipped files, closed path, and branch deletion status when present.
+
+## Error Handling
+
+- **"No open worktree found for task"**: Run `arbiter wt list` to see existing worktrees.
+- **"Worktree has uncommitted changes"**: Commit or stash changes, use `--harvest-all`, or use `--force` only when losing changes is acceptable.
+- **"Branch has not been merged"**: Merge the PR first, use `--harvest-all` to copy files back, or use `--force` only when safe.
+- **"Close hook failed"**: Fix the hook or use `--force`; forced failures still emit a warning.
+- **"Must run from the main repository"**: `cd` back to the main repo first.
+
+## Allowed Tools
+
+- `Bash` for running `arbiter wt close`.
+
+## Notes
+
+- `--harvest-all` skips the merge check and copies additions/modifications back to the main repo.
+- Harvested files that conflict with uncommitted changes in the main repo are skipped, not overwritten.
+- If multiple worktrees are open for the same task, `wt-close` picks the first live log entry.
+- The worktree directory is removed after close; only the branch may be preserved with `--keep-branch`.

package/dist/templates/claude/commands/wt-list.md.ejs

@@ -0,0 +1,48 @@
+# /wt-list
+
+List active git worktrees with branch names, paths, and status.
+
+## What This Does
+
+Show all active worktrees managed by the worktree system. Delegates to `git worktree list`.
+
+**Example output:**
+```
+/home/user/repos/<%= projectName %>                                 a1b2c3d [main]
+/home/user/repos/<%= projectName %>.worktrees/#123-feat       e4f5g6h [task/#123-feat]
+/home/user/repos/<%= projectName %>.worktrees/#456-fix        i7j8k9l [task/#456-fix]
+```
+
+## Steps
+
+1. Run `git worktree list` to show all worktrees.
+
+2. For each worktree, check:
+   - Current branch name
+   - Whether branch has a remote tracking branch (`git branch -vv`)
+   - Whether remote branch is `[gone]` (PR merged, remote deleted)
+   - Whether worktree has uncommitted changes (`git status --porcelain` in that worktree)
+
+3. Print a table: Path, Branch, Task ID, Status.
+
+4. Flag any anomalies:
+   - `[gone]` remote branch → suggest `/wt-close` to clean up
+   - Uncommitted changes → warn about lost work risk
+   - Detached HEAD → note if intentional
+   - No upstream → never pushed; note if task is old
+
+## Allowed Tools
+
+- `Bash` for `git worktree list`, `git branch -vv`, `git status`
+
+## Related Commands
+
+- **Prune stale metadata:** `/wt-prune` (remove metadata for deleted worktrees)
+- **Close finished worktree:** `/wt-close #NNN` (safe cleanup)
+- **Open new worktree:** `/wt-open #NNN [slug]` (create isolated worktree)
+
+## Troubleshooting
+
+- **Stale worktree (dir deleted from disk):** use `/wt-prune` to clean metadata
+- **Locked worktree:** `git worktree remove --force <path>`
+- **`[gone]` branches in `git branch -vv`:** remote deleted post-merge; run `/wt-close #NNN`

package/dist/templates/claude/commands/wt-open.md.ejs

@@ -0,0 +1,61 @@
+# /wt-open <task-id> [slug]
+
+Open a git worktree for parallel task development.
+
+## Lifecycle
+
+```
+wt-open #NNN [slug]          → creates worktree, writes log entry
+  work in worktree           → edit, commit, push
+wt-close #NNN [--harvest]    → reads log to find worktree path, removes it
+```
+
+`wt-open` writes an entry to `.arbiter/worktree-open.log.json`. `wt-close` reads that log to locate the worktree — no manual path tracking needed.
+
+## Steps
+
+1. Parse `$ARGUMENTS` for task ID and optional slug.
+   - Format: `#NNN` or `NNN` for task ID, followed by optional slug.
+   - Example: `/wt-open #99 smoke-test` → task ID `#99`, slug `smoke-test`.
+   - Multiple worktrees per task are allowed with different slugs.
+
+2. Run the arbiter worktree open command:
+
+   ```bash
+   arbiter wt open <TASK_ID> [SLUG]
+   ```
+
+   Add `--base <branch>` if the user specified a base branch other than `main`.
+
+3. Parse the output:
+   - Worktree path: line starting with `Worktree ready:`.
+   - Branch name: line starting with `Branch:`.
+   - Base ref: line starting with `Base:`.
+   - Link status: line starting with `Links:`.
+
+4. Switch the session to the worktree:
+
+   ```bash
+   cd <worktree-path>
+   ```
+
+5. Print a summary with worktree path, branch, base ref, and link status.
+
+## Error Handling
+
+- **"Working tree has uncommitted changes"**: Ask the user to commit or stash changes before retrying.
+- **"Worktree already exists"**: Run `arbiter wt list`, close the existing worktree with `/wt-close`, or use a different slug.
+- **"Base branch does not exist"**: Ask the user to specify a valid base branch with `--base`.
+- **"Must run from the main repository"**: `cd` back to the main repo first.
+- **Links show `N missing`**: If `node_modules` is missing, run the package install command inside the worktree.
+
+## Allowed Tools
+
+- `Bash` for running `arbiter wt open` and `cd`.
+- `Read` for reading AGENTS.md in the worktree if needed.
+
+## Notes
+
+- The worktree is created as a sibling of the main repo, not inside it.
+- Config files like `.claude/settings.local.json` are symlinked from the main repo using absolute paths.
+- The open log at `.arbiter/worktree-open.log.json` is appended on every open; `wt-close` uses it to locate the worktree.

package/dist/templates/claude/commands/wt-prune.md.ejs

@@ -0,0 +1,38 @@
+# /wt-prune
+
+Prune stale git worktree metadata for worktrees whose directories no longer exist on disk.
+
+## What This Does
+
+Clean up worktree metadata from `.git/worktrees/` when a worktree directory has been manually deleted.
+
+**Important scope distinction:**
+- `/wt-prune` (this command) → only removes metadata for **missing directories** on disk
+- Does NOT remove worktrees whose directory still exists, even if the branch is merged
+- Worktrees done but still on disk → use `/wt-close #NNN`
+
+**When to use:**
+- After manually deleting a worktree directory
+- When `git worktree list` shows worktrees with paths that no longer exist
+- Regular cleanup to keep worktree metadata in sync
+
+## Steps
+
+1. Run `git worktree prune` to clean `.git/worktrees/` metadata for deleted directories.
+
+2. Print a summary of what was pruned (or confirm nothing to clean).
+
+## Allowed Tools
+
+- `Bash` for `git worktree prune`
+
+## Related Commands
+
+- **List all worktrees with status:** `/wt-list` (show path, branch, remote status)
+- **Close finished worktree safely:** `/wt-close #NNN` (remove directory + metadata)
+
+## Troubleshooting
+
+- **"No stale worktrees to prune"** → nothing to clean, good state
+- **Worktree still shows after prune** → directory still on disk; use `/wt-close #NNN`
+- **Cannot prune locked worktree** → unlock first with `git worktree unlock <path>`

package/dist/templates/claude/hooks/check-circular-deps.mjs.ejs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// Arbiter hook: detect circular dependencies after TypeScript/JS edits
+// Hook type: PostToolUse (Edit|Write) — TypeScript projects only
+// Runs madge --circular on src/ for project-wide cycle detection. Exits 2 if circular deps found.
+// Soft-skips when madge is not installed in node_modules.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { resolveToolInputPath, debounceHook } from "./lib.mjs";
+
+const file = resolveToolInputPath();
+if (!file) process.exit(0);
+
+const isJs = file.endsWith(".ts") || file.endsWith(".tsx") || file.endsWith(".js") || file.endsWith(".jsx");
+if (!isJs) process.exit(0);
+
+const repoRoot = process.cwd();
+const madgeBin = join(repoRoot, "node_modules", ".bin", "madge");
+if (!existsSync(madgeBin)) {
+  process.stdout.write(`[arbiter] circular-deps: madge not installed — skip (run: npm install -D madge)\n`);
+  process.exit(0);
+}
+
+// madge rebuilds the WHOLE src/ import graph; it cannot be scoped to one file.
+// Debounce so a burst of edits triggers at most one run instead of O(repo)/edit
+// (#1515). The L1 gate runs madge --circular authoritatively before commit/push,
+// so a skipped per-edit run never lets a cycle reach a commit.
+if (debounceHook("madge-circular-deps")) process.exit(0);
+
+const srcDir = existsSync(join(repoRoot, "src")) ? "src" : ".";
+const result = spawnSync(madgeBin, ["--circular", "--extensions", "ts,tsx,js,jsx", srcDir], {
+  encoding: "utf-8",
+  cwd: repoRoot,
+  shell: false,
+});
+
+if (result.error) {
+  process.stderr.write(`[arbiter] circular-deps: failed to spawn madge: ${result.error.message}\n`);
+  process.exit(0);
+}
+
+if (result.signal) {
+  process.stderr.write(`[arbiter] circular-deps: madge killed by signal ${result.signal}\n`);
+  process.exit(0);
+}
+
+const output = (result.stdout ?? "").trim();
+const circularLines = output.split("\n").filter((l) => l.includes(" > "));
+
+if (result.status !== 0 || circularLines.length > 0) {
+  process.stderr.write(`[arbiter] INV-01: Circular dependency detected (triggered by ${file.replace(repoRoot + "/", "")}):\n`);
+  circularLines.slice(0, 5).forEach((l) => process.stderr.write(`  ${l}\n`));
+  if (!circularLines.length && output) process.stderr.write(`  ${output.slice(0, 400)}\n`);
+  process.stderr.write(`[arbiter] Run \`arbiter explain INV-01\` for details.\n`);
+  process.exit(2);
+}

package/dist/templates/claude/hooks/check-no-orphan-todo.mjs.ejs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// Arbiter hook: block orphan TODO comments (INV-21)
+// Fires on: PostToolUse → Edit|Write
+import { readFileSync, existsSync } from 'node:fs';
+import { extname } from 'node:path';
+import { addedLinesVsHEAD, resolveToolInputPath } from './lib.mjs';
+
+// Match comment-context TODO but not TODO(#NNN).
+const ORPHAN_TODO = /(?:\/\/|\/\*|\*)\s*TODO(?!\s*\(#\d+\))/;
+const EXTENSIONS = new Set(<%- JSON.stringify(sourceExtensions) %>);
+
+const file = resolveToolInputPath();
+if (!file || !existsSync(file)) process.exit(0);
+if (!EXTENSIONS.has(extname(file).toLowerCase())) process.exit(0);
+
+let content;
+try {
+  content = readFileSync(file, 'utf-8');
+} catch {
+  process.stderr.write('[arbiter] ERROR: cannot read applicable source file\n');
+  process.exit(2);
+}
+
+// #2539: scan only the lines THIS edit added, not the whole file — a
+// pre-existing orphan-TODO-shaped line on an untouched line (this checker's
+// own doc comment illustrating the pattern, or its own regex definition) must
+// not block an unrelated edit elsewhere in the same file. Untracked files and
+// git errors fail OPEN to the whole-file scan (never skip).
+const { tracked, added } = addedLinesVsHEAD(file);
+const scanLines = tracked
+  ? added.map(({ line, content: text }) => [line - 1, text])
+  : content.split('\n').map((text, index) => [index, text]);
+
+const offending = scanLines
+  .filter(([, line]) => ORPHAN_TODO.test(line))
+  .map(([i, line]) => `${i + 1}: ${line.trim()}`);
+
+if (offending.length > 0) {
+  process.stderr.write(
+    `[arbiter] INV-21: Orphan TODO found in ${file} (must reference task ID like TODO(#123)):\n`,
+  );
+  offending.slice(0, 3).forEach((line) => process.stderr.write(`  ${line}\n`));
+  process.stderr.write(`[arbiter] Run \`arbiter explain INV-21\` for details.\n`);
+  process.exit(2);
+}

package/dist/templates/claude/hooks/check-no-pii.mjs.ejs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// Arbiter hook: block PII patterns in edited files (INV-12)
+// Fires on: PostToolUse → Edit|Write
+import { readFileSync, existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { addedLinesVsHEAD, findInlineSuppression, resolveToolInputPath } from "./lib.mjs";
+
+const file = resolveToolInputPath();
+if (!file || !existsSync(file)) process.exit(0);
+
+// Load suppressions/pii-allowlist.json: the hook pointed users at this file for
+// fixtures but never actually consulted it. Self-contained (no cross-file import,
+// generated projects must not depend on scripts/pii-scan.mjs) — mirrors that
+// script's own specificity-floor semantics (#1669): a suppression must be an exact
+// (file + line) pair or an exact match string, never a bare/substring entry.
+const ROOT = process.cwd();
+const ALLOWLIST_PATH = join(ROOT, "suppressions", "pii-allowlist.json");
+let allowlist = [];
+if (existsSync(ALLOWLIST_PATH)) {
+  try {
+    const parsed = JSON.parse(readFileSync(ALLOWLIST_PATH, "utf-8"));
+    if (Array.isArray(parsed)) allowlist = parsed;
+  } catch {
+    // Malformed allowlist: fail closed (no entries allowed), do not weaken enforcement.
+  }
+}
+
+function isAllowlisted(filePath, lineNum, matchStr) {
+  const rel = relative(ROOT, filePath).split("\\").join("/");
+  return allowlist.some((entry) => {
+    const hasFile = typeof entry.file === "string" && entry.file.length > 0;
+    const hasLine = typeof entry.line === "number";
+    const hasPattern = typeof entry.pattern === "string" && entry.pattern.length > 0;
+    if (!(hasPattern || (hasFile && hasLine))) return false;
+    if (hasFile) {
+      const ef = entry.file.split("\\").join("/");
+      const prefix = ef.endsWith("/") ? ef : ef + "/";
+      if (rel !== ef && !rel.startsWith(prefix)) return false;
+    }
+    if (hasLine && entry.line !== lineNum) return false;
+    if (hasPattern && matchStr !== entry.pattern) return false;
+    return true;
+  });
+}
+
+const SKIP_EXTENSIONS = [
+  ".lock",
+  ".lockb",
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".svg",
+  ".wasm",
+  ".bin",
+  ".toml",
+  ".json",
+  ".md",
+];
+if (SKIP_EXTENSIONS.some((ext) => file.endsWith(ext))) process.exit(0);
+
+let content;
+try {
+  content = readFileSync(file, "utf-8");
+} catch {
+  process.exit(0);
+}
+
+const PII_PATTERNS = [
+  {
+    label: "email address",
+    re: /\b[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\b/,
+  },
+  { label: "phone (E.164)", re: /\+\d{7,15}\b/ },
+  {
+    label: "credit card (Luhn-like)",
+    re: /\b(?:4\d{12}(?:\d{3})?|5[1-5]\d{14}|3[47]\d{13}|6(?:011|5\d{2})\d{12})\b/,
+  },
+];
+
+// #2539: scan only the lines THIS edit added, not the whole file — a
+// pre-existing fixture value on an untouched line (a fake email planted for a
+// test, a fixture credit-card number) must not block an unrelated edit
+// elsewhere in the same file. Untracked files and git errors fail OPEN to the
+// whole-file scan (never skip).
+const { tracked, added } = addedLinesVsHEAD(file);
+const scanLines = tracked
+  ? added.map(({ line, content: text }) => [line - 1, text])
+  : content.split("\n").map((text, index) => [index, text]);
+
+const findings = [];
+for (const { label, re } of PII_PATTERNS) {
+  for (const [i, line] of scanLines) {
+    const m = line.match(re);
+    if (!m) continue;
+    if (findInlineSuppression(content, i, "INV-12")) continue;
+    if (isAllowlisted(file, i + 1, m[0])) continue;
+    findings.push(
+      `  line ${i + 1} [${label}]: ${line.trim().slice(0, 80)}`,
+    );
+  }
+}
+
+if (findings.length > 0) {
+  process.stderr.write(`[arbiter] INV-12: PII pattern detected in ${file}:\n`);
+  findings.slice(0, 5).forEach((f) => process.stderr.write(`${f}\n`));
+  process.stderr.write(
+    `If this is a test fixture / known-safe value, add an inline\n` +
+      // Built via interpolation, not a literal "// arbiter-suppress(" substring:
+      // this help text renders identically but does not trip THIS generated
+      // project's own check-inline-suppressions.mjs, which scans raw source text
+      // for that exact pattern regardless of string-literal context (#1772).
+      `  ${"//"} arbiter-suppress(INV-12, until=YYYY-MM-DD, reason="known-safe test value", owner=you)\n` +
+      `directive on the line above the match, or add an entry to\n` +
+      `suppressions/pii-allowlist.json ({ "file", "line" } or { "pattern" }).\n`,
+  );
+  process.stderr.write(`[arbiter] Run \`arbiter explain INV-12\` for details.\n`);
+  // Exit 2 feeds the violation back to the agent for a PostToolUse guard (#1631);
+  // exit 1 shows the user only and the agent never sees the leak.
+  process.exit(2);
+}

package/dist/templates/claude/hooks/check-no-placeholders.mjs.ejs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Arbiter hook: block unfinished-code patterns in edited source files
+// Fires on: PostToolUse → Edit|Write
+import { readFileSync, existsSync } from 'node:fs';
+import { extname } from 'node:path';
+import { addedLinesVsHEAD, resolveToolInputPath } from './lib.mjs';
+
+const EXTENSIONS = new Set(<%- JSON.stringify(sourceExtensions) %>);
+
+// #2528/#2539: every marker below is built by concatenation so this checker's
+// own source never contains one as a contiguous string — a literal occurrence
+// here would make this hook block edits to itself (and to its own test) even
+// with #2539's diff-scoped scan, since touching the PATTERNS array itself is
+// an ADDED line that legitimately spells the marker out in full. `marker()`
+// also drops the case-insensitive flag the word-family markers used to carry:
+// the plain word is ordinary English, only the all-caps form is a violation.
+// The emitted `label` still reads correctly, since it is the same
+// (correctly-cased) word passed in.
+const marker = (word) => ({ re: new RegExp(`\\b${word}\\b`), label: word });
+
+const PATTERNS = [
+  marker(`PLACE${'HOLDER'}`),
+  marker(`FIX${'ME'}`),
+  marker(`XX${'X'}`),
+  marker(`HA${'CK'}`),
+  marker(`WI${'P'}`),
+  marker(`CHANGE${'ME'}`),
+  marker(`REPLACE${'ME'}`),
+  { re: /\b(it|describe|test)\.skip\s*\(/, label: 'disabled-test method' },
+  { re: /\b(xit|xdescribe|xtest)\s*\(/, label: 'disabled-test alias' },
+];
+
+const file = resolveToolInputPath();
+if (!file || !existsSync(file)) process.exit(0);
+if (!EXTENSIONS.has(extname(file).toLowerCase())) process.exit(0);
+
+let content;
+try {
+  content = readFileSync(file, 'utf-8');
+} catch {
+  process.stderr.write('[arbiter] ERROR: cannot read applicable source file\n');
+  process.exit(2);
+}
+
+// #2539: scan only the lines THIS edit added, not the whole file — a
+// pre-existing marker on an untouched line (the checker's own PATTERNS array,
+// a deliberately-planted test fixture, a coincidentally-matching identifier
+// like a checker's own uppercase constant name) must not block an unrelated
+// edit to the same file. Untracked files and git errors fail OPEN to the
+// whole-file scan (never skip) — see addedLinesVsHEAD's doc comment.
+const { tracked, added } = addedLinesVsHEAD(file);
+const scanLines = tracked
+  ? added.map(({ line, content: text }) => [line - 1, text])
+  : content.split('\n').map((text, index) => [index, text]);
+
+const found = [];
+for (const [index, line] of scanLines) {
+  for (const { re, label } of PATTERNS) {
+    if (re.test(line)) {
+      found.push(`  line ${index + 1}: [${label}]  ${line.trim()}`);
+      break;
+    }
+  }
+}
+
+if (found.length > 0) {
+  process.stderr.write(`Unfinished-code patterns found in ${file}:\n`);
+  for (const message of found) process.stderr.write(`${message}\n`);
+  process.stderr.write('\nRemove unfinished or disabled-test patterns before saving.\n');
+  process.exit(2);
+}