@lifeaitools/rdc-skills 0.37.2 → 0.37.5

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rdc",
-  "version": "0.37.2",
+  "version": "0.37.5",
   "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/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## v0.37.5 — lesson drain: skills say what the gates check
+
+### Fixed
+- `rdc:fixit` seeds the required `decomp-fix` / `test-fix-proof` rows at insert and ticks them before review; `done` refused every fixit item without them. Recovery via `append_checklist_item` is documented. (regen-root#194)
+- `rdc:fixit` reviews `git diff --cached --stat` before committing and uses `git add -p` on a file that was already dirty. (#195)
+- `rdc:release` and `rdc:fixit` verify a publish with an exact-version registry fetch, not `npm view`. (#231)
+- `rdc:release` reads `<repo>/RELEASE.md` first, and treats E403/E409 right after a tag as "CI already published". (#196)
+- `rdc:flow hotfix|maintenance` writes the mode store as well as the flow store; `setFlow` alone relaxed no guard. `rdc:flow normal` clears both.
+- `rdc:status` reads PM2 through `ssh-clauth.sh`; the raw key fetch it documented is guard-blocked. (#216)
+- `require-work-item-on-commit`: `git` must be the command word; prose containing "git" and "commit" no longer trips it. (#243)
+- `validate-publish-manifests`: a DEPLOY block whose `staging_gates` is a list or inline value fails. (#210)
+- Installer warns when run from a checkout behind `origin/master`. (#230)
+- `scripts/acceptance.mjs` compared its URL to a hand-built one; under a Windows 8.3 path (`NAME~1`) they never matched, `main()` never ran and every call exited 0. It compares paths now.
+
+### Added
+- Notes: `rdc:build` holds a human-only blocker with `rdc-work hold` (#199); `rdc:plan` keeps unapproved architecture drafts in `.rdc/research/<topic>-draft.md` (#198); `rdc:collab` says `-verify` sessions close after ready (#193); `rdc:terminal-config` stale-environment diagnosis and `rdc:edit` target-URL probe from PR #13 (#192).
+- Regression tests for `truthGateWiredForEvent` (#212 — fix shipped in 83fd6f9), `isGitCommit`, `staging_gates` shape, and the stale-checkout warning.
+
+### Removed
+- `hooks/task-completed-gate.js` and `hooks/post-tool-batch-gate.js`: both sat behind env flags nothing set, so every call was a no-op. Unregistered, and the installer deletes installed copies. (#237)
+
+---
+
 ## v0.37.2 — the release doc says what actually happens
 
 ### Fixed

package/clauth-plugin.json

@@ -1,7 +1,7 @@
 {
   "schema": "lifeai.plugin.v1",
   "id": "rdc-skills",
-  "version": "0.37.2",
+  "version": "0.37.5",
   "publisher": "LIFEAI",
   "core": false,
   "documentation": {

package/commands/flow.md

@@ -61,20 +61,29 @@ node -e "import(require('url').pathToFileURL(process.env.LIFEAI_ENV + '/hooks/li
 
 ### 3. Setting hotfix or maintenance — a reason is REQUIRED
 
-Refuse to proceed without one — `setFlow` throws on an empty reason for these two values, by design, same as `setMode` always did: an unexplained disarm is how a temporary state becomes permanent.
+Refuse to proceed without one — both setters throw on an empty reason for these two values, by design: an unexplained disarm is how a temporary state becomes permanent.
+
+Guard relaxation reads the **mode** store (`rdc-mode.mjs` `isRelaxedFor()`); the work-item
+exemption reads the **flow** store. `setFlow` alone relaxes no guard, so this one command
+writes both — `setFlowOrMode` routes `hotfix`/`maintenance` to `setMode`, then `setFlow`
+records the flow:
 
 ```bash
-node -e "import(require('url').pathToFileURL(process.env.LIFEAI_ENV + '/hooks/lib/rdc-flow.mjs').href).then(m=>console.log(JSON.stringify(m.setFlow('hotfix',{reason:process.argv[1],setBy:process.argv[2]}),null,2)))" "<reason>" "<session-id>"
+node -e "import(require('url').pathToFileURL(process.env.LIFEAI_ENV + '/hooks/lib/rdc-flow.mjs').href).then(m=>{const [n,reason,setBy]=process.argv.slice(1);const o={reason,setBy};m.setFlowOrMode(n,o);m.setFlow(n,o);console.log(JSON.stringify(m.currentState(),null,2))})" "<hotfix|maintenance>" "<reason>" "<session-id>"
 ```
 
+Read the printed state: `flow` and `mode` must both show the name. If `mode` is still `normal`, no guard is relaxed — stop and say so.
+
 Then state plainly, in the checklist: **which guards are now relaxed, that the safety set is still armed, and that this stays active until explicitly cleared (no TTL — active management, not a silent timer).**
 
 ### 4. Returning to normal
 
 ```bash
-node -e "import(require('url').pathToFileURL(process.env.LIFEAI_ENV + '/hooks/lib/rdc-flow.mjs').href).then(m=>{m.clearFlow();console.log('cleared')})"
+node -e "import(require('url').pathToFileURL(process.env.LIFEAI_ENV + '/hooks/lib/rdc-flow.mjs').href).then(m=>{m.clearFlow();m.setFlowOrMode('normal');console.log(JSON.stringify(m.currentState(),null,2))})"
 ```
 
+This clears both stores; a hotfix mode left open after the flow is cleared would keep guards relaxed.
+
 Do this **as soon as the incident is over**, or the moment the declared work-shape changes.
 
 ## Rules

package/git-sha.json

@@ -1,3 +1,3 @@
 {
-  "sha": "c22b3e63abdb2c8628348bd436077688b1243b41"
+  "sha": "a96832c1aa663240fecf042c6b41d7017c8bce47"
 }

package/guides/lessons-learned-spec.md

@@ -35,7 +35,7 @@ propose-rule for one domain. This generalizes that pattern fleet-wide.
 
 ### Why lessons are not files any more
 
-Until 2026-09 every lesson was a markdown file in the capturing repository's
+Until 2026-09-17 every lesson was a markdown file in the capturing repository's
 `.rdc/lessons/`. A census of one repository found 315 of them: 157 already enforced in code,
 where the file only repeated what a guard or test already guaranteed, and 32 enforced
 nowhere, sitting in a directory the owner of the fix never reads. A lesson filed where it
@@ -48,6 +48,13 @@ So the record now follows the fix:
 - **An unencoded lesson is a GitHub issue in the repository the fix belongs to**, labelled
   `lesson` + `proposal`. **An issue proposes; a work item commits.**
 
+### Retired on-disk log
+
+The old lesson log and its `.session-*.done` sentinels were retired from the active
+regen-root tree by `247571602` on 2026-09-17. They remain recoverable from Git history;
+they are not a conversion backlog and must not be recreated. The active record is now the
+owning-repository lesson issue, its work item when accepted, and the enforcing commit.
+
 ---
 
 ## When to capture (at skill exit)
@@ -218,9 +225,8 @@ the command exits 1. Treat that as an incomplete triage, never as "no lessons th
      API/MCP changes, skill-contract changes affecting multiple skills). When unsure, it is
      architectural.
 3. Route per the mode below.
-4. Work the conversion backlog (§ Existing `.rdc/lessons/` files) with whatever capacity is left.
-5. Summarize in the housekeeping report: open / recurred / accepted / closed-fixed /
-   closed-won't-fix counts with issue URLs, plus backlog files converted and remaining.
+4. Summarize in the housekeeping report: open / recurred / accepted / closed-fixed /
+   closed-won't-fix counts with issue URLs.
 
 ### Attended mode (default — a human is present)
 
@@ -255,17 +261,13 @@ reason, is the audit trail.
 
 ---
 
-## Existing `.rdc/lessons/` files — the conversion backlog
-
-Files written under the old procedure are retired by state: an encoded lesson's file is
-deleted and links to it point at the enforcing artifact; an unencoded one becomes an issue in
-its owning repository. **The files that remain — doc-only lessons and product lessons — are a
-backlog to convert, not a place to capture.** Each is done when a guard or test carries it:
-ship that artifact, point any live link at it, and delete the file in the same commit.
+## Historical records and archive policy
 
-Housekeeping lists the remaining `.rdc/lessons/*.md` files for exactly that purpose and
-reports the count converted and remaining. Nothing new is written there: a new lesson — a
-doc-only one included — is an issue (§ Capture procedure).
+Do not create, scan, or modify `.rdc/lessons/` as part of normal capture or triage. The
+retired files are preserved by Git history. Lesson issues are also never deleted: a closed
+issue retains its evidence, comments, labels, and linked commit and can be reopened if the
+lesson recurs. Close an issue only after the fixing commit lands or with a clear won't-fix /
+duplicate reason; leave an unaccepted `proposal` issue open as the active queue.
 
 ---
 

package/hooks/gate-watchdog-selfcheck.js

@@ -13,7 +13,12 @@
  *   1. work-item-exit-gate.js  — exists in the installed rdc-skills hooks AND is
  *      referenced by a registered hook command (PreToolUse).
  *   2. truth-gate.mjs          — exists in the repo's .claude/hooks AND is
- *      registered on Stop and SubagentStop in .claude/settings.json.
+ *      reachable from Stop and SubagentStop: either registered directly in
+ *      .claude/settings.json, or invoked by the stage dispatcher
+ *      (hooks/stages/stop.mjs / subagent-stop.mjs) that event registers, per
+ *      the post-2026-09-02 stage-merge architecture (AGENTS.md "Hook parity").
+ *      repoRoot is resolved by walking up from cwd to the nearest
+ *      .claude/settings.json (worktree-safe), never a hardcoded main-tree path.
  *   3. the LIVE hookify plugin hooks.json — the plugin's OWN hooks manifest under
  *      ~/.claude/plugins/cache/.../hookify/<hash>/hooks/hooks.json.
  *      ⛔ It deliberately does NOT trust the dead ~/.claude/hooks/hookify-*.js
@@ -34,13 +39,88 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
-const REPO_ROOT = process.env.RDC_TRUTH_GATE_REPO || 'C:/Dev/regen-root';
 const HOOKS_DIR = __dirname; // installed rdc-skills hooks dir (where this file lives)
 
 function readJsonSafe(p) {
   try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) { return null; }
 }
 
+/**
+ * Walk up from startCwd looking for a `.claude/settings.json` — the same
+ * convention codeflow-hooks-selfcheck.js already uses. This is what makes the
+ * watchdog worktree-safe: a lane session's cwd is its own worktree
+ * (C:/Dev/regen-root.wt/<lane>), never the main tree, and hardcoding
+ * C:/Dev/regen-root here would silently check a DIFFERENT checkout's files —
+ * exactly the cross-tree-hardcode anti-pattern the repo's own CLAUDE.md warns
+ * every lane session about. RDC_TRUTH_GATE_REPO remains a manual override for
+ * the rare case cwd isn't inside a worktree at all (e.g. a bare probe).
+ */
+function findRepoRoot(startCwd) {
+  let dir = startCwd || process.cwd();
+  for (let i = 0; i < 8; i++) {
+    if (fs.existsSync(path.join(dir, '.claude', 'settings.json'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/** Expand ${VAR:-default} / ${VAR} / $VAR references against process.env. */
+function expandEnvRefs(str) {
+  return String(str)
+    .replace(/\$\{([A-Z_][A-Z0-9_]*):-([^}]*)\}/gi, (_, name, dflt) => process.env[name] || dflt)
+    .replace(/\$\{([A-Z_][A-Z0-9_]*)\}/gi, (_, name) => process.env[name] || '')
+    .replace(/\$([A-Z_][A-Z0-9_]*)/gi, (_, name) => process.env[name] || '');
+}
+
+/** Pull every quoted/bare .mjs or .js path out of a hook command string. */
+function extractScriptPaths(command) {
+  const out = [];
+  const re = /["']([^"']+\.(?:mjs|js))["']|(\S+\.(?:mjs|js))/gi;
+  let m;
+  while ((m = re.exec(command))) out.push(expandEnvRefs(m[1] || m[2]));
+  return out;
+}
+
+/**
+ * Is `needle` reachable from this event's registered hook commands, either
+ * directly in the command text (old one-hook-per-registration style) or via a
+ * stage dispatcher (hooks/stages/stop.mjs, subagent-stop.mjs, ...) that the
+ * command invokes and whose OWN source references the needle?
+ *
+ * Since the 2026-09-02 stage merge (see AGENTS.md "Hook parity"), Claude Code
+ * registers ONE dispatcher per event that fans out internally — the literal
+ * hook filename never appears in settings.json's command text anymore, only
+ * inside the dispatcher script it points at. A plain substring check against
+ * commandText alone is a false positive under that architecture; this walks
+ * one hop into each referenced script before concluding "not registered".
+ */
+function truthGateWiredForEvent(commandText, event, needle, { maxDepth = 2 } = {}) {
+  const lines = commandText.split('\n').filter((l) => l.startsWith(`${event}::`));
+  if (lines.some((l) => l.includes(needle))) return true;
+  const seen = new Set();
+  const visit = (scriptPath, depth) => {
+    if (depth > maxDepth) return false;
+    const norm = path.normalize(scriptPath).toLowerCase();
+    if (seen.has(norm)) return false;
+    seen.add(norm);
+    let src;
+    try { src = fs.readFileSync(scriptPath, 'utf8'); } catch (_) { return false; }
+    if (src.includes(needle)) return true;
+    for (const p of extractScriptPaths(src)) {
+      if (fs.existsSync(p) && visit(p, depth + 1)) return true;
+    }
+    return false;
+  };
+  for (const line of lines) {
+    for (const p of extractScriptPaths(line)) {
+      if (fs.existsSync(p) && visit(p, 1)) return true;
+    }
+  }
+  return false;
+}
+
 /** Serialize all hook command strings in a settings.json hooks object. */
 function settingsCommandText(settings) {
   if (!settings || !settings.hooks || typeof settings.hooks !== 'object') return '';
@@ -103,7 +183,11 @@ function deadWrapperPluginRoot(home) {
  * object consumed by the pure evaluator. Kept separate from evaluateWatchdog so
  * the decision logic is unit-testable without a filesystem.
  */
-function gatherFacts({ home = os.homedir(), repoRoot = REPO_ROOT, hooksDir = HOOKS_DIR } = {}) {
+function gatherFacts({
+  home = os.homedir(),
+  repoRoot = findRepoRoot(process.cwd()) || process.env.RDC_TRUTH_GATE_REPO || 'C:/Dev/regen-root',
+  hooksDir = HOOKS_DIR,
+} = {}) {
   const exitGatePath = path.join(hooksDir, 'work-item-exit-gate.js');
   const truthGatePath = path.join(repoRoot, '.claude', 'hooks', 'truth-gate.mjs');
   // Claude Code enforces the MERGED user+project hook set. A gate registered in
@@ -131,8 +215,8 @@ function gatherFacts({ home = os.homedir(), repoRoot = REPO_ROOT, hooksDir = HOO
     exitGateFileExists: fs.existsSync(exitGatePath),
     exitGateRegistered: registeredForEvent(commandText, 'PreToolUse', 'work-item-exit-gate.js'),
     truthGateFileExists: fs.existsSync(truthGatePath),
-    truthGateOnStop: registeredForEvent(commandText, 'Stop', 'truth-gate.mjs'),
-    truthGateOnSubagentStop: registeredForEvent(commandText, 'SubagentStop', 'truth-gate.mjs'),
+    truthGateOnStop: truthGateWiredForEvent(commandText, 'Stop', 'truth-gate.mjs'),
+    truthGateOnSubagentStop: truthGateWiredForEvent(commandText, 'SubagentStop', 'truth-gate.mjs'),
     liveHookifyManifestExists: Boolean(liveHookifyManifest),
     liveHookifyManifestPath: liveHookifyManifest,
     // Drift: a dead wrapper that points at a different cache hash than the live one.
@@ -253,5 +337,9 @@ if (require.main === module) {
     findLiveHookifyManifest,
     settingsCommandText,
     registeredForEvent,
+    findRepoRoot,
+    truthGateWiredForEvent,
+    extractScriptPaths,
+    expandEnvRefs,
   };
 }

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

@@ -119,9 +119,23 @@ const DEFAULT_SUPABASE_URL = 'https://uvojezuorjgqzmhhgluu.supabase.co';
 // ---------------------------------------------------------------------------
 
 /** True when the Bash command is a real `git commit` (not e.g. `git commit --help`). */
+// `git` must be the command word: start of the text or after a shell separator
+// (`;` `&&` `||` `|` `(` `$(` newline), optionally behind VAR=value assignments,
+// with only git's own global options (`-C <dir>`, `-c k=v`, `--no-pager`, …)
+// between it and `commit`. The old test — the words "git" and "commit" anywhere
+// on one line — fired on prose inside a quoted argument (an issue body, a lesson
+// description) and on `git log --grep commit`.
+const GIT_COMMIT_INVOCATION = new RegExp(
+  String.raw`(?:^|[\n;&|(]|\$\()\s*` +                       // command position
+  String.raw`(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S*)\s+)*` + // VAR=value prefixes
+  'git' +
+  String.raw`(?:\s+(?:-[Cc]\s+(?:"[^"]*"|'[^']*'|\S+)|--?[A-Za-z][\w-]*(?:=(?:"[^"]*"|'[^']*'|\S+))?))*` + // global options
+  String.raw`\s+commit\b`,
+);
+
 function isGitCommit(command) {
   if (typeof command !== 'string') return false;
-  if (!/\bgit\b[^\n]*\bcommit\b/.test(command)) return false;
+  if (!GIT_COMMIT_INVOCATION.test(command)) return false;
   if (/\bcommit\b[^\n]*--help/.test(command) || /\bcommit\b[^\n]*\s-h\b/.test(command)) return false;
   return true;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/rdc-skills",
-  "version": "0.37.2",
+  "version": "0.37.5",
   "description": "RDC typed-agent dispatch skill suite for Claude Code - plan, build, review, overnight builds",
   "keywords": [
     "claude-code",
@@ -19,7 +19,7 @@
     "type": "plugin",
     "skills": "skills/",
     "guides": "guides/",
-    "version": "0.37.2",
+    "version": "0.37.5",
     "commands": "commands/"
   },
   "bin": {
@@ -45,7 +45,7 @@
     "rdc-design": "node scripts/rdc-design-cli.mjs",
     "test:hooks": "node scripts/test-rdc-hooks.mjs",
     "test:truth-gate": "node tests/run-evidence-gate.test.mjs && node tests/work-item-exit-gate-l2.test.mjs && node tests/work-item-exit-gate-l3.test.mjs && node tests/require-work-item-on-commit.test.mjs && node tests/harness-gates.test.mjs && node tests/foreground-process-gate.test.mjs",
-    "test:acceptance": "node tests/acceptance.test.mjs && node tests/install-rdc-skills.test.mjs && node tests/help-surface.test.mjs && node tests/manifest-contract-fields.test.mjs && node --test tests/manifest-version-parity.test.mjs && node tests/plugin-namespace-names.test.mjs && node tests/skill-test-matrix.test.mjs && node tests/completion-gate-supervisor-admission.test.mjs && node tests/curl-surface.test.mjs && node tests/clauth-plugin-postinstall.test.mjs && node tests/install-duplicate-purge.test.mjs",
+    "test:acceptance": "node tests/acceptance.test.mjs && node tests/install-rdc-skills.test.mjs && node tests/help-surface.test.mjs && node tests/manifest-contract-fields.test.mjs && node --test tests/manifest-version-parity.test.mjs && node tests/plugin-namespace-names.test.mjs && node tests/skill-test-matrix.test.mjs && node tests/completion-gate-supervisor-admission.test.mjs && node tests/curl-surface.test.mjs && node tests/clauth-plugin-postinstall.test.mjs && node tests/install-duplicate-purge.test.mjs && node --test tests/install-stale-checkout.test.mjs tests/publish-manifest-staging-gates.test.mjs",
     "acceptance": "node scripts/acceptance.mjs --changed",
     "test:mcp": "node tests/mcp.test.mjs",
     "test:mcp:remote": "node tests/mcp.test.mjs --remote",

package/scripts/acceptance.mjs

@@ -30,7 +30,7 @@ const ENGINE = arg('--engine', process.env.RDC_ACCEPTANCE_ENGINE || 'claude').to
 const BASE = arg('--base', process.env.RDC_ACCEPTANCE_BASE || 'HEAD~1');
 const PROJECT_CWD = resolve(arg('--project-root', process.env.REGEN_ROOT || process.cwd()));
 const RUN_ID = arg('--run-id', `acceptance-${new Date().toISOString().replace(/[:.]/g, '-')}`);
-const PARALLEL = Math.max(1, parseInt(arg('--parallel', '1'), 10) || 1);
+const PARALLEL = Math.max(1, Number.parseInt(arg('--parallel', '1'), 10) || 1);
 const CHANGED = has('--changed');
 const STRICT_RECORDING = has('--strict-recording');
 const ONLY_SKILLS = args
@@ -488,7 +488,10 @@ export { assistantText, codexToolCalls, normalizeSkillName };
 
 const isMain = (() => {
   try {
-    return import.meta.url === new URL(`file://${process.argv[1].replace(/\\/g, '/')}`).href;
+    // Compare paths, not URLs: import.meta.url percent-encodes `~` (%7E) and a
+    // hand-built URL keeps it, so under a Windows 8.3 path (C:\Users\NAME~1\...)
+    // the URL comparison was never equal and main() silently never ran (exit 0).
+    return fileURLToPath(import.meta.url) === resolve(process.argv[1]);
   } catch {
     return false;
   }

package/scripts/install-rdc-skills.js

@@ -30,7 +30,7 @@ const fs           = require('fs');
 const path         = require('path');
 const os           = require('os');
 const readline     = require('readline');
-const { execSync } = require('child_process');
+const { execSync, execFileSync } = require('child_process');
 
 // ── Args ──────────────────────────────────────────────────────────────────────
 const args       = process.argv.slice(2);
@@ -568,6 +568,26 @@ function cleanGlobalSkillsRoot(skillsDir) {
   return removed;
 }
 
+// ── Stale checkout warning (LIFEAI/regen-root#230) ────────────────────────────
+// The installer links .claude/skills and copies hooks from ITS OWN package root.
+// Run from a dev clone parked on an old branch, it serves that branch's skills to
+// every session. `git pull` above only fast-forwards the current branch, so a
+// feature branch stays behind master after it. Warn, never refuse — installing
+// from a branch is sometimes the point. Returns { behind, branch } or null when
+// root is not a git checkout (an npm install) or origin/master is unknown.
+function checkoutBehindMaster(root) {
+  if (!fs.existsSync(path.join(root, '.git'))) return null;
+  const run = (args) => execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: 'pipe' }).trim();
+  try {
+    const behind = Number(run(['rev-list', '--count', 'HEAD..origin/master']));
+    let branch = '';
+    try { branch = run(['branch', '--show-current']); } catch {}
+    return { behind, branch: branch || '(detached)' };
+  } catch {
+    return null;
+  }
+}
+
 // ── Stale hook cleanup ────────────────────────────────────────────────────────
 // Remove ONLY explicitly orphaned hook files — hooks that were previously shipped
 // by rdc-skills and have since been removed from the project.
@@ -579,6 +599,10 @@ function cleanStaleHooks(hooksDstDir) {
   // Format: filename that should be deleted if it still exists.
   const ORPHANED_HOOKS = [
     'verify-rdc-skills.js', // removed in v0.9.7 — was checking for old flat-file format
+    // removed in v0.37.5 — shipped behind env flags nothing ever set, so every
+    // call was a no-op (LIFEAI/regen-root#237).
+    'task-completed-gate.js',
+    'post-tool-batch-gate.js',
   ];
   let removed = 0;
   for (const f of ORPHANED_HOOKS) {
@@ -1063,15 +1087,6 @@ function buildHooksConfig(hooksDir, profile = 'core') {
     config.PreToolUse[0].hooks.push(
       cmd('work-item-exit-gate.js', 'Checking work item exit gates...'),
     );
-    // Truth Gate 3.0 Layer 5 — harness completion gates. Both blocking hooks are
-    // FLAG-GATED, default OFF (no-op until the env/DB flag is flipped at deploy),
-    // so registering them does NOT disrupt the in-flight build session.
-    config.TaskCompleted = [{ hooks: [
-      cmd('task-completed-gate.js', 'Truth Gate: verifying task closure...'),
-    ]}];
-    config.PostToolBatch = [{ hooks: [
-      cmd('post-tool-batch-gate.js', 'Truth Gate: checking build-wave worktree bases...'),
-    ]}];
     config.PreCompact = [{ hooks: [
       cmd('precompact-log.js'),
     ]}];
@@ -1271,6 +1286,14 @@ async function main() {
   } catch {
     warn('[0/6] git pull failed — installing from local copy');
   }
+  {
+    const stale = checkoutBehindMaster(repoRoot);
+    if (stale && stale.behind > 0) {
+      warn(`[0/6] this checkout (${stale.branch}) is ${stale.behind} commit(s) behind origin/master — `
+        + 'every session will get these older skills and hooks.');
+      warn('       Install from the published package instead: npm i -g @lifeaitools/rdc-skills && rdc-skills-install');
+    }
+  }
 
   // Read version + git SHA after pull so plugin caches and the MCP install do
   // not stamp the pre-update checkout.
@@ -1533,7 +1556,7 @@ async function main() {
 // scripts/probe-installed-hooks.mjs verify the real install path instead of
 // re-implementing it — a probe that copies its own way proves nothing about what
 // ships. Without this guard, requiring the module would run a full install.
-module.exports = { copyHookFiles, assertHooksLoadable, registerCodexTarget, syncMarketplaceCheckout, RDC_ENV_HOOK_TIMEOUT_SEC, isRdcSkillDuplicate, cleanUserSkills, cleanGlobalSkillsRoot, shippedSkillNames, isProvablyOurRdcSkill, disposeRdcDuplicate, rdcQuarantineDir };
+module.exports = { checkoutBehindMaster, copyHookFiles, assertHooksLoadable, registerCodexTarget, syncMarketplaceCheckout, RDC_ENV_HOOK_TIMEOUT_SEC, isRdcSkillDuplicate, cleanUserSkills, cleanGlobalSkillsRoot, shippedSkillNames, isProvablyOurRdcSkill, disposeRdcDuplicate, rdcQuarantineDir };
 
 if (require.main === module) {
   main().catch(e => { fail(e.message); process.exit(1); });

package/scripts/rdc-release.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * Commit and tag one declared release change set.
+ *
+ * The wrapper owns the only documented commit/tag path so the staged-path
+ * guard runs while there is still something to reject.
+ */
+import { execFileSync, spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+function fail(message) {
+  process.stderr.write(`rdc-release: ${message}\n`);
+  process.exit(2);
+}
+
+function git(repo, args, options = {}) {
+  return execFileSync('git', args, { cwd: repo, encoding: 'utf8', ...options });
+}
+
+function readArgs(argv) {
+  const result = { allow: [], dryRun: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--dry-run') {
+      result.dryRun = true;
+      continue;
+    }
+    if (!['--repo', '--allow', '--message', '--tag'].includes(arg)) fail(`unknown argument ${arg}`);
+    const value = argv[index + 1];
+    if (!value || value.startsWith('--')) fail(`${arg} requires a value`);
+    index += 1;
+    if (arg === '--allow') result.allow.push(value);
+    else result[arg.slice(2)] = value;
+  }
+  return result;
+}
+
+function normalizedPath(value) {
+  const normalized = value.replaceAll('\\', '/');
+  if (!normalized || path.posix.isAbsolute(normalized) || normalized.split('/').includes('..')) {
+    fail(`--allow must be a repository-relative path: ${value}`);
+  }
+  return normalized.replace(/^\.\//, '');
+}
+
+const options = readArgs(process.argv.slice(2));
+if (!options.repo || !options.message || !options.tag || options.allow.length === 0) {
+  fail('usage: rdc-release --repo <path> --allow <path> [--allow <path>] --message <message> --tag <tag> [--dry-run]');
+}
+
+const repo = path.resolve(options.repo);
+try {
+  git(repo, ['rev-parse', '--is-inside-work-tree']);
+} catch {
+  fail(`not a Git worktree: ${repo}`);
+}
+
+const allowed = new Set(options.allow.map(normalizedPath));
+// A rename is two release-relevant paths: the removed source and the added
+// destination. Disable Git's similarity presentation so neither can disappear
+// behind a single destination path in the allowlist check.
+const staged = git(repo, ['diff', '--cached', '--no-renames', '--name-only', '-z'])
+  .split('\0')
+  .filter(Boolean)
+  .map((value) => value.replaceAll('\\', '/'));
+if (staged.length === 0) fail('no staged release paths; run this before committing');
+
+const stagedSet = new Set(staged);
+const undeclared = staged.filter((file) => !allowed.has(file));
+const missing = [...allowed].filter((file) => !stagedSet.has(file));
+if (undeclared.length || missing.length) {
+  const details = [
+    undeclared.length ? `undeclared staged path(s): ${undeclared.join(', ')}` : null,
+    missing.length ? `declared path(s) not staged: ${missing.join(', ')}` : null,
+  ].filter(Boolean);
+  fail(details.join('; '));
+}
+
+const tagCheck = spawnSync('git', ['check-ref-format', `refs/tags/${options.tag}`], { cwd: repo, encoding: 'utf8' });
+if (tagCheck.status !== 0) fail(`invalid tag: ${options.tag}`);
+const existingTag = spawnSync('git', ['rev-parse', '--verify', '--quiet', `refs/tags/${options.tag}`], { cwd: repo, encoding: 'utf8' });
+if (existingTag.status === 0) fail(`tag already exists: ${options.tag}`);
+
+if (options.dryRun) {
+  process.stdout.write(`rdc-release: dry-run passed for ${staged.length} declared path(s); would commit and tag ${options.tag}\n`);
+  process.exit(0);
+}
+
+git(repo, ['commit', '-m', options.message], { stdio: 'inherit' });
+git(repo, ['tag', options.tag], { stdio: 'inherit' });
+process.stdout.write(`rdc-release: committed ${staged.length} declared path(s) and created ${options.tag}\n`);

package/scripts/validate-publish-manifests.js

@@ -240,10 +240,7 @@ function parseFrontmatter(content) {
 function parseSurfaceIds(content) {
   const ids = [];
   const re = /<!--\s*SURFACE:([a-zA-Z0-9_-]+)\s*-->/g;
-  let m;
-  while ((m = re.exec(content)) !== null) {
-    ids.push(m[1]);
-  }
+  for (const m of content.matchAll(re)) ids.push(m[1]);
   return ids;
 }
 
@@ -392,6 +389,32 @@ function validateApp(slug) {
   return { fm, surfaceIds, publishPath };
 }
 
+/**
+ * `staging_gates:` must be a MAPPING (`  tsc_clean: true`), never a list
+ * (`  - tsc_clean`) — the shape scripts/gen-deploy-blocks.mjs emits. A list was
+ * once hand-written and parsed as the wrong type downstream. Returns an error
+ * string, or null when the key is absent or correctly shaped.
+ */
+function stagingGatesShapeError(body) {
+  const lines = String(body).split(/\r?\n/);
+  const at = lines.findIndex((l) => /^staging_gates:\s*(#.*)?$/.test(l));
+  if (at === -1) {
+    const inline = lines.find((l) => /^staging_gates:\s*\S/.test(l) && !/^staging_gates:\s*#/.test(l));
+    return inline ? `DEPLOY block staging_gates must be a mapping on its own lines, not inline: '${inline.trim()}'` : null;
+  }
+  const entries = [];
+  for (const l of lines.slice(at + 1)) {
+    if (!l.trim() || /^\s*#/.test(l)) continue;
+    if (!/^\s/.test(l)) break; // next top-level key
+    entries.push(l.trim());
+  }
+  const listItem = entries.find((e) => e.startsWith('-'));
+  if (listItem) return `DEPLOY block staging_gates must be a mapping (key: value), not a list item: '${listItem}'`;
+  const bad = entries.find((e) => !/^[A-Za-z0-9_]+:\s*\S/.test(e));
+  if (bad) return `DEPLOY block staging_gates entry is not 'key: value': '${bad}'`;
+  return null;
+}
+
 /**
  * Validate the <!-- DEPLOY --> block. Returns true iff valid.
  * Contract: .claude/rules/app-deploy-manifest.md (port-from-registry, Approved 2026-07-05).
@@ -412,6 +435,12 @@ function validateDeployBlock(slug, content, publishPath) {
     }
   }
 
+  const gatesError = stagingGatesShapeError(body);
+  if (gatesError) {
+    emit('FAIL', slug, gatesError, publishPath);
+    ok = false;
+  }
+
   const portLine = body.match(/^port:\s*([^\s#]+)/m);
   if (portLine) {
     const val = portLine[1].trim();
@@ -525,7 +554,11 @@ async function main() {
   process.exit(hasHardFail ? 1 : 0);
 }
 
-main().catch((err) => {
-  console.error(`FATAL: ${err.message}`);
-  process.exit(1);
-});
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(`FATAL: ${err.message}`);
+    process.exit(1);
+  });
+} else {
+  module.exports = { stagingGatesShapeError };
+}

package/skills/build/SKILL.md

@@ -747,6 +747,10 @@ NEVER run pnpm build or pnpm turbo. Use npx vitest run only.
 - Unattended: max 2 retries per task before escalating to advisor
 - Every Agent() dispatch: `model: <routed>` + `max_turns: 70` — non-negotiable. Every dispatched writer uses `isolation: "worktree"` after the HARD GATE; non-isolated agents are read-only. Model is chosen per task per the routing table in Step 7. Exception: the validator omits isolation because it is read-only and must inspect merged source.
 - Finding an existing file is NOT task completion — verify it satisfies the spec
+- **A blocker only a human can clear** (a secret to set, an approval, a manual prod step):
+  file it as a `human_items` row, then `node "$LIFEAI_ENV/bin/rdc-work.mjs" hold --work-item <leaf-uuid> --reason "<blocker> — human_items <id>"`
+  (and the same for the epic), and end the turn. `hold` sets `blocked` and releases the
+  Stop gate; leaving the item `in_progress` keeps the completion gate firing on work nobody can do.
 
 ## Capture lessons (exit step)
 

package/skills/collab/SKILL.md

@@ -502,6 +502,8 @@ chitchat MCP + SSE; you are the build half of a live session.
   or a non-200 is a real failure (lesson `2026-06-08-collab-sse-exit-28-is-success`).
 - Poll fallback: `chitchat_poll` at 2s — `{status:"idle"}` keep polling,
   `{status:"ready", message}` consume.
+- A `build-*-verify` session closes itself after the ready handshake. A later
+  `not_found` on poll there is expected, not a failure.
 - `type: stop` ends the session; send a final summary, then `chitchat_stop`.
 - Stream progress mid-work with `chitchat_reply` on long tasks.