@lifeaitools/rdc-skills 0.36.1 → 0.37.1

package/scripts/sync-manifest-versions.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * sync-manifest-versions.mjs — copy package.json's version into every other place the
+ * package declares it (scripts/lib/manifest-versions.mjs holds the list).
+ *
+ * Wired as the npm `version` lifecycle script (with --stage), so
+ * `npm version patch|minor|major` bumps package.json and then every manifest in the
+ * same step, and stages them for the version commit. Before this, plugin.json was a
+ * hand edit and clauth-plugin.json was never bumped at all (0.35.10 through 0.37.0).
+ *
+ *   node scripts/sync-manifest-versions.mjs          rewrite what differs, print it
+ *   node scripts/sync-manifest-versions.mjs --stage  the same, then `git add` every
+ *                                                    declaration file (npm version)
+ *   node scripts/sync-manifest-versions.mjs --check  change nothing; exit 1 on drift
+ */
+import { execFileSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { VERSION_DECLARATIONS, describeValue, mismatches, syncDeclarations } from './lib/manifest-versions.mjs';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const log = (line) => console.log(`[sync-manifest-versions] ${line}`);
+
+/** One spelling per directory: long names (not 8.3), and case-folded on Windows. */
+function canonical(dir) {
+  const real = realpathSync.native(path.resolve(dir));
+  return process.platform === 'win32' ? real.toLowerCase() : real;
+}
+
+/**
+ * True only when this package root IS the top of a git work tree. A package unpacked
+ * inside some other repository must not stage into that repository's index.
+ */
+function ownsGitWorkTree() {
+  try {
+    const top = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return canonical(top) === canonical(root);
+  } catch {
+    return false;
+  }
+}
+
+if (process.argv.includes('--check')) {
+  const drift = mismatches(root);
+  for (const d of drift) {
+    console.error(`[sync-manifest-versions] ${d.label} is ${describeValue(d)}, package.json is ${d.expected}`);
+  }
+  if (drift.length) process.exit(1);
+  log('every declaration matches package.json');
+} else {
+  const changed = syncDeclarations(root);
+  for (const c of changed) log(`${c.label}: ${c.from} -> ${c.to}`);
+  if (!changed.length) log('nothing to change');
+  if (process.argv.includes('--stage')) {
+    // npm version skips its own git steps outside a work tree; so does this.
+    if (!ownsGitWorkTree()) {
+      log('this package is not the top of a git work tree — nothing staged');
+    } else {
+      const files = [...new Set(VERSION_DECLARATIONS.map((d) => d.file))];
+      execFileSync('git', ['add', '--', ...files], { cwd: root, stdio: 'inherit' });
+      log(`staged ${files.join(', ')}`);
+    }
+  }
+}

package/skills/build/SKILL.md

@@ -644,27 +644,30 @@ Read the task title and description, then:
 
     ⛔ **NO wave may dispatch until the previous wave's code-review pass clears.** Memory `feedback_code_review_per_wave.md` — Davesend 2026-05-24 incident.
 
-    Dispatch ONE `pr-review-toolkit:code-reviewer` agent with the wave's merged diff:
-
-    ```
-    Agent({
-      subagent_type: "pr-review-toolkit:code-reviewer",
-      description: "Wave <N> code review",
-      prompt: "Review the diff `git diff <wave-base-sha>..HEAD` on develop.
-               Focus on: bugs, logic errors, security vulnerabilities, project-convention adherence
-               (.claude/rules/*, CLAUDE.md). Apply confidence-based filtering — high-confidence
-               findings only. Report severity per finding: critical | high | medium | low.
-               Return CODE_REVIEW_COMPLETE with: { critical_count, high_count, medium_count,
-               low_count, findings: [{severity, file:line, issue, suggested_fix}] }."
-    })
-    ```
-
-    **Severity gate (default — high+ blocks):**
-    - `critical` or `high` findings → reopen affected work items to `todo` with finding text in notes; fix in a new wave before continuing
-    - `medium` or `low` findings → append to each work item's `implementation_report.flags`; do NOT reopen; validator sees them
-    - Zero findings → log `CODE_REVIEW: CLEAN` and proceed to next wave
-
-    Under `RDC_TEST=1`: echo `[RDC_TEST] skipping code-review dispatch` and proceed.
+    Run the deterministic review gate in `guides/review-gate.md` over the wave's
+    merged diff, with `BASE=<wave-base-sha>` and `SCOPE` set to each package or
+    app the wave touched. That covers `rdc-solid-score --diff`, the repo linter on
+    changed files, `tsc`, scoped tests, and the UI spec when a route changed. It
+    takes one to two minutes; an open-ended reviewer agent took 4–10.
+    Approved: direct operator instruction — "we need to tune our code reviews to be
+    specific -- if you ran the validator for solid and lint etc... it should take 1-2
+    minutes". 2026-09-21, Dave, in session.
+
+    Dispatch `pr-review-toolkit:code-reviewer` only for a **named question** the
+    validators cannot answer, scoped to the files it touches (the guide's
+    "When an LLM reviewer is still right" section). Never dispatch it with a bare
+    "review the diff".
+
+    **Gate outcome:**
+    - A red gate step, or a critical/high finding from a named-question pass →
+      reopen the affected work items to `todo` with the `REVIEW_GATE` receipt and
+      the failing output in notes. Fix in a new wave before continuing.
+    - Medium/low findings from a named-question pass → append them to each work
+      item's `implementation_report.flags`. Do not reopen; the validator sees them.
+    - All steps green → log the `REVIEW_GATE` receipt with `verdict: "CLEAN"` and
+      proceed to the next wave.
+
+    Under `RDC_TEST=1`: echo `[RDC_TEST] skipping review gate` and proceed.
 
 10. **Mandatory validator gate (runs after ALL waves complete — before any work item closes):**
 

package/skills/clean-code-analyzer/SKILL.md

@@ -65,6 +65,12 @@ matches the numeric-suffix heuristic) alongside real hits (`data`, `temp`,
    `bin.rdc-clean-code-score`; falls back to
    `node <rdc-skills-install-path>/scripts/clean-code-score.mjs`.)
 
+   **In a monorepo, always pass `--project-root <package or app dir>`.** Without
+   it, the dead-export scan walks the whole git repo. On regen-root that ran out
+   of 4 GB of heap after 18 s (exit 134); scoped to `apps/prtrust` it took 7.9 s.
+   This scorer has no `--diff` and reports absolute counts, so it is advisory,
+   not part of the merge gate (`guides/review-gate.md`).
+
 2. **Read `results`** — per-unit findings for N1 (cryptic names), N2 (heuristic
    meaningless-distinction names, low confidence), N4 (magic numbers), N7
    (generic class/function names), F1 (>20 statements), F2 (>3 params), E1

package/skills/fixit/SKILL.md

@@ -111,26 +111,27 @@ fi
 
 ⛔ **No fixit closes without a code-review pass.** Even single-file changes go through review.
 
-Dispatch ONE `pr-review-toolkit:code-reviewer` agent on the fixit commit:
-
-```
-Agent({
-  subagent_type: "pr-review-toolkit:code-reviewer",
-  description: "fixit code review",
-  prompt: "Review `git show HEAD` on the development branch. Focus on:
-           bugs, logic errors, security, project-convention adherence (.claude/rules/*).
-           Confidence-based filtering — high-confidence findings only.
-           Return CODE_REVIEW_COMPLETE with: { critical_count, high_count, medium_count,
-           low_count, findings: [{severity, file:line, issue, suggested_fix}] }."
-})
-```
-
-**Severity gate:**
-- `critical` or `high` findings → fix in this same fixit session (do not escalate to rdc:build for the fix itself; the original fixit owns the cleanup), re-commit, re-run review until clean
-- `medium` or `low` findings → record in `implementation_report.flags`; proceed to close
-- Zero findings → proceed to close
-
-Under `RDC_TEST=1`: echo `[RDC_TEST] skipping code-review dispatch` and proceed.
+Run the deterministic review gate in `guides/review-gate.md` with
+`BASE=HEAD~1` (or the commit before the fixit's first commit) and `SCOPE` set
+to the touched package. For a fixit this usually takes seconds.
+Approved: direct operator instruction — "we need to tune our code reviews to be
+specific -- if you ran the validator for solid and lint etc... it should take 1-2
+minutes". 2026-09-21, Dave, in session.
+
+Dispatch `pr-review-toolkit:code-reviewer` only for a **named question** the
+validators cannot answer, scoped to the files it touches. Never dispatch it with
+a bare "review the commit".
+
+**Gate outcome:**
+- A red gate step, or a critical/high finding from a named-question pass → fix
+  it in this same fixit session. Do not escalate the fix to rdc:build; the
+  original fixit owns the cleanup. Re-commit and re-run the gate until it is clean.
+- Medium/low findings from a named-question pass → record them in
+  `implementation_report.flags` and proceed to close.
+- All steps green → quote the `REVIEW_GATE` receipt in the implementation report
+  and proceed to close.
+
+Under `RDC_TEST=1`: echo `[RDC_TEST] skipping review gate` and proceed.
 
 ### 5.7 Deliver to done (MANDATORY — a fixit is not done until the change is LIVE)
 

package/skills/overnight/SKILL.md

@@ -144,7 +144,7 @@ After each wave: check `BUILD_STATUS`. If `escalated: true`, log the escalation
 in the overnight doc and continue — don't stop the loop.
 After each wave and after every resumed epic, require the `runOrchestrator()` receipt from `rdc:build` **where the orchestrator applies** — the target contains `corpus/_shared/build/phase-manifest.json` (today: regen-root; see `rdc:build` §1a). Elsewhere, require the contract checklist (`rdc-work check`) instead; an absent orchestrator is not a hold. `admission_refocus` or `pipeline_blocked` means the epic is held for an explicitly requested Design Review or validator closure; log that state and do not hand-reconstruct a dispatch wave.
 
-**Mandatory code-review gate inherited from rdc:build (Step 9b).** Every wave inside `rdc:build` runs a `pr-review-toolkit:code-reviewer` pass before the next wave dispatches. Critical/high findings reopen the affected work items to `todo` and the next wave fixes them. Overnight does not skip or weaken this gate. If a wave's code-review escalates twice, advisor decides; otherwise the loop continues.
+**Mandatory code-review gate inherited from rdc:build (Step 9b).** Every wave inside `rdc:build` runs the deterministic review gate (`guides/review-gate.md`: solid-score --diff, linter on changed files, tsc, scoped tests, UI spec) before the next wave dispatches. It takes one to two minutes, where an open-ended reviewer took 4–10, which matters most across an overnight queue. A red step reopens the affected work items to `todo` and the next wave fixes them. Overnight does not skip or weaken this gate. If a wave's gate escalates twice, the advisor decides; otherwise the loop continues.
 
 ### 3d. Review
 

package/skills/release/SKILL.md

@@ -41,7 +41,7 @@ rdc:release: <repo> vX.Y.Z -> vA.B.C
 [ ] Dry-run gate handled
 [ ] Version files updated
 [ ] Tests/self-test passed
-[ ] Mandatory release code-review (pr-review-toolkit:code-reviewer on `git diff <last-released-tag>..HEAD`). Block release on `critical`/`high` findings; record `medium`/`low` in the release notes and proceed.
+[ ] Mandatory release review gate (`guides/review-gate.md`, BASE=<last-released-tag>): solid-score --diff, linter on changed files, tsc, scoped tests. Block the release on any red step; LLM reviewer only for a named question.
 [ ] Commit created
 [ ] Tag created
 [ ] Branch and tag pushed

package/skills/review/SKILL.md

@@ -12,8 +12,9 @@ description: rdc:review () - [--unattended] — post-build gate over tsc, tests,
 > **Sandbox contract:** This skill honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Destructive external calls short-circuit under the flag.
 
 > **Standard being enforced:** `docs/CODING-STANDARDS.md` (SOLID/Clean-Architecture —
-> regen-root; skip if absent). Step 8c is where it's actually checked, via this package's
+> regen-root; skip if absent). Steps 8b and 8c check it, via this package's
 > own `rdc-solid-score` (also invoked by ATF's Test-Ladder as a consumer, not an owner).
+> Step 8b runs the deterministic review gate, `guides/review-gate.md`.
 
 
 # rdc:review — Quality Gate
@@ -84,41 +85,47 @@ description: rdc:review () - [--unattended] — post-build gate over tsc, tests,
    - Never silently leave orphaned tasks
    - **⛔ Raw `UPDATE work_items SET parent_id = ...` is forbidden** — bypasses RLS and all constraint checks
 
-8b. **Mandatory code-review gate — dispatch pr-review-toolkit:code-reviewer:**
-
-   ⛔ **No CLEAN verdict without a code-review pass.** This is the second half of the quality gate; tsc/vitest catch type and behavior errors, code-reviewer catches logic, security, and convention drift.
-
-   Dispatch ONE `pr-review-toolkit:code-reviewer` agent on the full diff under review:
-
-   ```
-   Agent({
-     subagent_type: "pr-review-toolkit:code-reviewer",
-     description: "rdc:review code-review pass",
-     prompt: "Review `git diff origin/main...HEAD` on the development branch.
-              Focus on: bugs, logic errors, security vulnerabilities, project-convention
-              adherence (.claude/rules/*, CLAUDE.md, engineering-behavior.md).
-              Confidence-based filtering — high-confidence findings only.
-              Return CODE_REVIEW_COMPLETE with: { critical_count, high_count, medium_count,
-              low_count, findings: [{severity, file:line, issue, suggested_fix}] }."
-   })
-   ```
-
-   **Severity gate:**
-   - `critical` or `high` → verdict cannot be CLEAN. Interactive: report and pause. Unattended: auto-fix if mechanical (rename, missing await, obvious null check), otherwise escalate via advisor and mark HAS_ISSUES.
-   - `medium` or `low` → record in the review report's "Issues" section; verdict can still be CLEAN.
-   - Zero findings → log `CODE_REVIEW: CLEAN` and continue.
-
-   Under `RDC_TEST=1`: echo `[RDC_TEST] skipping code-review dispatch` and continue.
+8b. **Mandatory code-review gate — deterministic validators on the diff:**
+
+   ⛔ **No CLEAN verdict without a review-gate pass.** Run `guides/review-gate.md`
+   over the diff under review, with `BASE` set to the review's base ref and `SCOPE`
+   set to each modified package from step 1. Its checks are
+   `rdc-solid-score --diff`, the repo linter on changed files (`--write`, then
+   check), `tsc`, scoped tests, and the UI spec for changed routes. It finishes in
+   one to two minutes and gives the same answer twice.
+   Approved: direct operator instruction — "we need to tune our code reviews to be
+   specific -- if you ran the validator for solid and lint etc... it should take 1-2
+   minutes". 2026-09-21, Dave, in session.
+
+   Dispatch `pr-review-toolkit:code-reviewer` only for a **named question** the
+   validators cannot answer, such as auth bypass on a protected path or a return
+   figure in public copy. Scope it to the files that question touches, following
+   the guide's "When an LLM reviewer is still right" section. A bare "review the
+   diff" dispatch is retired.
+
+   **Gate outcome:**
+   - A red gate step, or a critical/high finding from a named-question pass →
+     the verdict cannot be CLEAN. Interactive: report and pause. Unattended:
+     fix it if the fix is mechanical (`--write` lint fixes, a missing await, an
+     obvious null check); otherwise escalate via the advisor and mark HAS_ISSUES.
+   - Medium/low findings from a named-question pass → record them in the review
+     report's "Issues" section. The verdict can still be CLEAN.
+   - All steps green → quote the `REVIEW_GATE` receipt and continue.
+
+   Under `RDC_TEST=1`: echo `[RDC_TEST] skipping review gate` and continue.
 
 8c. **Form/fit/function gate — solid-validator + architecture-reviewer:**
 
-   ⛔ **No CLEAN verdict without this pass either.** Step 8b catches logic,
-   security, and convention drift. This step catches a different failure
-   shape entirely: code that is logically correct and convention-clean but
-   architecturally wrong — the `Harness` case (a use-case orchestrator that
-   reimplements what sibling packages exist to do, scoring fine on every
-   generic metric while failing the one check that names the actual rule).
+   ⛔ **No CLEAN verdict without this pass either.** Step 8b's lint, tsc and
+   tests catch convention drift and broken behavior. This step catches a
+   different failure shape: code that is logically correct and
+   convention-clean but architecturally wrong. The `Harness` case is the
+   example: a use-case orchestrator that reimplements what sibling packages
+   exist to do, scores fine on every generic metric, and fails the one check
+   that names the actual rule.
 
+   Reuse the `rdc-solid-score` JSON from step 8b rather than running the scorer
+   twice. If 8b ran without the repo's boundary config, re-run it with the config:
    ```bash
    rdc-solid-score <modified-package-path> --diff origin/main --config <repo>/.solid-score.yml --format json
    ```

package/tests/lib/solid-score-diff.test.mjs

@@ -0,0 +1,103 @@
+import assert from 'node:assert/strict';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+import { isAbsentAtRef } from '../../scripts/solid-score.mjs';
+
+const SCORER = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'scripts', 'solid-score.mjs');
+
+// ── isAbsentAtRef: git's two "not at this ref" messages, and nothing else ──
+
+test('isAbsentAtRef: "does not exist in" (absent at ref and on disk) is absent', () => {
+  assert.equal(isAbsentAtRef("fatal: path 'src/a.ts' does not exist in 'origin/develop'\n"), true);
+});
+
+test('isAbsentAtRef: "exists on disk, but not in" (a NEW working-tree file) is absent', () => {
+  // The message every --diff over a change that adds a file produces; it was
+  // unmatched until 2026-09-21 and crashed the gate.
+  assert.equal(isAbsentAtRef("fatal: path 'apps/x/tests/ui/home.spec.ts' exists on disk, but not in 'origin/develop'\n"), true);
+});
+
+test('isAbsentAtRef: a bad ref is NOT absent — it must be rethrown', () => {
+  assert.equal(isAbsentAtRef("fatal: invalid object name 'no-such-ref'.\n"), false);
+});
+
+test('isAbsentAtRef: a path-form mismatch is NOT absent — it must be rethrown', () => {
+  assert.equal(
+    isAbsentAtRef("fatal: path 'src/a.ts' exists, but not 'a.ts'\nhint: Did you mean 'HEAD:src/a.ts' aka 'HEAD:./a.ts'?\n"),
+    false,
+  );
+});
+
+test('isAbsentAtRef: empty or missing stderr is NOT absent', () => {
+  assert.equal(isAbsentAtRef(''), false);
+  assert.equal(isAbsentAtRef(undefined), false);
+});
+
+// ── end to end: --diff over a change that adds a file ──
+
+function git(cwd, ...args) {
+  return execFileSync('git', ['-c', 'user.email=t@example.com', '-c', 'user.name=t', '-c', 'commit.gpgsign=false', ...args], {
+    cwd,
+    encoding: 'utf8',
+  });
+}
+
+const CLEAN_CLASS = (name) => `export class ${name} {\n  private n = 0;\n  add(x: number): number {\n    this.n += x;\n    return this.n;\n  }\n}\n`;
+
+test('solid-score --diff scores a new file as a new unit instead of crashing', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'solid-diff-'));
+  try {
+    git(dir, 'init', '-q');
+    writeFileSync(join(dir, 'a.ts'), CLEAN_CLASS('Alpha'));
+    git(dir, 'add', 'a.ts');
+    git(dir, 'commit', '-q', '-m', 'base');
+
+    // One untracked new file, and one committed-after-base new file: both are
+    // "exists on disk, but not in <ref>" at the base ref.
+    writeFileSync(join(dir, 'b.ts'), CLEAN_CLASS('Beta'));
+    writeFileSync(join(dir, 'c.ts'), CLEAN_CLASS('Gamma'));
+    git(dir, 'add', 'c.ts');
+    git(dir, 'commit', '-q', '-m', 'add c');
+
+    const run = spawnSync(process.execPath, [SCORER, dir, '--diff', 'HEAD~1', '--format', 'json'], { encoding: 'utf8' });
+    assert.equal(run.status, 0, `scorer exited ${run.status}: ${run.stderr}`);
+    const out = JSON.parse(run.stdout);
+    const scored = out.results.map((r) => r.file).sort();
+    assert.deepEqual(scored, ['b.ts', 'c.ts'], 'both new files are scored');
+    assert.deepEqual(out.regressions, [], 'clean new units are not regressions');
+    assert.deepEqual(out.removedFiles, [], 'nothing was deleted');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('solid-score --diff reports a deleted file in removedFiles instead of crashing', () => {
+  // A deleted file is listed by `git diff --name-only <ref>`; before
+  // 2026-09-21 it went to extractUnits and the gate died with ENOENT.
+  const dir = mkdtempSync(join(tmpdir(), 'solid-diff-del-'));
+  try {
+    git(dir, 'init', '-q');
+    writeFileSync(join(dir, 'a.ts'), CLEAN_CLASS('Alpha'));
+    writeFileSync(join(dir, 'gone.ts'), CLEAN_CLASS('Gone'));
+    git(dir, 'add', 'a.ts', 'gone.ts');
+    git(dir, 'commit', '-q', '-m', 'base');
+
+    // One deletion committed after base, one edit left uncommitted.
+    git(dir, 'rm', '-q', 'gone.ts');
+    git(dir, 'commit', '-q', '-m', 'remove gone');
+    writeFileSync(join(dir, 'a.ts'), `${CLEAN_CLASS('Alpha')}\nexport const touched = 1;\n`);
+
+    const run = spawnSync(process.execPath, [SCORER, dir, '--diff', 'HEAD~1', '--format', 'json'], { encoding: 'utf8' });
+    assert.equal(run.status, 0, `scorer exited ${run.status}: ${run.stderr}`);
+    const out = JSON.parse(run.stdout);
+    assert.deepEqual(out.removedFiles, ['gone.ts'], 'the deletion is reported, not dropped');
+    assert.deepEqual(out.results.map((r) => r.file), ['a.ts'], 'only the surviving changed file is scored');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/tests/manifest-version-parity.test.mjs

@@ -0,0 +1,155 @@
+// Every place the package declares its version equals package.json.
+//
+// 0.37.0 shipped with clauth-plugin.json at 0.35.10 and package.json `claude.version`
+// at 0.10.0. The only check, self-test, compared plugin.json alone, so both drifted for
+// releases without a single red. This test reads the shared declaration list, and it
+// also scans the repository, so a new manifest with a `version` cannot slip past the list.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  VERSION_DECLARATIONS, VERSION_SOURCE, describeValue, label, mismatches, readDeclarations, replaceJsonString,
+  syncDeclarations,
+} from '../scripts/lib/manifest-versions.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * The JSON files this repository holds: tracked, plus new files git does not ignore.
+ * Read from git, not the disk, so local reports, stamps and editor JSONC that git
+ * ignores can neither fail this test on one machine nor pass it on another.
+ */
+function jsonFilesWithTopLevelVersion() {
+  const listed = execFileSync('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard', '--', '*.json'], {
+    cwd: ROOT, encoding: 'utf8',
+  }).split('\0').filter(Boolean);
+  return [...new Set(listed)].filter((file) => {
+    const json = JSON.parse(readFileSync(path.join(ROOT, file), 'utf8'));
+    return json && typeof json === 'object' && !Array.isArray(json) && typeof json.version === 'string';
+  });
+}
+
+test('every version declaration equals package.json', () => {
+  const drift = mismatches(ROOT);
+  assert.deepEqual(
+    drift.map((d) => `${d.label} = ${describeValue(d)}`),
+    [],
+    `package.json is ${readDeclarations(ROOT).source}; run \`node scripts/sync-manifest-versions.mjs\``,
+  );
+});
+
+test('no JSON file declares a top-level version the list does not know about', () => {
+  const known = new Set([VERSION_SOURCE.file, ...VERSION_DECLARATIONS.filter((d) => d.keyPath.length === 1).map((d) => d.file)]);
+  const found = jsonFilesWithTopLevelVersion();
+  // Positive controls: a root file, and one inside a dot-directory.
+  assert.ok(found.includes('package.json'), 'the scan must find package.json');
+  assert.ok(found.includes('.claude-plugin/plugin.json'), 'the scan must find .claude-plugin/plugin.json');
+  assert.deepEqual(found.filter((f) => !known.has(f)), [], 'add each to VERSION_DECLARATIONS in scripts/lib/manifest-versions.mjs');
+});
+
+test('the declaration list names every file the fleet reads a version from', () => {
+  const labels = VERSION_DECLARATIONS.map(label);
+  for (const expected of ['.claude-plugin/plugin.json version', 'clauth-plugin.json version', 'package.json claude.version']) {
+    assert.ok(labels.includes(expected), `${expected} must be a declaration`);
+  }
+});
+
+test('npm version runs the sync hook, which stages every declaration file', () => {
+  const pkg = JSON.parse(readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+  assert.equal(pkg.scripts?.version, 'node scripts/sync-manifest-versions.mjs --stage');
+});
+
+test('replaceJsonString edits only the named key and keeps the formatting', () => {
+  const text = '{\n  "name": "x",\n  "version": "1.0.0",\n  "packages": {\n    "": { "version": "1.0.0" },\n    "node_modules/a": {\n      "version": "1.0.0"\n    }\n  }\n}\n';
+  const nested = replaceJsonString(text, ['packages', '', 'version'], '1.0.0', '2.0.0');
+  assert.equal(nested, text.replace('{ "version": "1.0.0" }', '{ "version": "2.0.0" }'));
+  const top = replaceJsonString(text, ['version'], '1.0.0', '2.0.0');
+  assert.equal(top, text.replace('"version": "1.0.0",', '"version": "2.0.0",'));
+  assert.throws(() => replaceJsonString(text, ['version'], '9.9.9', '2.0.0'), /could not locate/);
+});
+
+function copyManifests(tmp) {
+  for (const file of new Set([VERSION_SOURCE.file, ...VERSION_DECLARATIONS.map((d) => d.file)])) {
+    mkdirSync(path.dirname(path.join(tmp, file)), { recursive: true });
+    cpSync(path.join(ROOT, file), path.join(tmp, file));
+  }
+}
+
+test('an unreadable declaration is reported on its own and hides no other', () => {
+  const tmp = mkdtempSync(path.join(os.tmpdir(), 'rdc-version-read-'));
+  try {
+    copyManifests(tmp);
+    writeFileSync(path.join(tmp, 'clauth-plugin.json'), '{ "version": ');
+    const drift = mismatches(tmp);
+    assert.deepEqual(drift.map((d) => d.label), ['clauth-plugin.json version']);
+    assert.match(describeValue(drift[0]), /^\(unreadable: /);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('sync writes nothing when any declaration cannot be set', () => {
+  const tmp = mkdtempSync(path.join(os.tmpdir(), 'rdc-version-sync-'));
+  try {
+    copyManifests(tmp);
+    const pkgFile = path.join(tmp, 'package.json');
+    writeFileSync(pkgFile, readFileSync(pkgFile, 'utf8').replace(/"version": "[^"]+"/, '"version": "9.8.7"'));
+    const clauth = path.join(tmp, 'clauth-plugin.json');
+    writeFileSync(clauth, readFileSync(clauth, 'utf8').replace(/"version": "[^"]+"/, '"version": 1'));
+    const before = readFileSync(path.join(tmp, '.claude-plugin', 'plugin.json'), 'utf8');
+    assert.throws(() => syncDeclarations(tmp), /clauth-plugin\.json version is 1, not a version string/);
+    assert.equal(readFileSync(path.join(tmp, '.claude-plugin', 'plugin.json'), 'utf8'), before, 'plugin.json must be untouched');
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('the hook stages nothing into a repository the package is merely inside', () => {
+  const parent = mkdtempSync(path.join(os.tmpdir(), 'rdc-version-parent-'));
+  try {
+    const pkg = path.join(parent, 'vendor', 'rdc-skills');
+    copyManifests(pkg);
+    for (const file of ['scripts/sync-manifest-versions.mjs', 'scripts/lib/manifest-versions.mjs']) {
+      mkdirSync(path.dirname(path.join(pkg, file)), { recursive: true });
+      cpSync(path.join(ROOT, file), path.join(pkg, file));
+    }
+    execFileSync('git', ['init', '-q'], { cwd: parent });
+    const out = execFileSync(process.execPath, ['scripts/sync-manifest-versions.mjs', '--stage'], { cwd: pkg, encoding: 'utf8' });
+    assert.match(out, /nothing staged/);
+    assert.equal(execFileSync('git', ['diff', '--cached', '--name-only'], { cwd: parent, encoding: 'utf8' }), '');
+  } finally {
+    rmSync(parent, { recursive: true, force: true });
+  }
+});
+
+test('npm version in a throwaway copy moves every declaration and stages it', () => {
+  const tmp = mkdtempSync(path.join(os.tmpdir(), 'rdc-version-hook-'));
+  try {
+    copyManifests(tmp);
+    for (const file of ['scripts/sync-manifest-versions.mjs', 'scripts/lib/manifest-versions.mjs']) {
+      mkdirSync(path.dirname(path.join(tmp, file)), { recursive: true });
+      cpSync(path.join(ROOT, file), path.join(tmp, file));
+    }
+    execFileSync('git', ['init', '-q'], { cwd: tmp });
+    // npm is a .cmd shim on Windows; run it through cmd.exe rather than `shell: true`,
+    // which newer Node deprecates for argument arrays (DEP0190).
+    const npmArgs = ['version', '9.8.7', '--no-git-tag-version', '--ignore-scripts=false'];
+    const [cmd, args] = process.platform === 'win32'
+      ? ['cmd.exe', ['/d', '/s', '/c', 'npm', ...npmArgs]]
+      : ['npm', npmArgs];
+    execFileSync(cmd, args, { cwd: tmp, stdio: 'pipe' });
+    const { source, declarations } = readDeclarations(tmp);
+    assert.equal(source, '9.8.7');
+    assert.deepEqual(declarations.filter((d) => d.value !== '9.8.7').map((d) => `${d.label} = ${d.value}`), []);
+    const staged = execFileSync('git', ['diff', '--cached', '--name-only'], { cwd: tmp, encoding: 'utf8' }).split('\n').filter(Boolean);
+    for (const file of new Set(VERSION_DECLARATIONS.map((d) => d.file))) {
+      assert.ok(staged.includes(file), `${file} must be staged for the version commit (staged: ${staged.join(', ')})`);
+    }
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});

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

@@ -219,8 +219,17 @@ EOF
     ['heredoc with a quoted delimiter passes', 'git commit -F - <<"MSG"\nfix(a): b\nMSG', 'pass'],
     ['heredoc carrying only a UUID passes', "git commit -F - <<'EOF'\nwip\n\nWork-Item: f27ff5fa-0000-4000-8000-000000000000\nEOF", 'pass'],
     ['-m still passes', 'git commit -m "fix(x): y"', 'pass'],
+    // -m "$(cat <<'EOF' … EOF)" — the -m regex used to match the FIRST
+    // unrelated quote inside the substitution (the heredoc delimiter's own
+    // opening quote) and return early with literal shell text as the
+    // "message", never reaching the heredoc fallback below. Same defect
+    // class as the 2026-08-29 fix, one wrapper layer further out. Filed as
+    // regen-root#243.
+    ['-m "$(cat <<EOF …)" substitution passes', "git commit -m \"$(cat <<'EOF'\nfix(guards): correct the heredoc substitution match\n\nBody line two.\nEOF\n)\"", 'pass'],
+    ['-m "$(cat <<-EOF …)" dash-form substitution passes', "git commit -m \"$(cat <<-'EOF'\nfix(a): b\nEOF\n)\"", 'pass'],
     // Negative controls — reading the message is not a bypass.
     ['heredoc without a type or UUID still blocks', "git commit -F - <<'EOF'\nrandom words\nEOF", 'block'],
+    ['-m "$(cat <<EOF …)" without a type or UUID still blocks', "git commit -m \"$(cat <<'EOF'\nrandom words\nEOF\n)\"", 'block'],
     ['a bare commit still blocks', 'git commit', 'block'],
     // Honest about what it cannot see, rather than calling it absent.
     ['a real stdin pipe reports unreadable', 'cat msg.txt | git commit -q -F -', 'unreadable'],

package/.rdc/lessons/2026-08-17-fixit-codex-mcp-only-skills.md

@@ -1,24 +0,0 @@
----
-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`.