@popovych.co/witness 0.4.0

package/dist/worktree.js

@@ -0,0 +1,73 @@
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, sep } from 'node:path';
+import { git, tryGit } from './gitio.js';
+import { ok, refuse, v } from './refusal.js';
+export function worktreesDir(root) {
+    return join(root, '.witness', 'worktrees');
+}
+export function worktreePath(root, planId) {
+    return join(worktreesDir(root), planId);
+}
+// primaryRoot resolves a worktree cwd up to the primary root and drops WHICH worktree it
+// was. That identity is the flow, so recover it here rather than re-deriving from git.
+// (Lives here, not in gitio.ts, because gitio.ts is what this module imports — the other
+// direction would close an import cycle.)
+export function worktreeFlow(cwd, root) {
+    const top = tryGit(cwd, 'rev-parse', '--show-toplevel');
+    if (!top.ok)
+        return undefined;
+    const dir = worktreesDir(root);
+    if (!top.out.startsWith(dir + sep))
+        return undefined;
+    const rest = top.out.slice(dir.length + 1);
+    // Round-tripping the last path segment back to a plan id is safe: worktreePath is a
+    // bare join with no slugification, and doc ids are /^[a-z0-9-]+$/ (dsl.ts).
+    return rest.length > 0 && !rest.includes(sep) ? rest : undefined;
+}
+export function branchName(planId) {
+    return `witness/${planId}`;
+}
+export function ensureExcluded(root) {
+    const commonDir = git(root, 'rev-parse', '--git-common-dir').trim();
+    const gitDir = isAbsolute(commonDir) ? commonDir : join(root, commonDir);
+    const infoDir = join(gitDir, 'info');
+    mkdirSync(infoDir, { recursive: true });
+    const excludePath = join(infoDir, 'exclude');
+    const current = existsSync(excludePath) ? readFileSync(excludePath, 'utf8') : '';
+    const lines = current.split('\n');
+    // screens are witnessed evidence, regenerable, never committed — ignored in every
+    // worktree so they stay out of changedFiles() and the reviewed tree-sha
+    for (const line of ['.witness/worktrees/', '.witness/screens/']) {
+        if (!lines.includes(line))
+            appendFileSync(excludePath, `${line}\n`);
+    }
+}
+export function createWorktree(root, planId, baseBranch) {
+    const path = worktreePath(root, planId);
+    const branch = branchName(planId);
+    ensureExcluded(root);
+    mkdirSync(worktreesDir(root), { recursive: true });
+    if (existsSync(path))
+        return ok({ path, branch });
+    tryGit(root, 'worktree', 'prune');
+    const branchExists = tryGit(root, 'rev-parse', '--verify', '--quiet', `refs/heads/${branch}`).ok;
+    const r = branchExists
+        ? tryGit(root, 'worktree', 'add', path, branch)
+        : tryGit(root, 'worktree', 'add', '-b', branch, path, baseBranch);
+    if (!r.ok) {
+        return refuse([v('worktree', 'worktree-create-failed', r.out.slice(0, 200), 'git worktree add to succeed')]);
+    }
+    return ok({ path, branch });
+}
+export function removeWorktree(root, planId) {
+    const path = worktreePath(root, planId);
+    if (existsSync(path))
+        tryGit(root, 'worktree', 'remove', '--force', path);
+    tryGit(root, 'worktree', 'prune');
+}
+export function listWorktrees(root) {
+    const dir = worktreesDir(root);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@popovych.co/witness",
+  "version": "0.4.0",
+  "description": "Evidence-gated spec-driven development pipeline for AI coding agents: brainstorm to PR in six stages, where specs are state, plans are motion, and no transition passes without evidence. Drives from Claude Code or Pi.",
+  "keywords": [
+    "spec-driven-development",
+    "sdd",
+    "ai-agent",
+    "agentic-workflow",
+    "claude-code",
+    "claude-code-plugin",
+    "anthropic",
+    "llm",
+    "code-review",
+    "tdd",
+    "test-driven-development",
+    "developer-tools",
+    "cli",
+    "pipeline",
+    "codegen",
+    "ai-coding-assistant",
+    "specs",
+    "agent-skills"
+  ],
+  "homepage": "https://github.com/popovych-co/witness#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/popovych-co/witness.git"
+  },
+  "bugs": {
+    "url": "https://github.com/popovych-co/witness/issues"
+  },
+  "author": "Kostiantyn Popovych",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "witness": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "prompts",
+    "calibration.yaml",
+    "calibration",
+    "plugin",
+    "LICENSES",
+    "NOTICE.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "sync-versions": "node scripts/sync-versions.mjs"
+  },
+  "dependencies": {
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "witness",
+  "description": "Spec-driven development with evidence gates: brainstorm → PR through six stages and five gates. Skills author, the pinned witness CLI writes state and witnesses evidence; gates stop where judgment is owed.",
+  "version": "0.4.0",
+  "author": {
+    "name": "Kostiantyn Popovych"
+  },
+  "homepage": "https://github.com/popovych-co/witness",
+  "repository": "https://github.com/popovych-co/witness",
+  "license": "MIT",
+  "keywords": [
+    "spec-driven-development",
+    "evidence-gated",
+    "code-review",
+    "tdd",
+    "workflow",
+    "agent-skills"
+  ]
+}

package/plugin/commands/witness.md

@@ -0,0 +1,46 @@
+---
+description: Run the witness pipeline — ask the CLI what's next, do it, loop; stop where a human is owed a decision
+argument-hint: "[--manual]"
+---
+
+# /witness — the engine
+
+The CLI decides, you act. If `$ARGUMENTS` contains `--manual`, append `--manual` to **every** `witness gate` command you run this session — caution is a per-run mood, never config.
+
+Resolve the CLI once:
+
+```bash
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.4.0}"
+```
+
+If the repo has no `witness.config.yaml`, run `$WITNESS init` first (one bootstrap commit), then proceed. If init or any verb refuses on a dirty tree, the human commits or cleans it — **never `git commit` yourself, anywhere, at any stage**: the CLI makes its own state commits, and the ship phase makes the sole code commit.
+
+## Loop
+
+Every turn is `witness next`, read, act on the first matching row, repeat:
+
+1. Run `$WITNESS next`.
+2. Read its TOON lines: `next:` (a command line), and optional `stage:`, `target:`, `note:`, `home:` (the directory this action's session belongs in), `run:` (the paste-ready handoff command), `relay:` (how a session continues in a fresh context in the same `home:`). `run:` and `relay:` are rendered by the CLI for the harness you are running on — never rewrite them, never substitute a command you remember.
+3. Act on the **first** matching row, then go to 1:
+
+| Signal | Action |
+|---|---|
+| `note:` contains `multiple ready — choose` | Show the listed spec ids, ask the human which to plan. Then use the `witness-plan` skill with the chosen id. |
+| `next:` names `witness decide` | A gate is stopped and the decision is the human's. Run `$WITNESS decide <gate> <target> --show`, render the checks and findings verbatim, render the `exits:` line the CLI emitted verbatim — never a remembered set, which is wrong at the round bound and in the reopened and stale states — and **END YOUR TURN**. Never run `--approve`, `--revise`, or `--stop` on your own judgment. |
+| `home:` present and ≠ your cwd | This stage belongs to a different session. Print the `run:` line verbatim for the human (if this session is `--manual`-armed, change the argument to `'/witness --manual'`), say that work continues in the fresh session, and **END YOUR TURN**. Never use a stage skill or run the `next:` command from the wrong `home:` — a fresh session is the execution model, and it is the only one. |
+| `stage: brainstorm` | Use the `witness-brainstorm` skill. |
+| `stage: decompose` | Use the `witness-decompose` skill with `target` (the effort slug). |
+| `stage: design` | Use the `witness-design` skill with `target` (the spec id). |
+| `stage: plan` | Use the `witness-plan` skill with `target` (the spec id). |
+| `stage: implement` | Use the `witness-implement` skill with `target` (the plan id). |
+| `stage: ship`, or `next:` names `witness ship` | Use the `witness-ship` skill with `target` (the plan id). |
+| any other `next:` line (`witness gate …`, `witness start …`, `witness check`, `witness recover …`, `witness check --drift`) | Run it verbatim via Bash (plus `--manual` on `gate` when armed). Exit 0 or 1 → loop. Exit 2 or 3 → render the refusal; if it names a mechanical remedy you can do without judgment (e.g. `witness recover --complete`), do it and loop, else stop for the human. |
+
+## Stop conditions (end your turn)
+
+- A `decide` line surfaced — the standing stops (ship always; feature scope; fix-created-spec) and every blocking finding land here by design.
+- The same `next:` line came back twice with nothing changed in between → report `no progress: <line>`, what you tried, and hand off.
+- An exit 2/3 you cannot mechanically satisfy — `needs-unmet` (show the human `witness satisfy <id> --need <text>`), `slug-reuse`, lock contention, calibration floor stops under `--manual`.
+- A skill ended its turn for a gate stop — that stop is yours too; do not restart the loop until the human decides.
+
+**Never merge a PR** — merging is the human's act on GitHub; the lazy stamp finishes the lifecycle on the next scan. **Never edit `specs/` or `plans/`** (or wherever the repo's `paths:` config relocates them) — that is what the skills' write path is for. If the dashboard warns the reviewer model is uncalibrated, surface the warning; under `--manual` treat it as a stop.

package/plugin/hooks/canon-guard.mjs

@@ -0,0 +1,105 @@
+// witness canon guard — the shared core behind every harness's write block.
+//
+// Dependency-free ON PURPOSE (Decision 13): the Claude Code hook runs from
+// ${CLAUDE_PLUGIN_ROOT}, which has no node_modules, and a Pi user's repo has no reason
+// to have @popovych.co/witness installed. An import from the CLI package would
+// resolve-fail into the fail-open path on both — a SILENTLY ABSENT guard. Adapters
+// import this file by relative path and stay thin.
+//
+// Friction, not the guarantee (the trailer audit is) — Decision 31. Anything
+// unparseable falls open: a broken guard must never brick a session.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+
+// Claude Code and Pi vocabularies. Pi has no MultiEdit; Claude Code has no lowercase
+// forms. Listing both keeps the adapters free of translation tables.
+const WRITE_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'edit', 'write']);
+const BASH_TOOLS = new Set(['Bash', 'bash']);
+
+function configRoot(startDir) {
+  let dir = startDir;
+  for (;;) {
+    if (existsSync(join(dir, 'witness.config.yaml'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+// Canon roots from the repo's `paths:` config key (flow or block style), extracted
+// without a YAML dependency. Anything unparseable falls back to the defaults.
+function canonDirs(root) {
+  try {
+    const text = readFileSync(join(root, 'witness.config.yaml'), 'utf8');
+    const flow = text.match(/^paths:[ \t]*\{([^}]*)\}/m);
+    const section = flow ? flow[1] : (text.match(/^paths:[ \t]*\n((?:[ \t]+\S.*\n?)*)/m) || [])[1] || '';
+    const dir = (key) => {
+      const m = section.match(new RegExp(`(?:^|[\\s{,])${key}:[ \\t]*['"]?([^'"\\s,}#]+)`, 'm'));
+      return m ? m[1].replace(/\/+$/, '') : key;
+    };
+    return [dir('specs'), dir('plans'), dir('designs')];
+  } catch {
+    return ['specs', 'plans', 'designs'];
+  }
+}
+
+function isStateRel(rel, dirs) {
+  const posix = rel.split('\\').join('/');
+  return dirs.some((d) => posix === d || posix.startsWith(`${d}/`));
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+function statePathRe(dirs) {
+  return new RegExp(`(^|[\\s"'=;|&(])(\\./)?(${dirs.map(escapeRe).join('|')})/`);
+}
+
+const WRITEISH = /(>>?|\btee\b|\bsed\b[^\n]*\s-i\b|\bmv\b|\bcp\b|\brm\b|\btouch\b|\btruncate\b|\bdd\b)/;
+
+function reasonFor(what) {
+  return (
+    `witness: ${what} is CLI-written state — use the witness CLI (write / design / adopt), ` +
+    'never a direct edit. Direct edits are refused; the Witness-State trailer audit catches end-runs.'
+  );
+}
+
+/**
+ * @param {{ tool?: unknown, input?: unknown, cwd?: unknown }} call
+ * @returns {{ block: true, reason: string } | undefined}
+ */
+export function canonGuard(call) {
+  try {
+    const tool = typeof call?.tool === 'string' ? call.tool : '';
+    const args = call?.input && typeof call.input === 'object' ? call.input : {};
+    const cwd = typeof call?.cwd === 'string' && call.cwd !== '' ? call.cwd : process.cwd();
+
+    if (WRITE_TOOLS.has(tool)) {
+      // Claude Code sends file_path; pi sends path (core/tools/write.js:12).
+      const fp = typeof args.file_path === 'string' ? args.file_path : args.path;
+      if (typeof fp !== 'string' || fp === '') return undefined;
+      const abs = isAbsolute(fp) ? fp : resolve(cwd, fp);
+      const root = configRoot(dirname(abs));
+      if (!root) return undefined;
+      const rel = relative(root, abs);
+      if (rel.startsWith('..')) return undefined;
+      if (!isStateRel(rel, canonDirs(root))) return undefined;
+      return { block: true, reason: reasonFor(rel.split('\\').join('/')) };
+    }
+
+    if (BASH_TOOLS.has(tool)) {
+      const cmd = args.command;
+      if (typeof cmd !== 'string') return undefined;
+      const root = configRoot(cwd);
+      if (!root) return undefined;
+      const dirs = canonDirs(root);
+      if (statePathRe(dirs).test(cmd) && WRITEISH.test(cmd)) {
+        return { block: true, reason: reasonFor(`a ${dirs.map((d) => `${d}/`).join(' or ')} path in that command`) };
+      }
+      return undefined;
+    }
+
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}

package/plugin/hooks/guard-state.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// witness PreToolUse guard — the Claude Code adapter over canonGuard.
+// stdin JSON in, exit 2 + stderr out (stderr is fed back to the model). The logic
+// lives in canon-guard.mjs so the Pi extension shares it byte for byte. Any
+// parse/read failure exits 0: a broken hook must never brick a session.
+import { canonGuard } from './canon-guard.mjs';
+
+let raw = '';
+process.stdin.on('data', (chunk) => {
+  raw += chunk;
+});
+process.stdin.on('end', () => {
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+  let verdict;
+  try {
+    verdict = canonGuard({
+      tool: input.tool_name,
+      input: input.tool_input,
+      cwd: typeof input.cwd === 'string' && input.cwd !== '' ? input.cwd : process.cwd(),
+    });
+  } catch {
+    process.exit(0);
+  }
+  if (verdict && verdict.block) {
+    process.stderr.write(`${verdict.reason}\n`);
+    process.exit(2);
+  }
+  process.exit(0);
+});

package/plugin/hooks/hooks.json

@@ -0,0 +1,17 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/guard-state.mjs\"" }]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/guard-state.mjs\"" }]
+      }
+    ],
+    "SessionStart": [
+      { "hooks": [{ "type": "command", "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/session-dashboard.sh\"" }] }
+    ]
+  }
+}

package/plugin/hooks/session-dashboard.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+# witness SessionStart hook — inject the dashboard (stdout becomes session
+# context). Silent everywhere that isn't a witness repo; failures swallowed:
+# session start must never hang or die on this.
+[ -f witness.config.yaml ] || exit 0
+${WITNESS_BIN:-npx -y @popovych.co/witness@0.4.0} 2>/dev/null || true

package/plugin/hooks/witness-pi.ts

@@ -0,0 +1,67 @@
+// witness Pi extension — the canon guard plus the session dashboard.
+//
+// The Pi half of Decision 8: one pure canonGuard, thin per-harness adapters. The tool
+// names are pi's (`write`, `edit`, `bash` — there is no MultiEdit) and the path key is
+// `path`; canonGuard accepts both vocabularies so this file needs no translation table.
+//
+// canon-guard.mjs is imported by RELATIVE path and is a sibling in the installed
+// layout (.pi/extensions/) — see the pi descriptor's payload recipe. A package import
+// would resolve-fail in a repo with no witness install (Decision 13).
+//
+// Every failure path falls open: a broken extension must never brick a session. On Pi
+// that is NOT free. docs/extensions.md, "Error Handling": *extension errors are logged,
+// agent continues; `tool_call` errors block the tool (fail-safe)* — the inversion is
+// scoped to exactly the event the guard uses. So the try/catch below is load-bearing,
+// not garnish: without it an unparseable witness.config.yaml would refuse every write
+// in the repo, `src/` included. Do not remove it because canonGuard already catches.
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { canonGuard } from "./canon-guard.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+// The Claude Code SessionStart hook injects the dashboard as session context. Pi's
+// analogue is before_agent_start's `message`, which is stored in the session and sent
+// to the model — a real transcript entry, not a toast. Once per session, latched.
+function dashboardText(cwd: string): string {
+  const script = process.env.WITNESS_DASHBOARD ?? join(here, "session-dashboard.sh");
+  try {
+    const r = spawnSync("sh", [script], { cwd, encoding: "utf8", timeout: 60_000 });
+    return (r.stdout ?? "").trim();
+  } catch {
+    return "";
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("tool_call", async (event, ctx) => {
+    try {
+      const verdict = canonGuard({ tool: event.toolName, input: event.input, cwd: ctx.cwd });
+      if (!verdict) return undefined;
+      // Isolated: the toast is cosmetic, the verdict is not. A notify failure must
+      // never downgrade a block we already decided into an allow.
+      try {
+        if (ctx.hasUI) ctx.ui.notify("witness: canon write blocked — use the CLI", "warning");
+      } catch {
+        /* cosmetic only */
+      }
+      return { block: true, reason: verdict.reason };
+    } catch {
+      return undefined;
+    }
+  });
+
+  let injected = false;
+  pi.on("session_start", async () => {
+    injected = false;
+  });
+  pi.on("before_agent_start", async (_event, ctx) => {
+    if (injected) return undefined;
+    injected = true;
+    const text = dashboardText(ctx.cwd);
+    if (text === "") return undefined;
+    return { message: { customType: "witness-dashboard", content: text, display: true } };
+  });
+}

package/plugin/skills/witness-brainstorm/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: witness-brainstorm
+description: Stateless scope interview for a witness effort — one question at a time, each with a firm recommendation, ending in a confirmed scope recap persisted via witness recap. Use when starting a new effort or re-scoping one; normally invoked by /witness.
+---
+
+# witness-brainstorm — scope interview → confirmed recap
+
+<!-- Derived (MIT): interview style from mattpocock/skills grill-me (one
+question at a time, always with a recommendation); intent-before-design
+exploration from obra/superpowers brainstorming. Rewritten stateless for
+witness: ends in a confirmed scope recap, writes no document. See NOTICE.md. -->
+
+## Ground rules (every witness skill)
+
+Resolve the CLI once per session:
+
+```bash
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.4.0}"
+```
+
+- **Never edit `specs/**` or `plans/**`** (the canon dirs — `paths:` in witness.config.yaml may relocate them) — not with an edit tool, not with a write tool, not with Bash redirection. The CLI is the sole writer of state; you author in scratch files under `$(mktemp -d)` and hand them to the CLI. (The canon guard blocks you; the trailer audit catches what it can't.)
+- **Never invoke gate reviewers or relay verdicts.** `witness gate` runs reviewers itself and journals what they said; your summary of a verdict is not evidence.
+- **Refusal repair loop:** a `witness` verb exiting 2 prints structured violations (`field · rule · got · want`). Fix your input and retry — **3 total attempts** per artifact, then stop, show the human the violation list verbatim, and end your turn.
+- **A refused or hook-blocked command is a stop, not a step to drop.** Re-issue it on its own; if it still refuses, tell the human what was blocked and why. Never proceed by deleting the refused half of a compound command — a dropped step is silent, and silence is how a skipped check becomes a shipped defect.
+- **Re-entrancy:** derive position from CLI output (`$WITNESS next`, the dashboard, `log`, `index`) — never from conversation memory. Killed and re-run, you must converge.
+
+## What you produce
+
+No canon, only evidence: a **confirmed scope recap** persisted by `witness recap` as the birth entry of the effort journal. This skill writes no spec, no plan, no brief — decompose consumes the recap after you, including after session death.
+
+## Interview protocol
+
+**One question per turn.** Every question carries a concrete recommendation, a one-line why, and the strongest rejected alternative. Lock each answer before the next; walk in dependency order:
+
+1. **Class** — `feature | fix | chore`. Recommend from the opening ask: `fix` restores promised behavior; `chore` is motion with no state change (deps, tooling); everything else is `feature`.
+2. **Problem & outcome goals** — what observably changes, for whom. Number them `g1, g2, …`. Each goal is an outcome someone can observe — "Guests can pay by card", never "Integrate Stripe".
+3. **Non-goals** — what this effort deliberately will not do: `n1, n2, …`. Push for at least one; scope without a "no" is unbounded.
+4. **Constraints** — standing limits (compliance, performance budgets, compatibility): `c1, …`. Empty is fine.
+5. **Slice candidates** — non-binding thin vertical slices you would expect decompose to cut. Plain strings.
+
+**Short forms.** `fix`: two questions — (1) what breaks, with the observable evidence; (2) the fix boundary — what must NOT change (its non-goals). `chore`: two questions — what maintenance, which area it touches.
+
+## Confirmation
+
+Render the recap as a table (class · goals · non-goals · constraints · slices) and get an explicit yes. Adjust and re-render until confirmed. The recap is decompose's input contract — a fuzzy recap poisons every stage after it.
+
+## Persist
+
+```bash
+DIR=$(mktemp -d)
+cat > "$DIR/recap.json" <<'EOF'
+{
+  "effort": "auth-hardening",
+  "class": "feature",
+  "goals": [{ "id": "g1", "text": "Refresh tokens rotate before expiry" }],
+  "non_goals": [{ "id": "n1", "text": "No SSO provider changes" }],
+  "constraints": [],
+  "slices": ["token rotation"]
+}
+EOF
+$WITNESS recap --file "$DIR/recap.json"
+```
+
+- Effort slug: kebab-case `[a-z0-9-]+`, minted from the scope title. A `slug-reuse` refusal means that history exists — mint a different slug; histories never merge, and `--amend` is never the dodge.
+- **Amending scope** — mid-effort scope change, or the decompose gate's stop screen handed off to re-interview: run the interview shortened to what changed, confirm, then `$WITNESS recap --amend <effort> --file "$DIR/recap.json"`. An amendment re-arms the decompose gate's feature-class stop: scope changed, scope gets re-approved.
+- The refusal repair loop applies (3 attempts, then stop with the violation list).
+
+## Stateless by design
+
+Session died mid-interview? Start over — nothing was persisted; that is the accepted cost. If the dashboard's efforts table already shows the effort (the recap landed), do not re-interview — hand back to /witness.

package/plugin/skills/witness-decompose/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: witness-decompose
+description: Slice a witness effort's confirmed recap into vertical spec slices, or route a fix to the one spec it amends — manifests handed to witness write, then the decompose gate. Chores never reach this stage. Normally invoked by /witness with the effort slug.
+---
+
+# witness-decompose — recap → sliced specs → gate
+
+## Ground rules (every witness skill)
+
+Resolve the CLI once per session:
+
+```bash
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.4.0}"
+```
+
+- **Never edit `specs/**` or `plans/**`** (the canon dirs — `paths:` in witness.config.yaml may relocate them) — not with an edit tool, not with a write tool, not with Bash redirection. The CLI is the sole writer of state; you author in scratch files under `$(mktemp -d)` and hand them to the CLI. (The canon guard blocks you; the trailer audit catches what it can't.)
+- **Never invoke gate reviewers or relay verdicts.** `witness gate` runs reviewers itself and journals what they said; your summary of a verdict is not evidence.
+- **Refusal repair loop:** a `witness` verb exiting 2 prints structured violations (`field · rule · got · want`). Fix your input and retry — **3 total attempts** per artifact, then stop, show the human the violation list verbatim, and end your turn.
+- **A refused or hook-blocked command is a stop, not a step to drop.** Re-issue it on its own; if it still refuses, tell the human what was blocked and why. Never proceed by deleting the refused half of a compound command — a dropped step is silent, and silence is how a skipped check becomes a shipped defect.
+- **Re-entrancy:** derive position from CLI output (`$WITNESS next`, the dashboard, `log`, `index`) — never from conversation memory. Killed and re-run, you must converge.
+
+## Inputs (rebuild them, never remember them)
+
+```bash
+$WITNESS log <effort>     # the latest recap entry is your contract: class, goals g*, non-goals n*, constraints c*
+$WITNESS index            # live canon: id · summary · status · depends, grouped by dir
+$WITNESS decide decompose <effort> --show   # ONLY when re-entered after a revise
+```
+
+The class comes from the recap. Never ask for it again.
+
+## Route by class
+
+- **feature** — slice (next section). Expect the gate to stop for scope approval afterwards: that is the standing stop working, not a failure.
+- **fix** — find **THE one spec** to amend: match the broken behavior against `witness index` summaries; when summaries tie, grep `specs/` read-only. Amend exactly one spec. If the fix genuinely needs a brand-new spec, write it — the gate's tripwire stops for a human, which is the designed check on your routing (on a young canon this fires often; say so rather than fighting it).
+- **chore** — **write NO specs** (a chore writing spec content is refused at write time, by definition of the class). There is nothing here for you: `next` routes a chore straight to the plan stage, because the decompose gate refuses `nothing-to-gate` without written specs and `write` refuses spec content from a chore — the stage is unsatisfiable in both directions. The parent for the coming plan is chosen when that plan is authored. Hand back immediately if you were invoked for one.
+
+## Slicing rules (feature)
+
+- Thin **vertical** slices: each spec independently shippable, observable end-to-end. Never layers ("the schema", "the client").
+- Each spec answers exactly one question; no two overlap; **one fact, one home**. A fact needed by two slices gets extracted into its own spec, and both `depends` on it.
+- Amending a living spec is the same write with the existing id — its status resets to `draft` (re-approval owed). If the CLI warns the spec has an in-flight child plan, surface that warning at the gate stop.
+- Boundary changes (split, merge, extraction out of a live spec) → the new spec's manifest carries `supersedes: <old-id>`; rewrite every dependent's `depends` in the same effort — the CLI refuses dangling edges.
+- Cross-cutting changes → sequenced per-slice amendments ordered via `depends`, expand-contract style (accept both → switch → drop old), each step independently shippable.
+- Self-check totality before gating: every goal covered by ≥ 1 spec, every spec covers ≥ 1 goal.
+
+## Author each spec
+
+Manifest + body in scratch, then the write:
+
+```bash
+DIR=$(mktemp -d)
+cat > "$DIR/meta.json" <<'EOF'
+{
+  "type": "spec",
+  "summary": "Refresh tokens rotate before expiry",
+  "depends": ["auth-login"],
+  "needs": [],
+  "criteria": [
+    { "id": "ac-rotate", "test": "@spec:auth-refresh" },
+    { "id": "ac-smoke", "cmd": "npm run smoke:auth" }
+  ],
+  "covers": ["g1"]
+}
+EOF
+cat > "$DIR/body.md" <<'EOF'
+## Motivation
+
+Why this slice exists — the recap goal in context, one short paragraph.
+
+## Behavior
+
+What must observably be true, public surface only. State every `cmd:`
+criterion's expected behavior and thresholds HERE — a fact that lives only
+inside a script has a hidden home and drifts invisibly.
+EOF
+$WITNESS write auth-refresh --effort <effort> --meta "$DIR/meta.json" --body "$DIR/body.md"
+```
+
+Get these right the first time — the dashboard trends your first-try valid rate:
+
+- `summary` ≤ 120 chars: what the slice **is** (Motivation carries the why).
+- `criteria`: ≥ 1 entry, unique ids, each exactly one of `test` (value must be `@spec:<this-spec-id>`) or `cmd`. A criterion that cannot fail is not a criterion.
+- `covers`: the recap goal ids this spec honestly advances — the critic judges the mapping's quality.
+- Body: exactly the `## Motivation` and `## Behavior` headings; behavior-only — internal interfaces never appear in a spec.
+- `id`: `[a-z0-9-]+`; new ids land at `specs/<id>.md` (or the repo's configured specs dir).
+- `needs`: external prerequisites only, machine-checkable (`env:` / `cmd:` / `manual:` + `satisfied`).
+- `ui`: set `ui: true` in the manifest **iff** the slice changes browser-rendered or interactive behavior (a screen, a form, client-side interaction). A browser-behavior slice **without** the flag, or a flag on a non-UI slice, is a slicing-critic finding. A `ui` spec earns a **design stage** before its plan — the look is approved before code (Decision 69).
+
+## Gate
+
+```bash
+$WITNESS gate decompose --effort <effort>    # append --manual when the run asked for it
+```
+
+- **Auto-pass** (green path) → done; hand back to /witness.
+- **Stop** (standing stop, blocking findings, fix-created-spec tripwire) → render the gate output verbatim, print the human's exits — `witness decide decompose <effort> --approve | --revise --note "…" | --stop` — and END YOUR TURN. You never decide.
+- **Re-entered after `--revise`** → `decide --show` reconstructs the verdict + human note; findings anchor to spec headings. Fix via new `witness write` calls (same ids amend in place), self-check totality, re-gate. The 3-round bound is the CLI's — surface it, never fight it. `--show` also emits `state:` and `exits:` — a `reopened` or `settled` state means the verdict above it is history, so act on the `exits:` line, not on remembered findings.
+- Findings implicate the **scope itself** (goals wrong, not slicing wrong)? Tell the human that `--revise --upstream` on the stop screen routes back to re-interview via `witness recap --amend`.