@lifeaitools/rdc-skills 0.23.0 → 0.24.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rdc",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "description": "RDC typed-agent dispatch skill suite for Claude Code — plan, build, review, overnight unattended builds with work-item tracking and TDD enforcement.",
   "author": {
     "name": "LIFEAI",

package/git-sha.json

@@ -1,3 +1,3 @@
 {
-  "sha": "7b0495d94de2ee447dadb0f1228bbbe9650a5563"
+  "sha": "e04654eb140982dd3d79fe474a8a681c131e2e3d"
 }

package/hooks/require-work-item-on-commit.js

@@ -1,25 +1,44 @@
 #!/usr/bin/env node
 /**
- * PreToolUse hook — block git commits without a linked work item.
+ * Work-item commit hook — Truth Gate 3.0 Layer 1 (commit capture).
  *
- * Fires before any Bash tool call. If the command contains "git commit",
- * checks whether a fixit.marker exists (fixit workflow is self-documenting)
- * OR the commit message references a work item ID or conventional type.
+ * Registered on BOTH:
+ *   - PreToolUse(Bash):  intent check (preserved legacy behavior — WARN only,
+ *                        never hard-blocks a commit).
+ *   - PostToolUse(Bash): commit capture — after a `git commit` lands, the hook
+ *                        runs `git rev-parse HEAD` and records the REAL SHA +
+ *                        session against the active work item in the
+ *                        `work_item_commits` side table.
  *
- * BLOCKS the commit if:
- *   - No fixit.marker exists
- *   - Commit message has no work item reference AND no conventional commit type
+ * ⛔ THE AGENT NEVER WRITES THE COMMIT FIELD. The system does. The work item is
+ * identified from the work-item UUID the agent referenced in the commit message
+ * (its "active work-item ref"); the SHA is taken from `git rev-parse HEAD`, not
+ * from anything the agent typed. This kills the "real-but-wrong commit SHA"
+ * fabrication class (FMEA #1) at the source — WP-2's closure gate then asserts a
+ * report's codeflow_post.commit is one of these captured, session-authored SHAs.
  *
- * A "work item reference" is any of:
- *   - A UUID pattern (work item ID)
- *   - "#<issue>" reference
- *   - Conventional commit prefix: feat/fix/chore/refactor/test/docs/style/perf/ci/build
+ * PreToolUse (intent) behavior is unchanged:
+ *   - fixit.marker present                  -> pass
+ *   - conventional type / UUID / #issue ref -> pass
+ *   - otherwise                             -> WARN (proceed anyway)
+ *
+ * PostToolUse (capture) behavior:
+ *   - only fires on a `git commit` whose tool result indicates success
+ *   - extracts the work-item UUID from the commit message (active ref)
+ *   - no UUID -> NO-OP (no orphan row), logs `capture-no-item`
+ *   - UUID    -> `git rev-parse HEAD` -> INSERT { work_item_id, sha, session_id }
+ *
+ * Capture sink (for tests / offline): if `RDC_COMMIT_CAPTURE_SINK` is set to a
+ * file path, the capture payload is appended there as JSONL in addition to the
+ * DB write. This lets the hook be verified deterministically without a live DB.
  */
+'use strict';
 
-const fs      = require('fs');
-const path    = require('path');
-const os      = require('os');
-const hookLog = require('./hook-logger');
+const fs        = require('fs');
+const path      = require('path');
+const os        = require('os');
+const { execFileSync } = require('child_process');
+const hookLog   = require('./hook-logger');
 
 const MARKER_FILE = path.join(
   process.env.USERPROFILE || process.env.HOME || os.homedir(),
@@ -30,55 +49,246 @@ const MARKER_FILE = path.join(
 const CONVENTIONAL_TYPES = /^(feat|fix|chore|refactor|test|docs|style|perf|ci|build|revert)(\(.+\))?:/i;
 const UUID_PATTERN = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
 const ISSUE_REF = /#[a-zA-Z0-9-]+/;
+const SHA_PATTERN = /^[0-9a-f]{7,40}$/i;
 
-function main() {
-  let input = '';
-  process.stdin.resume();
-  process.stdin.setEncoding('utf8');
+const DEFAULT_SUPABASE_URL = 'https://uvojezuorjgqzmhhgluu.supabase.co';
+
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for unit tests)
+// ---------------------------------------------------------------------------
 
-  process.stdin.on('data', chunk => { input += chunk; });
-  process.stdin.on('end', () => {
-    let toolInput;
+/** True when the Bash command is a real `git commit` (not e.g. `git commit --help`). */
+function isGitCommit(command) {
+  if (typeof command !== 'string') return false;
+  if (!/\bgit\b[^\n]*\bcommit\b/.test(command)) return false;
+  if (/\bcommit\b[^\n]*--help/.test(command) || /\bcommit\b[^\n]*\s-h\b/.test(command)) return false;
+  return true;
+}
+
+/** Extract the -m "..." message (or fall back to the whole command). */
+function extractCommitMessage(command) {
+  const cmd = String(command || '');
+  const msgMatch = cmd.match(/-m\s+["']([^"']+)["']/s) ||
+                   cmd.match(/-m\s+"([\s\S]+?)"\s*(?:&&|$)/);
+  return msgMatch ? msgMatch[1] : cmd;
+}
+
+/**
+ * Find the work-item UUID the agent referenced in the commit message — the
+ * "active work-item ref". Returns the first UUID, or null when none is present.
+ * A null result means "no active work item" -> capture must NO-OP.
+ */
+function parseCommitMessageWorkItem(message) {
+  const m = String(message || '').match(UUID_PATTERN);
+  return m ? m[0].toLowerCase() : null;
+}
+
+/**
+ * Did the committed tool call actually succeed? PostToolUse provides the tool
+ * result. A failed commit (nothing to commit / hook reject / non-zero exit)
+ * must NOT capture a row. We treat it as success unless we have positive
+ * evidence of failure, OR there is positive evidence of success in stdout.
+ */
+function commitSucceeded(toolResult) {
+  if (!toolResult || typeof toolResult !== 'object') return true; // no signal -> trust HEAD check below
+  const code = toolResult.exit_code ?? toolResult.exitCode ?? toolResult.code;
+  if (typeof code === 'number') return code === 0;
+  const out = `${toolResult.stdout || ''}\n${toolResult.stderr || ''}\n${toolResult.output || ''}`;
+  if (/nothing to commit|no changes added|did not match any files|commit failed|error:/i.test(out)) return false;
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Capture side effects
+// ---------------------------------------------------------------------------
+
+/** Real `git rev-parse HEAD` in the given cwd. Returns the SHA, or null on error. */
+function gitHead(cwd) {
+  try {
+    const sha = execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: cwd || process.cwd(),
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return SHA_PATTERN.test(sha) ? sha : null;
+  } catch {
+    return null;
+  }
+}
+
+async function getServiceKey() {
+  if (process.env.SUPABASE_SERVICE_ROLE_KEY) return process.env.SUPABASE_SERVICE_ROLE_KEY;
+  if (process.env.SUPABASE_SERVICE_KEY) return process.env.SUPABASE_SERVICE_KEY;
+  for (const endpoint of ['supabase-service', 'supabase-service-role']) {
     try {
-      toolInput = JSON.parse(input);
-    } catch {
-      process.exit(0);
-    }
+      const res = await fetch(`http://127.0.0.1:52437/v/${endpoint}`, { signal: AbortSignal.timeout(2000) });
+      if (res.ok) {
+        const text = (await res.text()).trim();
+        if (text && !text.startsWith('{')) return text;
+      }
+    } catch (_) {}
+  }
+  return null;
+}
 
-    if (toolInput.tool_name !== 'Bash') {
-      process.exit(0);
-    }
+/** Append the capture payload to the test/offline sink, if configured. */
+function writeSink(payload) {
+  const sink = process.env.RDC_COMMIT_CAPTURE_SINK;
+  if (!sink) return;
+  try {
+    fs.mkdirSync(path.dirname(sink), { recursive: true });
+    fs.appendFileSync(sink, JSON.stringify(payload) + '\n');
+  } catch (_) {}
+}
 
-    const command = toolInput.tool_input?.command || '';
-    if (!command.includes('git commit')) {
-      process.exit(0);
-    }
+/**
+ * INSERT the captured row into work_item_commits via the Supabase REST API
+ * using the service-role key (bypasses RLS — capture is system-only). The SHA
+ * is the live `git rev-parse HEAD`, never an agent-supplied value.
+ */
+async function insertCommitRow(payload) {
+  const key = await getServiceKey();
+  if (!key) return { ok: false, reason: 'no-service-key' };
+  const base = (process.env.SUPABASE_URL || process.env.NEXT_PUBLIC_SUPABASE_URL || DEFAULT_SUPABASE_URL).replace(/\/$/, '');
+  try {
+    const res = await fetch(`${base}/rest/v1/work_item_commits`, {
+      method: 'POST',
+      headers: {
+        apikey: key,
+        Authorization: `Bearer ${key}`,
+        'Content-Type': 'application/json',
+        Prefer: 'return=minimal',
+      },
+      body: JSON.stringify({
+        work_item_id: payload.work_item_id,
+        sha: payload.sha,
+        session_id: payload.session_id,
+        source: 'commit-hook',
+      }),
+      signal: AbortSignal.timeout(3500),
+    });
+    if (!res.ok) return { ok: false, reason: `http-${res.status}` };
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, reason: e.message };
+  }
+}
 
-    // fixit.marker means this is a self-documenting fixit session — allow
-    if (fs.existsSync(MARKER_FILE)) {
-      hookLog('require-work-item', 'PreToolUse', 'pass-fixit', {});
-      process.exit(0);
-    }
+/**
+ * Capture orchestration for a single PostToolUse(git commit) event.
+ * Returns a result object (also used by tests). NEVER throws.
+ */
+async function captureCommit(raw) {
+  const command = raw?.tool_input?.command || '';
+  if (!isGitCommit(command)) return { captured: false, reason: 'not-git-commit' };
 
-    // Extract -m "..." message from command
-    const msgMatch = command.match(/-m\s+["']([^"']+)["']/s) ||
-                     command.match(/-m\s+"([\s\S]+?)"\s*(?:&&|$)/);
-    const msg = msgMatch ? msgMatch[1] : command;
+  const toolResult = raw.tool_response || raw.tool_result || raw.result || null;
+  if (!commitSucceeded(toolResult)) {
+    hookLog('require-work-item', 'PostToolUse', 'capture-skip-failed-commit', {});
+    return { captured: false, reason: 'commit-not-successful' };
+  }
 
-    if (CONVENTIONAL_TYPES.test(msg.trim()) || UUID_PATTERN.test(msg) || ISSUE_REF.test(msg)) {
-      hookLog('require-work-item', 'PreToolUse', 'pass', { msg: msg.slice(0, 80) });
-      process.exit(0);
-    }
+  const message = extractCommitMessage(command);
+  const workItemId = parseCommitMessageWorkItem(message);
+  if (!workItemId) {
+    // No active work item -> NO-OP. No orphan row is ever written.
+    hookLog('require-work-item', 'PostToolUse', 'capture-no-item', { msg: String(message).slice(0, 80) });
+    return { captured: false, reason: 'no-active-work-item' };
+  }
+
+  const cwd = raw.cwd || process.cwd();
+  const sha = gitHead(cwd);
+  if (!sha) {
+    hookLog('require-work-item', 'PostToolUse', 'capture-no-head', { work_item_id: workItemId });
+    return { captured: false, reason: 'no-head-sha', work_item_id: workItemId };
+  }
 
-    hookLog('require-work-item', 'PreToolUse', 'warn', { msg: msg.slice(0, 80) });
-    // Warn only — never hard-block commits. A missing work item is informational,
-    // not a blocker. Conventional commit format is sufficient self-documentation.
-    process.stdout.write(JSON.stringify({
-      systemMessage: `⚠️ Commit has no work item reference or conventional commit type.\n` +
-        `Preferred format: fix(<scope>): <message> — proceeding anyway.`
-    }));
-    process.exit(0);
+  const payload = {
+    work_item_id: workItemId,
+    sha,                                   // <-- system-derived HEAD, never agent text
+    session_id: raw.session_id || null,
+  };
+
+  writeSink(payload);
+  const insert = await insertCommitRow(payload);
+  hookLog('require-work-item', 'PostToolUse', insert.ok ? 'capture-recorded' : 'capture-deferred', {
+    work_item_id: workItemId,
+    sha,
+    insert_reason: insert.reason || null,
   });
+  return { captured: true, sha, work_item_id: workItemId, db: insert };
 }
 
-main();
+// ---------------------------------------------------------------------------
+// PreToolUse intent check (unchanged legacy behavior)
+// ---------------------------------------------------------------------------
+
+function preToolUse(raw) {
+  if (raw.tool_name !== 'Bash') return process.exit(0);
+  const command = raw.tool_input?.command || '';
+  if (!command.includes('git commit')) return process.exit(0);
+
+  if (fs.existsSync(MARKER_FILE)) {
+    hookLog('require-work-item', 'PreToolUse', 'pass-fixit', {});
+    return process.exit(0);
+  }
+
+  const msg = extractCommitMessage(command);
+  if (CONVENTIONAL_TYPES.test(msg.trim()) || UUID_PATTERN.test(msg) || ISSUE_REF.test(msg)) {
+    hookLog('require-work-item', 'PreToolUse', 'pass', { msg: msg.slice(0, 80) });
+    return process.exit(0);
+  }
+
+  hookLog('require-work-item', 'PreToolUse', 'warn', { msg: msg.slice(0, 80) });
+  // Warn only — never hard-block commits. Conventional commit format is
+  // sufficient self-documentation.
+  process.stdout.write(JSON.stringify({
+    systemMessage: `⚠️ Commit has no work item reference or conventional commit type.\n` +
+      `Preferred format: fix(<scope>): <message> — proceeding anyway.`,
+  }));
+  return process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// Entry point — event-aware
+// ---------------------------------------------------------------------------
+
+async function main() {
+  let input = '';
+  await new Promise((resolve) => {
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { input += chunk; });
+    process.stdin.on('end', resolve);
+  });
+
+  let raw;
+  try { raw = JSON.parse(input); } catch { return process.exit(0); }
+
+  const event = raw.hook_event_name || raw.hookEventName || 'PreToolUse';
+
+  if (event === 'PostToolUse') {
+    if (raw.tool_name && raw.tool_name !== 'Bash') return process.exit(0);
+    try { await captureCommit(raw); } catch (e) {
+      hookLog('require-work-item', 'PostToolUse', 'capture-error', { error: e.message });
+    }
+    return process.exit(0); // capture is observe-only; never blocks the loop
+  }
+
+  // Default / PreToolUse intent path.
+  preToolUse(raw);
+}
+
+// Run when executed as a hook; export pure pieces when required by a test.
+if (require.main === module) {
+  main();
+} else {
+  module.exports = {
+    isGitCommit,
+    extractCommitMessage,
+    parseCommitMessageWorkItem,
+    commitSucceeded,
+    gitHead,
+    captureCommit,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/rdc-skills",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "description": "RDC typed-agent dispatch skill suite for Claude Code - plan, build, review, overnight builds",
   "keywords": [
     "claude-code",

package/scripts/install-rdc-skills.js

@@ -696,9 +696,14 @@ function buildHooksConfig(hooksDir, profile = 'core') {
         cmd('require-work-item-on-commit.js'),
       ]},
     ],
-    PostToolUse: [{ hooks: [
-      cmd('check-services.js'),
-    ]}],
+    PostToolUse: [
+      { hooks: [
+        cmd('check-services.js'),
+      ]},
+      { matcher: 'Bash', hooks: [
+        cmd('require-work-item-on-commit.js', 'Capturing commit SHA for work item...'),
+      ]},
+    ],
     Stop: [{ hooks: [
       cmd('rdc-output-contract-gate.js', 'Checking RDC output contract...'),
       cmd('post-work-check.js',    'Checking for undocumented work...'),

package/skills/build/SKILL.md

@@ -214,24 +214,42 @@ Read the task title and description, then:
 7. **For each wave — dispatch typed agents in parallel:**
 
    ### ⛔ Agent Dispatch Non-Negotiable Defaults
-   Every `Agent()` call MUST include these parameters — no exceptions:
+   Every `Agent()` call MUST include these parameters:
    ```
    model: <chosen per the routing table below>
    max_turns: 70
-   isolation: "worktree"
    ```
-
-   ### ⛔ Concurrent committers ⇒ worktree isolation, no exceptions (docs included)
-   For ANY parallel agent dispatch where the agents COMMIT — **including a pure
-   docs wave** — force `isolation: "worktree"` so each agent commits in its own
-   tree and the orchestrator merges. NEVER fan out concurrent committers onto one
-   shared working tree (lesson 2026-06-13-build-concurrent-agents-same-branch-git-race:
-   three parallel doc agents on one `develop` tree raced on the git index/stash —
-   one commit swept in another agent's staged-but-uncommitted files under the wrong
-   message, two agents reported the SAME SHA, and a pre-commit `sync:docs` ref-lock
-   race misattributed authorship). "It's just docs" is NOT an exemption. The only
-   alternative to worktree isolation is running the committing agents **sequentially**
-   on the shared tree (one commits and pushes before the next starts).
+   `isolation` is chosen per the dispatch-mode rule below — it is NOT a blanket
+   default. Worktree isolation is reserved for true parallel MULTI-committer waves
+   in the same repo; doc-only and single-committer waves default to NON-isolated.
+
+   ### ⛔ Dispatch mode — non-isolated is the default for single-committer / doc-only waves
+   Worktree isolation exists to protect a SHARED working tree from a git-index race
+   between MULTIPLE agents committing in parallel. When there is only ONE committer,
+   that race cannot occur, and the stale-base hazard of worktrees (see the HARD GATE
+   below — recurring across 2026-06-10/11/15/16/17/23) is pure downside. Pick the
+   dispatch mode by committer count, not by reflex:
+
+   | Wave shape | Dispatch mode | isolation |
+   |---|---|---|
+   | **Doc-only wave** (markdown/docs/plans, no code build) | NON-isolated, one committer on `develop` | omit `isolation` |
+   | **Single-committer wave** (only one agent commits, or work serializes to the supervisor) | NON-isolated, one committer on `develop` | omit `isolation` |
+   | **True parallel MULTI-committer wave** (2+ agents committing concurrently in the same repo, disjoint files) | worktree-isolated, supervisor merges | `isolation: "worktree"` |
+
+   - **Default = NON-isolated.** Only escalate to `isolation: "worktree"` when the
+     wave genuinely has 2+ concurrent committers in the same repo.
+   - A pure docs wave is single-committer by default: either dispatch ONE doc agent,
+     or have parallel doc agents return diffs/patches that the supervisor commits
+     serially. Do NOT fan out 2+ concurrent committers onto one shared `develop`
+     tree (lesson 2026-06-13-build-concurrent-agents-same-branch-git-race: three
+     parallel doc agents on one `develop` tree raced on the git index/stash — one
+     commit swept in another agent's staged-but-uncommitted files under the wrong
+     message, two agents reported the SAME SHA, a pre-commit `sync:docs` ref-lock
+     race misattributed authorship). The fix for that race is single-committer
+     serialization, NOT blanket worktree isolation.
+   - When you DO need a true MULTI-committer parallel wave, worktree isolation is
+     mandatory AND the HARD GATE below (base == develop HEAD) MUST pass before
+     dispatch — a stale-base worktree wave is a build failure, not a warning.
 
    ### ⛔ Foreign concurrent session guard — `git status` BEFORE the build
    Worktree isolation protects against THIS build's own agents, not against a
@@ -270,25 +288,34 @@ Read the task title and description, then:
    Without `max_turns: 70`, agents hit the default turn cap mid-task and stop.
    `isolation: "worktree"` gives each agent its own git worktree and branch — eliminates push race conditions and index lock contention when multiple agents commit in parallel. The supervisor merges worktree branches after each wave (Step 9).
 
-   ### ⛔ Worktree base must equal develop HEAD — assert BEFORE every isolated wave
+   ### ⛔ HARD GATE — Worktree base MUST equal develop HEAD (blocking, not advisory)
    The worktree-isolation harness has shipped worktrees pinned to a STALE base
-   commit (lessons 2026-06-10-build-worktree-stale-base, 2026-06-11-build-worktree-stale-base:
-   agents branched 464 commits / 4 days behind develop HEAD, on a tree where the
-   target app did not yet exist — their diffs would have silently reverted merged
-   work or operated on a deleted structure). **Before dispatching ANY
-   `isolation:"worktree"` wave**, assert each worktree's base equals current
-   develop HEAD:
+   commit (lessons 2026-06-10-build-worktree-stale-base, 2026-06-11-build-worktree-stale-base,
+   2026-06-15-build-worktree-stale-base, 2026-06-16-build-worktree-stale-base,
+   2026-06-17-build-worktree-stale-base, 2026-06-23-build-worktree-stale-base:
+   agents branched hundreds of commits / multiple days behind develop HEAD, on a
+   tree where the target app did not yet exist — their diffs would have silently
+   reverted merged work or operated on a deleted structure). This is a recurring
+   harness defect, so the check is a **HARD BLOCKING GATE, not a suggestion.**
+
+   **Before dispatching ANY `isolation:"worktree"` wave**, the supervisor MUST run
+   the base==HEAD assertion and MUST abort isolation on any mismatch — there is no
+   "proceed anyway" path:
    ```bash
    DEV_HEAD=$(git rev-parse develop)
    # After worktrees are created, for each agent worktree:
    git worktree list   # compare each agent worktree's SHA to $DEV_HEAD
-   # If a worktree base != $DEV_HEAD (it is behind), the wave is UNSAFE.
+   # If ANY worktree base != $DEV_HEAD (it is behind), the wave is UNSAFE — ABORT.
    ```
-   - If any worktree base is behind `$DEV_HEAD`: **ABORT isolation for this wave.**
-     Do NOT merge stale worktree output. Pivot to **sequential, non-isolated
-     dispatch on a real `develop` checkout** (one disjoint WP at a time to avoid
-     `.git/index` races; the supervisor pushes) — the same reason the validator
-     runs non-isolated (it must see merged develop).
+   - **MANDATORY ABORT:** if ANY worktree base != `$DEV_HEAD`, you MUST abort
+     isolation for this wave. Do NOT merge stale worktree output. Do NOT "fast-forward
+     and continue". Do NOT proceed with the isolated wave under any circumstance.
+     Pivot to **sequential, non-isolated dispatch on a real `develop` checkout**
+     (one disjoint WP at a time to avoid `.git/index` races; the supervisor pushes) —
+     the same reason the validator runs non-isolated (it must see merged develop).
+   - This gate is blocking by design: an isolated wave dispatched on a stale base
+     is treated as a build failure, not a warning. Skipping or downgrading this
+     assertion to advisory is a contract violation.
    - Also at every merge: `git show <branch>:<key-file> | grep -c <symbol-a-prior-wave-introduced>`
      — a 0 where there should be ≥1 means the branch is stale or deleted a shared
      export; resolve to `--ours` and re-apply that wave's real delta on current HEAD.
@@ -509,7 +536,7 @@ NEVER run pnpm build or pnpm turbo. Use npx vitest run only.
 - Push after each wave, not just at the end
 - Unattended: NEVER pause — continue automatically
 - Unattended: max 2 retries per task before escalating to advisor
-- Every Agent() dispatch: `model: <routed>` + `max_turns: 70` + `isolation: "worktree"` — non-negotiable. Model is chosen per task per the routing table in Step 7: Sonnet 4.6 for updates/edits, Opus 4.6 for harder coding, Opus 4.8 for design/innovative thought (CS 2.0, brand/UX, architecture). Supervisor logs `model=<chosen> reason=<phrase>` per agent. Exception: validator agent in Step 10 omits isolation; validator model stays `claude-sonnet-4-6` (verification, not generation).
+- Every Agent() dispatch: `model: <routed>` + `max_turns: 70` — non-negotiable. `isolation` is per the dispatch-mode rule in Step 7: NON-isolated (omit `isolation`) for doc-only and single-committer waves; `isolation: "worktree"` ONLY for true parallel MULTI-committer waves, and only after the HARD GATE (worktree base == develop HEAD) passes — a stale-base isolated wave is a build failure. Model is chosen per task per the routing table in Step 7: Sonnet 4.6 for updates/edits, Opus 4.6 for harder coding, Opus 4.8 for design/innovative thought (CS 2.0, brand/UX, architecture). Supervisor logs `model=<chosen> reason=<phrase>` per agent. Exception: validator agent in Step 10 always omits isolation; validator model stays `claude-sonnet-4-6` (verification, not generation).
 - Finding an existing file is NOT task completion — verify it satisfies the spec
 
 ## Capture lessons (exit step)

package/tests/require-work-item-on-commit.test.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * Truth Gate L1 — commit-capture hook tests.
+ *
+ * Proves:
+ *   1. parse: the work-item UUID is extracted from a commit message; absent UUID -> null.
+ *   2. capture: on a PostToolUse(git commit), the captured `sha` EQUALS the real
+ *      `git rev-parse HEAD` of the repo (verified against a throwaway git repo,
+ *      via the RDC_COMMIT_CAPTURE_SINK file — no live DB required).
+ *   3. no-item: capture NO-OPs (writes nothing) when the commit message carries
+ *      no work-item UUID. No orphan row.
+ *
+ * Run: node tests/require-work-item-on-commit.test.mjs   (or `node --test tests/`)
+ */
+import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync, execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, '..');
+const HOOK = join(REPO_ROOT, 'hooks', 'require-work-item-on-commit.js');
+
+const require = createRequire(import.meta.url);
+const failures = [];
+function assert(name, condition, detail = '') {
+  if (!condition) failures.push(`${name}${detail ? `: ${detail}` : ''}`);
+}
+
+// ---------------------------------------------------------------------------
+// 1. Pure parse assertions
+// ---------------------------------------------------------------------------
+const hook = require(HOOK);
+const WI = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee';
+
+assert('parse: extracts UUID from message',
+  hook.parseCommitMessageWorkItem(`feat(x): do thing for ${WI}`) === WI);
+assert('parse: null when no UUID',
+  hook.parseCommitMessageWorkItem('feat(x): no work item here') === null);
+assert('isGitCommit: true for real commit',
+  hook.isGitCommit('git commit -m "feat: x"') === true);
+assert('isGitCommit: false for --help',
+  hook.isGitCommit('git commit --help') === false);
+assert('isGitCommit: false for unrelated',
+  hook.isGitCommit('git status') === false);
+assert('commitSucceeded: false on nothing-to-commit',
+  hook.commitSucceeded({ stdout: 'nothing to commit, working tree clean' }) === false);
+assert('commitSucceeded: true on exit 0',
+  hook.commitSucceeded({ exit_code: 0 }) === true);
+
+// ---------------------------------------------------------------------------
+// helper: build a throwaway git repo with one commit
+// ---------------------------------------------------------------------------
+function makeRepo() {
+  const dir = mkdtempSync(join(tmpdir(), 'wic-repo-'));
+  const g = (...args) => execFileSync('git', args, { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  g('init', '-q');
+  g('config', 'user.email', 'test@example.com');
+  g('config', 'user.name', 'Test');
+  writeFileSync(join(dir, 'f.txt'), 'hello\n');
+  g('add', 'f.txt');
+  g('commit', '-q', '-m', `feat: seed for ${WI}`);
+  const head = g('rev-parse', 'HEAD').trim();
+  return { dir, head };
+}
+
+function runHook(payload, extraEnv = {}) {
+  return spawnSync(process.execPath, [HOOK], {
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+    env: { ...process.env, ...extraEnv },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 2. Capture: sha == git rev-parse HEAD
+// ---------------------------------------------------------------------------
+{
+  const { dir, head } = makeRepo();
+  const sink = join(dir, 'sink.jsonl');
+  // Point Supabase at an unreachable host so the test never touches a real DB;
+  // capture still writes the sink, which is what we assert on.
+  const res = runHook({
+    hook_event_name: 'PostToolUse',
+    tool_name: 'Bash',
+    session_id: 'sess-capture-1',
+    cwd: dir,
+    tool_input: { command: `git commit -m "feat: thing for ${WI}"` },
+    tool_response: { exit_code: 0, stdout: '1 file changed' },
+  }, {
+    RDC_COMMIT_CAPTURE_SINK: sink,
+    SUPABASE_URL: 'http://127.0.0.1:9',     // unreachable -> DB insert fails fast, capture still records sink
+    SUPABASE_SERVICE_ROLE_KEY: 'test-key-not-real',
+  });
+  assert('capture: hook exits zero', res.status === 0, res.stderr);
+  assert('capture: sink written', existsSync(sink), 'no sink file');
+  if (existsSync(sink)) {
+    const row = JSON.parse(readFileSync(sink, 'utf8').trim().split('\n')[0]);
+    assert('capture: sha equals real HEAD', row.sha === head, `${row.sha} !== ${head}`);
+    assert('capture: work_item_id parsed', row.work_item_id === WI, row.work_item_id);
+    assert('capture: session_id recorded', row.session_id === 'sess-capture-1', row.session_id);
+  }
+  rmSync(dir, { recursive: true, force: true });
+}
+
+// ---------------------------------------------------------------------------
+// 3. No active work item -> NO-OP (no sink row)
+// ---------------------------------------------------------------------------
+{
+  const { dir } = makeRepo();
+  const sink = join(dir, 'sink.jsonl');
+  const res = runHook({
+    hook_event_name: 'PostToolUse',
+    tool_name: 'Bash',
+    session_id: 'sess-no-item',
+    cwd: dir,
+    tool_input: { command: 'git commit -m "feat: no work item ref"' },
+    tool_response: { exit_code: 0 },
+  }, { RDC_COMMIT_CAPTURE_SINK: sink });
+  assert('no-item: hook exits zero', res.status === 0, res.stderr);
+  assert('no-item: no sink row written', !existsSync(sink), 'orphan capture written for no-item commit');
+  rmSync(dir, { recursive: true, force: true });
+}
+
+// ---------------------------------------------------------------------------
+// 4. PreToolUse legacy behavior preserved (warn-only, never blocks)
+// ---------------------------------------------------------------------------
+{
+  const res = runHook({
+    hook_event_name: 'PreToolUse',
+    tool_name: 'Bash',
+    tool_input: { command: 'git commit -m "no convention and no uuid"' },
+  });
+  assert('pre: warn exits zero (never blocks)', res.status === 0, res.stderr);
+  assert('pre: emits warn systemMessage', /no work item reference/.test(res.stdout), res.stdout);
+
+  const ok = runHook({
+    hook_event_name: 'PreToolUse',
+    tool_name: 'Bash',
+    tool_input: { command: 'git commit -m "feat(x): conventional"' },
+  });
+  assert('pre: conventional passes silently', ok.status === 0 && ok.stdout.trim() === '', ok.stdout);
+}
+
+// ---------------------------------------------------------------------------
+if (failures.length > 0) {
+  console.error('\ncommit-capture hook tests — FAIL\n');
+  for (const f of failures) console.error(`  - ${f}`);
+  process.exit(1);
+}
+console.log('commit-capture hook tests — PASS');