@lifeaitools/rdc-skills 0.30.1 → 0.31.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rdc",
-  "version": "0.30.1",
+  "version": "0.31.0",
   "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/.rdc/lessons/2026-08-17-fixit-codex-mcp-only-skills.md

@@ -0,0 +1,24 @@
+---
+id: 2026-08-17-fixit-codex-mcp-only-skills
+date: "2026-08-17"
+skill: fixit
+session: codex-mcp-startup-20260817
+scope: simple
+status: applied
+area: skill
+links:
+  commits:
+    - 263231a
+  memory: []
+  work_items:
+    - dc076f35-236b-4f8d-be3f-646a66514ba5
+---
+
+## What happened
+Codex's real numbered-lane startup completed MCP initialization but emitted a red skill-budget error on every launch. The machine had 36 RDC skill directories in each of the global `.codex/skills` and `.agents/skills` roots while the same 36-skill catalog was already registered through the RDC-Skills MCP endpoint.
+
+## Root cause
+`scripts/install-rdc-skills.js` registered the MCP endpoint and then copied the full RDC catalog into every detected Codex skill directory. Codex loaded those duplicate surfaces together, inflating startup metadata to 113 skills. The same install also left a legacy RDC marketplace block that Codex rejected as an unsupported plugin source.
+
+## The fix / rule
+Codex receives RDC skills exclusively through MCP. The installer now verifies the MCP config before purging legacy file copies, fails closed if the replacement cannot be established, removes the obsolete marketplace/plugin blocks with CRLF coverage, and verifies that live Codex skill roots contain zero RDC duplicates. Implemented in commit `263231a`.

package/README.md

@@ -209,6 +209,14 @@ Located in `guides/agents/` — plain markdown playbooks spawned as sub-agents:
 ### Reporting
 - rdc:help, rdc:housekeeping, rdc:report, rdc:status, rdc:watch
 
+### Operating mode
+- rdc:mode — show or set the operating mode. `HotFix` relaxes ceremony gates
+  (full-build, polling-loops, persistent-cd, truth-gate, completion-gate, …) for
+  a bounded, reasoned window. It **cannot** relax a safety guard: push-main,
+  push-force, rm-rf, credential exposure, cross-lane writes and the authority
+  check stay armed in every mode, enforced as an allowlist so a guard added
+  tomorrow is essential by default.
+
 ### Tooling
 - rdc:channel-formatter — channel-native formatting and content repurposing for LinkedIn, Twitter/X, Slack/Teams, email, decks, Word/PDF structure, web copy, and content packs
 - rdc:brochure — HTML/folder/zip/URL/Markdown to print-quality PDF

package/commands/build.md

@@ -1,5 +1,5 @@
 ---
-name: rdc:build
+name: build
 description: >-
   Usage `rdc:build <epic-id|topic> [--unattended]` — dispatch typed agents from an epic, commit, push, update work items. The build engine. Use after rdc:plan or when the project lead says "build it".
 ---

package/commands/collab.md

@@ -1,5 +1,5 @@
 ---
-name: rdc:collab
+name: collab
 description: >-
   Usage `rdc:collab --session <id>` — bidirectional relay with claude.ai. Read inbox, do work, write outbox, loop. Dave watches terminal and can interject.
 ---

package/commands/deploy.md

@@ -1,5 +1,5 @@
 ---
-name: rdc:deploy
+name: deploy
 description: >-
   Coolify ops. Usage `rdc:deploy <slug> [build-id]`, `rdc:deploy new <slug>`, `rdc:deploy maintenance <service>`, `rdc:deploy diagnose <slug>`, or `rdc:deploy audit [--fix]` — typed checklists, private-service controls, DNS decision tree, and mandatory post-deploy gates. Checklist-only output.
 ---

package/commands/design.md

@@ -1,5 +1,5 @@
 ---
-name: rdc:design
+name: design
 description: >-
   Usage `rdc:design <command|brief>` — RDC-owned design skill for Studio, Palette Library, token-aware UI work, and Rampa CLI-assisted color systems.
 ---

package/commands/edit.md

@@ -1,5 +1,5 @@
 ---
-name: rdc:edit
+name: edit
 description: >-
   Usage `rdc:edit <site|brand|route|file>` — open a target in the local website editor host on port 3015. Resolves the site, launches or reuses the editor, and opens the target URL when available.
 ---

package/commands/fixit.md

@@ -1,5 +1,5 @@
 ---
-name: rdc:fixit
+name: fixit
 description: >-
   Usage `rdc:fixit <description>` — sanctioned bypass for quick fixes under 5 files / 30 min. Creates minimal work item, makes fix, commits, DELIVERS it to where it is consumed (publish/deploy/land) and verifies, then closes. The ONLY alternative to rdc:build. For typos, config patches, hotfixes, dep bumps.
 ---

package/commands/handoff.md

@@ -1,5 +1,5 @@
 ---
-name: rdc:handoff
+name: handoff
 description: >-
   Usage `rdc:handoff <topic>` — structured handoff from planning session to CLI agents. Produces plan doc in .rdc/plans/, work items in DB, prototype registry entry if applicable. Use when plan/prototype is finalized and ready for implementation.
 ---

package/commands/help.md

@@ -1,5 +1,5 @@
 ---
-name: rdc:help
+name: help
 description: >-
   Usage `rdc:help` or `rdc` — manifest-driven menu of all MCP skills with
   argument syntax, requirements, decision hints, and direct MCP/curl access.

package/commands/mode.md

@@ -0,0 +1,122 @@
+---
+name: mode
+description: >-
+  Usage `rdc:mode [status|hotfix "<reason>" [minutes]|normal]` — show or set the operating mode. HotFix relaxes ceremony gates for a bounded window; it never relaxes a safety guard.
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+# rdc:mode — operating mode
+
+## When to Use
+- A production incident where process ceremony is costing minutes that matter
+- Checking whether a permissive window is currently open (and when it closes)
+- Closing one early, the moment the incident is over
+
+## The one thing to understand first
+
+**HotFix relaxes CEREMONY. It cannot relax SAFETY.**
+
+That is enforced in code as an allowlist, not a promise in a doc: only the eight
+ceremony rules named in `$LIFEAI_ENV/hooks/lib/rdc-mode.mjs` (`HOTFIX_DISABLES`)
+can ever be skipped, and the filtering happens at one place —
+`ALL_RULES()` in `guard-rules.mjs` — which all four of `evaluateGuard`'s passes
+iterate. A guard added tomorrow is **essential by default**.
+
+| relaxed in HotFix | never relaxed, in any mode |
+|---|---|
+| `full-build` · `polling-loops` · `persistent-cd` · `powershell-5.1` · `build-shortcircuit` · `codex-work-item-wrapper` · `codex-supabase-rpc-wrapper` · `codex-ssh-preflight` | `push-main` · `push-force` · `no-verify` · `rm-rf-danger` · `remove-item-danger` · `reset-hard-pool` · `clauth-exposure` · `ssh-key-raw-fetch` · `cross-tree-bash` · `lane-push-develop` · `git-add-all-standalone` · `coolify-direct` · `execution-scope` · `env-repo-maintainer-only` · `settings-json-direct-edit` · `node-modules-write` · `neo4j-outside-codeflow` · `resurrect-deleted-path` · `onramp-*` · `terminal-window-mutation` |
+
+Everything in the left column costs **time or tidiness**, and fails immediately,
+locally and visibly. Everything in the right column is irreversible, destroys
+another session's work, leaks a secret into a transcript forever, or fabricates
+governance evidence.
+
+Ceremony **gates** are relaxed alongside the guards: `truth-gate`,
+`completion-gate`, `stop-test-nudge`, `rdc-commit-gate`.
+
+## Why this exists
+
+Five unrelated escape hatches had already accumulated — `ALLOW_RESURRECT`,
+`LIFEAI_ENV_MAINTAINER`, `RDC_TEST`, the `RDC-Bypass:` commit trailer, and a
+CodeFlow break-glass file. Each was added when one guard got in the way, each has
+its own spelling, **none expires**, and none is audited with the others. Somebody
+in a hurry cannot find the right one, so they reach for the one they remember —
+usually the biggest.
+
+One named state, with a reason and a deadline, is easier to find *and* smaller in
+blast radius than any of them.
+
+## Usage
+
+```
+rdc:mode                              # status — the default
+rdc:mode status
+rdc:mode hotfix "prod checkout 500s"  # open a 60-minute window
+rdc:mode hotfix "prod down" 120       # explicit minutes, capped at 240
+rdc:mode normal                       # close it early
+```
+
+## Steps
+
+### 1. Read the current mode
+
+```bash
+node -e "import('file:///C:/Dev/lifeai-env/hooks/lib/rdc-mode.mjs').then(m=>console.log(JSON.stringify(m.currentMode(),null,2)))"
+```
+
+Report `mode`, and when not normal also `reason`, `setBy`, and `minutesLeft`.
+A mode with no minutes left is already normal — the state expires on read, not on
+a timer, so there is nothing to clean up.
+
+### 2. Setting hotfix — a reason is REQUIRED
+
+Refuse to proceed without one. `setMode` throws on an empty reason by design: an
+unexplained disarm is how a temporary state becomes permanent, and the reason is
+the entire content of the audit line.
+
+```bash
+node -e "import('file:///C:/Dev/lifeai-env/hooks/lib/rdc-mode.mjs').then(m=>console.log(JSON.stringify(m.setMode('hotfix',{reason:process.argv[1],minutes:Number(process.argv[2]||60),setBy:process.argv[3]}),null,2)))" "<reason>" "<minutes>" "<session-id>"
+```
+
+Then state plainly, in the checklist: **which guards are now off, that the safety
+set is still armed, and the exact wall-clock time the window closes.**
+
+### 3. Returning to normal
+
+```bash
+node -e "import('file:///C:/Dev/lifeai-env/hooks/lib/rdc-mode.mjs').then(m=>{m.clearMode();console.log('normal')})"
+```
+
+Do this **as soon as the incident is over**. The window expiring on its own is
+the backstop, not the plan.
+
+## Rules
+
+- **A reason is mandatory.** No reason, no mode change.
+- **Bounded.** Default 60 minutes, hard cap 240. A hotfix is an incident, not a
+  working style. If the work needs longer than 240 minutes it is not a hotfix and
+  wants `rdc:fixit` or `rdc:build`.
+- **Fail-closed.** Absent, malformed, unknown-mode or expired state all read as
+  `normal`. The hurry that motivates a hotfix is exactly the state in which a
+  silently-stuck permissive mode does the most damage.
+- **Never widen the disable set to unblock yourself.** A guard blocking a hotfix
+  is information. If it is genuinely wrong, that is its own change with its own
+  review — editing `HOTFIX_DISABLES` to get past a red guard is the same
+  violation as editing code to satisfy a failing gate
+  (`.claude/rules/debugging-protocol.md` Rule 10). The safety list is asserted by
+  name in `tests/rdc-mode.test.mjs`, so that edit fails a test.
+- **HotFix is not a bypass of review.** Work done in a hotfix window still needs
+  its work item, its evidence, and its close. The window buys speed on ceremony,
+  not permission to skip the record.
+
+## Verification
+
+```bash
+node --test $LIFEAI_ENV/tests/rdc-mode.test.mjs
+```
+
+Seven cases, including the load-bearing one: every safety guard is asserted **by
+name** to remain armed while a hotfix window is open.

package/commands/overnight.md

@@ -1,5 +1,5 @@
 ---
-name: rdc:overnight
+name: overnight
 description: >-
   Usage `rdc:overnight [epic-id|label=X]` — unattended overnight supervisor, chains preplan → plan → build → review → report across all high-priority epics in --unattended mode. Use for "run overnight", "build while I sleep".
 ---

package/commands/plan.md

@@ -1,5 +1,5 @@
 ---
-name: rdc:plan
+name: plan
 description: >-
   Usage `rdc:plan <topic> [--unattended]` — architecture doc with design decisions, tradeoffs, work packages. Creates Supabase epics/tasks. Use after rdc:preplan or when given clear architectural direction.
 ---

package/commands/preplan.md

@@ -1,5 +1,5 @@
 ---
-name: rdc:preplan
+name: preplan
 description: >-
   Usage `rdc:preplan <topic> [--unattended]` — research best practices, analyze codebase, compare approaches, surface unknowns before committing to a plan. Produces a research doc. No decisions, no code.
 ---

package/commands/prototype.md

@@ -1,5 +1,5 @@
 ---
-name: rdc:prototype
+name: prototype
 description: >-
   Usage `rdc:prototype <description>` — build JSX/TSX prototype for review before CLI handoff. Saves to docs/source/, registers in prototype_registry. Use for "mock this up", "show me what it looks like". Reference material only, not production.
 ---

package/commands/report.md

@@ -1,5 +1,5 @@
 ---
-name: rdc:report
+name: report
 description: >-
   Usage `rdc:report [--unattended]` — nightly markdown report, writes to .rdc/reports/YYYY-MM-DD.md. Covers completed/open work items, per-project progress, infra status, git stats, test counts.
 ---

package/commands/review.md

@@ -1,5 +1,5 @@
 ---
-name: rdc:review
+name: review
 description: >-
   Usage `rdc:review [--unattended]` — tests, typecheck, stale docs, export conflicts across modified packages. Fixes issues found. Use after a build session or before merging to main.
 ---

package/commands/self-test.md

@@ -1,5 +1,5 @@
 ---
-name: rdc:self-test
+name: self-test
 description: >-
   Usage `rdc:self-test [--strict] [--skill <name>] [--json] [--fix] [--tier2] [--parallel <n>] [--quick]` — validates every rdc-*.md skill: frontmatter, Usage marker, name↔filename match, referenced guides/rules/hooks exist, output contract banner, plugin manifest, duplicate-name + collision checks. Tier 1 static lint; Tier 2 behavioral runs via headless Claude or Codex in isolated worktrees + Supabase branch. Run before every release.
 ---

package/commands/status.md

@@ -1,5 +1,5 @@
 ---
-name: rdc:status
+name: status
 description: >-
   Usage `rdc:status` — open epics, work items by project, Coolify health, blockers, next recommended action. Read-only situational awareness.
 ---

package/commands/watch.md

@@ -1,5 +1,5 @@
 ---
-name: rdc:watch
+name: watch
 description: >-
   Usage `rdc:watch` — initialize a session-log viewer and report its path; open it only during attended, non-test use. Zero infra, pure filesystem + static HTML.
 ---

package/commands/workitems.md

@@ -1,5 +1,5 @@
 ---
-name: rdc:workitems
+name: workitems
 description: >-
   Usage `rdc:workitems <action> [args]` — create, update, query work items via Supabase RPCs. Actions: add, update, done, list, epics. Use for "add to backlog", "mark done", "show open epics", any work item CRUD.
 ---

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

@@ -17,10 +17,23 @@
  * fabrication class (FMEA #1) at the source — WP-2's closure gate then asserts a
  * report's codeflow_post.commit is one of these captured, session-authored SHAs.
  *
- * PreToolUse (intent) behavior is unchanged:
+ * PreToolUse (intent) behavior (2026-08-16 — real teeth, flow-gated):
+ *   - flow does NOT require a work item (rdc-flow.mjs: plan/design/collab,
+ *     or a relaxed mode — hotfix/maintenance) -> pass silently, no nag
  *   - fixit.marker present                  -> pass
  *   - conventional type / UUID / #issue ref -> pass
- *   - otherwise                             -> WARN (proceed anyway)
+ *   - otherwise, flow DOES require one (build/refactor/overnight, or no
+ *     flow declared at all — fail-closed default)
+ *                                            -> BLOCK (was: warn, proceed anyway)
+ *
+ * Was advisory-only unconditionally ("never hard-block commits... proceeding
+ * anyway") — Dave, 2026-08-16, on seeing that exact text fire with no
+ * enforcement behind it: the model declares its own flow (rdc-flow.mjs,
+ * lifeai-env), and THIS is where that declaration gets teeth. A
+ * conversational flow (plan/design/collab) never needed a work item and
+ * still doesn't — silently, not even a warning. A code-shipping flow
+ * (build/refactor/overnight) now actually stops the commit instead of
+ * printing a sentence nobody reads.
  *
  * PostToolUse (capture) behavior:
  *   - only fires on a `git commit` whose tool result indicates success
@@ -220,14 +233,42 @@ async function captureCommit(raw) {
 }
 
 // ---------------------------------------------------------------------------
-// PreToolUse intent check (unchanged legacy behavior)
+// PreToolUse intent check — flow-gated (2026-08-16)
 // ---------------------------------------------------------------------------
 
-function preToolUse(raw) {
+/**
+ * Does the CURRENT model-declared flow (rdc-flow.mjs, lifeai-env) require a
+ * work item right now? Dynamic import because this file is CommonJS and
+ * rdc-flow.mjs is ESM; resolved via $LIFEAI_ENV so this works identically on
+ * whichever machine/lane the hook actually runs from.
+ *
+ * FAILS CLOSED: any error (lifeai-env not on this box, module not found,
+ * whatever) returns true — "requires a work item" — the exact behavior this
+ * file had before flow-state existed. Introducing this mechanism can only
+ * EXEMPT a case that used to warn, never silently add a requirement that
+ * was not already effectively there.
+ */
+async function requiresWorkItemNow() {
+  const hub = process.env.LIFEAI_ENV || 'C:/Dev/lifeai-env';
+  try {
+    const mod = await import(`file://${path.join(hub, 'hooks', 'lib', 'rdc-flow.mjs').replace(/\\/g, '/')}`);
+    return mod.requiresWorkItem();
+  } catch (e) {
+    hookLog('require-work-item', 'PreToolUse', 'flow-check-error-fail-closed', { error: e.message });
+    return true;
+  }
+}
+
+async function preToolUse(raw) {
   if (raw.tool_name !== 'Bash') return process.exit(0);
   const command = raw.tool_input?.command || '';
   if (!command.includes('git commit')) return process.exit(0);
 
+  if (!(await requiresWorkItemNow())) {
+    hookLog('require-work-item', 'PreToolUse', 'pass-flow-exempt', {});
+    return process.exit(0);
+  }
+
   if (fs.existsSync(MARKER_FILE)) {
     hookLog('require-work-item', 'PreToolUse', 'pass-fixit', {});
     return process.exit(0);
@@ -239,12 +280,16 @@ function preToolUse(raw) {
     return process.exit(0);
   }
 
-  hookLog('require-work-item', 'PreToolUse', 'warn', { msg: msg.slice(0, 80) });
-  // Warn only — never hard-block commits. Conventional commit format is
-  // sufficient self-documentation.
+  // BLOCK, not warn (2026-08-16). The current flow (build/refactor/overnight,
+  // or none declared at all) requires a work item and none was referenced —
+  // this used to print a sentence and let the commit through regardless.
+  hookLog('require-work-item', 'PreToolUse', 'block', { msg: msg.slice(0, 80) });
   process.stdout.write(JSON.stringify({
-    systemMessage: `⚠️ Commit has no work item reference or conventional commit type.\n` +
-      `Preferred format: fix(<scope>): <message> — proceeding anyway.`,
+    decision: 'block',
+    reason: '⛔ [require-work-item] No work item reference or conventional commit type, and the current '
+      + 'flow requires one (build/refactor/overnight, or no flow declared). Add a Work-Item UUID or '
+      + '#issue ref to the message, use fix(<scope>): ..., or declare a flow that does not need one '
+      + '(rdc-flow.mjs: plan/design/collab) if this genuinely ships no trackable work.',
   }));
   return process.exit(0);
 }
@@ -276,7 +321,7 @@ async function main() {
   }
 
   // Default / PreToolUse intent path.
-  preToolUse(raw);
+  await preToolUse(raw);
 }
 
 // Run when executed as a hook; export pure pieces when required by a test.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/rdc-skills",
-  "version": "0.30.1",
+  "version": "0.31.0",
   "description": "RDC typed-agent dispatch skill suite for Claude Code - plan, build, review, overnight builds",
   "keywords": [
     "claude-code",

package/scripts/install-rdc-skills.js

@@ -8,8 +8,8 @@
  *   node scripts/install-rdc-skills.js --profile core       ← clean-box portable hooks
  *   node scripts/install-rdc-skills.js --profile lifeai     ← LIFEAI/regen-root hooks
  *   node scripts/install-rdc-skills.js --claude-home <path> ← custom CLI home
- *   node scripts/install-rdc-skills.js --codex-root <path>  ← also install to .agents/skills/user/
- *   node scripts/install-rdc-skills.js --codex-skill-dir <path> ← also install to a Codex skill dir
+ *   node scripts/install-rdc-skills.js --codex-root <path>  ← purge legacy project-local rdc skill copies
+ *   node scripts/install-rdc-skills.js --codex-skill-dir <path> ← purge one legacy Codex skill dir
  *   node scripts/install-rdc-skills.js --project-root <path> --write-startup-blocks
  *   node scripts/install-rdc-skills.js --migrate <path>     ← migrate docs/ → .rdc/
  *
@@ -17,7 +17,7 @@
  *   1. git pull (latest commands + guides)
  *   2. CLI plugin  — registers in ~/.claude/plugins/ + settings.json
  *   3. Cowork      — registers in Desktop cowork_plugins/ + cowork_settings.json
- *   3.5 Codex      — copies skills to detected Codex skill dirs
+ *   3.5 Codex      — removes stale file-based copies; Codex loads RDC skills through MCP
  *   4. Hook files  — copies hooks/*.js → ~/.claude/hooks/
  *   5. Hook wiring — wires hooks into ~/.claude/settings.json
  *   6. Zip         — builds dist/rdc-skills-plugin.zip for claude.ai / distribution
@@ -101,26 +101,36 @@ function run(cmd, options = {}) {
 }
 
 function updateCodexMcpToml(toml, mcpUrl) {
+  const eol = toml.includes('\r\n') ? '\r\n' : '\n';
+  toml = toml.replace(/\r\n/g, '\n');
+  // RDC skills are MCP-only in Codex. Older installs also registered an RDC
+  // marketplace/plugin, which Codex now rejects as an unsupported source and
+  // reports during every startup. Remove only those exact legacy blocks.
+  toml = toml
+    .replace(/(^|\n)\[marketplaces\.rdc-skills\]\n[\s\S]*?(?=\n\[|\s*$)/g, '$1')
+    .replace(/(^|\n)\[plugins\."rdc-skills@rdc-skills"\]\n[\s\S]*?(?=\n\[|\s*$)/g, '$1');
   const blockRe = /(^|\n)(\[mcp_servers\.rdc-skills\]\n)([\s\S]*?)(?=\n\[|\s*$)/;
   const desiredLine = `url = '${mcpUrl}'`;
   if (blockRe.test(toml)) {
-    return toml.replace(blockRe, (match, prefix, header, body) => {
+    const updated = toml.replace(blockRe, (match, prefix, header, body) => {
       if (/^url\s*=.*$/m.test(body)) {
         return `${prefix}${header}${body.replace(/^url\s*=.*$/m, desiredLine)}`;
       }
       const trimmed = body.replace(/\s*$/, '');
       return `${prefix}${header}${trimmed}${trimmed ? '\n' : ''}${desiredLine}\n`;
     });
+    return updated.replace(/\n/g, eol);
   }
-  return toml.replace(/\s*$/, '\n') + `\n[mcp_servers.rdc-skills]\n${desiredLine}\n`;
+  return (toml.replace(/\s*$/, '\n') + `\n[mcp_servers.rdc-skills]\n${desiredLine}\n`).replace(/\n/g, eol);
 }
 
 function selfTestCodexMcpToml() {
   const url = 'https://rdc-skills.regendevcorp.com/mcp';
-  const stale = "[mcp_servers.clauth]\nurl = 'https://clauth.regendevcorp.com/mcp'\n\n[mcp_servers.rdc-skills]\nurl = 'https://rdc-skills.dev.regendevcorp.com/mcp'\n\n[mcp_servers.web-research]\nurl = 'https://research.regendevcorp.com/mcp'\n";
+  const stale = "[mcp_servers.clauth]\nurl = 'https://clauth.regendevcorp.com/mcp'\n\n[mcp_servers.rdc-skills]\nurl = 'https://rdc-skills.dev.regendevcorp.com/mcp'\n\n[marketplaces.rdc-skills]\nsource_type = 'git'\nsource = 'https://github.com/LIFEAI/rdc-skills.git'\n\n[plugins.\"rdc-skills@rdc-skills\"]\nenabled = true\n\n[mcp_servers.web-research]\nurl = 'https://research.regendevcorp.com/mcp'\n";
   const updated = updateCodexMcpToml(stale, url);
   if (!updated.includes(`url = '${url}'`)) throw new Error('did not write production rdc-skills URL');
   if (updated.includes('rdc-skills.dev.regendevcorp.com')) throw new Error('stale dev URL survived');
+  if (updated.includes('[marketplaces.rdc-skills]') || updated.includes('[plugins."rdc-skills@rdc-skills"]')) throw new Error('legacy Codex plugin state survived');
   if (!updated.includes('[mcp_servers.clauth]') || !updated.includes('[mcp_servers.web-research]')) throw new Error('neighbor MCP blocks were damaged');
 
   const missing = updateCodexMcpToml("[mcp_servers.clauth]\nurl = 'https://clauth.regendevcorp.com/mcp'\n", url);
@@ -129,6 +139,10 @@ function selfTestCodexMcpToml() {
   const noUrl = updateCodexMcpToml('[mcp_servers.rdc-skills]\nstartup_timeout_sec = 30\n', url);
   if (!noUrl.includes("startup_timeout_sec = 30") || !noUrl.includes(`url = '${url}'`)) throw new Error('url-less block was not repaired');
 
+  const crlf = updateCodexMcpToml(stale.replace(/\n/g, '\r\n'), url);
+  if (crlf.includes('[marketplaces.rdc-skills]') || crlf.includes('[plugins."rdc-skills@rdc-skills"]')) throw new Error('CRLF legacy Codex plugin state survived');
+  if (!crlf.includes(`url = '${url}'`) || !crlf.includes('\r\n')) throw new Error('CRLF MCP config was not preserved');
+
   console.log('install-rdc-skills codex MCP TOML self-test — PASS');
 }
 
@@ -474,6 +488,42 @@ function flushOldCaches(cacheBase /* keepVersion intentionally unused */) {
   return flushed;
 }
 
+// ── Marketplace checkout sync ────────────────────────────────────────────────
+// The marketplace directory is a git CLONE, and this installer historically only
+// rewrote `.claude-plugin/marketplace.json` inside it. The rest of the working
+// tree stayed at whatever commit it was cloned at — and since the plugin loader
+// registers every directory it finds, that stale tree is a second, older copy of
+// every command sitting in the menu beside the current one.
+//
+// Fetching is not installing. On 2026-08-16 this clone had a same-day FETCH_HEAD
+// and a working tree 77 commits behind, still serving the pre-rename
+// `name: rdc:<x>` commands that rendered /rdc:rdc:plan next to /rdc:plan.
+//
+// PRESERVE-DIRTY: a clone with local modifications is never reset. It is a
+// consumer copy, so uncommitted content there is unexpected — which is exactly
+// why it gets reported rather than destroyed.
+function syncMarketplaceCheckout(mktDir) {
+  const gitDir = path.join(mktDir, '.git');
+  if (!fs.existsSync(gitDir)) return; // manifest-only directory; nothing to sync
+  const git = (...args) =>
+    execSync(`git -C "${mktDir}" ${args.join(' ')}`, { encoding: 'utf8', stdio: 'pipe' }).trim();
+  try {
+    if (git('status', '--porcelain')) {
+      warn(`marketplace clone has local changes at ${mktDir} — left untouched; it may serve stale commands`);
+      return;
+    }
+    const branch = git('rev-parse', '--abbrev-ref', 'HEAD') || 'master';
+    const ref = branch === 'HEAD' ? 'master' : branch;
+    git('fetch', 'origin', ref, '--quiet');
+    const behind = Number(git('rev-list', '--count', `HEAD..origin/${ref}`)) || 0;
+    if (behind === 0) return;
+    git('reset', '--hard', `origin/${ref}`, '--quiet');
+    info(`       marketplace: advanced ${behind} commit(s) -> ${git('rev-parse', '--short', 'HEAD')}`);
+  } catch (e) {
+    warn(`marketplace clone could not be synced (${String(e.message).split('\n')[0]}) — it may serve stale commands`);
+  }
+}
+
 // ── Step 2: CLI plugin registration (→ ~/.claude/plugins/) ───────────────────
 function registerCLI(version, gitSha) {
   const pluginDir  = path.join(claudeHome, 'plugins');
@@ -486,6 +536,24 @@ function registerCLI(version, gitSha) {
   fs.mkdirSync(mktPlugDir, { recursive: true });
   fs.copyFileSync(path.join(repoRoot, '.claude-plugin', 'marketplace.json'), path.join(mktPlugDir, 'marketplace.json'));
 
+  // 1b. The marketplace dir is a CLONE, and this installer only ever rewrote the
+  // manifest inside it. Everything else — commands/, skills/, hooks/ — stayed at
+  // whatever commit it was cloned at, and the plugin loader registers every dir
+  // it finds (see the note on cache flushing below). So a stale clone is a
+  // second, older copy of every command, live in the menu next to the current
+  // one.
+  //
+  // Observed 2026-08-16: this clone sat at v0.24.36, SEVENTY-SEVEN commits
+  // behind master, with a FETCH_HEAD from the same day. Fetched and never
+  // checked out — the identical failure the environment harness had, where a
+  // bare hub advanced its ref while the files consumers actually execute never
+  // moved. Its stale commands still declared the old `name: rdc:<x>`, so the
+  // menu showed /rdc:rdc:plan beside /rdc:plan, one entry per source.
+  //
+  // A fetch is not an install. Bring the working tree to the ref, or do not
+  // treat the directory as installed.
+  syncMarketplaceCheckout(mktDir);
+
   // 2. known_marketplaces.json
   const kmpPath = path.join(pluginDir, 'known_marketplaces.json');
   const knownMp = readJson(kmpPath);
@@ -637,6 +705,8 @@ function addCodexTarget(targets, label, targetDir) {
 // connector add in its UI (no programmatic API).
 function registerMcpEndpoints() {
   const out = [];
+  let codexReady = false;
+  let codexError = null;
 
   // Claude Code — user-level ~/.claude.json mcpServers (covers EVERY project).
   try {
@@ -656,17 +726,33 @@ function registerMcpEndpoints() {
   // Codex — ensure [mcp_servers.rdc-skills] exists and points at the live shared endpoint.
   try {
     const codexToml = path.join(os.homedir(), '.codex', 'config.toml');
-    if (fs.existsSync(codexToml)) {
-      const toml = fs.readFileSync(codexToml, 'utf8');
-      const next = updateCodexMcpToml(toml, PUBLIC_MCP_URL);
-      if (next !== toml) {
-        fs.writeFileSync(codexToml, next);
-        out.push('codex(~/.codex/config.toml)');
+    fs.mkdirSync(path.dirname(codexToml), { recursive: true });
+    const toml = fs.existsSync(codexToml) ? fs.readFileSync(codexToml, 'utf8') : '';
+    const next = updateCodexMcpToml(toml, PUBLIC_MCP_URL);
+    if (next !== toml) {
+      const tmp = `${codexToml}.tmp-${process.pid}`;
+      const mode = fs.existsSync(codexToml) ? (fs.statSync(codexToml).mode & 0o777) : 0o600;
+      try {
+        fs.writeFileSync(tmp, next, { mode });
+        fs.chmodSync(tmp, mode);
+        fs.renameSync(tmp, codexToml);
+      } finally {
+        if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
       }
+      out.push('codex(~/.codex/config.toml)');
     }
-  } catch (e) { out.push(`codex WARN:${e.message}`); }
+    const verified = fs.readFileSync(codexToml, 'utf8').replace(/\r\n/g, '\n');
+    const block = verified.match(/\[mcp_servers\.rdc-skills\]\n([\s\S]*?)(?=\n\[|\s*$)/)?.[1] || '';
+    codexReady = new RegExp(`^url\\s*=\\s*['\"]${PUBLIC_MCP_URL.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['\"]$`, 'm').test(block)
+      && !verified.includes('[marketplaces.rdc-skills]')
+      && !verified.includes('[plugins."rdc-skills@rdc-skills"]');
+    if (!codexReady) throw new Error('Codex MCP endpoint did not verify after write');
+  } catch (e) {
+    codexError = e.message;
+    out.push(`codex ERROR:${e.message}`);
+  }
 
-  return out;
+  return { updates: out, codexReady, codexError };
 }
 
 function findCodexTargets() {
@@ -711,19 +797,11 @@ function registerCodexTarget(targetDir) {
     }
   }
 
-  // Copy: each source skill dir that has a SKILL.md → rdc-<name>/
-  const skillsSrc = path.join(repoRoot, 'skills');
-  let copied = 0;
-  for (const entry of fs.readdirSync(skillsSrc, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    const skillFile = path.join(skillsSrc, entry.name, 'SKILL.md');
-    if (!fs.existsSync(skillFile)) continue;
-    const dst = path.join(targetDir, `rdc-${entry.name}`);
-    copyDirRecursive(path.join(skillsSrc, entry.name), dst);
-    copied++;
-  }
-
-  return { removed, copied };
+  // 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 };
 }
 
 // ── Step 6: Zip for claude.ai / distribution ─────────────────────────────────
@@ -874,6 +952,32 @@ function reportMcpConnector() {
   info(`       claude.ai / MCP clients: ${PUBLIC_MCP_URL} (Auth: none)`);
 }
 
+/**
+ * Live cross-surface proof, run at the end of every install.
+ *
+ * Everything above this line WRITES config files and TRUSTS they took effect.
+ * On 2026-08-16 that trust was wrong for one whole surface — the production
+ * MCP endpoint answered {"skills":0} while origin/master carried 36 — and
+ * nothing in this installer had ever asked it. This is the ask: ADVISORY
+ * only (never blocks a Claude CLI / Codex install that IS correct just
+ * because a shared remote service is stale), but it prints in every run so
+ * the gap cannot go quiet again.
+ */
+function runLiveProof() {
+  const script = path.join(repoRoot, 'scripts', 'verify-live-install.mjs');
+  if (!fs.existsSync(script)) return;
+  console.log('');
+  console.log('  \x1b[36mLive cross-surface proof:\x1b[0m');
+  try {
+    const codexRootArg = codexRoot ? ` --codex-root "${codexRoot}"` : '';
+    execSync(`node "${script}"${codexRootArg}`, { stdio: 'inherit', cwd: repoRoot });
+  } catch {
+    // Non-zero = a surface is stale. Already printed by the script itself;
+    // advisory here on purpose — see docstring.
+    warn('       one or more live surfaces do not match origin/master — see table above');
+  }
+}
+
 // ── Preflight ─────────────────────────────────────────────────────────────────
 function runPreflight() {
   const nodeMajor = parseInt(process.versions.node.split('.')[0], 10);
@@ -1051,7 +1155,18 @@ async function main() {
     warn('[2/6] Cowork     — no Desktop workspaces found (open Claude Desktop once to create them)');
   }
 
-  // 2.5. Codex registration
+  // 2.5. Establish and verify the MCP replacement BEFORE purging file copies.
+  const mcpReg = registerMcpEndpoints();
+  if (!mcpReg.codexReady) {
+    throw new Error(`Codex MCP registration failed; retaining file-based skills: ${mcpReg.codexError || 'unknown error'}`);
+  }
+  if (mcpReg.updates.length > 0) {
+    ok(`[2.5] MCP        — registered rdc-skills endpoint: ${mcpReg.updates.join(', ')}`);
+  } else {
+    info('[2.5] MCP        — rdc-skills endpoint verified (claude + codex)');
+  }
+
+  // 2.6. Codex migration: MCP is authoritative; purge legacy file copies.
   const codexTargets = findCodexTargets();
   if (codexTargets.length > 0) {
     let copiedTotal = 0;
@@ -1060,20 +1175,11 @@ async function main() {
       const { removed, copied } = registerCodexTarget(target.targetDir);
       copiedTotal += copied;
       removedTotal += removed;
-      info(`       ${target.label.padEnd(15)}: ${target.targetDir} (${copied} installed, ${removed} stale removed)`);
+      info(`       ${target.label.padEnd(15)}: ${target.targetDir} (${removed} stale removed; MCP authoritative)`);
     }
-    ok(`[2.5] Codex      — ${copiedTotal} skill install(s), ${removedTotal} stale removed across ${codexTargets.length} target(s)`);
-  } else {
-    info('[2.5] Codex      — skipped (no Codex skill dirs found; use --codex-root or --codex-skill-dir)');
-  }
-
-  // 2.6. Register the rdc-skills MCP endpoint globally (Claude Code + Codex) so
-  // EVERY agent can reach the skills via MCP, not only where a project .mcp.json exists.
-  const mcpReg = registerMcpEndpoints();
-  if (mcpReg.length > 0) {
-    ok(`[2.6] MCP        — registered rdc-skills endpoint: ${mcpReg.join(', ')}`);
+    ok(`[2.6] Codex      — ${removedTotal} stale file-based skill(s) removed across ${codexTargets.length} target(s); MCP authoritative`);
   } else {
-    info('[2.6] MCP        — rdc-skills endpoint already registered (claude + codex)');
+    info('[2.6] Codex      — skipped (no Codex skill dirs found; use --codex-root or --codex-skill-dir)');
   }
 
   // 2.7. Symlinks in regen-root/.claude/skills/ (FS MCP + claude.ai access)
@@ -1209,6 +1315,9 @@ async function main() {
   console.log('  \x1b[36mMCP connector:\x1b[0m');
   reportMcpConnector();
 
+  // 7.5 Live cross-surface proof — advisory, never blocks install exit code
+  runLiveProof();
+
   // Done
   console.log('');
   console.log('  \x1b[32mDone!\x1b[0m');
@@ -1238,7 +1347,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, RDC_ENV_HOOK_TIMEOUT_SEC };
+module.exports = { copyHookFiles, assertHooksLoadable, registerCodexTarget, RDC_ENV_HOOK_TIMEOUT_SEC };
 
 if (require.main === module) {
   main().catch(e => { fail(e.message); process.exit(1); });

package/scripts/verify-live-install.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * verify-live-install.mjs — proof, not hope.
+ *
+ * install-rdc-skills.js's "post-install verification" step only checks LOCAL
+ * structural counts (cache dir count, installed_plugins entry count, orphan
+ * cleanup) — it never asks any of the four surfaces a Claude/Codex session
+ * actually reads from whether they are serving the CURRENT catalog. On
+ * 2026-08-16 that gap was live: the production MCP endpoint answered
+ * `{"skills":0,"version":"0.0.0"}` while origin/master carried 37 skills, and
+ * nothing had ever noticed. This script is the missing check: it names a
+ * SOURCE OF TRUTH (origin/master, fetched fresh — never local disk, which is
+ * exactly what was stale) and asks each live surface to prove it matches.
+ *
+ * Surfaces checked (all four the installer registers):
+ *   1. Claude CLI  — ~/.claude/plugins/installed_plugins.json + cache/latest/skills/
+ *   2. Codex       — every skill dir the installer's findCodexTargets() would touch
+ *   3. Claude MCP  — live GET <mcp-url>/health (shared endpoint, also what claude.ai uses)
+ *   4. Codex MCP   — ~/.codex/config.toml points at the SAME endpoint checked in (3)
+ *
+ * Usage:
+ *   node scripts/verify-live-install.mjs                  human table, exit 1 on any FAIL
+ *   node scripts/verify-live-install.mjs --json            machine-readable
+ *   node scripts/verify-live-install.mjs --mcp-url <url>   override (default: production)
+ *   node scripts/verify-live-install.mjs --codex-root <dir> consuming project root
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execSync } from 'node:child_process';
+import https from 'node:https';
+import http from 'node:http';
+
+const args = process.argv.slice(2);
+const asJson = args.includes('--json');
+const mcpUrlIdx = args.indexOf('--mcp-url');
+const MCP_URL = mcpUrlIdx >= 0 ? args[mcpUrlIdx + 1] : 'https://rdc-skills.regendevcorp.com';
+const codexRootIdx = args.indexOf('--codex-root');
+const CODEX_ROOT = codexRootIdx >= 0 ? path.resolve(args[codexRootIdx + 1]) : null;
+
+const repoRoot = path.resolve(new URL('.', import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1'), '..');
+const claudeHome = path.join(os.homedir(), '.claude');
+const PLUGIN_KEY = 'rdc-skills@rdc-skills';
+
+function readJson(p, fallback = {}) {
+  if (!fs.existsSync(p)) return fallback;
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return fallback; }
+}
+
+function readFrontmatterName(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
+    const m = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!m) return null;
+    const nm = m[1].match(/^name:\s*(.+)$/m);
+    return nm ? nm[1].trim() : null;
+  } catch { return null; }
+}
+
+function httpGetJson(url, timeoutMs = 8000) {
+  return new Promise((resolve) => {
+    const lib = url.startsWith('https') ? https : http;
+    const req = lib.get(url, { timeout: timeoutMs }, (res) => {
+      let body = '';
+      res.on('data', (c) => { body += c; });
+      res.on('end', () => {
+        try { resolve({ ok: true, status: res.statusCode, json: JSON.parse(body) }); }
+        catch (e) { resolve({ ok: false, error: `bad JSON: ${e.message}`, raw: body.slice(0, 200) }); }
+      });
+    });
+    req.on('timeout', () => { req.destroy(); resolve({ ok: false, error: 'timeout' }); });
+    req.on('error', (e) => resolve({ ok: false, error: e.message }));
+  });
+}
+
+// ── Source of truth — origin/master, FRESHLY FETCHED. Never local disk: a
+// checkout can silently sit behind origin (this is the exact failure the
+// "canonical fallback" repo had this session — 31 commits behind while being
+// treated as the source of truth). ──────────────────────────────────────────
+function sourceOfTruth() {
+  execSync('git fetch origin master', { cwd: repoRoot, stdio: 'pipe' });
+  const sha = execSync('git rev-parse origin/master', { cwd: repoRoot, encoding: 'utf8' }).trim();
+  const pkgRaw = execSync('git show origin/master:package.json', { cwd: repoRoot, encoding: 'utf8' });
+  const version = JSON.parse(pkgRaw).version;
+  const skillDirs = execSync('git ls-tree -d --name-only origin/master:skills', { cwd: repoRoot, encoding: 'utf8' })
+    .split('\n').map((s) => s.trim()).filter(Boolean);
+  // Only count dirs that actually carry a SKILL.md at that ref — matches what
+  // the installer/MCP catalog treat as a real skill, not a stray directory.
+  let skillCount = 0;
+  for (const d of skillDirs) {
+    try {
+      execSync(`git cat-file -e origin/master:skills/${d}/SKILL.md`, { cwd: repoRoot, stdio: 'pipe' });
+      skillCount++;
+    } catch { /* not a real skill dir */ }
+  }
+  return { sha, shortSha: sha.slice(0, 7), version, skillCount };
+}
+
+// ── Surface 1: Claude CLI ────────────────────────────────────────────────────
+function checkClaudeCli(truth) {
+  const ipPath = path.join(claudeHome, 'plugins', 'installed_plugins.json');
+  const installed = readJson(ipPath, { plugins: {} });
+  const entries = installed.plugins[PLUGIN_KEY] || [];
+  if (entries.length !== 1) {
+    return { surface: 'Claude CLI', pass: false, detail: `expected 1 installed_plugins entry, found ${entries.length}` };
+  }
+  const entry = entries[0];
+  const cacheSkillsDir = entry.installPath ? path.join(entry.installPath, 'skills') : null;
+  const cacheCount = cacheSkillsDir && fs.existsSync(cacheSkillsDir)
+    ? fs.readdirSync(cacheSkillsDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && fs.existsSync(path.join(cacheSkillsDir, e.name, 'SKILL.md'))).length
+    : -1;
+  const shaMatch = entry.gitCommitSha === truth.sha;
+  const versionMatch = entry.version === truth.version;
+  const countMatch = cacheCount === truth.skillCount;
+  const pass = shaMatch && versionMatch && countMatch;
+  return {
+    surface: 'Claude CLI',
+    pass,
+    detail: pass
+      ? `v${entry.version} @ ${truth.shortSha}, ${cacheCount} skills — matches origin/master`
+      : `v${entry.version || '?'} @ ${(entry.gitCommitSha || '?').slice(0, 7)}, ${cacheCount} skills`
+        + ` — expected v${truth.version} @ ${truth.shortSha}, ${truth.skillCount} skills`
+        + `${shaMatch ? '' : ' [SHA MISMATCH]'}${versionMatch ? '' : ' [VERSION MISMATCH]'}${countMatch ? '' : ' [COUNT MISMATCH]'}`,
+  };
+}
+
+// ── Surface 2: Codex (MCP-only; no stale file-based skill dirs) ─────────────
+function findCodexTargets(codexRoot) {
+  const targets = [];
+  const add = (label, dir) => {
+    if (dir && fs.existsSync(dir) && !targets.some((t) => t.dir.toLowerCase() === dir.toLowerCase())) {
+      targets.push({ label, dir });
+    }
+  };
+  if (codexRoot) add('project .agents', path.join(codexRoot, '.agents', 'skills', 'user'));
+  add('global .codex', path.join(os.homedir(), '.codex', 'skills'));
+  add('global .agents', path.join(os.homedir(), '.agents', 'skills'));
+  return targets;
+}
+
+function checkCodex(truth) {
+  const codexRootCandidates = [
+    CODEX_ROOT,
+    process.env.REGEN_ROOT ? path.resolve(process.env.REGEN_ROOT) : null,
+    path.resolve(repoRoot, '..', 'regen-root'),
+    process.cwd(),
+  ].filter(Boolean);
+  const codexRoot = codexRootCandidates.find((c) => fs.existsSync(path.join(c, '.agents')));
+  const targets = findCodexTargets(codexRoot);
+  if (targets.length === 0) {
+    return { surface: 'Codex', pass: false, detail: 'no Codex skill directories found on this machine — install never ran with a Codex target' };
+  }
+  const results = [];
+  for (const t of targets) {
+    const dirs = fs.readdirSync(t.dir, { withFileTypes: true }).filter((e) => e.isDirectory());
+    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('; ');
+  return { surface: 'Codex', pass, detail };
+}
+
+// ── Surface 3: Claude MCP (live) ─────────────────────────────────────────────
+async function checkClaudeMcp(truth) {
+  const res = await httpGetJson(`${MCP_URL}/health`);
+  if (!res.ok) {
+    return { surface: 'Claude MCP', pass: false, detail: `${MCP_URL}/health unreachable — ${res.error}` };
+  }
+  const { skills, git_sha, version, status } = res.json;
+  const shaMatch = git_sha === truth.sha;
+  const countMatch = skills === truth.skillCount;
+  const pass = status === 'ok' && shaMatch && countMatch;
+  return {
+    surface: 'Claude MCP',
+    pass,
+    detail: pass
+      ? `${MCP_URL}/health — v${version}, ${skills} skills @ ${truth.shortSha} — matches origin/master`
+      : `${MCP_URL}/health — status=${status} v${version} skills=${skills} sha=${(git_sha || '?').slice(0, 7)}`
+        + ` — expected ${truth.skillCount} skills @ ${truth.shortSha}`
+        + `${shaMatch ? '' : ' [SHA MISMATCH]'}${countMatch ? '' : ' [COUNT MISMATCH]'}`,
+  };
+}
+
+// ── Surface 4: Codex MCP config points at the same live endpoint ───────────
+function checkCodexMcpConfig() {
+  const codexToml = path.join(os.homedir(), '.codex', 'config.toml');
+  if (!fs.existsSync(codexToml)) {
+    return { surface: 'Codex MCP', pass: false, detail: `${codexToml} does not exist` };
+  }
+  const toml = fs.readFileSync(codexToml, 'utf8').replace(/\r\n/g, '\n');
+  const blockRe = /\[mcp_servers\.rdc-skills\]\n([\s\S]*?)(?=\n\[|\s*$)/;
+  const m = toml.match(blockRe);
+  if (!m) return { surface: 'Codex MCP', pass: false, detail: 'no [mcp_servers.rdc-skills] block in config.toml' };
+  const urlM = m[1].match(/^url\s*=\s*'([^']+)'/m);
+  const configuredUrl = urlM ? urlM[1] : null;
+  const pass = configuredUrl === `${MCP_URL}/mcp`;
+  return {
+    surface: 'Codex MCP',
+    pass,
+    detail: pass
+      ? `config.toml points at ${configuredUrl} — same live endpoint verified above`
+      : `config.toml url=${configuredUrl || 'MISSING'} — expected ${MCP_URL}/mcp`,
+  };
+}
+
+async function main() {
+  const truth = sourceOfTruth();
+  const rows = [];
+  rows.push(checkClaudeCli(truth));
+  rows.push(checkCodex(truth));
+  rows.push(await checkClaudeMcp(truth));
+  rows.push(checkCodexMcpConfig());
+
+  const allPass = rows.every((r) => r.pass);
+
+  if (asJson) {
+    console.log(JSON.stringify({ truth, rows, allPass }, null, 2));
+  } else {
+    console.log('');
+    console.log(`  Source of truth: origin/master @ ${truth.shortSha}, v${truth.version}, ${truth.skillCount} skills`);
+    console.log('');
+    for (const r of rows) {
+      const mark = r.pass ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+      console.log(`  ${mark} ${r.surface.padEnd(12)} ${r.detail}`);
+    }
+    console.log('');
+    console.log(allPass
+      ? '  \x1b[32mAll surfaces verified live — proof, not assumption.\x1b[0m'
+      : '  \x1b[31mAt least one surface does NOT match origin/master. This is the exact blind spot install-rdc-skills.js does not check.\x1b[0m');
+    console.log('');
+  }
+  process.exit(allPass ? 0 : 1);
+}
+
+main().catch((e) => { console.error(e.stack || e.message); process.exit(2); });

package/skills/collab/COLLABORATOR.md

@@ -127,11 +127,29 @@ is not helpful — it is what the format exists to remove.
 **One block per point:**
 
 ```
-POINT <n>: AGREE | AGREE-WITH-AMENDMENT | DISAGREE
+POINT <n>: AGREE | AGREE-WITH-AMENDMENT | DISAGREE | UNKNOWN | DEFER
 EDIT: <the exact section and change that SHOULD be made, or NONE — describe it, do not make it>
-REASON: <one sentence — only if AMENDMENT or DISAGREE>
+REASON: <one sentence — required for AMENDMENT, DISAGREE, UNKNOWN and DEFER>
 ```
 
+**`UNKNOWN` and `DEFER` are answers, not failures.** If you lack the evidence to
+hold a position, say so. A three-value contract forces you to invent one, and an
+invented position is indistinguishable from a settled one in the next round —
+which is how a negotiation converges on something nobody checked. `UNKNOWN` = you
+cannot determine it. `DEFER` = it is determinable but belongs to another owner or
+another round.
+
+**Always carry `AS_OF` and `PROBE_STATE`:**
+
+```
+AS_OF: <timestamp of your last observation of what you are describing>
+PROBE_STATE: live | cached | absent
+```
+
+A claim with no as-of is a claim about an unknown moment. `live` = you probed it
+this turn; `cached` = you are reporting an earlier observation; `absent` = you
+could not observe it and are reasoning from something else. Say which.
+
 **For a factual question rather than a proposal:**
 
 ```
@@ -147,6 +165,43 @@ OWNER: <who lands the resulting Decision or work item — exactly one agent>
 BLOCKED: <what you cannot do from where you are, or NONE>
 ```
 
+### 1b. A broken briefing is the HOST's defect. Report it; do not repair it.
+
+**You are a guest in this workspace.** Checking that everything you were handed is
+actually there is welcome — one quick pass, seconds, before you start reading. It
+catches the host's mistakes early, which is worth doing.
+
+**What is not yours is the RECOVERY.** If a path does not exist, a service is
+down, or the tree is not in the state the dispatch claims — say so, in one line,
+and stop. Do not go find the file. Do not search the filesystem, do not search git
+objects, do not resolve which branch really has it, do not reconcile the
+initiator's checkouts. Verifying takes seconds and helps; recovering takes minutes
+and hides the defect.
+
+This is not laziness, and it is the opposite of unhelpful. Measured 2026-08-15: a
+peer was handed six paths, two of which did not exist where stated. It did
+everything a capable agent would do — searched the tree, searched hidden files,
+searched `git ls-tree` across refs, found the real versions in `origin/develop`
+and a `v0.30.1` tag, read them from immutable git objects without touching either
+worktree, and reported the mismatch precisely. **The answer was correct and it
+cost 4m23s instead of 60s.** Worse, the initiator's two drifted checkouts stayed
+drifted, because the peer had quietly worked around them — the defect was
+absorbed instead of returned, so nothing got fixed and the next session hit it
+again.
+
+```
+BLOCKED: path 3 does not exist: C:/path/as/given. Not searching — fix the briefing.
+```
+
+One line, immediately, before reading anything else. The host can fix a wrong path
+in seconds; you cannot fix it at all, because you cannot know whether the path was
+mistyped, the file was renamed, or their checkout is stale. **Guessing which,
+correctly, still leaves their room broken.**
+
+The same applies to a service the dispatch told you to use: if CodeFlow or an MCP
+is unreachable, report it and stop. Do not restart it, do not route around it, do
+not substitute a different tool and carry on as though nothing happened.
+
 ### 2. Declare `BLOCKED` loudly. Silence is the worst answer.
 
 If you cannot write, cannot reach a service, or lack the credential — **say it in

package/skills/collab/SKILL.md

@@ -296,9 +296,22 @@ Two rules that override the table:
 Every dispatch carries an explicit answer format. The contract is not politeness —
 it is what makes the reply *checkable*.
 
-**Every field returns information. No field asks the peer what it changed** — if a
-contract invites `CHANGED: <file paths>`, it has invited the peer to mutate the
-repo mid-conversation, which is the v0.27.0 defect this version removes.
+**During a NEGOTIATION, the contract returns information — no field asks the peer
+what it changed.** A `CHANGED: <file paths>` field invites both sides to mutate the
+same artifact mid-argument, which is the v0.27.0 defect this version removes.
+
+**This is not a read-only peer, and never say it is.** The constraint is
+SINGLE-WRITER-PER-ARTIFACT (Step 4), not "the guest may not touch anything". A
+peer that is the named writer for an artifact writes it — that is the whole
+mechanism by which an agreed change gets made. What it must not do is edit the
+artifact under negotiation while the negotiation is still open, or edit one it
+does not own.
+
+Telling a capable peer it is read-only when the workspace imposes no such rule is
+an invented constraint, and inventing constraints on someone else's behalf costs
+exactly what a wrong constraint always costs: work that could have been done in
+the same turn gets deferred to another round, or gets done anyway and now
+contradicts what you told them. In `delegate` mode the peer is expected to write.
 
 **The contract — one block per open point:**
 
@@ -417,6 +430,16 @@ dispatch.
 > Two active writers on one surface is forbidden — the same rule the fleet plans
 > state as *"never run two active writers for one effect."*
 
+> **The single-writer rule is a stopgap, and it is worth knowing what it stands
+> in for.** Per-artifact version numbers solved this in the 1970s — VMS gave every
+> file a generation (`FILE.TXT;1`, `;2`), so two writers produced two versions and
+> the collision was *detected* instead of silently losing one. Git is that
+> mechanism, better: content-addressed versions plus a merge base that says
+> exactly where two lines of work diverged. A rule that forbids concurrent writing
+> is a rule that declines to use it. Keep single-writer for now — it is cheap and
+> it holds — but do not mistake it for the right answer to two agents on one file.
+> GitHub already handles most of it.
+
 **Scope ownership to a named effect or artifact, never to an agent in general** —
 "Claude owns `fleet-throughput-remediation.md`", not "Claude is the writer".
 Transfer is explicit and acknowledged; **silence never transfers ownership**. A

package/tests/install-rdc-skills.test.mjs

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = resolve(__dirname, '..');
 const script = join(REPO_ROOT, 'scripts', 'install-rdc-skills.js');
+const require = createRequire(import.meta.url);
 
 const syntax = spawnSync(process.execPath, ['--check', script], { encoding: 'utf8' });
 assert.equal(syntax.status, 0, syntax.stderr);
@@ -21,6 +24,12 @@ assert.match(toml.stdout, /PASS/);
 
 const source = readFileSync(script, 'utf8');
 const plugin = JSON.parse(readFileSync(join(REPO_ROOT, '.claude-plugin', 'plugin.json'), 'utf8'));
+const packageJson = JSON.parse(readFileSync(join(REPO_ROOT, 'package.json'), 'utf8'));
+assert.equal(
+  plugin.version,
+  packageJson.version,
+  'plugin manifest version must match the published package version',
+);
 const skillCount = Array.isArray(plugin.skills_meta)
   ? plugin.skills_meta.length
   : Object.keys(plugin.skills_meta || {}).length;
@@ -45,5 +54,36 @@ assert.match(
   /no plugin upload needed for MCP/,
   'installer should not imply claude.ai MCP usage requires uploading an artifact',
 );
+assert.ok(
+  source.indexOf('const mcpReg = registerMcpEndpoints();') < source.indexOf('const codexTargets = findCodexTargets();'),
+  'installer must establish the Codex MCP endpoint before removing file-based skills',
+);
+assert.match(
+  source,
+  /if \(!mcpReg\.codexReady\)[\s\S]*retaining file-based skills/,
+  'installer must fail closed and retain file-based skills when MCP registration fails',
+);
+assert.match(
+  source,
+  /const mode = fs\.existsSync\(codexToml\)[\s\S]*fs\.chmodSync\(tmp, mode\)[\s\S]*finally[\s\S]*fs\.unlinkSync\(tmp\)/,
+  'Codex config replacement must preserve permissions and remove failed temporary copies',
+);
+
+const { registerCodexTarget } = require(script);
+const codexSkills = mkdtempSync(join(tmpdir(), 'rdc-codex-skills-'));
+try {
+  mkdirSync(join(codexSkills, 'rdc-build'), { recursive: true });
+  writeFileSync(join(codexSkills, 'rdc-build', 'SKILL.md'), '---\nname: rdc:build\n---\n');
+  mkdirSync(join(codexSkills, 'legacy-name'), { recursive: true });
+  writeFileSync(join(codexSkills, 'legacy-name', 'SKILL.md'), '---\nname: rdc:plan\n---\n');
+  mkdirSync(join(codexSkills, 'keep-me'), { recursive: true });
+  writeFileSync(join(codexSkills, 'keep-me', 'SKILL.md'), '---\nname: local:keep\n---\n');
+
+  const migrated = registerCodexTarget(codexSkills);
+  assert.deepEqual(migrated, { removed: 2, copied: 0 });
+  assert.equal(readFileSync(join(codexSkills, 'keep-me', 'SKILL.md'), 'utf8').includes('local:keep'), true);
+} finally {
+  rmSync(codexSkills, { recursive: true, force: true });
+}
 
 console.log('install-rdc-skills tests — PASS');

package/tests/require-work-item-on-commit.test.mjs

@@ -125,29 +125,45 @@ function runHook(payload, extraEnv = {}) {
 }
 
 // ---------------------------------------------------------------------------
-// 4. PreToolUse legacy behavior preserved (warn-only, never blocks)
-//    Uses a fresh temp dir as HOME/USERPROFILE so no fixit.marker is visible
-//    regardless of real machine state — makes the warn-path assertion deterministic.
+// 4. PreToolUse — flow-gated (2026-08-16): BLOCKS when the current flow
+//    requires a work item, exempt SILENTLY when it doesn't. Uses a fresh temp
+//    dir as HOME/USERPROFILE so no fixit.marker is visible regardless of real
+//    machine state, and real RDC_FLOW_STATE/RDC_MODE_STATE temp files so the
+//    test exercises the ACTUAL cross-repo dynamic-import path against
+//    whatever $LIFEAI_ENV resolves to on this box — not a mock.
 // ---------------------------------------------------------------------------
 {
   const fakeHome = mkdtempSync(join(tmpdir(), 'wic-home-'));
+  const flowState = join(fakeHome, 'flow.json');
+  const modeState = join(fakeHome, 'mode.json');
   try {
-    const preEnv = { HOME: fakeHome, USERPROFILE: fakeHome };
+    const preEnv = { HOME: fakeHome, USERPROFILE: fakeHome, RDC_FLOW_STATE: flowState, RDC_MODE_STATE: modeState };
 
-    const res = runHook({
+    // No flow declared -> fail-closed default -> requires a work item -> BLOCK.
+    const blocked = runHook({
       hook_event_name: 'PreToolUse',
       tool_name: 'Bash',
       tool_input: { command: 'git commit -m "no convention and no uuid"' },
     }, preEnv);
-    assert('pre: warn exits zero (never blocks)', res.status === 0, res.stderr);
-    assert('pre: emits warn systemMessage', /no work item reference/.test(res.stdout), res.stdout);
+    assert('pre: no-flow-declared BLOCKS (was: warn, never blocked)',
+      JSON.parse(blocked.stdout || '{}').decision === 'block', blocked.stdout || blocked.stderr);
 
+    // Conventional format still passes even when a work item IS required.
     const ok = runHook({
       hook_event_name: 'PreToolUse',
       tool_name: 'Bash',
       tool_input: { command: 'git commit -m "feat(x): conventional"' },
     }, preEnv);
-    assert('pre: conventional passes silently', ok.status === 0 && ok.stdout.trim() === '', ok.stdout);
+    assert('pre: conventional passes silently even when required', ok.status === 0 && ok.stdout.trim() === '', ok.stdout);
+
+    // A conversational flow (plan) exempts — silently, no message at all.
+    writeFileSync(flowState, JSON.stringify({ flow: 'plan', setBy: 'test', setAt: new Date().toISOString() }));
+    const exempt = runHook({
+      hook_event_name: 'PreToolUse',
+      tool_name: 'Bash',
+      tool_input: { command: 'git commit -m "no convention and no uuid"' },
+    }, preEnv);
+    assert('pre: plan flow exempts silently', exempt.status === 0 && exempt.stdout.trim() === '', exempt.stdout);
   } finally {
     rmSync(fakeHome, { recursive: true, force: true });
   }