@lifeaitools/rdc-skills 0.37.0 → 0.37.2

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rdc",
-  "version": "0.37.0",
+  "version": "0.37.2",
   "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/.github/workflows/publish.yml

@@ -53,8 +53,19 @@ jobs:
       - name: Ensure npm supports trusted publishing
         run: npm install -g npm@latest && npm --version
 
+      # Every tag from v0.33.0 to v0.37.0 failed here with a bare E404 on the PUT and no
+      # reason, and no published version carries provenance, so the OIDC exchange has not
+      # succeeded once since this workflow moved to it. npm logs that exchange only at
+      # verbose level. The next step pulls those lines out, so the reason is printed
+      # rather than inferred.
       - name: Publish
-        run: npm publish --access public
+        run: |
+          set -o pipefail
+          npm publish --access public --loglevel verbose 2>&1 | tee publish.log
+
+      - name: OIDC exchange result
+        if: always()
+        run: grep -iE 'oidc|provenance|trusted|npm error' publish.log || echo "no oidc lines logged"
 
       - name: Notify clauth channel
         if: always()

package/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## v0.37.2 — the release doc says what actually happens
+
+### Fixed
+- RELEASE.md step 3 is one command, `work-ship --publish`, which waits for the tag's CI publish, falls back to the token route with npm's reason printed, and installs the exact version once npm serves it (lifeai-env d4ff3f6).
+- RELEASE.md step 4 records the measured CI state: npm's OIDC exchange answers "package not found" for @lifeaitools/rdc-skills, so no trusted publisher matches LIFEAI/rdc-skills publish.yml, and names what corrects it.
+
+---
+
+## v0.37.1 — one version in every manifest
+
+### Fixed
+- `clauth-plugin.json` declared 0.35.10 while the package shipped 0.37.0, and
+  `package.json` `claude.version` still said 0.10.0. Both are now 0.37.1, with
+  `.claude-plugin/plugin.json`, `package.json` and `package-lock.json`. Nothing had
+  failed on either: the only check, `rdc-skills-self-test`, compared `plugin.json`
+  alone.
+
+### Added
+- `scripts/lib/manifest-versions.mjs` is one list of every place the package
+  declares its version, built from a repository search for `"version"`. Three
+  things read it:
+  - `tests/manifest-version-parity.test.mjs` (in `test:acceptance`) fails on any
+    declaration that differs from `package.json`. It also scans the repository and
+    fails on any JSON file with a top-level `version` that the list does not name.
+  - `rdc-skills-self-test` now checks every packaged declaration, not only
+    `plugin.json`.
+  - The npm `version` lifecycle hook, `scripts/sync-manifest-versions.mjs --stage`,
+    means `npm version patch|minor|major` sets and stages every manifest in the
+    same step. `--check` changes nothing and exits 1 on drift.
+
+### Changed
+- `RELEASE.md` step 2 drops the hand edit of `plugin.json`: `npm version` now sets
+  every manifest, and `node scripts/sync-manifest-versions.mjs --check` confirms it.
+
+---
+
 ## v0.37.0 — review gates run the deterministic validators, in 1–2 minutes
 
 ### Changed

package/RELEASE.md

@@ -27,25 +27,38 @@ git checkout master
 git pull --ff-only origin master
 git merge <feature-branch> --no-edit
 
-# 2. Bump the version — package.json AND the plugin manifest, they must match.
-#    rdc-skills-self-test fails the whole run (plugin manifest FAIL) if they drift,
-#    and .claude-plugin/plugin.json ships inside the published npm package, so a
-#    stale plugin.json version is a real defect in the release, not a lint nit.
+# 2. Bump the version. `npm version` bumps package.json and package-lock.json, then
+#    its `version` lifecycle hook (scripts/sync-manifest-versions.mjs --stage) sets
+#    every other declaration to match and stages it: .claude-plugin/plugin.json,
+#    clauth-plugin.json, and package.json `claude.version`. The list lives in
+#    scripts/lib/manifest-versions.mjs. Never hand-edit a manifest version.
 npm version patch|minor|major --no-git-tag-version
-# then hand-edit .claude-plugin/plugin.json's top-level "version" field to match —
-# there is no script for this yet, only the self-test catches drift after the fact.
-
-# 3. Commit, tag, and push
-git add package.json .claude-plugin/plugin.json
-git commit -m "release: v$(node -e \"console.log(require('./package.json').version)\")"
-git tag "v$(node -e \"console.log(require('./package.json').version)\")"
-git push origin master --tags
-
-# 4. Publish through the tag-triggered GitHub workflow
-
-# 5. Verify the published package
-npm view @lifeaitools/rdc-skills version
-npm install -g @lifeaitools/rdc-skills@latest
+node scripts/sync-manifest-versions.mjs --check   # exit 1 names any declaration that drifted
+#    tests/manifest-version-parity.test.mjs and rdc-skills-self-test (plugin
+#    manifest FAIL) both fail on drift. 0.37.0 shipped clauth-plugin.json at 0.35.10
+#    because the self-test then checked plugin.json alone.
+
+# 3. Ship it — ONE command. Write the release commit message to a file first.
+#    work-ship checks every version field, commits, runs test:acceptance, pushes
+#    master, pushes the tag, WAITS for the tag's publish.yml run, and:
+#      - CI published    -> reports the run id (the version carries provenance)
+#      - CI refused      -> prints npm's own reason as `warn ci-publish`, then
+#                           publishes with the vault's npm token instead
+#    Then it waits until npm SERVES that exact version (npm processes a publish
+#    first; 0.37.1 took 239 s) and installs that version, failing on a mismatch.
+node "$LIFEAI_ENV/sessions/work-ship.mjs" --repo rdc-skills --lane <this worktree> -F <msgfile> --publish
+
+# 4. CI's publish, as measured 2026-09-21: every tag since v0.33.0 was refused at
+#    npm's OIDC exchange with "OIDC token exchange error - package not found" --
+#    npm holds no trusted publisher for @lifeaitools/rdc-skills that matches
+#    LIFEAI / rdc-skills / publish.yml. publish.yml prints that line on every run
+#    (step "OIDC exchange result"). Correcting it takes the npm owner's 2FA:
+#    npmjs.com -> @lifeaitools/rdc-skills -> Settings -> Trusted Publisher, or
+#    `npm trust github @lifeaitools/rdc-skills --file publish.yml --repository LIFEAI/rdc-skills --allow-publish`.
+#    Until then step 3 finishes every release through the token route and says so.
+
+# 5. Refresh the local plugin cache and read the verdict
+rdc-skills-install --profile lifeai
 npm list -g @lifeaitools/rdc-skills --depth=0
 rdc-skills-self-test
 # ^ run this LAST and read the verdict line, not just the section pass counts —

package/clauth-plugin.json

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

package/git-sha.json

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

package/package.json

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

package/scripts/lib/manifest-versions.mjs

@@ -0,0 +1,154 @@
+/**
+ * Every place this package states its own version, and one way to keep them equal.
+ *
+ * package.json `version` is the source. Every entry in VERSION_DECLARATIONS must equal
+ * it. The list was built from a repository search for `"version"`, not from memory:
+ * 0.37.0 shipped with clauth-plugin.json at 0.35.10 and package.json `claude.version`
+ * at 0.10.0, because the only check (self-test) compared plugin.json alone.
+ *
+ * Three readers share this list, so none can drift from the others:
+ *   - tests/manifest-version-parity.test.mjs  fails on any mismatch, and on any JSON
+ *     file with a top-level `version` that is not listed here
+ *   - scripts/self-test.mjs                   the packaged declarations, post-install
+ *   - scripts/sync-manifest-versions.mjs      the `version` lifecycle hook, so
+ *     `npm version <x>` moves every declaration and the test never has to catch it
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { isDeepStrictEqual } from 'node:util';
+import path from 'node:path';
+
+export const VERSION_SOURCE = Object.freeze({ file: 'package.json', keyPath: Object.freeze(['version']) });
+
+/** `packaged: false` — npm never ships the file, so an installed copy cannot check it. */
+export const VERSION_DECLARATIONS = Object.freeze([
+  { file: 'package.json', keyPath: ['claude', 'version'], packaged: true },
+  { file: '.claude-plugin/plugin.json', keyPath: ['version'], packaged: true },
+  { file: 'clauth-plugin.json', keyPath: ['version'], packaged: true },
+  { file: 'package-lock.json', keyPath: ['version'], packaged: false },
+  { file: 'package-lock.json', keyPath: ['packages', '', 'version'], packaged: false },
+].map((d) => Object.freeze({ ...d, keyPath: Object.freeze([...d.keyPath]) })));
+
+export function label({ file, keyPath }) {
+  return `${file} ${keyPath.map((k) => (k === '' ? '""' : k)).join('.')}`;
+}
+
+function getPath(obj, keyPath) {
+  let cur = obj;
+  for (const key of keyPath) {
+    if (cur === null || typeof cur !== 'object' || !(key in cur)) return undefined;
+    cur = cur[key];
+  }
+  return cur;
+}
+
+function setPath(obj, keyPath, value) {
+  const copy = structuredClone(obj);
+  let cur = copy;
+  for (const key of keyPath.slice(0, -1)) cur = cur[key];
+  cur[keyPath[keyPath.length - 1]] = value;
+  return copy;
+}
+
+/** `{ exists, text, json, error }` — an unreadable file is reported, never thrown past the caller. */
+function readJson(root, file) {
+  const full = path.join(root, file);
+  if (!existsSync(full)) return { exists: false, text: null, json: null, error: null };
+  try {
+    const text = readFileSync(full, 'utf8');
+    return { exists: true, text, json: JSON.parse(text), error: null };
+  } catch (error) {
+    return { exists: true, text: null, json: null, error: error.message };
+  }
+}
+
+/** The source version: package.json `version`. Throws when package.json cannot say. */
+export function sourceVersion(root) {
+  const { json, error } = readJson(root, VERSION_SOURCE.file);
+  if (error) throw new Error(`${VERSION_SOURCE.file} is unreadable: ${error}`);
+  const version = json ? getPath(json, VERSION_SOURCE.keyPath) : undefined;
+  if (typeof version !== 'string' || !version) throw new Error(`${VERSION_SOURCE.file} has no version`);
+  return version;
+}
+
+/**
+ * Every declaration with its current value. Each is read on its own: one unreadable
+ * file is that declaration's `error`, and every other declaration is still checked.
+ * @returns {{ source: string, declarations: Array<{file, keyPath, packaged, label, exists, value, error}> }}
+ */
+export function readDeclarations(root, { packagedOnly = false } = {}) {
+  const source = sourceVersion(root);
+  const cache = new Map();
+  const declarations = VERSION_DECLARATIONS
+    .filter((d) => !packagedOnly || d.packaged)
+    .map((d) => {
+      if (!cache.has(d.file)) cache.set(d.file, readJson(root, d.file));
+      const { exists, json, error } = cache.get(d.file);
+      return { ...d, label: label(d), exists, error, value: json ? getPath(json, d.keyPath) : undefined };
+    });
+  return { source, declarations };
+}
+
+/** The declarations that do not equal package.json's version (missing or unreadable counts). */
+export function mismatches(root, options = {}) {
+  const { source, declarations } = readDeclarations(root, options);
+  return declarations.filter((d) => d.error || d.value !== source).map((d) => ({ ...d, expected: source }));
+}
+
+/** What a declaration currently says, for a message: the value, or why there is none. */
+export function describeValue(d) {
+  if (!d.exists) return '(file missing)';
+  if (d.error) return `(unreadable: ${d.error})`;
+  if (d.value === undefined) return '(key missing)';
+  return JSON.stringify(d.value);
+}
+
+/**
+ * Replace one string value in JSON text without reformatting the file. Each
+ * `"<key>": "<old>"` occurrence is tried in turn and kept only when the result parses
+ * to exactly the original document with that one value changed — so a same-named key
+ * elsewhere (package-lock.json has hundreds of `version`s) is never the one edited.
+ */
+export function replaceJsonString(text, keyPath, oldValue, newValue) {
+  const original = JSON.parse(text);
+  const want = setPath(original, keyPath, newValue);
+  const key = keyPath[keyPath.length - 1];
+  const literal = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pattern = new RegExp(`("${literal(key)}"\\s*:\\s*)"${literal(oldValue)}"`, 'g');
+  for (const match of text.matchAll(pattern)) {
+    const at = match.index;
+    const candidate = `${text.slice(0, at)}${match[1]}${JSON.stringify(newValue)}${text.slice(at + match[0].length)}`;
+    let parsed;
+    try { parsed = JSON.parse(candidate); } catch { continue; }
+    if (isDeepStrictEqual(parsed, want)) return candidate;
+  }
+  throw new Error(`could not locate ${keyPath.join('.')} = "${oldValue}" as a plain string to rewrite`);
+}
+
+/**
+ * Set every declaration to package.json's version, formatting untouched. All or
+ * nothing: every new file text is computed first and nothing is written unless every
+ * declaration could be set, so a failure never leaves some manifests bumped. A missing
+ * file or a non-string value is an error, never skipped.
+ * @returns {Array<{label, from, to}>} what changed
+ */
+export function syncDeclarations(root) {
+  const source = sourceVersion(root);
+  const texts = new Map();
+  const changed = [];
+  for (const d of VERSION_DECLARATIONS) {
+    const full = path.join(root, d.file);
+    if (!texts.has(full)) {
+      if (!existsSync(full)) throw new Error(`${d.file} is listed as a version declaration but does not exist`);
+      texts.set(full, { original: readFileSync(full, 'utf8'), text: null });
+    }
+    const entry = texts.get(full);
+    const text = entry.text ?? entry.original;
+    const current = getPath(JSON.parse(text), d.keyPath);
+    if (current === source) continue;
+    if (typeof current !== 'string') throw new Error(`${label(d)} is ${JSON.stringify(current)}, not a version string`);
+    entry.text = replaceJsonString(text, d.keyPath, current, source);
+    changed.push({ label: label(d), from: current, to: source });
+  }
+  for (const [full, { text }] of texts) if (text !== null) writeFileSync(full, text);
+  return changed;
+}

package/scripts/self-test.mjs

@@ -33,6 +33,7 @@ import { join, basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 import { loadAllManifests } from "./lib/manifest-schema.mjs";
+import { describeValue as describeVersionValue, mismatches as versionMismatches } from "./lib/manifest-versions.mjs";
 import { runManifest } from "./lib/runner.mjs";
 import {
   generateRunId,
@@ -48,7 +49,6 @@ const GUIDES_DIR = join(REPO_ROOT, "guides");
 const AGENT_GUIDES_DIR = join(GUIDES_DIR, "agents");
 const HOOKS_DIR = join(REPO_ROOT, "hooks");
 const PLUGIN_MANIFEST = join(REPO_ROOT, ".claude-plugin", "plugin.json");
-const PACKAGE_JSON = join(REPO_ROOT, "package.json");
 
 // ─── Guide-content validator constants ───────────────────────────────────────
 // Path to the regen-root project (sibling of rdc-skills).
@@ -600,19 +600,24 @@ function auditPluginManifest() {
     });
   }
   try {
-    const pkg = JSON.parse(readFileSync(PACKAGE_JSON, "utf8"));
-    if (manifest.version && pkg.version && manifest.version !== pkg.version) {
+    // Every declaration an installed copy carries, from the one list the parity test and
+    // the `npm version` hook also read (scripts/lib/manifest-versions.mjs). This checked
+    // plugin.json alone, and clauth-plugin.json sat at 0.35.10 through 0.37.0. Each
+    // declaration is read on its own, so an unreadable file is its own error and never
+    // hides the others.
+    for (const d of versionMismatches(REPO_ROOT, { packagedOnly: true })) {
       findings.push({
         level: "error",
         code: "manifest-version-mismatch",
-        message: `plugin.json version "${manifest.version}" ≠ package.json version "${pkg.version}"`,
+        message: `${d.label} ${describeVersionValue(d)} ≠ package.json version "${d.expected}"`,
       });
     }
   } catch (e) {
+    // Only package.json itself lands here: without it no version can be verified.
     findings.push({
-      level: "warn",
+      level: "error",
       code: "package-json-unreadable",
-      message: `could not read package.json for version cross-check: ${e.message}`,
+      message: `could not read package.json for the version cross-check: ${e.message}`,
     });
   }
   const ok = findings.every((f) => f.level !== "error");

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/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 });
+  }
+});