@lifeaitools/rdc-skills 0.24.0 → 0.24.2

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": "e6ebb365ff8dc12473f5e2a8e0de04dee4003a91"
 }

package/hooks/lib/run-evidence-gate.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * run-evidence-gate.mjs — Truth Gate 3.0 Layer 2, the FUSED evidence primitive.
+ *
+ * Nidus / D4 principle: "you cannot submit evidence without running the test."
+ * This is ONE atomic call that (1) RUNS a verification command, (2) HASHES its
+ * captured output server-side, and (3) records the verdict TOGETHER with the
+ * hash and a timestamp. Evidence and execution are produced in the same call —
+ * an agent can never hand the gate a hash for a run that never happened.
+ *
+ * The output of runEvidenceGate() is the only legitimate shape of a
+ * machine-parseable `verification` artifact: it carries the exact command, the
+ * exit code, an SHA-256 of stdout+stderr, and a pass/fail verdict the CALLER
+ * did not author. The exit-gate's L2 verifier recognises this shape (and a few
+ * other captured-artifact shapes) and rejects anything that is bare prose.
+ *
+ * Pure-ish: it shells out to run the command but has no DB or network side
+ * effects, so it is unit-testable offline.
+ */
+'use strict';
+
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+
+/** Stable SHA-256 of a string (server-side hash — the caller cannot forge it). */
+export function hashOutput(text) {
+  return createHash('sha256').update(String(text == null ? '' : text), 'utf8').digest('hex');
+}
+
+/**
+ * The discriminant marker stamped on every fused artifact. The exit-gate keys
+ * on this to recognise a real run-and-attest result vs. an agent-typed string.
+ */
+export const EVIDENCE_KIND = 'run-evidence-gate/v1';
+
+/**
+ * Run a verification command and atomically produce a hashed, verdicted
+ * evidence artifact. There is NO path to a verdict that skips the run: the
+ * verdict is derived from the actual exit code of the actual spawn.
+ *
+ * @param {object} spec
+ * @param {string}   spec.command       executable to run (e.g. "node", "npx")
+ * @param {string[]} [spec.args]        argv for the command
+ * @param {string}   [spec.cwd]         working directory
+ * @param {object}   [spec.env]         extra env
+ * @param {number}   [spec.timeoutMs]   hard timeout (default 120s)
+ * @param {string}   [spec.label]       human label for the check
+ * @param {(spec)=>{status:number,stdout:string,stderr:string}} [runner]
+ *        injectable runner — defaults to spawnSync. Lets tests drive a fake
+ *        process WITHOUT removing the "must run" property (the runner is still
+ *        invoked exactly once and its result is what the verdict is built from).
+ * @returns {object} a fused evidence artifact (see EVIDENCE_KIND).
+ */
+export function runEvidenceGate(spec, runner) {
+  if (!spec || typeof spec !== 'object' || typeof spec.command !== 'string' || !spec.command) {
+    // Fail-closed: a malformed request can never produce a "pass".
+    return {
+      kind: EVIDENCE_KIND,
+      ran: false,
+      verdict: 'error',
+      reason: 'invalid-spec: command is required',
+      ts: new Date().toISOString(),
+    };
+  }
+
+  const exec = typeof runner === 'function' ? runner : defaultRunner;
+
+  let result;
+  try {
+    result = exec(spec);
+  } catch (e) {
+    // Spawn itself threw — fail-closed.
+    return {
+      kind: EVIDENCE_KIND,
+      ran: false,
+      verdict: 'error',
+      reason: `runner-threw: ${e && e.message ? e.message : String(e)}`,
+      command: renderCommand(spec),
+      ts: new Date().toISOString(),
+    };
+  }
+
+  // The runner MUST return a numeric status for the verdict to exist. No status
+  // (e.g. the process could not be spawned) => no run => fail-closed.
+  const status = result && typeof result.status === 'number' ? result.status : null;
+  const stdout = result && result.stdout != null ? String(result.stdout) : '';
+  const stderr = result && result.stderr != null ? String(result.stderr) : '';
+
+  if (status === null) {
+    return {
+      kind: EVIDENCE_KIND,
+      ran: false,
+      verdict: 'error',
+      reason: 'runner-produced-no-exit-status (process did not run)',
+      command: renderCommand(spec),
+      ts: new Date().toISOString(),
+    };
+  }
+
+  const combined = `EXIT:${status}\n--STDOUT--\n${stdout}\n--STDERR--\n${stderr}`;
+  return {
+    kind: EVIDENCE_KIND,
+    ran: true,
+    label: spec.label || null,
+    command: renderCommand(spec),
+    exit_code: status,
+    verdict: status === 0 ? 'pass' : 'fail',
+    output_sha256: hashOutput(combined),
+    output_bytes: Buffer.byteLength(combined, 'utf8'),
+    ts: new Date().toISOString(),
+  };
+}
+
+function renderCommand(spec) {
+  return [spec.command, ...(Array.isArray(spec.args) ? spec.args : [])].join(' ');
+}
+
+function defaultRunner(spec) {
+  const res = spawnSync(spec.command, Array.isArray(spec.args) ? spec.args : [], {
+    cwd: spec.cwd || process.cwd(),
+    env: { ...process.env, ...(spec.env || {}) },
+    encoding: 'utf8',
+    timeout: typeof spec.timeoutMs === 'number' ? spec.timeoutMs : 120000,
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  return { status: res.status, stdout: res.stdout, stderr: res.stderr };
+}
+
+/**
+ * Is `v` a legitimate machine-parseable verification artifact (NOT prose)?
+ *
+ * Accepts, in order of strength:
+ *   1. A fused run-evidence-gate artifact (object or its JSON string) — strongest.
+ *   2. A captured-artifact OBJECT with a recognised machine shape:
+ *        - { exit_code: <number> }            (tsc / test-runner exit)
+ *        - { http_status: <number> }          (captured HTTP status)
+ *        - { rowcount: <number> } / row_count (SQL rowcount)
+ *        - { passed: <number>, ... }          (test-runner JSON, e.g. vitest)
+ *      (a JSON string of any of these is also accepted)
+ * REJECTS:
+ *   - bare strings ("HTTP 200", "107 nodes", "works", "done") — proxy/prose.
+ *   - objects with no machine field.
+ */
+export function isMachineArtifact(v) {
+  if (v == null) return false;
+
+  // String input: only accepted if it parses to a recognised JSON artifact.
+  if (typeof v === 'string') {
+    const s = v.trim();
+    if (!(s.startsWith('{') || s.startsWith('['))) return false; // bare prose
+    let parsed;
+    try { parsed = JSON.parse(s); } catch { return false; }
+    return isMachineArtifact(parsed);
+  }
+
+  if (typeof v !== 'object') return false;
+
+  // 1. Fused artifact.
+  if (v.kind === EVIDENCE_KIND && v.ran === true && typeof v.output_sha256 === 'string') {
+    return true;
+  }
+
+  // 2. Recognised captured-artifact object shapes.
+  if (typeof v.exit_code === 'number') return true;
+  if (typeof v.http_status === 'number' || typeof v.httpStatus === 'number') return true;
+  if (typeof v.status_code === 'number' || typeof v.statusCode === 'number') return true;
+  if (typeof v.rowcount === 'number' || typeof v.row_count === 'number' || typeof v.rowCount === 'number') return true;
+  if (typeof v.passed === 'number' && (typeof v.failed === 'number' || typeof v.total === 'number')) return true;
+  if (typeof v.tsc_errors === 'number' || typeof v.tscErrors === 'number') return true;
+
+  return false;
+}
+
+export default { runEvidenceGate, hashOutput, isMachineArtifact, EVIDENCE_KIND };

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,
+  };
+}