@lifeaitools/rdc-skills 0.37.4 → 0.37.7

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rdc",
-  "version": "0.37.4",
+  "version": "0.37.7",
   "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.4",
+  "version": "0.37.7",
   "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": "7174da1ee88b03b186bfc102a951ac2f770aec6c"
+  "sha": "9621389d4e4724ae260e0d4e91651c10b3ac0e2c"
 }

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.4",
+  "version": "0.37.7",
   "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.4",
+    "version": "0.37.7",
     "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) {
@@ -927,7 +951,7 @@ function findCodexTargets() {
   return targets;
 }
 
-function registerCodexTarget(targetDir) {
+function registerCodexTarget(targetDir, { install = false } = {}) {
   fs.mkdirSync(targetDir, { recursive: true });
 
   // Clean: remove dirs that are rdc skills — by prefix OR by frontmatter name
@@ -943,11 +967,21 @@ function registerCodexTarget(targetDir) {
     }
   }
 
-  // Do not reinstall file-based copies. Codex discovers the live catalog via
-  // [mcp_servers.rdc-skills]. Keeping the same skills in ~/.codex and ~/.agents
-  // registers every skill two or three times, exhausts Codex's skill metadata
-  // budget, and emits a red startup error on every session.
-  return { removed, copied: 0 };
+  if (!install) return { removed, copied: 0 };
+
+  // Install into exactly ONE Codex skill dir. Copies in both ~/.codex and
+  // ~/.agents registered every skill twice and exhausted Codex's skill metadata
+  // budget; bf88292 answered that by installing none, which left Codex with
+  // rdc: skills only while the remote MCP was reachable.
+  const skillsSrc = path.join(repoRoot, 'skills');
+  let copied = 0;
+  for (const entry of fs.readdirSync(skillsSrc, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    if (!fs.existsSync(path.join(skillsSrc, entry.name, 'SKILL.md'))) continue;
+    copyDirRecursive(path.join(skillsSrc, entry.name), path.join(targetDir, `rdc-${entry.name}`));
+    copied++;
+  }
+  return { removed, copied };
 }
 
 // ── Step 6: Zip for claude.ai / distribution ─────────────────────────────────
@@ -1063,15 +1097,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 +1296,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.
@@ -1349,21 +1382,24 @@ async function main() {
     info('[2.5] MCP        — rdc-skills endpoint verified (claude + codex)');
   }
 
-  // 2.6. Codex migration: MCP is authoritative; purge legacy file copies.
+  // 2.6. Codex: rdc skill files in ONE dir (the explicit one, else ~/.codex/skills);
+  // every other Codex skill dir is only cleaned, so nothing registers twice.
   const codexTargets = findCodexTargets();
-  if (codexTargets.length > 0) {
-    let copiedTotal = 0;
-    let removedTotal = 0;
-    for (const target of codexTargets) {
-      const { removed, copied } = registerCodexTarget(target.targetDir);
-      copiedTotal += copied;
-      removedTotal += removed;
-      info(`       ${target.label.padEnd(15)}: ${target.targetDir} (${removed} stale removed; MCP authoritative)`);
-    }
-    ok(`[2.6] Codex      — ${removedTotal} stale file-based skill(s) removed across ${codexTargets.length} target(s); MCP authoritative`);
-  } else {
-    info('[2.6] Codex      — skipped (no Codex skill dirs found; use --codex-root or --codex-skill-dir)');
+  const primaryCodexDir = explicitCodexSkillDir || path.join(os.homedir(), '.codex', 'skills');
+  if (!codexTargets.some((t) => t.targetDir === primaryCodexDir)) {
+    codexTargets.unshift({ label: 'global .codex', targetDir: primaryCodexDir });
+  }
+  let copiedTotal = 0;
+  let removedTotal = 0;
+  for (const target of codexTargets) {
+    const install = target.targetDir === primaryCodexDir;
+    const { removed, copied } = registerCodexTarget(target.targetDir, { install });
+    copiedTotal += copied;
+    removedTotal += removed;
+    info(`       ${target.label.padEnd(15)}: ${target.targetDir} (${install ? `${copied} installed` : 'cleaned only'}, ${removed} stale removed)`);
   }
+  if (copiedTotal === 0) throw new Error(`Codex skill install wrote nothing to ${primaryCodexDir}`);
+  ok(`[2.6] Codex      — ${copiedTotal} skill(s) installed in ${primaryCodexDir}; ${removedTotal} stale copies removed across ${codexTargets.length} dir(s)`);
 
   // 2.7. Symlinks in regen-root/.claude/skills/ (FS MCP + claude.ai access)
   if (codexRoot) {
@@ -1533,7 +1569,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/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/scripts/verify-live-install.mjs

@@ -178,10 +178,16 @@ function checkCodex(truth) {
     const rdcDirs = dirs.filter((e) => /^rdc-/.test(e.name) || readFrontmatterName(path.join(t.dir, e.name, 'SKILL.md'))?.startsWith('rdc:'));
     results.push({ label: t.label, dir: t.dir, count: rdcDirs.length });
   }
-  const pass = results.every((r) => r.count === 0);
-  const detail = results.map((r) =>
-    `${r.label}: ${r.count} legacy file-based rdc skill(s)${r.count === 0 ? '' : ' [MCP DUPLICATES PRESENT]'}`
-  ).join('; ');
+  // Codex keeps rdc skills as files in exactly one dir (~/.codex/skills), so it
+  // works without the network; any copy elsewhere registers the skill twice.
+  const skillsSrc = path.join(repoRoot, 'skills');
+  const expected = fs.readdirSync(skillsSrc, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(skillsSrc, e.name, 'SKILL.md'))).length;
+  const isPrimary = (r) => r.label === 'global .codex';
+  const pass = results.some(isPrimary) && results.every((r) => (isPrimary(r) ? r.count === expected : r.count === 0));
+  const detail = results.map((r) => (isPrimary(r)
+    ? `${r.label}: ${r.count}/${expected} rdc skill(s) installed`
+    : `${r.label}: ${r.count} rdc skill(s)${r.count === 0 ? '' : ' [DUPLICATES — would register twice]'}`)).join('; ');
   return { surface: 'Codex', pass, detail };
 }
 

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.
 

package/skills/deploy/SKILL.md

@@ -27,6 +27,20 @@ Run it from the regen-root checkout you are working in. That is the whole
 instruction. There is no checklist to follow, no mode to pick, and no decision
 for you to make on the success path.
 
+## Local build contract
+
+Standard dev deployment builds on the workstation first. `DEPLOY_MGR_URL`
+must name a loopback manager whose health response reports `host.role: local`.
+The program requests `builder: local` explicitly; Docker or build failure stops
+the deployment. It never falls back to a remote builder.
+
+The target must have a registered image route. Legacy remote build/reload routes
+are refused until a proper local artifact build-and-ship route is implemented.
+Do not enable an image route without its runtime and build configuration.
+
+The manager's explicitly requested remote maintenance operations remain separate
+from this standard command. `promote` remains build-free and approval-gated.
+
 ## Exit 0 — you are done
 
 Print the URL the program reports, and stop.
@@ -46,8 +60,8 @@ followed by the same record as one line of JSON.
 | exit | meaning | first move |
 |---|---|---|
 | 2 | usage — bad or missing arguments | read the usage line; this program takes a slug and optionally `promote` |
-| 3 | deploy manager unreachable | `pm2 restart regen-deploy-mgr` (it is a local PM2 process), then re-run |
-| 4 | slug not resolvable or not routable | the block names what is missing — a registry row, or an allowlist entry |
+| 3 | deploy manager unavailable or unsuitable for local building | read the block; restore the workstation manager and its local host identity, then re-run |
+| 4 | slug not resolvable or no local artifact route | the block names the missing registry or image route; repair that route before deployment |
 | 5 | a submitted job failed or was rejected | the block carries the manager's own step, command, exit code and stderr tail |
 | 6 | the job succeeded but the health probe did not | bytes shipped, app did not come up — read the job the block names |
 | 7 | polling exceeded the deadline | the job is NOT cancelled; the block gives the URL to read it |
@@ -110,9 +124,10 @@ manager, where it runs, rather than in a document that hopes to be read.
 
 A dev deploy needs no approval. `promote` puts bytes on production and needs
 explicit go-ahead for that call. The program itself refuses to promote anything
-that is not an image-model app, because promote retags the digest dev already
-runs — **a promote never builds**, and one that fell back to building would ship
-bytes production has never seen under a name claiming it had.
+that is not an image-model app. **A promote never builds**; it retags an existing
+image through the manager. The current manager resolves the configured dev tag
+(normally `develop`); a successful dev deploy alone does not prove that this
+mutable tag still identifies the running dev image when promotion begins.
 
 ## Verification