@rosenfan/matrix 0.1.0

package/assets/skills-zh-CN/matrix/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: matrix
+description: 启动、恢复并治理持久化的 Matrix 开发工作流。
+---
+
+# Matrix
+
+Matrix 的事实来源是当前项目的 `.matrix/`，不得从聊天记录推断阶段。
+
+先执行：
+
+```powershell
+matrix workflow inspect
+```
+
+只有当系统明确报告 `matrix` 命令不存在时，才解析当前 Matrix Skill 目录并执行：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect
+```
+
+若没有活动变更，为开发请求创建 kebab-case 变更 ID：
+
+```powershell
+matrix workflow init <change-id> --workflow <full|hotfix|tweak> --title "<title>"
+```
+
+阶段只能由 `matrix workflow transition` 推进；架构、范围或归档前必须征求用户确认。

package/assets/skills-zh-CN/matrix-archive/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: matrix-archive
+description: 关闭并归档已经验证的 Matrix 变更。
+---
+
+# Matrix Archive
+
+仅在 verify 证据完整、用户确认归档时执行：
+
+```powershell
+matrix workflow archive
+```

package/assets/skills-zh-CN/matrix-build/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: matrix-build
+description: 用测试优先的纵向切片实现冻结的 Matrix 计划。
+---
+
+# Matrix Build
+
+只实现冻结计划中的范围。使用 `implement` 与预先确认的 `tdd` 测试边界；持续记录 `artifacts/verification.md` 的 `## Build evidence`。如发现范围或设计变化，返回设计阶段。
+
+```powershell
+matrix workflow guard build
+matrix workflow transition verify
+```

package/assets/skills-zh-CN/matrix-claude/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: matrix-claude
+description: 将冻结的 Matrix 设计导出为受边界约束的 Claude Code 任务包，不改变 Matrix 工作流状态。
+---
+
+# Matrix Claude Handoff
+
+这是可选的旁路操作，而不是 Matrix phase。它不得执行 `transition`、`archive`，也不得写入 `matrix.yaml`、`run-state.json` 或 `events.jsonl`。
+
+仅当设计阶段守卫已通过，并且用户明确选择由 Claude Code 实现时使用。先检查：
+
+```powershell
+matrix workflow guard design
+```
+
+如果主命令确实不在 PATH 中，才使用已安装根 Matrix Skill 中的 bundled runtime；主命令已启动但返回业务错误时不得回退。
+
+导出通用任务包：
+
+```powershell
+matrix workflow export --task-id <ID> --target generic
+```
+
+导出 FnSec 任务包时，只有在 `docs/tasks/active.md` 包含 `NO_ACTIVE_OBJECTIVE` 时才可使用 `--apply-fnsec-board`；现有任务绝不覆盖：
+
+```powershell
+matrix workflow export --task-id <ID> --target fnsec --apply-fnsec-board
+```
+
+任务包会包含冻结的 proposal、design、plan，以及 Claude Code 回执所需的改动、验证、边界确认和 `NEEDS_DECISION` 项目。

package/assets/skills-zh-CN/matrix-design/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: matrix-design
+description: 在实现前设计并冻结活动 Matrix 变更。
+---
+
+# Matrix Design
+
+阅读 proposal，写入 `design.md`（`## Decisions`、`## Boundaries`、`## Test seams`、`## Risks`）与 `plan.md`（`## Steps`、`## Validation`、`## Stop conditions`）。重大范围或架构决策须先由用户确认。
+
+```powershell
+matrix workflow guard design
+matrix workflow transition build
+```

package/assets/skills-zh-CN/matrix-hotfix/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: matrix-hotfix
+description: 为可复现的小型缺陷运行受约束的 Matrix 工作流。
+---
+
+# Matrix Hotfix
+
+从 `$matrix` 以 `hotfix` 工作流启动。使用 `diagnosing-bugs` 建立可复现的红色反馈循环；如果问题影响架构、公开 API、数据模式或多模块协调，要求升级为完整工作流。

package/assets/skills-zh-CN/matrix-open/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: matrix-open
+description: 将开发请求澄清为有证据的 Matrix 提案。
+---
+
+# Matrix Open
+
+读取 `matrix workflow inspect` 的活动变更。使用 `grill-with-docs` 澄清完整工作流请求；写入 `artifacts/proposal.md`，必须包含 `## Goal`、`## Scope`、`## Non-goals`、`## Acceptance`、`## Risks`。
+
+```powershell
+matrix workflow guard open
+matrix workflow transition design
+```

package/assets/skills-zh-CN/matrix-status/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: matrix-status
+description: 检查活动 Matrix 工作流的磁盘状态、守卫与恢复命令。
+---
+
+# Matrix Status
+
+执行：
+
+```powershell
+matrix workflow inspect
+```
+
+报告变更 ID、工作流、阶段、守卫结果和 `next_skill`；不得修改状态。

package/assets/skills-zh-CN/matrix-tweak/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: matrix-tweak
+description: 为边界清晰的小改动运行轻量 Matrix 工作流。
+---
+
+# Matrix Tweak
+
+从 `$matrix` 以 `tweak` 工作流启动。保持提案和设计简洁，但仍定义验收条件与测试边界。若涉及 API、模式、架构或跨模块协调，升级为完整工作流。

package/assets/skills-zh-CN/matrix-verify/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: matrix-verify
+description: 依据计划验证 Matrix 变更并审查差异。
+---
+
+# Matrix Verify
+
+运行计划的验证命令，在 `verification.md` 写入 `## Test evidence`。使用 `code-review` 完成标准与规格双轴审查，并在 `## Review evidence` 记录结论。失败时回到产生问题的阶段。
+
+```powershell
+matrix workflow guard verify
+matrix workflow transition archive
+```

package/bin/matrix.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli.js";
+
+main(process.argv.slice(2)).then((exitCode) => {
+  if (Number.isInteger(exitCode) && exitCode !== 0) process.exitCode = exitCode;
+}).catch((error) => {
+  if (error.code === "CANCELLED") {
+    console.log("\nCancelled.");
+    process.exitCode = 0;
+  } else {
+    console.error(`\nMatrix error: ${error.message}`);
+    process.exitCode = 1;
+  }
+});

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@rosenfan/matrix",
+  "version": "0.1.0",
+  "description": "Install and manage the Matrix workflow for Matt Pocock's agent skills.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "matrix": "bin/matrix.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "assets/skills-zh-CN",
+    ".claude/skills/matrix",
+    ".claude/skills/matrix-open",
+    ".claude/skills/matrix-design",
+    ".claude/skills/matrix-build",
+    ".claude/skills/matrix-verify",
+    ".claude/skills/matrix-archive",
+    ".claude/skills/matrix-hotfix",
+    ".claude/skills/matrix-tweak",
+    ".claude/skills/matrix-status",
+    ".claude/skills/matrix-claude",
+    "!.claude/skills/**/__pycache__",
+    "!.claude/skills/**/scripts/test_*.py",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm run test && npm run pack:check"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rosenfan/Matrix.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Rosenfan/Matrix/issues"
+  },
+  "homepage": "https://github.com/Rosenfan/Matrix#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "claude-code",
+    "agent-skills",
+    "workflow",
+    "tdd",
+    "ai"
+  ]
+}

package/src/catalog.js

@@ -0,0 +1,87 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const LANGUAGE_IDS = ["en", "zh-CN"];
+export const PLATFORM_IDS = ["claude-code", "codex"];
+export const MATRIX_SKILLS = [
+  "matrix", "matrix-open", "matrix-design", "matrix-build", "matrix-verify",
+  "matrix-archive", "matrix-hotfix", "matrix-tweak", "matrix-status", "matrix-claude"
+];
+export const MATT_SKILLS = [
+  "grill-with-docs", "domain-modeling", "research", "wayfinder", "prototype",
+  "codebase-design", "implement", "tdd", "code-review", "diagnosing-bugs",
+  "resolving-merge-conflicts", "improve-codebase-architecture"
+];
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const packageManifest = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+
+export const PLATFORMS = {
+  "claude-code": {
+    id: "claude-code", name: "Claude Code", skillsCliAgent: "claude-code",
+    skillRoot(base) { return path.join(base, ".claude", "skills"); },
+    legacyRoots() { return []; }
+  },
+  codex: {
+    id: "codex", name: "Codex", skillsCliAgent: "codex",
+    skillRoot(base) { return path.join(base, ".agents", "skills"); },
+    legacyRoots(base) { return [path.join(base, ".codex", "skills")]; }
+  }
+};
+
+export function sourceSkillsRoot(language = "en") {
+  const localized = language === "zh-CN"
+    ? path.join(packageRoot, "assets", "skills-zh-CN")
+    : path.join(packageRoot, ".claude", "skills");
+  if (!fs.existsSync(localized)) throw new Error(`Matrix package is incomplete: ${language} assets are missing.`);
+  return localized;
+}
+
+export function scopeBase(scope, projectRoot, home = os.homedir()) {
+  return scope === "global" ? home : projectRoot;
+}
+
+export function installationRoot(scope, projectRoot, home) {
+  return path.join(scopeBase(scope, projectRoot, home), ".matrix");
+}
+
+export function manifestPath(scope, projectRoot, home) {
+  return path.join(installationRoot(scope, projectRoot, home), "installation.json");
+}
+
+export function hashDirectory(directory, extraFiles = []) {
+  const hash = crypto.createHash("sha256");
+  const files = new Map();
+  const visit = (current, relative = "") => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const child = path.join(current, entry.name);
+      const childRelative = path.join(relative, entry.name).replaceAll("\\", "/");
+      if (entry.isDirectory()) visit(child, childRelative);
+      else if (entry.isFile()) {
+        files.set(childRelative, fs.readFileSync(child));
+      }
+    }
+  };
+  visit(directory);
+  for (const extra of extraFiles) files.set(extra.path, Buffer.from(extra.contents));
+  for (const [relative, contents] of [...files.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+    hash.update(`${relative}\0`);
+    hash.update(contents);
+  }
+  return hash.digest("hex");
+}
+
+export function workflowRuntimeSource() { return path.join(packageRoot, "src", "workflow.js"); }
+
+export function releaseCatalog(language = "en") {
+  if (!LANGUAGE_IDS.includes(language)) throw new Error(`Unsupported language: ${language}`);
+  const root = sourceSkillsRoot(language);
+  const missing = MATRIX_SKILLS.filter((skill) => !fs.existsSync(path.join(root, skill, "SKILL.md")));
+  if (missing.length) throw new Error(`Matrix package is incomplete. Missing: ${missing.join(", ")}`);
+  const runtime = fs.readFileSync(workflowRuntimeSource());
+  const skills = Object.fromEntries(MATRIX_SKILLS.map((skill) => [skill, hashDirectory(path.join(root, skill), [{ path: "scripts/matrix-runtime.mjs", contents: runtime }])]));
+  return { language, root, version: packageManifest.version, skills, digest: crypto.createHash("sha256").update(JSON.stringify(skills)).digest("hex") };
+}

package/src/cli.js

@@ -0,0 +1,117 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { PLATFORMS } from "./catalog.js";
+import { createDistribution } from "./distribution.js";
+import { text } from "./messages.js";
+import { createUi } from "./ui.js";
+import { invoke } from "./workflow.js";
+
+const packagePath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+const version = JSON.parse(fs.readFileSync(packagePath, "utf8")).version;
+const HELP = `Matrix ${version}\n\nUsage: matrix init [directory] [options]\n       matrix doctor [directory] [options]\n\nOptions:\n  --language <en|zh-CN>\n  --scope <project|global>\n  --platform <claude-code|codex>  (repeatable)\n  --mode <copy|symlink>\n  --with-mattpocock | --without-mattpocock\n  --force  --yes, -y  --dry-run  --json  --no-color`;
+
+function parse(argv) {
+  const result = { command: null, directory: null, scope: null, language: null, platforms: [], mode: "copy", matt: null, matrixPolicy: "safe", yes: false, dryRun: false, json: false, color: true };
+  const values = [...argv];
+  if (values[0] && !values[0].startsWith("-")) result.command = values.shift();
+  while (values.length) {
+    const token = values.shift();
+    if (!token.startsWith("-") && !result.directory) result.directory = token;
+    else if (token === "--scope") result.scope = values.shift();
+    else if (token === "--language") result.language = values.shift();
+    else if (token === "--platform") result.platforms.push(values.shift());
+    else if (token === "--mode") result.mode = values.shift();
+    else if (token === "--with-mattpocock") result.matt = "missing";
+    else if (token === "--without-mattpocock") result.matt = "none";
+    else if (token === "--force") result.matrixPolicy = "replace";
+    else if (["--yes", "-y"].includes(token)) result.yes = true;
+    else if (token === "--dry-run") result.dryRun = true;
+    else if (token === "--json") result.json = true;
+    else if (token === "--no-color") result.color = false;
+    else if (["--help", "-h"].includes(token)) result.help = true;
+    else if (["--version", "-v"].includes(token)) result.version = true;
+    else throw new Error(`Unknown option: ${token}`);
+  }
+  return result;
+}
+
+function projectRoot(directory) {
+  const value = path.resolve(directory ?? process.cwd());
+  if (!fs.existsSync(value) || !fs.statSync(value).isDirectory()) throw new Error(`Not a directory: ${value}`);
+  return value;
+}
+
+function labelsFor(language) { return { yes: text(language, "yes"), no: text(language, "no") }; }
+
+function localizedState(language, state) {
+  return text(language, ({ missing: "stateMissing", matching: "stateMatching", complete: "stateComplete", "user-modified": "stateUserModified", partial: "statePartial", damaged: "statePartial", newer: "stateMatching", "outdated-unchanged": "stateOutdated" })[state] ?? state);
+}
+
+function localizedAction(language, action) {
+  return text(language, ({ install: "actionInstall", keep: "actionKeep", "backup-replace": "actionBackupReplace", repair: "actionRepair", blocked: "actionBlocked" })[action] ?? action);
+}
+
+async function intentFrom(options, ui) {
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY && !options.json);
+  const language = options.language ?? (options.yes ? "en" : await ui.select("Language / 语言", [{ label: "English", value: "en" }, { label: "中文", value: "zh-CN" }]));
+  const scope = options.scope ?? (options.yes ? "project" : await ui.select(text(language, "scopeQuestion"), [{ label: text(language, "project"), value: "project" }, { label: text(language, "global"), value: "global" }]));
+  let platforms = options.platforms;
+  if (!platforms.length && interactive && !options.yes) platforms = await ui.selectMany(text(language, "platformsQuestion"), [{ label: "Claude Code", value: "claude-code" }, { label: "Codex", value: "codex" }]);
+  const matt = options.matt ?? (interactive && !options.yes ? (await ui.confirm(text(language, "mattQuestion"), true, labelsFor(language)) ? "missing" : "none") : "missing");
+  return { projectRoot: projectRoot(options.directory), language, scope, platforms, mode: options.mode, matt, matrixPolicy: options.matrixPolicy, dryRun: options.dryRun };
+}
+
+function render(ui, evaluation) {
+  const language = evaluation.intent?.language ?? "en";
+  const actions = (evaluation.actions ?? []).map((item) => `${item.platform}: ${localizedAction(language, item.matrix)}`).join(", ");
+  ui.info(actions ? `${text(language, "preview")}: ${actions}` : evaluation.code);
+  for (const item of evaluation.observations ?? []) ui.muted(`${item.name}: ${text(language, "matrix")} ${localizedState(language, item.matrix)}；${text(language, "matt")} ${localizedState(language, item.matt.state)}${item.matt.inherited ? ` (${text(language, "global")})` : ""}`);
+  for (const item of evaluation.diagnostics ?? []) ui.warn(item.code === "USER_MODIFIED_BLOCKED" ? text(language, "replaceQuestion") : item.message ?? item.code);
+  for (const item of evaluation.diagnosis ?? []) (item.code === "MATT_INHERITED" ? ui.muted : ui.warn)(item.message ?? item.code);
+}
+
+async function init(options) {
+  const ui = createUi({ color: options.color && !options.json });
+  if (!options.json) await ui.banner();
+  const intent = await intentFrom(options, ui);
+  const distribution = createDistribution();
+  let evaluation = distribution.evaluate(intent);
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY && !options.json);
+  if (!evaluation.ok && evaluation.code === "USER_MODIFIED_BLOCKED" && interactive && !options.yes && await ui.confirm(text(intent.language, "replaceQuestion"), false, labelsFor(intent.language))) evaluation = distribution.evaluate({ ...intent, matrixPolicy: "replace" });
+  if (options.json) { console.log(JSON.stringify(evaluation)); return evaluation.ok ? 0 : 2; }
+  render(ui, evaluation);
+  if (!evaluation.ok) return 2;
+  if (!options.yes && interactive && !options.dryRun && !await ui.confirm(text(intent.language, "confirm"), true, labelsFor(intent.language))) return 0;
+  const result = distribution.commit(evaluation.plan);
+  if (!result.ok) { ui.warn(result.error ?? result.code); return 2; }
+  if (result.code === "PARTIAL") { ui.warn(result.recovery); return 1; }
+  ui.success(options.dryRun ? text(intent.language, "dryRunComplete") : text(intent.language, "ready"));
+  ui.muted(evaluation.intent.platforms.map((id) => `${PLATFORMS[id].name}: $matrix <request>`).join("\n"));
+  return 0;
+}
+
+async function doctor(options) {
+  const ui = createUi({ color: options.color && !options.json });
+  const intent = await intentFrom({ ...options, yes: true }, ui);
+  const evaluation = createDistribution().diagnose(intent);
+  if (options.json) console.log(JSON.stringify(evaluation));
+  else { await ui.banner(); ui.info(text(intent.language, "doctor")); render(ui, evaluation); }
+  return evaluation.ok ? 0 : 2;
+}
+
+export async function main(argv) {
+  if (argv[0] === "workflow") {
+    const json = argv.includes("--json");
+    const result = invoke(argv.slice(1).filter((value) => value !== "--json"));
+    if (json) console.log(JSON.stringify(result));
+    else console.log(result.ok ? JSON.stringify(result, null, 2) : `MATRIX ERROR [${result.code}]: ${result.message}`);
+    return result.ok ? 0 : 2;
+  }
+  const options = parse(argv);
+  if (options.version) { console.log(version); return 0; }
+  if (options.help || !options.command) { console.log(HELP); return 0; }
+  if (options.command === "init") return init(options);
+  if (options.command === "doctor") return doctor(options);
+  throw new Error(`Unknown command: ${options.command}. Run matrix --help.`);
+}

package/src/distribution.js

@@ -0,0 +1,192 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  MATRIX_SKILLS, MATT_SKILLS, PLATFORM_IDS, PLATFORMS, hashDirectory,
+  installationRoot, manifestPath, releaseCatalog, scopeBase, sourceSkillsRoot, workflowRuntimeSource
+} from "./catalog.js";
+import { createMattAdapter } from "./matt.js";
+import { text } from "./messages.js";
+
+const VERSION = 1;
+const digest = (value) => crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const exists = (value) => fs.existsSync(value);
+const pathExists = (value) => { try { fs.lstatSync(value); return true; } catch { return false; } };
+const nowStamp = () => new Date().toISOString().replace(/[:.]/g, "-");
+const transactionPath = (intent) => path.join(installationRoot(intent.scope, intent.projectRoot, intent.home), "transaction.json");
+const writeJson = (file, value) => {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`);
+  fs.renameSync(temporary, file);
+};
+const readJson = (file) => { try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; } };
+const removeEntry = (value) => { if (pathExists(value)) fs.rmSync(value, { recursive: true, force: true }); };
+const removeStaging = (stagingRoot) => {
+  removeEntry(stagingRoot);
+  const parent = path.dirname(stagingRoot);
+  if (exists(parent) && fs.readdirSync(parent).length === 0) fs.rmdirSync(parent);
+};
+const compareVersions = (left, right) => {
+  const parse = (value) => String(value ?? "0.0.0").split("-")[0].split(".").map((part) => Number(part) || 0);
+  const a = parse(left); const b = parse(right);
+  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;
+};
+const skillPresent = (root, skill) => exists(path.join(root, skill, "SKILL.md"));
+const isBrokenLink = (value) => { try { return fs.lstatSync(value).isSymbolicLink() && !exists(value); } catch { return false; } };
+
+function readManifest(intent) { return readJson(manifestPath(intent.scope, intent.projectRoot, intent.home)); }
+
+function detectPlatforms(projectRoot, scope, home) {
+  const bases = [scopeBase(scope, projectRoot, home)];
+  if (scope === "project") bases.push(home);
+  return PLATFORM_IDS.filter((id) => bases.some((base) => exists(PLATFORMS[id].skillRoot(base))));
+}
+
+function normalizeIntent(raw) {
+  const scope = raw.scope ?? "project";
+  const platforms = [...new Set(raw.platforms ?? [])];
+  if (!["project", "global"].includes(scope)) return { error: "INVALID_INTENT", detail: "scope" };
+  if (!["copy", "symlink"].includes(raw.mode ?? "copy")) return { error: "INVALID_INTENT", detail: "mode" };
+  if (!["en", "zh-CN"].includes(raw.language ?? "en")) return { error: "INVALID_INTENT", detail: "language" };
+  if (platforms.some((id) => !PLATFORM_IDS.includes(id))) return { error: "UNVERIFIED_PLATFORM" };
+  return { projectRoot: path.resolve(raw.projectRoot ?? process.cwd()), home: raw.home ?? os.homedir(), scope, platforms,
+    language: raw.language ?? "en", mode: raw.mode ?? "copy", matrixPolicy: raw.matrixPolicy ?? "safe",
+    matt: raw.matt ?? "none", dryRun: Boolean(raw.dryRun) };
+}
+
+function observePlatform(intent, catalog, manifest, platformId) {
+  const platform = PLATFORMS[platformId]; const base = scopeBase(intent.scope, intent.projectRoot, intent.home);
+  const root = platform.skillRoot(base); const records = manifest?.platforms?.[platformId]?.skills ?? {};
+  const skills = MATRIX_SKILLS.map((skill) => {
+    const target = path.join(root, skill);
+    if (!pathExists(target)) return { skill, target, state: "missing" };
+    if (isBrokenLink(target) || !exists(path.join(target, "SKILL.md"))) return { skill, target, state: "damaged" };
+    const actual = hashDirectory(target); const recorded = records[skill]?.hash; const expected = catalog.skills[skill];
+    if (!recorded) return { skill, target, state: "user-modified", actual };
+    if (actual === expected) return { skill, target, state: "matching", actual };
+    if (actual === recorded) return { skill, target, state: compareVersions(manifest?.catalogVersion, catalog.version) > 0 ? "newer" : "outdated-unchanged", actual };
+    return { skill, target, state: "user-modified", actual };
+  });
+  const states = new Set(skills.map((item) => item.state));
+  const matrix = states.size === 1 && states.has("matching") ? "matching" : states.has("user-modified") ? "user-modified"
+    : states.has("missing") && states.size === 1 ? "missing" : states.has("newer") ? "newer"
+      : states.has("damaged") ? "damaged" : states.has("outdated-unchanged") ? "outdated-unchanged" : "partial";
+  const globalRoot = platform.skillRoot(intent.home);
+  const mattPresent = MATT_SKILLS.filter((skill) => skillPresent(root, skill));
+  const globalMatt = intent.scope === "project" ? MATT_SKILLS.filter((skill) => skillPresent(globalRoot, skill)) : [];
+  const availableMatt = new Set([...mattPresent, ...globalMatt]); const missing = MATT_SKILLS.filter((skill) => !availableMatt.has(skill));
+  const inherited = globalMatt.filter((skill) => !mattPresent.includes(skill)).length;
+  return { id: platformId, name: platform.name, root, skills, matrix, matt: { present: mattPresent.length, missing, total: MATT_SKILLS.length, inherited,
+    state: availableMatt.size === MATT_SKILLS.length ? "complete" : availableMatt.size ? "partial" : "missing" } };
+}
+
+function actionFor(observation, policy) {
+  if (observation.matrix === "matching" || observation.matrix === "newer") return "keep";
+  if (observation.matrix === "missing") return "install";
+  if (observation.matrix === "outdated-unchanged") return "backup-replace";
+  if (["damaged", "user-modified"].includes(observation.matrix)) return policy === "replace" ? "backup-replace" : "blocked";
+  return "repair";
+}
+
+export function recoverPendingTransaction(intent) {
+  const file = transactionPath(intent); const journal = readJson(file);
+  if (!journal) return { ok: true, recovered: false };
+  try {
+    if (journal.state === "committed") {
+      removeStaging(journal.stagingRoot);
+      for (const operation of journal.operations ?? []) removeEntry(operation.backup);
+      removeEntry(journal.manifest?.backup); removeEntry(file);
+      return { ok: true, recovered: true, receipt: `Finalized completed Matrix transaction ${journal.id}.` };
+    }
+    for (const operation of [...(journal.operations ?? [])].reverse()) {
+      if (operation.status !== "pending") removeEntry(operation.target);
+      if (operation.backup && pathExists(operation.backup)) { fs.mkdirSync(path.dirname(operation.target), { recursive: true }); fs.renameSync(operation.backup, operation.target); }
+    }
+    if (journal.manifest?.backup && pathExists(journal.manifest.backup)) {
+      removeEntry(journal.manifest.path); fs.mkdirSync(path.dirname(journal.manifest.path), { recursive: true }); fs.renameSync(journal.manifest.backup, journal.manifest.path);
+    } else if (journal.manifest?.written && !journal.manifest?.existed) removeEntry(journal.manifest.path);
+    removeStaging(journal.stagingRoot); removeEntry(file);
+    return { ok: true, recovered: true, receipt: `Recovered interrupted Matrix transaction ${journal.id}.` };
+  } catch (error) { return { ok: false, code: "RECOVERY_REQUIRED", recovery: `Keep ${file} and restore the paths recorded there before retrying.`, error: error.message }; }
+}
+
+export function createDistribution({ failAt, mattAdapter = createMattAdapter() } = {}) {
+  const evaluate = (rawIntent) => {
+    const intent = normalizeIntent(rawIntent); const language = intent.language ?? rawIntent.language ?? "en";
+    if (intent.error) return { ok: false, code: intent.error, diagnostics: [{ code: intent.error, message: text(language, "noPlatform") }] };
+    if (!intent.platforms.length) { const detected = detectPlatforms(intent.projectRoot, intent.scope, intent.home); if (!detected.length) return { ok: false, code: "INPUT_REQUIRED", diagnostics: [{ code: "INPUT_REQUIRED", message: text(language, "noPlatform") }] }; intent.platforms = detected; }
+    let catalog; try { catalog = releaseCatalog(intent.language); } catch (error) { return { ok: false, code: "PACKAGE_INCOMPLETE", intent, diagnostics: [{ code: "PACKAGE_INCOMPLETE", message: error.message }] }; }
+    const manifest = readManifest(intent); const observations = intent.platforms.map((id) => observePlatform(intent, catalog, manifest, id));
+    const actions = observations.map((item) => ({ platform: item.id, matrix: actionFor(item, intent.matrixPolicy), matt: item.matt.state === "complete" || intent.matt === "none" ? { kind: "keep", skills: [] } : { kind: "install-missing", skills: item.matt.missing } }));
+    const blocked = actions.filter((item) => item.matrix === "blocked"); const plan = { version: VERSION, intent, catalogDigest: catalog.digest, manifestPath: manifestPath(intent.scope, intent.projectRoot, intent.home), actions, observations, preconditionDigest: digest(observations) };
+    plan.seal = digest({ intent, catalogDigest: plan.catalogDigest, actions, preconditionDigest: plan.preconditionDigest });
+    return { ok: blocked.length === 0, code: blocked.length ? "USER_MODIFIED_BLOCKED" : "OK", intent, observations, actions, plan, diagnostics: blocked.map((item) => ({ code: "USER_MODIFIED_BLOCKED", platform: item.platform, message: `${item.platform}: existing Matrix assets are not proven managed.` })), summary: `${text(intent.language, "preview")}: ${actions.map((item) => `${item.platform}: ${item.matrix}`).join(", ")}` };
+  };
+
+  return { evaluate,
+    diagnose(rawIntent) {
+      const evaluation = evaluate(rawIntent); if (!evaluation.intent) return evaluation;
+      const diagnostics = []; const pending = readJson(transactionPath(evaluation.intent)); const manifest = readManifest(evaluation.intent);
+      if (pending) diagnostics.push({ code: "RECOVERY_REQUIRED", message: text(evaluation.intent.language, "transactionPending") });
+      if (!manifest) diagnostics.push({ code: "MANIFEST_MISSING", message: text(evaluation.intent.language, "manifestMissing") });
+      for (const observation of evaluation.observations ?? []) {
+        diagnostics.push({ code: `MATRIX_${observation.matrix.toUpperCase().replaceAll("-", "_")}`, platform: observation.id, message: `${observation.name}: Matrix is ${observation.matrix}.` });
+        const matrixRoot = path.join(observation.root, "matrix");
+        if (pathExists(matrixRoot) && (!exists(matrixRoot) || !exists(path.join(matrixRoot, "scripts", "matrix-runtime.mjs")))) diagnostics.push({ code: "RUNTIME_MISSING", platform: observation.id, message: `${observation.name}: ${text(evaluation.intent.language, "runtimeMissing")}` });
+        for (const skill of observation.skills.filter((entry) => isBrokenLink(entry.target))) diagnostics.push({ code: "BROKEN_LINK", platform: observation.id, path: skill.target, message: `${observation.name}: ${text(evaluation.intent.language, "brokenLink")} ${skill.target}` });
+        if (observation.id === "codex" && PLATFORMS.codex.legacyRoots(scopeBase(evaluation.intent.scope, evaluation.intent.projectRoot, evaluation.intent.home)).some(exists)) diagnostics.push({ code: "CODEX_LEGACY_DETECTED", platform: observation.id, message: "Codex legacy .codex/skills was detected; Matrix will not write there." });
+        diagnostics.push({ code: `MATT_${observation.matt.state.toUpperCase()}`, platform: observation.id, message: `${observation.name}: Matt Pocock skills are ${observation.matt.state}.` });
+        if (observation.matt.inherited) diagnostics.push({ code: "MATT_INHERITED", platform: observation.id, message: `${observation.name}: ${observation.matt.inherited} ${text(evaluation.intent.language, "mattInherited")}` });
+      }
+      return { ...evaluation, diagnosis: diagnostics };
+    },
+    commit(plan) {
+      if (!plan?.seal || plan.seal !== digest({ intent: plan.intent, catalogDigest: plan.catalogDigest, actions: plan.actions, preconditionDigest: plan.preconditionDigest })) return { ok: false, code: "INVALID_INTENT" };
+      const recovery = recoverPendingTransaction(plan.intent); if (!recovery.ok) return recovery;
+      const refreshed = evaluate({ ...plan.intent, platforms: plan.intent.platforms });
+      if (!refreshed.plan || refreshed.plan.preconditionDigest !== plan.preconditionDigest || refreshed.plan.catalogDigest !== plan.catalogDigest) return { ok: false, code: "PLAN_STALE" };
+      if (!refreshed.ok) return { ok: false, code: refreshed.code, diagnostics: refreshed.diagnostics };
+      if (plan.intent.dryRun) return { ok: true, code: "DRY_RUN", actions: plan.actions };
+      const root = installationRoot(plan.intent.scope, plan.intent.projectRoot, plan.intent.home); const id = nowStamp(); const stagingRoot = path.join(root, "staging", id); const journalFile = transactionPath(plan.intent);
+      const journal = { id, state: "in-progress", stagingRoot, manifest: { path: plan.manifestPath, existed: pathExists(plan.manifestPath), backup: null, written: false }, operations: [] };
+      for (const item of refreshed.observations) if (plan.actions.find((entry) => entry.platform === item.id).matrix !== "keep") for (const skill of MATRIX_SKILLS) journal.operations.push({ target: path.join(item.root, skill), backup: null, status: "pending" });
+      const persist = () => writeJson(journalFile, journal);
+      try {
+        persist(); const catalog = releaseCatalog(plan.intent.language); const stagedPlatforms = new Map();
+        for (const item of refreshed.observations) {
+          if (plan.actions.find((entry) => entry.platform === item.id).matrix === "keep") continue;
+          const platformStage = path.join(stagingRoot, item.id);
+          for (const skill of MATRIX_SKILLS) { const staged = path.join(platformStage, skill); fs.mkdirSync(path.dirname(staged), { recursive: true }); fs.cpSync(path.join(catalog.root, skill), staged, { recursive: true }); fs.mkdirSync(path.join(staged, "scripts"), { recursive: true }); fs.copyFileSync(workflowRuntimeSource(), path.join(staged, "scripts", "matrix-runtime.mjs")); if (skill === "matrix") for (const filename of ["matrix_state.py", "matrix_claude.py"]) fs.copyFileSync(path.join(sourceSkillsRoot("en"), "matrix", "scripts", filename), path.join(staged, "scripts", filename)); if (!exists(path.join(staged, "SKILL.md"))) throw new Error(`Stage validation failed: ${item.id}/${skill}`); }
+          stagedPlatforms.set(item.id, platformStage);
+        }
+        failAt?.("after-stage"); let operationIndex = 0;
+        for (const item of refreshed.observations) {
+          if (plan.actions.find((entry) => entry.platform === item.id).matrix === "keep") continue;
+          fs.mkdirSync(item.root, { recursive: true });
+          for (const skill of MATRIX_SKILLS) {
+            const operation = journal.operations[operationIndex++]; const target = operation.target; operation.status = "backing-up";
+            if (pathExists(target)) operation.backup = path.join(root, "backups", id, item.id, skill); persist();
+            if (operation.backup) { fs.mkdirSync(path.dirname(operation.backup), { recursive: true }); fs.renameSync(target, operation.backup); }
+            operation.status = "backed-up"; persist(); failAt?.("after-backup", { platform: item.id, skill });
+            const staged = path.join(stagedPlatforms.get(item.id), skill);
+            if (plan.intent.mode === "symlink") { const store = path.join(root, "skills", catalog.digest, skill); if (!pathExists(store)) { fs.mkdirSync(path.dirname(store), { recursive: true }); fs.renameSync(staged, store); } fs.symlinkSync(store, target, process.platform === "win32" ? "junction" : "dir"); } else fs.renameSync(staged, target);
+            operation.status = "committed"; persist(); failAt?.("after-commit", { platform: item.id, skill });
+          }
+        }
+        if (journal.manifest.existed) { journal.manifest.backup = path.join(root, "backups", id, "installation.json"); persist(); fs.mkdirSync(path.dirname(journal.manifest.backup), { recursive: true }); fs.renameSync(plan.manifestPath, journal.manifest.backup); }
+        const records = Object.fromEntries(refreshed.observations.map((item) => [item.id, { root: item.root, skills: Object.fromEntries(MATRIX_SKILLS.map((skill) => [skill, { hash: catalog.skills[skill] }])) }]));
+        writeJson(plan.manifestPath, { version: VERSION, catalogVersion: catalog.version, language: plan.intent.language, mode: plan.intent.mode, catalogDigest: catalog.digest, platforms: records }); journal.manifest.written = true; persist(); failAt?.("after-manifest"); journal.state = "committed"; persist();
+        removeStaging(stagingRoot); removeEntry(journal.manifest.backup); removeEntry(journalFile);
+        const mattActions = plan.actions.filter((item) => item.matt.kind === "install-missing"); const mattResults = [];
+        for (const action of mattActions) { const result = mattAdapter.installMissing({ projectRoot: plan.intent.projectRoot, platforms: [action.platform], skills: action.matt.skills, global: plan.intent.scope === "global" }); mattResults.push({ platform: action.platform, ...result }); }
+        const postcondition = evaluate({ ...plan.intent, platforms: plan.intent.platforms }); const incomplete = mattActions.length ? postcondition.observations.filter((item) => item.matt.state !== "complete") : [];
+        const backups = journal.operations.filter((item) => item.backup).map((item) => ({ target: item.target, backup: item.backup }));
+        if (mattResults.some((item) => !item.ok) || incomplete.length) return { ok: true, code: "PARTIAL", committed: journal.operations.map((item) => item.target), backups, recovery: "Matrix is installed. Run matrix init --with-mattpocock after resolving the Matt skills installation.", matt: mattResults, recoveryReceipt: recovery.receipt };
+        return { ok: true, code: "OK", committed: journal.operations.map((item) => item.target), backups, matt: mattResults, recoveryReceipt: recovery.receipt };
+      } catch (error) { const restored = recoverPendingTransaction(plan.intent); return { ok: false, code: "MATRIX_COMMIT_FAILED", error: error.message, recovery: restored.ok ? "Matrix targets and installation manifest were restored." : restored.recovery }; }
+    }
+  };
+}