@rosenfan/matrix 0.1.5 → 0.1.7

package/src/installer.js

@@ -1,45 +1,45 @@
-import fs from "node:fs";
-import path from "node:path";
-import { createDistribution } from "./distribution.js";
-import { MATRIX_SKILLS, MATT_SKILLS, PLATFORMS, sourceSkillsRoot } from "./catalog.js";
-
-export { MATRIX_SKILLS, MATT_SKILLS, sourceSkillsRoot };
-
-export function destinationFor({ scope, projectRoot, platform = "claude-code", home }) {
-  const base = scope === "global" ? (home ?? process.env.USERPROFILE ?? process.env.HOME) : projectRoot;
-  return PLATFORMS[platform].skillRoot(base);
-}
-
-export function inspectInstallation(destination) {
-  const inspect = (names) => names.filter((skill) => {
-    try { return Boolean(destination) && requireExists(destination, skill); } catch { return false; }
-  });
-  const installed = inspect(MATRIX_SKILLS);
-  const mattInstalled = inspect(MATT_SKILLS);
-  return { installed, missing: MATRIX_SKILLS.filter((skill) => !installed.includes(skill)), mattInstalled, mattMissing: MATT_SKILLS.filter((skill) => !mattInstalled.includes(skill)) };
-}
-
-function requireExists(destination, skill) {
-  // Avoid exposing a second installation policy through this legacy helper.
-  return fs.existsSync(path.join(destination, skill, "SKILL.md"));
-}
-
-export function installMatrix({ destination, mode = "copy", conflict = "error", dryRun = false }) {
-  const platform = destination?.includes(".agents") ? "codex" : "claude-code";
-  const projectRoot = path.resolve(destination, "..", "..");
-  const distribution = createDistribution();
-  const evaluation = distribution.evaluate({ projectRoot, scope: "project", platforms: [platform], mode, matrixPolicy: conflict === "replace" ? "replace" : "safe", dryRun });
-  if (!evaluation.ok) throw new Error(evaluation.diagnostics?.[0]?.message ?? evaluation.code);
-  const result = distribution.commit(evaluation.plan);
-  if (!result.ok) throw new Error(result.error ?? result.code);
-  return { installed: result.committed ?? MATRIX_SKILLS, skipped: [], existing: [], backupRoot: result.backups?.[0] ? result.backups[0].backup : null };
-}
-
-export function installMattSkills({ projectRoot, platforms = ["claude-code"], skills = MATT_SKILLS, global = false, timeout = 300_000 }) {
-  void projectRoot; void platforms; void skills; void global; void timeout;
-  const error = new Error("Direct Matt installation was retired; run matrix init --with-mattpocock so Distribution owns the complete Matrix/Matt transaction.");
-  error.code = "MATT_DIRECT_INSTALL_UNSUPPORTED";
-  throw error;
-}
-
-export function findPython() { return null; }
+import fs from "node:fs";
+import path from "node:path";
+import { createDistribution } from "./distribution.js";
+import { MATRIX_SKILLS, MATT_SKILLS, PLATFORMS, PLATFORM_IDS, sourceSkillsRoot } from "./catalog.js";
+
+export { MATRIX_SKILLS, MATT_SKILLS, sourceSkillsRoot };
+
+export function destinationFor({ scope, projectRoot, platform = "claude-code", home }) {
+  const base = scope === "global" ? (home ?? process.env.USERPROFILE ?? process.env.HOME) : projectRoot;
+  return PLATFORMS[platform].skillRoot(base);
+}
+
+export function inspectInstallation(destination) {
+  const inspect = (names) => names.filter((skill) => {
+    try { return Boolean(destination) && requireExists(destination, skill); } catch { return false; }
+  });
+  const installed = inspect(MATRIX_SKILLS);
+  const mattInstalled = inspect(MATT_SKILLS);
+  return { installed, missing: MATRIX_SKILLS.filter((skill) => !installed.includes(skill)), mattInstalled, mattMissing: MATT_SKILLS.filter((skill) => !mattInstalled.includes(skill)) };
+}
+
+function requireExists(destination, skill) {
+  // Avoid exposing a second installation policy through this legacy helper.
+  return fs.existsSync(path.join(destination, skill, "SKILL.md"));
+}
+
+export function installMatrix({ destination, mode = "copy", conflict = "error", dryRun = false }) {
+  const projectRoot = path.resolve(destination, "..", "..");
+  const platform = PLATFORM_IDS.find((id) => PLATFORMS[id].skillRoot(projectRoot) === path.resolve(destination)) ?? "claude-code";
+  const distribution = createDistribution();
+  const evaluation = distribution.evaluate({ projectRoot, scope: "project", platforms: [platform], mode, matrixPolicy: conflict === "replace" ? "replace" : "safe", dryRun });
+  if (!evaluation.ok) throw new Error(evaluation.diagnostics?.[0]?.message ?? evaluation.code);
+  const result = distribution.commit(evaluation.plan);
+  if (!result.ok) throw new Error(result.error ?? result.code);
+  return { installed: result.committed ?? MATRIX_SKILLS, skipped: [], existing: [], backupRoot: result.backups?.[0] ? result.backups[0].backup : null };
+}
+
+export function installMattSkills({ projectRoot, platforms = ["claude-code"], skills = MATT_SKILLS, global = false, timeout = 300_000 }) {
+  void projectRoot; void platforms; void skills; void global; void timeout;
+  const error = new Error("Direct Matt installation was retired; run matrix init --with-mattpocock so Distribution owns the complete Matrix/Matt transaction.");
+  error.code = "MATT_DIRECT_INSTALL_UNSUPPORTED";
+  throw error;
+}
+
+export function findPython() { return null; }

package/src/matt-catalog.mjs

@@ -1,11 +1,11 @@
 import crypto from "node:crypto";
 
 export const MATT_COMPATIBILITY = Object.freeze({
-  matrixVersion: "0.1.5",
-  release: "v1.2.3",
-  commit: "6acc160e4e0cd062dbbbd7a1b26ae92855edf07e",
-  archive: "https://github.com/mattpocock/skills/archive/6acc160e4e0cd062dbbbd7a1b26ae92855edf07e.tar.gz",
-  skillsCli: "skills@1.5.22"
+  matrixVersion: "0.1.7",
+  release: "v1.3.1",
+  commit: "24fe0ef7737efae15c87225755e9f6f5965e4888",
+  archive: "https://github.com/mattpocock/skills/archive/24fe0ef7737efae15c87225755e9f6f5965e4888.tar.gz",
+  skillsCli: "skills@1.7.4"
 });
 
 export const MATT_ROLES = Object.freeze({
@@ -14,12 +14,12 @@ export const MATT_ROLES = Object.freeze({
     "tdd", "diagnosing-bugs", "code-review", "wizard", "writing-for-agents"
   ]),
   handoff: Object.freeze([
-    "setup-matt-pocock-skills", "improve-codebase-architecture", "wayfinder", "handoff", "to-questionnaire"
+    "setup-matt-pocock-skills", "improve-codebase-architecture", "wayfinder", "handoff", "to-questionnaire", "retro"
   ]),
   standalone: Object.freeze([
-    "ask-matt", "grill-with-docs", "triage", "to-spec", "to-tickets", "grill-me", "teach", "wait-what"
+    "ask-matt", "grill-with-docs", "triage", "to-spec", "to-tickets", "grill-me", "teach", "wait-what", "pr"
   ]),
-  incompatible: Object.freeze(["implement", "resolving-merge-conflicts"])
+  incompatible: Object.freeze(["implement", "implement-spec"])
 });
 
 export const MATT_AUTOMATIC_SKILLS = MATT_ROLES.automatic;
@@ -29,35 +29,37 @@ export const MATT_INSTALLABLE_SKILLS = Object.freeze([
   ...MATT_ROLES.standalone
 ]);
 export const MATT_OFFICIAL_SKILLS = Object.freeze(Object.values(MATT_ROLES).flat());
-// Content identities produced by skills@1.5.22 --copy from the exact v1.2.3 archive.
+// Content identities produced by skills@1.7.4 --copy from the exact v1.3.1 archive.
 // They let init classify existing project files before any target mutation without
 // bundling or redistributing Matt's Skill contents.
 export const MATT_CONTENT_HASHES = Object.freeze({
-  "grilling": "f6b0b6a07f6f51a7b39dfed4c737bd5990149e6ac227265dc457eb962e40fde6",
-  "domain-modeling": "8d774870ffd93ad77b07f56bbe59fb76c8f9e246fe49e0181ed65a519fc28929",
-  "research": "3bbc342f7484484d31118fd7cb148690aba2600b318d6b680edc6ce2c2399948",
-  "prototype": "08f5e9d003dfcbc274f4a31864c9fcbc2962ad8574f40e7bba7d78193f5d349f",
-  "codebase-design": "0050828acbec9af9711ac1376749acaf358fb1bbfd98c80fc20df7a26658ccd7",
-  "tdd": "775d2b0eb45fdf7a102f0ec0cfca8448c5d441c49373e0a89bc7a22dbe892c3c",
-  "diagnosing-bugs": "9fc5749a1671a7c894cc538fbbedda19890bd20f297eb6095ba0969a933ed2dc",
-  "code-review": "e4c202dae670331dab5aef98a05594a45ec3b8210a8f9c2ab8a8bba848da4c8e",
-  "wizard": "991cb02af3f4584b07f5b6ce30176d05bf2622152a8776db9832825f80601e3d",
-  "writing-for-agents": "f58ac3a5e4034da89bd31ff86ffdc74df9e986ef818055d9a399f05fc3b37a1b",
-  "setup-matt-pocock-skills": "cb2d75f72fb70ba283a5d76f2722d090a00cb4d3e227e32b05a547193e561800",
-  "improve-codebase-architecture": "986e4245d52053692fc866c4c3065a3b944fc2f27a1ea99785a2b116d785e964",
-  "wayfinder": "a99de1eab6ae2950b5d4146abfd58257a3e0cfdcbd5e9611f27b2a485fd52242",
-  "handoff": "9f8a832aafee3eec6dae6902d758b2438fefb116a6afb9914777238538b14d2b",
-  "to-questionnaire": "9a27c55ce8d45b8a7f1a7309bece202bebcd7cab359f551aeeeb3d5c320a3b55",
-  "ask-matt": "55c6191c39ad1727d8285225db5a97e622026f6c861f1c924dbc92d8c433e344",
-  "grill-with-docs": "05c1b216a482ea0fd5a5281e96b0f1b5fd5e1c1e9edd572709c71944ef6fd7d6",
-  "triage": "7009d742e1cf0e40b0d8de8fc47ece25161795da595bd7017a170426dbb51d9a",
-  "to-spec": "969b7955a044939809487b416d1e907021c6ad4b07bd5979f46e2f1c629ffd01",
-  "to-tickets": "b7c6499e10c567abdbfca7f5c730f2de91584a517816ace5aaaff49f4790e947",
-  "grill-me": "cec05582f13830a7bd63984474b999c806a7b93935ed638a27f32eac1b7f976b",
-  "teach": "209d2ead53b2c6eba2425198f6f09eb51fd2bde490c34da2d93b187b4b749414",
-  "wait-what": "345b8e9aba9f134944f37ae7807cadd19c1b6866d77e3414f2e8f3835061aac0",
+  "grilling": "229e9190ddcdf65fcfa68aeebe6edfcf3b039967e4d5321c48325ea197836b88",
+  "domain-modeling": "332c4e23360e692a488fa25fe878596f91e4eaf125f48ea280dca151f3798eaa",
+  "research": "8766e592808cb8e6951dd8e4d414f4fef3ee9dde1c487b2e5af7461027f794e2",
+  "prototype": "5fc3162feb286bc773e21c208c440de81f66ef36e6ae2fd2189a54756af4468c",
+  "codebase-design": "17a6a1ab67eff070a38564834d6e3ff82bc2d46cdc888a57f6bc18c3efe6442b",
+  "tdd": "cf0a63fd20988baef0a31d2d8467e70319fdc75d5bb3eaa60620abcedb97574c",
+  "diagnosing-bugs": "bc1ade4a8b7e988aed02c251d3d0d8cdbedc74ce3361a244e2cf12cbb6744d74",
+  "code-review": "9a883c4392f27b6d45c6a51d12d168897ba7707a5e70f8d45a042b41db58d5a5",
+  "wizard": "b2793f1654b9c518eb85386cc51f9218030c6dc83772bea3c128cb156c972300",
+  "writing-for-agents": "46d0c6f716d2c4cbb27ea157fd3e18675389fecf3d722343f05c82b7c1e61bf8",
+  "setup-matt-pocock-skills": "7fd2c1e02b10bdd59f2c15a7cbc364e247286884c1c5cdd21704f7cbc769b42a",
+  "improve-codebase-architecture": "4502270f003e0702f19da6c2436daffe0f9d4dafcea3de2759347b99c5a5c404",
+  "wayfinder": "a774efe838aede8db313dbf3cd16660075803b3ed3657d3297ec913ea67fad49",
+  "handoff": "5aff146205749c5daab83c1f0299b910a1caaa403bcd37f59f35513a6c13dc12",
+  "to-questionnaire": "51d0425a65248e2d5ca1b4d06e4f854cb131e49a43326f54a81690ce28e27535",
+  "retro": "e7b2f28bf8e88e539791db6f9ec566252b56afc179d5b881486340a477ec59bd",
+  "ask-matt": "b1cf1467569d4199e6cec74a3fa9036d42bb208e76084e5d5030e23cd7f1f1dc",
+  "grill-with-docs": "bbf60554b6f102ed734211b26c5d3cc237be19e0dd5d93c1a8dea1367d6ebc23",
+  "triage": "f44745c02d710fee1bd12e036f8a4d53a4615018c255dd90dba7ec09a23ebb6d",
+  "to-spec": "23e7133ad3781b22ddc23335c88a975b71ebc809a7b5f734b158bb05abaaa5e8",
+  "to-tickets": "b7296c8466d53eb832047afad28932db82b1f31da4b647ec0c63a5af824a8bbc",
+  "grill-me": "b37db6d78417792b8dd9a478bc8fcdf7a008dcb94cb172247b01fda6205ba6e3",
+  "teach": "78966fd2b3ab60f3c08c25660d7a237325c1a243a9ba1103e7dc77edf9713825",
+  "wait-what": "ea4bde2069b457b52a0b2ba39bfc686a54fff73b79c91ef974224d0215298a9f",
+  "pr": "4f2bdb1aaf75c6cd0f4696889ff1022cff86ab81c3c1e3a1ba4ce00964d98146",
   "implement": "3180dbe245245f99dceb669e597cf633935cc87be0ca3c39a86dde54e62a4db9",
-  "resolving-merge-conflicts": "cf66bf26fb8a943d426271120f033825f7ed591349812ff4f636d3db56c976dc"
+  "implement-spec": "9f2d9a27a67a0edee8bcc1c12c5dae69ea77ffaf2a4898a939c6afd0c7db7f47"
 });
 export const MATT_CATALOG_DIGEST = crypto.createHash("sha256").update(JSON.stringify({
   compatibility: MATT_COMPATIBILITY,

package/src/matt.js

@@ -1,127 +1,122 @@
-import { execFileSync } from "node:child_process";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { PLATFORMS, hashDirectory } from "./catalog.js";
-import { MATT_CATALOG_DIGEST, MATT_COMPATIBILITY, MATT_CONTENT_HASHES, MATT_INSTALLABLE_SKILLS } from "./matt-catalog.mjs";
-
-export const mattReceiptPath = (projectRoot) => path.join(path.resolve(projectRoot), ".matrix", "matt-installation.json");
-
-function readJson(file) {
-  try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; }
-}
-
-function releaseOrder(left, right) {
-  const parse = (value) => String(value ?? "").replace(/^v/, "").split(".").map((part) => Number(part));
-  const a = parse(left); const b = parse(right);
-  if (a.some(Number.isNaN) || b.some(Number.isNaN)) return null;
-  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
-    if ((a[index] ?? 0) !== (b[index] ?? 0)) return (a[index] ?? 0) > (b[index] ?? 0) ? 1 : -1;
-  }
-  return 0;
-}
-
-export function inspectMattInstallation({ projectRoot, platforms, home = os.homedir(), contentHashes = MATT_CONTENT_HASHES }) {
-  const receipt = readJson(mattReceiptPath(projectRoot));
-  const selected = [...new Set(platforms ?? Object.keys(receipt?.platforms ?? {}))];
-  const localPresence = selected.reduce((count, platform) => {
-    const root = PLATFORMS[platform]?.skillRoot(projectRoot);
-    return count + MATT_INSTALLABLE_SKILLS.filter((skill) => root && fs.existsSync(path.join(root, skill, "SKILL.md"))).length;
-  }, 0);
-  const base = { supported: MATT_COMPATIBILITY, installed: receipt?.compatibility?.release ?? "unknown", action: "matrix init . --with-mattpocock" };
-  if (!receipt) return { ...base, status: localPresence ? "unverified" : "incomplete", platforms: [] };
-  const order = releaseOrder(receipt.compatibility?.release, MATT_COMPATIBILITY.release);
-  if (order !== 0 || receipt.compatibility?.commit !== MATT_COMPATIBILITY.commit || receipt.catalogDigest !== MATT_CATALOG_DIGEST) {
-    return { ...base, status: order != null && order > 0 ? "unsupported-newer" : "update-required", platforms: [] };
-  }
-  try {
-    const findings = selected.map((platform) => {
-      const root = PLATFORMS[platform].skillRoot(projectRoot);
-      const records = receipt.platforms?.[platform]?.skills ?? {};
-      const missing = MATT_INSTALLABLE_SKILLS.filter((skill) => !fs.existsSync(path.join(root, skill, "SKILL.md")) || !records[skill]?.hash);
-      const modified = MATT_INSTALLABLE_SKILLS.filter((skill) => !missing.includes(skill) && (() => {
-        const actual = hashDirectory(path.join(root, skill));
-        return actual !== records[skill].hash || actual !== contentHashes[skill];
-      })());
-      const globalRoot = PLATFORMS[platform].skillRoot(home);
-      const ignoredGlobal = MATT_INSTALLABLE_SKILLS.filter((skill) => !fs.existsSync(path.join(root, skill, "SKILL.md")) && fs.existsSync(path.join(globalRoot, skill, "SKILL.md"))).length;
-      return { platform, root, missing, modified, ignoredGlobal };
-    });
-    const status = findings.some((item) => item.missing.length) ? "incomplete"
-      : findings.some((item) => item.modified.length) ? "user-modified" : "compatible";
-    return { ...base, status, action: status === "compatible" ? null : base.action, platforms: findings };
-  } catch (error) {
-    return { ...base, status: "unknown", message: error.message, platforms: [] };
-  }
-}
-
-export function buildProcessInvocation({ command, args, platform = process.platform, nodeExecutable = process.execPath, npmCliPath }) {
-  if (platform !== "win32" || command !== "npx") return { executable: command, args, shell: false };
-  const candidates = [npmCliPath, process.env.npm_execpath, path.join(path.dirname(nodeExecutable), "node_modules", "npm", "bin", "npm-cli.js")].filter(Boolean);
-  const cli = candidates.find((candidate) => npmCliPath || fs.existsSync(candidate));
-  if (!cli) throw new Error("npm CLI was not found beside the Node runtime.");
-  const [yes, packageSpec, ...commandArgs] = args;
-  if (yes !== "--yes" || !packageSpec) throw new Error("Windows npx invocation must use fixed npm exec arguments.");
-  return { executable: nodeExecutable, args: [cli, "exec", yes, packageSpec, "--", ...commandArgs], shell: false };
-}
-
-export function defaultProcessRunner({ command, args, cwd, timeout, stdio = "inherit" }) {
-  const invocation = buildProcessInvocation({ command, args });
-  return execFileSync(invocation.executable, invocation.args, { cwd, stdio, timeout, shell: invocation.shell });
-}
-
-export function createMattAdapter({
-  run = defaultProcessRunner,
-  stdio = "inherit",
-  makeTemporary = () => fs.mkdtempSync(path.join(os.tmpdir(), "matrix-matt-")),
-  remove = (target) => fs.rmSync(target, { recursive: true, force: true }),
-  verifyCandidate = ({ root, platforms, skills }) => {
-    for (const platform of platforms) for (const skill of skills) {
-      const installed = path.join(PLATFORMS[platform].skillRoot(root), skill);
-      if (hashDirectory(installed) !== MATT_CONTENT_HASHES[skill]) throw new Error(`Matt candidate content did not match the reviewed release: ${platform}/${skill}`);
-    }
-  }
-} = {}) {
-  return {
-    installMissing() {
-      return {
-        ok: false,
-        code: "MATT_DIRECT_INSTALL_UNSUPPORTED",
-        message: "Direct Matt installation was retired; use matrix init --with-mattpocock so Distribution owns staging, backup, and recovery.",
-        recovery: "Run matrix init --with-mattpocock."
-      };
-    },
-    prepareCandidate({ platforms, skills = MATT_INSTALLABLE_SKILLS, timeout = 300_000 }) {
-      const root = makeTemporary();
-      const attempted = [];
-      try {
-        for (const platform of platforms) {
-          const args = ["--yes", MATT_COMPATIBILITY.skillsCli, "add", MATT_COMPATIBILITY.archive, "--yes", "--copy", "--agent", PLATFORMS[platform].skillsCliAgent];
-          for (const skill of skills) args.push("--skill", skill);
-          run({ command: "npx", args, cwd: root, timeout, stdio });
-          attempted.push(platform);
-        }
-        verifyCandidate({ root, platforms, skills });
-        return {
-          ok: true,
-          code: "OK",
-          root,
-          attempted,
-          platforms: Object.fromEntries(platforms.map((platform) => [platform, PLATFORMS[platform].skillRoot(root)]))
-        };
-      } catch (error) {
-        remove(root);
-        return {
-          ok: false,
-          code: "MATT_INSTALL_FAILED",
-          attempted,
-          message: error.message,
-          recovery: "Run matrix init --with-mattpocock after resolving the skills CLI error."
-        };
-      }
-    },
-    discardCandidate(candidate) {
-      if (candidate?.root) remove(candidate.root);
-    }
-  };
-}
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { PLATFORMS, hashDirectory } from "./catalog.js";
+import { buildNpmProcessInvocation } from "./npm-invocation.js";
+import { MATT_CATALOG_DIGEST, MATT_COMPATIBILITY, MATT_CONTENT_HASHES, MATT_INSTALLABLE_SKILLS } from "./matt-catalog.mjs";
+
+export const mattReceiptPath = (projectRoot) => path.join(path.resolve(projectRoot), ".matrix", "matt-installation.json");
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; }
+}
+
+function releaseOrder(left, right) {
+  const parse = (value) => String(value ?? "").replace(/^v/, "").split(".").map((part) => Number(part));
+  const a = parse(left); const b = parse(right);
+  if (a.some(Number.isNaN) || b.some(Number.isNaN)) return null;
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    if ((a[index] ?? 0) !== (b[index] ?? 0)) return (a[index] ?? 0) > (b[index] ?? 0) ? 1 : -1;
+  }
+  return 0;
+}
+
+export function inspectMattInstallation({ projectRoot, platforms, home = os.homedir(), contentHashes = MATT_CONTENT_HASHES, action = "matrix init . --with-mattpocock" }) {
+  const receipt = readJson(mattReceiptPath(projectRoot));
+  const selected = [...new Set(platforms ?? Object.keys(receipt?.platforms ?? {}))];
+  const localPresence = selected.reduce((count, platform) => {
+    const root = PLATFORMS[platform]?.skillRoot(projectRoot);
+    return count + MATT_INSTALLABLE_SKILLS.filter((skill) => root && fs.existsSync(path.join(root, skill, "SKILL.md"))).length;
+  }, 0);
+  const base = { supported: MATT_COMPATIBILITY, installed: receipt?.compatibility?.release ?? "unknown", action };
+  if (!receipt) return { ...base, status: localPresence ? "unverified" : "incomplete", platforms: [] };
+  const order = releaseOrder(receipt.compatibility?.release, MATT_COMPATIBILITY.release);
+  if (order !== 0 || receipt.compatibility?.commit !== MATT_COMPATIBILITY.commit || receipt.catalogDigest !== MATT_CATALOG_DIGEST) {
+    return { ...base, status: order != null && order > 0 ? "unsupported-newer" : "update-required", platforms: [] };
+  }
+  try {
+    const findings = selected.map((platform) => {
+      const root = PLATFORMS[platform].skillRoot(projectRoot);
+      const records = receipt.platforms?.[platform]?.skills ?? {};
+      const missing = MATT_INSTALLABLE_SKILLS.filter((skill) => !fs.existsSync(path.join(root, skill, "SKILL.md")) || !records[skill]?.hash);
+      const modified = MATT_INSTALLABLE_SKILLS.filter((skill) => !missing.includes(skill) && (() => {
+        const actual = hashDirectory(path.join(root, skill));
+        return actual !== records[skill].hash || actual !== contentHashes[skill];
+      })());
+      const globalRoot = PLATFORMS[platform].skillRoot(home);
+      const ignoredGlobal = MATT_INSTALLABLE_SKILLS.filter((skill) => !fs.existsSync(path.join(root, skill, "SKILL.md")) && fs.existsSync(path.join(globalRoot, skill, "SKILL.md"))).length;
+      return { platform, root, missing, modified, ignoredGlobal };
+    });
+    const status = findings.some((item) => item.missing.length) ? "incomplete"
+      : findings.some((item) => item.modified.length) ? "user-modified" : "compatible";
+    return { ...base, status, action: status === "compatible" ? null : base.action, platforms: findings };
+  } catch (error) {
+    return { ...base, status: "unknown", message: error.message, platforms: [] };
+  }
+}
+
+export function buildProcessInvocation({ command, args, platform = process.platform, nodeExecutable = process.execPath, npmCliPath }) {
+  return buildNpmProcessInvocation({ command, args, platform, nodeExecutable, npmCliPath });
+}
+
+export function defaultProcessRunner({ command, args, cwd, timeout, stdio = "inherit" }) {
+  const invocation = buildProcessInvocation({ command, args });
+  return execFileSync(invocation.executable, invocation.args, { cwd, stdio, timeout, shell: invocation.shell });
+}
+
+export function createMattAdapter({
+  run = defaultProcessRunner,
+  stdio = "inherit",
+  makeTemporary = () => fs.mkdtempSync(path.join(os.tmpdir(), "matrix-matt-")),
+  remove = (target) => fs.rmSync(target, { recursive: true, force: true }),
+  verifyCandidate = ({ root, platforms, skills }) => {
+    for (const platform of platforms) for (const skill of skills) {
+      const installed = path.join(PLATFORMS[platform].skillRoot(root), skill);
+      if (hashDirectory(installed) !== MATT_CONTENT_HASHES[skill]) throw new Error(`Matt candidate content did not match the reviewed release: ${platform}/${skill}`);
+    }
+  }
+} = {}) {
+  return {
+    installMissing() {
+      return {
+        ok: false,
+        code: "MATT_DIRECT_INSTALL_UNSUPPORTED",
+        message: "Direct Matt installation was retired; use matrix init --with-mattpocock so Distribution owns staging, backup, and recovery.",
+        recovery: "Run matrix init --with-mattpocock."
+      };
+    },
+    prepareCandidate({ platforms, skills = MATT_INSTALLABLE_SKILLS, timeout = 300_000 }) {
+      const root = makeTemporary();
+      const attempted = [];
+      try {
+        for (const platform of platforms) {
+          const args = ["--yes", MATT_COMPATIBILITY.skillsCli, "add", MATT_COMPATIBILITY.archive, "--yes", "--copy", "--agent", PLATFORMS[platform].skillsCliAgent];
+          for (const skill of skills) args.push("--skill", skill);
+          run({ command: "npx", args, cwd: root, timeout, stdio });
+          attempted.push(platform);
+        }
+        verifyCandidate({ root, platforms, skills });
+        return {
+          ok: true,
+          code: "OK",
+          root,
+          attempted,
+          platforms: Object.fromEntries(platforms.map((platform) => [platform, PLATFORMS[platform].skillRoot(root)]))
+        };
+      } catch (error) {
+        remove(root);
+        return {
+          ok: false,
+          code: "MATT_INSTALL_FAILED",
+          attempted,
+          message: error.message,
+          recovery: "Run matrix init --with-mattpocock after resolving the skills CLI error."
+        };
+      }
+    },
+    discardCandidate(candidate) {
+      if (candidate?.root) remove(candidate.root);
+    }
+  };
+}

package/src/messages.js

@@ -1,37 +1,46 @@
-export const messages = {
-  en: {
-    title: "Evidence-driven workflow with Prim and Arch orchestration",
-    recommended: "Recommended setup", apply: "Apply", customize: "Customize", cancel: "Cancel",
-    project: "Project (current directory)", global: "Global Matrix Skills",
-    copy: "Copy (recommended)", symlink: "Symlink (advanced)",
-    matrix: "Matrix", matt: "Matt Pocock skills", installed: "installed", ready: "Matrix is ready.",
-    noPlatform: "No verified platform was detected. Select Claude Code, Codex, or both.",
-    preview: "Planned changes", confirm: "Apply these changes?", doctor: "Installation diagnosis",
-    languageQuestion: "Language", scopeQuestion: "Installation scope", platformsQuestion: "Platforms", orchestrationQuestion: "Default orchestration",
-    mattQuestion: "Install or reconcile the supported Matt Pocock release in this project?", replaceQuestion: "Existing Matrix files are not proven managed. Back up and replace?",
-    mattReplaceQuestion: "Matt Skills contain local or unreadable content. Back them up and replace them with the supported release?",
-    yes: "Yes", no: "No", stateMissing: "missing", stateMatching: "up to date", stateComplete: "complete", stateUserModified: "user-modified", statePartial: "partial", stateOutdated: "outdated", stateSafeUpdate: "safe update", stateAdoptable: "adoptable", stateUnreadable: "unreadable", stateCompatible: "compatible", stateUpdateRequired: "update required", stateUnsupportedNewer: "unsupported newer", stateUnverified: "unverified", stateUnknown: "unknown",
-    actionInstall: "install", actionKeep: "keep", actionBackupReplace: "back up and replace", actionRepair: "repair", actionBlocked: "requires approval",
-    dryRunComplete: "Dry run complete.", defaultOrchestration: "Default orchestration", mattCompatibilityStatus: "Matt {release}: {status}",
-    manifestMissing: "No Matrix installation manifest was found for this scope.", transactionPending: "An interrupted Matrix transaction is awaiting recovery. Run matrix init again before applying a new plan.", runtimeMissing: "Bundled Matrix runtime is missing.", brokenLink: "Broken Matrix link detected.", mattGlobalIgnored: "global Matt Skills are present but ignored by the project compatibility contract.", mattSetupHint: "Matt {release} is installed for this project. Optionally run $setup-matt-pocock-skills once to configure its user-owned integrations.",
-    matrixModifiedDiagnostic: "{platform}: existing Matrix assets are not proven managed.", mattModifiedDiagnostic: "{platform}: Matt Skills contain local or unreadable content that requires separate replacement approval.", archIncompleteDiagnostic: "Arch requires the exact reviewed cohort and trusted project receipt. Retry with --with-mattpocock.", matrixStateDiagnostic: "{platform}: Matrix is {state}.", mattStateDiagnostic: "{platform}: Matt Pocock skills are {state}.", codexLegacyDiagnostic: "Codex legacy .codex/skills was detected; Matrix will not write there.", unmanagedExtraDiagnostic: "{platform}: unmanaged extra Skills are preserved and will not be invoked: {skills}."
-  },
-  "zh-CN": {
-    manifestMissing: "当前安装范围没有 Matrix 安装清单。", transactionPending: "发现中断的 Matrix 安装事务。请再次运行 matrix init 后再应用新计划。", runtimeMissing: "缺少随附的 Matrix runtime。", brokenLink: "检测到断开的 Matrix 链接。", mattGlobalIgnored: "检测到全局 Matt Skills，但项目兼容性契约不会采用它们。", mattSetupHint: "已为当前项目安装 Matt {release}。如需配置由用户拥有的集成，可显式运行一次 $setup-matt-pocock-skills。",
-    languageQuestion: "语言", scopeQuestion: "安装范围", platformsQuestion: "要配置的平台", orchestrationQuestion: "默认编排模式",
-    mattQuestion: "是否在当前项目安装或核对 Matrix 支持的 Matt Pocock Release？", replaceQuestion: "现有 Matrix 文件无法确认由 Matrix 管理。是否备份并替换？", mattReplaceQuestion: "Matt Skills 存在本地修改或不可读内容。是否先备份，再替换为受支持的 Release？",
-    yes: "是", no: "否", stateMissing: "未安装", stateMatching: "已是最新", stateComplete: "完整", stateUserModified: "已被用户修改", statePartial: "不完整", stateOutdated: "可更新", stateSafeUpdate: "可安全更新", stateAdoptable: "可接管", stateUnreadable: "不可读", stateCompatible: "兼容", stateUpdateRequired: "需要更新", stateUnsupportedNewer: "版本过新且不受支持", stateUnverified: "未验证", stateUnknown: "未知",
-    actionInstall: "安装", actionKeep: "保留", actionBackupReplace: "备份并替换", actionRepair: "修复", actionBlocked: "需要确认",
-    dryRunComplete: "预览完成。", defaultOrchestration: "默认编排", mattCompatibilityStatus: "Matt {release}：{status}",
-    title: "提供 Prim 与 Arch 编排的证据驱动工作流",
-    recommended: "推荐配置", apply: "开始安装", customize: "自定义", cancel: "取消",
-    project: "项目（当前目录）", global: "全局 Matrix Skills",
-    copy: "复制（推荐）", symlink: "符号链接（高级）",
-    matrix: "Matrix", matt: "Matt Pocock skills", installed: "已安装", ready: "Matrix 已就绪。",
-    noPlatform: "未检测到已验证的平台。请选择 Claude Code、Codex，或两者。",
-    preview: "计划变更", confirm: "确认应用这些变更？", doctor: "安装诊断",
-    matrixModifiedDiagnostic: "{platform}：现有 Matrix 资产无法确认由 Matrix 管理。", mattModifiedDiagnostic: "{platform}：Matt Skills 存在本地修改或不可读内容，需要单独授权替换。", archIncompleteDiagnostic: "Arch 需要精确匹配已审查集合和可信项目 receipt。请使用 --with-mattpocock 重试。", matrixStateDiagnostic: "{platform}：Matrix 状态为 {state}。", mattStateDiagnostic: "{platform}：Matt Pocock Skills 状态为 {state}。", codexLegacyDiagnostic: "检测到 Codex 旧版 .codex/skills；Matrix 不会写入该目录。", unmanagedExtraDiagnostic: "{platform}：将保留但不会调用这些非托管附加 Skills：{skills}。"
-  }
-};
-
-export function text(language, key) { return messages[language]?.[key] ?? messages.en[key] ?? key; }
+export const messages = {
+  en: {
+    title: "Evidence-driven workflow with Prim and Arch orchestration",
+    recommended: "Recommended setup", apply: "Apply", customize: "Customize", cancel: "Cancel",
+    project: "Project (current directory)", global: "Global Matrix Skills",
+    copy: "Copy (recommended)", symlink: "Symlink (advanced)",
+    matrix: "Matrix", matt: "Matt Pocock skills", installed: "installed", ready: "Matrix is ready.",
+    noPlatform: "No verified platform was detected. Select Claude Code, Codex, or ZCode.",
+    preview: "Planned changes", confirm: "Apply these changes?", doctor: "Installation diagnosis",
+    languageQuestion: "Language", scopeQuestion: "Installation scope", platformsQuestion: "Platforms", orchestrationQuestion: "Default orchestration",
+    orchestrationArchDetail: "Orchestrates the installed Matt Skills cohort (requires Matt Skills).", orchestrationPrimDetail: "Uses Matrix's own capabilities only (no Matt dependency).",
+    readyHint: "Type $matrix followed by your request in {platform} to start the evidence-driven workflow.",
+    mattQuestion: "Install or reconcile the supported Matt Pocock release in this project?", replaceQuestion: "Existing Matrix files are not proven managed. Back up and replace?",
+    mattReplaceQuestion: "Matt Skills contain local or unreadable content. Back them up and replace them with the supported release?",
+    mattRepairQuestion: "Matt Skills are {state}. Re-pull the supported release ({release}) now?",
+    updateScopeQuestion: "Update scope", updateScopeCurrent: "Current project only", updateScopeAll: "All indexed projects",
+    yes: "Yes", no: "No", stateMissing: "missing", stateMatching: "up to date", stateComplete: "complete", stateUserModified: "user-modified", statePartial: "partial", stateOutdated: "outdated", stateSafeUpdate: "safe update", stateAdoptable: "adoptable", stateUnreadable: "unreadable", stateCompatible: "compatible", stateUpdateRequired: "update required", stateUnsupportedNewer: "unsupported newer", stateUnverified: "unverified", stateUnknown: "unknown",
+    actionInstall: "install", actionKeep: "keep", actionBackupReplace: "back up and replace", actionRepair: "repair", actionBlocked: "requires approval",
+    dryRunComplete: "Dry run complete.", defaultOrchestration: "Default orchestration", mattCompatibilityStatus: "Matt {release}: {status}",
+    manifestMissing: "No Matrix installation manifest was found for this scope.", transactionPending: "An interrupted Matrix transaction is awaiting recovery. Run matrix init again before applying a new plan.", runtimeMissing: "Bundled Matrix runtime is missing.", brokenLink: "Broken Matrix link detected.", mattGlobalIgnored: "global Matt Skills are present but ignored by the project compatibility contract.", mattSetupHint: "Matt {release} is installed for this project. Optionally run $setup-matt-pocock-skills once to configure its user-owned integrations.",
+    matrixModifiedDiagnostic: "{platform}: existing Matrix assets are not proven managed.", mattModifiedDiagnostic: "{platform}: Matt Skills contain local or unreadable content that requires separate replacement approval.", archIncompleteDiagnostic: "Arch requires the exact reviewed cohort and trusted project receipt. Retry with --with-mattpocock.", matrixStateDiagnostic: "{platform}: Matrix is {state}.", mattStateDiagnostic: "{platform}: Matt Pocock skills are {state}.", codexLegacyDiagnostic: "Codex legacy .codex/skills was detected; Matrix will not write there.", unmanagedExtraDiagnostic: "{platform}: unmanaged extra Skills are preserved and will not be invoked: {skills}."
+  },
+  "zh-CN": {
+    manifestMissing: "当前安装范围没有 Matrix 安装清单。", transactionPending: "发现中断的 Matrix 安装事务。请再次运行 matrix init 后再应用新计划。", runtimeMissing: "缺少随附的 Matrix runtime。", brokenLink: "检测到断开的 Matrix 链接。", mattGlobalIgnored: "检测到全局 Matt Skills，但项目兼容性契约不会采用它们。", mattSetupHint: "已为当前项目安装 Matt {release}。如需配置由用户拥有的集成，可显式运行一次 $setup-matt-pocock-skills。",
+    languageQuestion: "语言", scopeQuestion: "安装范围", platformsQuestion: "要配置的平台", orchestrationQuestion: "默认编排模式",
+    orchestrationArchDetail: "编排项目内已安装的 Matt Skills 集合（需先安装 Matt）。",
+    orchestrationPrimDetail: "仅使用 Matrix 自带能力，不依赖 Matt Skills。",
+    readyHint: "在 {platform} 中输入 `$matrix` 加你的请求，即可启动证据驱动工作流。",
+    mattQuestion: "是否在当前项目安装或核对 Matrix 支持的 Matt Pocock Release？", replaceQuestion: "现有 Matrix 文件无法确认由 Matrix 管理。是否备份并替换？", mattReplaceQuestion: "Matt Skills 存在本地修改或不可读内容。是否先备份，再替换为受支持的 Release？",
+    mattRepairQuestion: "Matt Skills {state}。是否立即重新拉取受支持的 release（{release}）？",
+    updateScopeQuestion: "更新范围", updateScopeCurrent: "仅当前项目", updateScopeAll: "全部已索引项目",
+    yes: "是", no: "否", stateMissing: "未安装", stateMatching: "已是最新", stateComplete: "完整", stateUserModified: "已被用户修改", statePartial: "不完整", stateOutdated: "可更新", stateSafeUpdate: "可安全更新", stateAdoptable: "可接管", stateUnreadable: "不可读", stateCompatible: "兼容", stateUpdateRequired: "需要更新", stateUnsupportedNewer: "版本过新且不受支持", stateUnverified: "未验证", stateUnknown: "未知",
+    actionInstall: "安装", actionKeep: "保留", actionBackupReplace: "备份并替换", actionRepair: "修复", actionBlocked: "需要确认",
+    dryRunComplete: "预览完成。", defaultOrchestration: "默认编排", mattCompatibilityStatus: "Matt {release}：{status}",
+    title: "提供 Prim 与 Arch 编排的证据驱动工作流",
+    recommended: "推荐配置", apply: "开始安装", customize: "自定义", cancel: "取消",
+    project: "项目（当前目录）", global: "全局 Matrix Skills",
+    copy: "复制（推荐）", symlink: "符号链接（高级）",
+    matrix: "Matrix", matt: "Matt Pocock skills", installed: "已安装", ready: "Matrix 已就绪。",
+    noPlatform: "未检测到已验证的平台。请选择 Claude Code、Codex 或 ZCode。",
+    preview: "计划变更", confirm: "确认应用这些变更？", doctor: "安装诊断",
+    matrixModifiedDiagnostic: "{platform}：现有 Matrix 资产无法确认由 Matrix 管理。", mattModifiedDiagnostic: "{platform}：Matt Skills 存在本地修改或不可读内容，需要单独授权替换。", archIncompleteDiagnostic: "Arch 需要精确匹配已审查集合和可信项目 receipt。请使用 --with-mattpocock 重试。", matrixStateDiagnostic: "{platform}：Matrix 状态为 {state}。", mattStateDiagnostic: "{platform}：Matt Pocock Skills 状态为 {state}。", codexLegacyDiagnostic: "检测到 Codex 旧版 .codex/skills；Matrix 不会写入该目录。", unmanagedExtraDiagnostic: "{platform}：将保留但不会调用这些非托管附加 Skills：{skills}。"
+  }
+};
+
+export function text(language, key) { return messages[language]?.[key] ?? messages.en[key] ?? key; }

package/src/npm-invocation.js

@@ -0,0 +1,23 @@
+import fs from "node:fs";
+import path from "node:path";
+
+// Windows CreateProcess cannot launch npm.cmd, so npm/npx must run as
+// `node <npm-cli.js> ...`. Resolution order: explicit path, npm_execpath,
+// the npm bundled beside the running Node. Non-Windows returns the command
+// unchanged so every caller keeps its POSIX behavior.
+export function resolveNpmCli({ platform = process.platform, nodeExecutable = process.execPath, npmCliPath } = {}) {
+  if (platform !== "win32") return null;
+  const candidates = [npmCliPath, process.env.npm_execpath, path.join(path.dirname(nodeExecutable), "node_modules", "npm", "bin", "npm-cli.js")].filter(Boolean);
+  const cli = candidates.find((candidate) => npmCliPath || fs.existsSync(candidate));
+  if (!cli) throw new Error("npm CLI was not found beside the Node runtime. Install the package manually with `npm i -g <package>` or reinstall Node.js so its bundled npm is present.");
+  return cli;
+}
+
+export function buildNpmProcessInvocation({ command, args, platform = process.platform, nodeExecutable = process.execPath, npmCliPath }) {
+  if (platform !== "win32" || (command !== "npm" && command !== "npx")) return { executable: command, args, shell: false };
+  const cli = resolveNpmCli({ platform, nodeExecutable, npmCliPath });
+  if (command === "npm") return { executable: nodeExecutable, args: [cli, ...args], shell: false };
+  const [yes, packageSpec, ...commandArgs] = args;
+  if (yes !== "--yes" || !packageSpec) throw new Error("Windows npx invocation must use fixed npm exec arguments.");
+  return { executable: nodeExecutable, args: [cli, "exec", yes, packageSpec, "--", ...commandArgs], shell: false };
+}