@lifeaitools/rdc-skills 0.37.4 → 0.37.5

package/.claude-plugin/plugin.json

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

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.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.4",
+    "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/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.
 

package/skills/edit/SKILL.md

@@ -93,6 +93,14 @@ launch if it is dead.
   ```
 
 ### 4. Open the page
+- **Probe the resolved `targetUrl` before calling the preview open** (skip for
+  `brandSlug=test`). The editor host on 3015 can be up while the iframe target
+  returns a 500 (e.g. a Supabase-gated app with no local `.env.local`):
+  ```bash
+  curl -s -o /dev/null -w "%{http_code}" <targetUrl>/
+  ```
+  Non-2xx: do not report the preview as open. Report the status code and the first
+  error line from the target's dev-server log, and stop.
 - Normal use: open the URL in the browser and confirm the editor loaded.
   Open via PowerShell `Start-Process`, NOT `cmd start` — `cmd` treats the `&`
   between query params as a command separator and truncates the URL:

package/skills/fixit/SKILL.md

@@ -50,11 +50,18 @@ SELECT insert_work_item(
   p_item_type := 'bug',
   p_priority  := 'urgent',
   p_status    := 'in_progress',
-  p_source    := 'fixit'
+  p_source    := 'fixit',
+  p_session_id := '<agent-session-id>',
+  p_checklist := '[
+    {"id":"decomp-fix","text":"<the fix, one line>","required":true,"checked":false},
+    {"id":"test-fix-proof","text":"<command that proves the defect is gone> exits 0","required":true,"checked":false}
+  ]'::jsonb
 );
 ```
 
-Note the returned `id`.
+Note the returned `id`. The two rows are not optional: `update_work_item_status(...,'done')`
+refuses any non-epic item without a required `decomp-*` AND a required `test-*` row.
+`p_session_id` must be this session — only it may tick them.
 
 ### 2a. Declare the fix and its proof (before touching any code)
 
@@ -99,6 +106,7 @@ files, and verify behavior before moving the work item to `review`.
 
 ```bash
 git add <specific files only — never git add -A for a fixit>
+git diff --cached --stat   # every staged file and hunk must be yours
 git commit -m "fix(<scope>): <description>"
 if [ "$RDC_TEST" != "1" ]; then
   git push origin {development-branch}
@@ -107,6 +115,10 @@ else
 fi
 ```
 
+`git add <file>` stages every hunk in that file, including another session's
+uncommitted edit. If a file was already dirty before you touched it, stage with
+`git add -p <file>` and take only your hunks.
+
 ### 5.5 Mandatory code-review gate (before submitting implementation report)
 
 ⛔ **No fixit closes without a code-review pass.** Even single-file changes go through review.
@@ -144,7 +156,7 @@ complete it:
 
 | Target shape | "Done" = delivered means | How + structural proof |
 |---|---|---|
-| Published package (npm / PyPI) | new version live on the registry | run the repo's release/publish path (e.g. `npm publish --access public`); verify `npm view <pkg> version` == new version |
+| Published package (npm / PyPI) | new version live on the registry | run the repo's release/publish path (e.g. `npm publish --access public`); verify `curl -fsS https://registry.npmjs.org/<pkg>/<version>` returns 200 (exact version; `npm view` lags the registry) |
 | Deployed app (`apps/*`, sites) | change live on the running host | `/rdc:deploy <slug>` (dev) / `promote` (prod); verify HTTP 200 + content probe |
 | Shared lib consumed in-repo | landed on the integration branch | `node scripts/land.mjs` (or repo equivalent); verify branch contains the SHA |
 | Standalone repo | its own release ritual completed | follow the repo's release script/tag; verify the artifact/tag exists |
@@ -172,11 +184,15 @@ is fleet-wide yet — its absence is not itself a fixit failure.
 
 ### 6. Close and clean up
 
-Submit implementation report first, move to review, then close as validator.
+Tick the two checklist rows from Step 2 as the originating session (after the proof
+command passes), submit the implementation report, move to review, then close as validator.
 **Precondition: Step 5.7 delivery is verified.** If delivery is blocked, set status
 `blocked` (not `done`) with the remaining step — never mark `done` on an undelivered change:
 
 ```sql
+SELECT update_checklist_item('<id>'::uuid, 'decomp-fix',     true, '<agent-session-id>', 'agent');
+SELECT update_checklist_item('<id>'::uuid, 'test-fix-proof', true, '<agent-session-id>', 'agent');
+
 SELECT submit_implementation_report('<id>'::uuid,
   '{"tldr":"<one sentence>","assumptions":[],"deviations":[],"uncertainty":[],"detail":"<what was fixed>","flags":[],"transactional":false,"memory_records":[],"codeflow_post":{"agent_session_id":"<agent-session-id>","summary":"<what changed and why>","files_changed":["<path>"],"verification":["<command/evidence>"],"commit":"<hash optional>"}}'::jsonb
 );
@@ -194,6 +210,10 @@ SELECT update_work_item_status('<id>'::uuid, 'done',
 );
 ```
 
+If `done` is rejected as `close_blocked_uninstrumented` (an item created without the
+rows), add them and tick them, then retry:
+`SELECT append_checklist_item('<id>'::uuid, 'test-fix-proof', '<proof>', true, '<agent-session-id>', 'agent');`
+
 If the fix touched a transactional flow, API boundary, or package contract, set `"transactional": true` and populate `memory_records` (see `agent-bootstrap.md`), then run:
 ```bash
 node scripts/work-item-memory.mjs <work-item-id>

package/skills/plan/SKILL.md

@@ -317,6 +317,8 @@ choose the most conservative/reversible approach and document the decision.
 - Interactive: ALWAYS get approval before proceeding to build
 - Unattended: proceed immediately without approval
 - Plan doc goes in `.rdc/plans/` (fallback: `.rdc/plans/` if `.rdc/` does not exist) — not `.planning/`
+- An architecture or spec draft that has not passed its approval interview goes in
+  `.rdc/research/<topic>-draft.md`. Nothing is written under `docs/systems/**` until it is approved.
 - Each work package must be independently executable by an agent
 - No file overlap between work packages
 - Include test requirements in every work package

package/skills/release/SKILL.md

@@ -34,6 +34,7 @@ If `<repo>` is not resolvable from the current workspace, ask for its local path
 rdc:release: <repo> vX.Y.Z -> vA.B.C
 [ ] PUBLISH.md status gate: status=active AND prod in environments (block if not)
 [ ] Source path resolved
+[ ] <repo>/RELEASE.md read (if present) — its steps override the generic flow below
 [ ] Release metadata read
 [ ] Working tree clean or user-approved dirty scope identified
 [ ] Current version detected
@@ -81,8 +82,13 @@ these was in the command and NOT in this file, which is precisely the drift that
 shipping one verb as two documents produces.
 
 - Do not release without explicit user authorization.
-- Prefer repo-local release instructions in `.rdc/release.json`, README, package
-  scripts, or CI workflows.
+- **Read `<repo>/RELEASE.md` first.** When it exists it is the release procedure
+  and overrides everything generic in this skill (branch, who publishes — a tag
+  workflow, a push hook or you — and post-publish gates). Otherwise prefer
+  `.rdc/release.json`, README, package scripts, or CI workflows.
+- **`E403`/`E409` "cannot publish over the previously published version" right
+  after a push or tag usually means CI already published it.** Verify the exact
+  version on the registry; never bump again to get past it.
 - **Never force push or bypass hooks.**
 - **Never declare success without verifying the installed or deployed version.**
   A publish that exits 0 is not a published package — the registry can lag
@@ -123,7 +129,10 @@ node scripts/rdc-release.mjs --repo <repo-path> \
   --message "chore(release): vA.B.C" --tag vA.B.C
 git push origin HEAD
 git push origin vA.B.C
-npm view <package-name> version
+# exact-version fetch: 200 = published. `npm view` reads a cache that can 404
+# for minutes after a successful publish.
+curl -fsS -o /dev/null -w "%{http_code}
+" https://registry.npmjs.org/<package-name>/A.B.C
 ```
 
 The wrapper owns this documented commit-and-tag step. It compares the exact

package/skills/status/SKILL.md

@@ -57,12 +57,10 @@ description: rdc:status () — snapshot open epics, health, blockers and next ac
    ```
 
 6. **Dev server health (PM2):**
-   SSH into the Coolify server and check PM2 process state:
+   Read PM2 process state on the dev host through the sanctioned wrapper (it loads
+   the clauth-held key into ssh-agent; a raw key fetch is guard-blocked):
    ```bash
-   # Note: clauth key name for the SSH key may vary by project. Common names: ssh-key-path, vultr-ssh-key, dev-ssh-key.
-   # Check available keys with: curl -s http://127.0.0.1:52437/list-services
-   SSH_KEY=$(curl -s http://127.0.0.1:52437/v/ssh-key-path)
-   ssh -i "$SSH_KEY" -o StrictHostKeyChecking=no root@64.237.54.189 "pm2 jlist 2>/dev/null"
+   bash "$LIFEAI_ENV/services/ssh-clauth.sh" "pm2 jlist 2>/dev/null"
    ```
    Parse the JSON array — for each process note `name`, `pm2_env.status` (online/stopped/errored), and `pm2_env.pm_uptime`.
    If SSH fails or PM2 returns nothing, note "PM2 unreachable" and continue.