@lifeaitools/rdc-skills 0.24.0 → 0.24.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rdc",
-  "version": "0.24.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": "46460e5add65d8555ec9246eed10eb2d7c5fcbb4"
+  "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.24.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/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');