@rosenfan/matrix 0.1.3 → 0.1.4

package/src/matt-catalog.mjs

@@ -0,0 +1,67 @@
+import crypto from "node:crypto";
+
+export const MATT_COMPATIBILITY = Object.freeze({
+  matrixVersion: "0.1.4",
+  release: "v1.2.3",
+  commit: "6acc160e4e0cd062dbbbd7a1b26ae92855edf07e",
+  archive: "https://github.com/mattpocock/skills/archive/6acc160e4e0cd062dbbbd7a1b26ae92855edf07e.tar.gz",
+  skillsCli: "skills@1.5.22"
+});
+
+export const MATT_ROLES = Object.freeze({
+  automatic: Object.freeze([
+    "grilling", "domain-modeling", "research", "prototype", "codebase-design",
+    "tdd", "diagnosing-bugs", "code-review", "wizard", "writing-for-agents"
+  ]),
+  handoff: Object.freeze([
+    "setup-matt-pocock-skills", "improve-codebase-architecture", "wayfinder", "handoff", "to-questionnaire"
+  ]),
+  standalone: Object.freeze([
+    "ask-matt", "grill-with-docs", "triage", "to-spec", "to-tickets", "grill-me", "teach", "wait-what"
+  ]),
+  incompatible: Object.freeze(["implement", "resolving-merge-conflicts"])
+});
+
+export const MATT_AUTOMATIC_SKILLS = MATT_ROLES.automatic;
+export const MATT_INSTALLABLE_SKILLS = Object.freeze([
+  ...MATT_ROLES.automatic,
+  ...MATT_ROLES.handoff,
+  ...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.
+// 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",
+  "implement": "3180dbe245245f99dceb669e597cf633935cc87be0ca3c39a86dde54e62a4db9",
+  "resolving-merge-conflicts": "cf66bf26fb8a943d426271120f033825f7ed591349812ff4f636d3db56c976dc"
+});
+export const MATT_CATALOG_DIGEST = crypto.createHash("sha256").update(JSON.stringify({
+  compatibility: MATT_COMPATIBILITY,
+  roles: MATT_ROLES,
+  installableSkills: MATT_INSTALLABLE_SKILLS,
+  contentHashes: MATT_CONTENT_HASHES
+})).digest("hex");

package/src/matt.js

@@ -1,7 +1,59 @@
-import { execFileSync } from "node:child_process";
-import fs from "node:fs";
-import path from "node:path";
-import { PLATFORMS, MATT_SKILLS } from "./catalog.js";
+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 };
@@ -13,33 +65,63 @@ export function buildProcessInvocation({ command, args, platform = process.platf
   return { executable: nodeExecutable, args: [cli, "exec", yes, packageSpec, "--", ...commandArgs], shell: false };
 }
 
-export function defaultProcessRunner({ command, args, cwd, timeout }) {
-  const invocation = buildProcessInvocation({ command, args });
-  return execFileSync(invocation.executable, invocation.args, { cwd, stdio: "inherit", timeout, shell: invocation.shell });
-}
+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 } = {}) {
-  return {
-    installMissing({ projectRoot, platforms, skills = MATT_SKILLS, global = false, timeout = 300_000 }) {
-      const attempted = [];
-      try {
-        for (const platform of platforms) {
-          const args = ["--yes", "skills@latest", "add", "mattpocock/skills", "--yes", "--agent", PLATFORMS[platform].skillsCliAgent];
-          for (const skill of skills) args.push("--skill", skill);
-          if (global) args.push("--global");
-          run({ command: "npx", args, cwd: projectRoot, timeout });
-          attempted.push(platform);
-        }
-        return { ok: true, code: "OK", attempted };
-      } catch (error) {
-        return {
-          ok: false,
-          code: "MATT_INSTALL_FAILED",
-          attempted,
-          message: error.message,
-          recovery: "Run matrix init --with-mattpocock after resolving the skills CLI error."
-        };
-      }
-    }
-  };
-}
+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

@@ -2,31 +2,35 @@ 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 (all projects)",
+    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 missing Matt Pocock skills?", replaceQuestion: "Existing Matrix files are not proven managed. Back up and replace?",
-    yes: "Yes", no: "No", stateMissing: "missing", stateMatching: "up to date", stateComplete: "complete", stateUserModified: "user-modified", statePartial: "partial", stateOutdated: "outdated",
+    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.", 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.", mattInherited: "Matt skills are satisfied by the global installation."
+    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 链接。", mattInherited: "Matt skills 由全局安装提供。",
+    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: "是否安装缺失的 Matt Pocock skills？", replaceQuestion: "现有 Matrix 文件无法确认由 Matrix 管理。是否备份并替换？",
-    yes: "是", no: "否", stateMissing: "未安装", stateMatching: "已是最新", stateComplete: "完整", stateUserModified: "已被用户修改", statePartial: "不完整", stateOutdated: "可更新",
+    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: "预览完成。",
+    dryRunComplete: "预览完成。", defaultOrchestration: "默认编排", mattCompatibilityStatus: "Matt {release}：{status}",
     title: "提供 Prim 与 Arch 编排的证据驱动工作流",
     recommended: "推荐配置", apply: "开始安装", customize: "自定义", cancel: "取消",
-    project: "项目（当前目录）", global: "全局（所有项目）",
+    project: "项目（当前目录）", global: "全局 Matrix Skills",
     copy: "复制（推荐）", symlink: "符号链接（高级）",
     matrix: "Matrix", matt: "Matt Pocock skills", installed: "已安装", ready: "Matrix 已就绪。",
     noPlatform: "未检测到已验证的平台。请选择 Claude Code、Codex，或两者。",
-    preview: "计划变更", confirm: "确认应用这些变更？", doctor: "安装诊断"
+    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}。"
   }
 };
 

package/src/runtime-resolver.js

@@ -0,0 +1,76 @@
+import fs from "node:fs";
+import path from "node:path";
+import { MATRIX_VERSION, PLATFORMS, hashDirectory, releaseCatalog } from "./catalog.js";
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; }
+}
+
+function installationScope(projectRoot) {
+  try {
+    const line = fs.readFileSync(path.join(projectRoot, ".matrix", "config.yaml"), "utf8").split(/\r?\n/).find((value) => value.startsWith("installation_scope:"));
+    return line?.split(":").slice(1).join(":").trim() === "global" ? "global" : "project";
+  } catch { return "project"; }
+}
+
+function runtimeCommand(runtime) {
+  const quoted = process.platform === "win32" ? `"${runtime}"` : `'${runtime.replaceAll("'", "'\\''")}'`;
+  return `node ${quoted}`;
+}
+
+export function resolveProjectRuntime({ projectRoot = process.cwd() } = {}) {
+  const root = path.resolve(projectRoot);
+  const manifest = readJson(path.join(root, ".matrix", "installation.json"));
+  if (!manifest) return installationScope(root) === "global"
+    ? { ok: true, code: "GLOBAL_INSTALLATION", runtime: null }
+    : { ok: true, code: "PROJECT_INSTALLATION_ABSENT", runtime: null };
+  const candidates = [];
+  let currentCatalog = null;
+  let catalogUnavailable = false;
+  try { currentCatalog = releaseCatalog(manifest.language ?? "en"); } catch { catalogUnavailable = true; }
+  for (const platform of ["codex", "claude-code"]) {
+    const expected = manifest.platforms?.[platform]?.skills?.matrix?.hash;
+    if (!expected) continue;
+    const matrixRoot = path.join(PLATFORMS[platform].skillRoot(root), "matrix");
+    const runtime = path.join(matrixRoot, "scripts", "matrix-runtime.mjs");
+    if (!fs.existsSync(runtime)) { candidates.push({ platform, matrixRoot, runtime, reason: "missing" }); continue; }
+    try {
+      const actual = hashDirectory(matrixRoot);
+      if (actual === expected) {
+        if (manifest.catalogVersion !== MATRIX_VERSION) {
+          const catalogVersion = manifest.catalogVersion ?? null;
+          return {
+            ok: false,
+            code: catalogVersion ? "PROJECT_RUNTIME_VERSION_MISMATCH" : "PROJECT_RUNTIME_VERSION_UNKNOWN",
+            message: catalogVersion
+              ? `The project Matrix Runtime is ${catalogVersion}, while this launcher is ${MATRIX_VERSION}. The project remains authoritative, but a different-release Runtime requires explicit invocation.`
+              : `The project Matrix Runtime has no release identity. The project remains authoritative, but an unidentified Runtime requires explicit invocation.`,
+            platform,
+            runtime,
+            catalogVersion,
+            launcherVersion: MATRIX_VERSION,
+            recovery_command: runtimeCommand(runtime)
+          };
+        }
+        if (catalogUnavailable
+          || manifest.catalogDigest !== currentCatalog.digest || expected !== currentCatalog.skills.matrix) {
+          return {
+            ok: false,
+            code: "PROJECT_RUNTIME_RELEASE_MISMATCH",
+            message: `The project Matrix Runtime claims ${MATRIX_VERSION} but does not match that release catalog. Run matrix update.`,
+            platform,
+            runtime,
+            catalogVersion: manifest.catalogVersion,
+            expected: currentCatalog?.skills.matrix ?? null,
+            actual
+          };
+        }
+        return { ok: true, code: "PROJECT_RUNTIME", platform, runtime, catalogVersion: manifest.catalogVersion };
+      }
+      candidates.push({ platform, matrixRoot, runtime, reason: "modified" });
+    } catch { candidates.push({ platform, matrixRoot, runtime, reason: "unreadable" }); }
+  }
+  return candidates.length
+    ? { ok: false, code: "PROJECT_RUNTIME_UNTRUSTED", message: "The project Matrix Runtime does not match its installation manifest.", findings: candidates }
+    : { ok: true, code: "PROJECT_RUNTIME_ABSENT", runtime: null };
+}

package/src/self-update.js

@@ -1,81 +1,81 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { spawnSync } from "node:child_process";
-
-export const PACKAGE_NAME = "@rosenfan/matrix";
-const REGISTRY = "https://registry.npmjs.org/@rosenfan%2fmatrix/latest";
-
-function parse(version) {
-  const match = String(version ?? "").match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
-  return match ? { numeric: match.slice(1, 4).map(Number), prerelease: match[4] ?? null } : null;
-}
-
-export function compareVersions(left, right) {
-  const a = parse(left); const b = parse(right);
-  if (!a || !b) return null;
-  for (let index = 0; index < 3; index += 1) if (a.numeric[index] !== b.numeric[index]) return a.numeric[index] - b.numeric[index];
-  if (a.prerelease === b.prerelease) return 0;
-  if (a.prerelease === null) return 1;
-  if (b.prerelease === null) return -1;
-  return a.prerelease.localeCompare(b.prerelease, undefined, { numeric: true });
-}
-
-export async function latestVersion(fetchImpl = fetch) {
-  const response = await fetchImpl(REGISTRY, { headers: { accept: "application/json" } });
-  if (!response.ok) throw new Error(`registry returned ${response.status}`);
-  const body = await response.json();
-  if (!parse(body.version)) throw new Error("registry returned an invalid version");
-  return body.version;
-}
-
-function run(command, args, options = {}) {
-  const result = spawnSync(command, args, { encoding: "utf8", ...options });
-  return { ok: !result.error && result.status === 0, status: result.status, error: result.error?.message, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
-}
-
-export function validateCandidate(packageRoot, expectedVersion) {
-  const manifestFile = path.join(packageRoot, "package.json");
-  try {
-    const manifest = JSON.parse(fs.readFileSync(manifestFile, "utf8"));
-    if (manifest.name !== PACKAGE_NAME || manifest.version !== expectedVersion) return { ok: false, reason: "candidate package identity mismatch" };
-    for (const directory of [".claude/skills", "assets/skills-zh-CN", "src", "bin"]) if (!fs.existsSync(path.join(packageRoot, directory))) return { ok: false, reason: `candidate missing ${directory}` };
-    for (const languageRoot of [path.join(packageRoot, ".claude", "skills"), path.join(packageRoot, "assets", "skills-zh-CN")]) if (!fs.existsSync(path.join(languageRoot, "matrix", "SKILL.md"))) return { ok: false, reason: "candidate Matrix assets are incomplete" };
-    for (const args of [["--version"], ["--help"], ["workflow", "doctor", "--json"]]) {
-      const result = run(process.execPath, [path.join(packageRoot, "bin", "matrix.js"), ...args], { cwd: os.tmpdir() });
-      if (!result.ok) return { ok: false, reason: `candidate command failed: matrix ${args.join(" ")}` };
-    }
-    return { ok: true };
-  } catch (error) { return { ok: false, reason: error.message }; }
-}
-
-export function npmGlobalRoot() {
-  const result = run("npm", ["root", "-g"]);
-  if (!result.ok) throw new Error(result.error ?? result.stderr.trim() ?? "npm root -g failed");
-  return result.stdout.trim();
-}
-
-export function validateRegistryCandidate(version) {
-  const temporary = fs.mkdtempSync(path.join(os.tmpdir(), "matrix-update-"));
-  try {
-    const install = run("npm", ["install", "--prefix", temporary, "--ignore-scripts", "--no-save", "--package-lock=false", `${PACKAGE_NAME}@${version}`], { cwd: temporary });
-    if (!install.ok) return { ok: false, reason: install.error ?? install.stderr.trim() ?? "candidate installation failed" };
-    return validateCandidate(path.join(temporary, "node_modules", "@rosenfan", "matrix"), version);
-  } finally { fs.rmSync(temporary, { recursive: true, force: true }); }
-}
-
-export function installGlobal(version) {
-  const result = run("npm", ["install", "--global", `${PACKAGE_NAME}@${version}`]);
-  return result.ok ? { ok: true } : { ok: false, reason: result.error ?? result.stderr.trim() ?? "npm install failed" };
-}
-
-export function selfUpdate(currentVersion, targetVersion) {
-  const candidate = validateRegistryCandidate(targetVersion);
-  if (!candidate.ok) return candidate;
-  const install = installGlobal(targetVersion);
-  if (install.ok) return install;
-  const rollback = installGlobal(currentVersion);
-  return { ok: false, reason: `${install.reason}; ${rollback.ok ? `restored ${currentVersion}` : `rollback failed: ${rollback.reason}`}` };
-}
-
-export function globalBinPath() { return path.join(npmGlobalRoot(), "@rosenfan", "matrix", "bin", "matrix.js"); }
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+export const PACKAGE_NAME = "@rosenfan/matrix";
+const REGISTRY = "https://registry.npmjs.org/@rosenfan%2fmatrix/latest";
+
+function parse(version) {
+  const match = String(version ?? "").match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+  return match ? { numeric: match.slice(1, 4).map(Number), prerelease: match[4] ?? null } : null;
+}
+
+export function compareVersions(left, right) {
+  const a = parse(left); const b = parse(right);
+  if (!a || !b) return null;
+  for (let index = 0; index < 3; index += 1) if (a.numeric[index] !== b.numeric[index]) return a.numeric[index] - b.numeric[index];
+  if (a.prerelease === b.prerelease) return 0;
+  if (a.prerelease === null) return 1;
+  if (b.prerelease === null) return -1;
+  return a.prerelease.localeCompare(b.prerelease, undefined, { numeric: true });
+}
+
+export async function latestVersion(fetchImpl = fetch) {
+  const response = await fetchImpl(REGISTRY, { headers: { accept: "application/json" } });
+  if (!response.ok) throw new Error(`registry returned ${response.status}`);
+  const body = await response.json();
+  if (!parse(body.version)) throw new Error("registry returned an invalid version");
+  return body.version;
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, { encoding: "utf8", ...options });
+  return { ok: !result.error && result.status === 0, status: result.status, error: result.error?.message, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+}
+
+export function validateCandidate(packageRoot, expectedVersion) {
+  const manifestFile = path.join(packageRoot, "package.json");
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestFile, "utf8"));
+    if (manifest.name !== PACKAGE_NAME || manifest.version !== expectedVersion) return { ok: false, reason: "candidate package identity mismatch" };
+    for (const directory of [".claude/skills", "assets/skills-zh-CN", "src", "bin"]) if (!fs.existsSync(path.join(packageRoot, directory))) return { ok: false, reason: `candidate missing ${directory}` };
+    for (const languageRoot of [path.join(packageRoot, ".claude", "skills"), path.join(packageRoot, "assets", "skills-zh-CN")]) if (!fs.existsSync(path.join(languageRoot, "matrix", "SKILL.md"))) return { ok: false, reason: "candidate Matrix assets are incomplete" };
+    for (const args of [["--version"], ["--help"], ["workflow", "doctor", "--json"]]) {
+      const result = run(process.execPath, [path.join(packageRoot, "bin", "matrix.js"), ...args], { cwd: os.tmpdir() });
+      if (!result.ok) return { ok: false, reason: `candidate command failed: matrix ${args.join(" ")}` };
+    }
+    return { ok: true };
+  } catch (error) { return { ok: false, reason: error.message }; }
+}
+
+export function npmGlobalRoot() {
+  const result = run("npm", ["root", "-g"]);
+  if (!result.ok) throw new Error(result.error ?? result.stderr.trim() ?? "npm root -g failed");
+  return result.stdout.trim();
+}
+
+export function validateRegistryCandidate(version) {
+  const temporary = fs.mkdtempSync(path.join(os.tmpdir(), "matrix-update-"));
+  try {
+    const install = run("npm", ["install", "--prefix", temporary, "--ignore-scripts", "--no-save", "--package-lock=false", `${PACKAGE_NAME}@${version}`], { cwd: temporary });
+    if (!install.ok) return { ok: false, reason: install.error ?? install.stderr.trim() ?? "candidate installation failed" };
+    return validateCandidate(path.join(temporary, "node_modules", "@rosenfan", "matrix"), version);
+  } finally { fs.rmSync(temporary, { recursive: true, force: true }); }
+}
+
+export function installGlobal(version) {
+  const result = run("npm", ["install", "--global", `${PACKAGE_NAME}@${version}`]);
+  return result.ok ? { ok: true } : { ok: false, reason: result.error ?? result.stderr.trim() ?? "npm install failed" };
+}
+
+export function selfUpdate(currentVersion, targetVersion) {
+  const candidate = validateRegistryCandidate(targetVersion);
+  if (!candidate.ok) return candidate;
+  const install = installGlobal(targetVersion);
+  if (install.ok) return install;
+  const rollback = installGlobal(currentVersion);
+  return { ok: false, reason: `${install.reason}; ${rollback.ok ? `restored ${currentVersion}` : `rollback failed: ${rollback.reason}`}` };
+}
+
+export function globalBinPath() { return path.join(npmGlobalRoot(), "@rosenfan", "matrix", "bin", "matrix.js"); }

package/src/workflow-transaction.js

@@ -1,14 +1,18 @@
 import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import crypto from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
 
 const JOURNAL_SCHEMA = "matrix/workflow-transaction/v1";
 const RECEIPT_SCHEMA = "matrix/workflow-transaction-receipt/v1";
 const LOCK_SCHEMA = "matrix/workflow-lock/v1";
 const MAX_JOURNAL_BYTES = 1024 * 1024;
 const MAX_TRANSACTIONS = 128;
-const RECEIPT_LIMIT = 32;
+const RECEIPT_LIMIT = 32;
+const quoteCommandPath = (value) => process.platform === "win32" ? `"${value}"` : `'${value.replaceAll("'", "'\\''")}'`;
+const workflowRuntimePath = path.join(path.dirname(fileURLToPath(import.meta.url)), "matrix-runtime.mjs");
+const workflowCommand = (argumentsText) => `node ${quoteCommandPath(workflowRuntimePath)} ${argumentsText}`;
 
 const stamp = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 const fail = (code, message, extra = {}) => ({ ok: false, code, message, ...extra });
@@ -430,11 +434,11 @@ export function workflowMutationGate(cwd) {
   let pending;
   try { pending = pendingTransactions(cwd); }
   catch (error) { return recoverError(error, null); }
-  if (pending.length) return fail("WORKFLOW_RECOVERY_REQUIRED", "An unfinished Workflow transaction must be resolved before starting another mutation.", { transactions: pending.map(({ id }) => id), recovery_command: "matrix workflow doctor" });
+  if (pending.length) return fail("WORKFLOW_RECOVERY_REQUIRED", "An unfinished Workflow transaction must be resolved before starting another mutation.", { transactions: pending.map(({ id }) => id), recovery_command: workflowCommand("doctor") });
   const currentLock = readLock(cwd);
   if (!currentLock) return null;
   const owner = lockOwner(currentLock);
-  return fail(owner === "active" ? "WORKFLOW_BUSY" : owner === "absent" ? "WORKFLOW_RECOVERY_REQUIRED" : "WORKFLOW_LOCK_CONFLICT", owner === "active" ? "An active Workflow mutation owns the project boundary." : "A Workflow lock requires explicit doctor recovery.", { lock_id: currentLock.id, transaction_id: currentLock.transaction_id, recovery_command: "matrix workflow doctor" });
+  return fail(owner === "active" ? "WORKFLOW_BUSY" : owner === "absent" ? "WORKFLOW_RECOVERY_REQUIRED" : "WORKFLOW_LOCK_CONFLICT", owner === "active" ? "An active Workflow mutation owns the project boundary." : "A Workflow lock requires explicit doctor recovery.", { lock_id: currentLock.id, transaction_id: currentLock.transaction_id, recovery_command: workflowCommand("doctor") });
 }
 
 function compactReceipt(cwd, journal, disposition) {
@@ -474,7 +478,7 @@ function recoverError(error, transactionId) {
   const code = error.code && String(error.code).startsWith("WORKFLOW_") ? error.code : "WORKFLOW_PERSISTENCE_FAILED";
   return fail(code, error.message, {
     transaction_id: transactionId,
-    recovery_command: `matrix workflow doctor --repair --transaction ${transactionId} --strategy continue`
+    recovery_command: workflowCommand(`doctor --repair --transaction ${transactionId} --strategy continue`)
   });
 }
 
@@ -559,7 +563,7 @@ function repairTransaction(cwd, id, strategy) {
 }
 
 function exactCommands(transaction) {
-  return transaction.strategies.map((strategy) => `matrix workflow doctor --repair --transaction ${transaction.id} --strategy ${strategy}`);
+  return transaction.strategies.map((strategy) => workflowCommand(`doctor --repair --transaction ${transaction.id} --strategy ${strategy}`));
 }
 
 export function workflowDoctor(cwd, { repair = false, transaction = null, strategy = null, lock = null } = {}) {
@@ -585,7 +589,7 @@ export function workflowDoctor(cwd, { repair = false, transaction = null, strate
         transaction_id: currentLock.transaction_id,
         owner,
         commands: owner === "absent" && !transactions.some((item) => item.id === currentLock.transaction_id && (item.corrupt || !["committed", "rolled-back"].includes(item.status)))
-          ? [`matrix workflow doctor --repair --lock ${currentLock.id}`]
+          ? [workflowCommand(`doctor --repair --lock ${currentLock.id}`)]
           : []
       }] : [])
     ];