@rosenfan/matrix 0.1.4 → 0.1.5

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

@@ -5,28 +5,28 @@ description: 依据计划验证 Matrix 变更并审查差异。
 
 # Matrix Verify
 
-运行已批准 Contract 的验证命令，在 `verification.md` 写入 `## Test evidence`。hotfix 另写 `## Regression evidence`；tweak 另写 `## Scope review evidence`。所有模式都必须写入 `## Review evidence`，并在其中保留内容充分的 `### Standards` 与 `### Spec` 两个子节。读取冻结 `orchestration`：
+运行已批准 Contract 的验证命令，在 `verification.md` 写入 `## Test evidence`。hotfix 另写 `## Regression evidence`；tweak 另写 `## Scope review evidence`。所有模式都必须写入 `## Review evidence`，并在其中保留内容充分的 `### Standards` 与 `### Spec` 两个子节。读取冻结 `orchestration`：
 
 验证正文使用 `artifact_language`；上述 Runtime 所需英文证据标题保持不变。
 
 - **Prim**：Matrix 自行完成 Standards 与 Spec 双轴审查。
 - **Arch**：调用 `code-review` 产生双轴证据，并说明调用原因。
 
-审查结果只是 Matrix Verify 的输入；companion 不得决定阶段结果、扩大已批准架构、推进或归档。不得调用事后架构改进 wrapper。正确安装的审查能力失败时最多执行一次同能力 Matrix fallback；安装完整性问题必须停止。
-
-Arch 正常执行 `code-review` 后，使用项目 Runtime 把 fixed point、HEAD/diff、Contract、审查正文和工作区绑定为当前 revision 的回执：
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs review --source code-review --fixed-point <ref> --standards <passed|failed> --spec <passed|failed>
-```
-
-只有在无 Git 基线、已提交的 HEAD diff 为空、仍存在 staged/unstaged/untracked 候选，或 capability 真实执行失败时，才记录限制并使用一次有界 fallback：
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs review --source matrix-fallback --reason <git-baseline-unavailable|empty-head-diff|uncommitted-worktree|capability-execution-failed> [--fixed-point <ref-for-empty-head-diff-or-uncommitted-worktree>] --standards <passed|failed> --spec <passed|failed>
-```
-
-不得把 fallback 写成 `code-review` 成功。`empty-head-diff` 必须提供 fixed point，由 Runtime 核实三点 diff 确实为空。`uncommitted-worktree` 也必须提供 fixed point，Runtime 会把 staged、unstaged 与 untracked 候选内容绑定为 `candidate_hash`，之后任意变化都会使回执过期。当前 revision 已有回执或任一审查轴失败时，必须先受控 Return，不能覆盖回执后继续。
+审查结果只是 Matrix Verify 的输入；companion 不得决定阶段结果、扩大已批准架构、推进或归档。不得调用事后架构改进 wrapper。正确安装的审查能力失败时最多执行一次同能力 Matrix fallback；安装完整性问题必须停止。
+
+Arch 正常执行 `code-review` 后，使用项目 Runtime 把 fixed point、HEAD/diff、Contract、审查正文和工作区绑定为当前 revision 的回执：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs review --source code-review --fixed-point <ref> --standards <passed|failed> --spec <passed|failed>
+```
+
+只有在无 Git 基线、已提交的 HEAD diff 为空、仍存在 staged/unstaged/untracked 候选，或 capability 真实执行失败时，才记录限制并使用一次有界 fallback：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs review --source matrix-fallback --reason <git-baseline-unavailable|empty-head-diff|uncommitted-worktree|capability-execution-failed> [--fixed-point <ref-for-empty-head-diff-or-uncommitted-worktree>] --standards <passed|failed> --spec <passed|failed>
+```
+
+不得把 fallback 写成 `code-review` 成功。`empty-head-diff` 必须提供 fixed point，由 Runtime 核实三点 diff 确实为空。`uncommitted-worktree` 也必须提供 fixed point，Runtime 会把 staged、unstaged 与 untracked 候选内容绑定为 `candidate_hash`，之后任意变化都会使回执过期。当前 revision 已有回执或任一审查轴失败时，必须先受控 Return，不能覆盖回执后继续。
 
 失败时使用受控 Return：
 
@@ -35,9 +35,9 @@ node <matrix-skill-directory>/scripts/matrix-runtime.mjs return build --reason v
 node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason acceptance-or-design-gap
 ```
 
-Return 会轮换旧 `verification.md`；不得把旧结论直接复制为新的当前证据。
-
-Arch 的 Return 也会轮换 `review-receipt.json`；新 revision 必须重新审查并生成新回执。仅有 Markdown 标题、旧回执或与当前工作区不匹配的回执都不能通过 guard。
+Return 会轮换旧 `verification.md`；不得把旧结论直接复制为新的当前证据。
+
+Arch 的 Return 也会轮换 `review-receipt.json`；新 revision 必须重新审查并生成新回执。仅有 Markdown 标题、旧回执或与当前工作区不匹配的回执都不能通过 guard。
 
 ```powershell
 node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard verify

package/bin/matrix.js

@@ -1,15 +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;
-  }
-});
+#!/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

@@ -1,6 +1,6 @@
 {
   "name": "@rosenfan/matrix",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Evidence-driven development workflow with Prim and Arch agent-skill orchestration.",
   "license": "MIT",
   "type": "module",
@@ -10,19 +10,10 @@
   "files": [
     "bin/",
     "src/",
+    "assets/skills",
     "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",
+    "!assets/skills/**/__pycache__",
+    "!assets/skills-zh-CN/**/__pycache__",
     "README.md",
     "README.zh-CN.md",
     "LICENSE"

package/src/catalog.js

@@ -1,87 +1,94 @@
-import crypto from "node:crypto";
-import fs from "node:fs";
-import os from "node:os";
+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";
 import { MATT_INSTALLABLE_SKILLS, MATT_ROLES } from "./matt-catalog.mjs";
-
-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 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 = MATT_INSTALLABLE_SKILLS;
 export const UNMANAGED_MATT_SKILLS = MATT_ROLES.incompatible;
-
+
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const packageManifest = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
 export const MATRIX_VERSION = packageManifest.version;
-
-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 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, "assets", "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");
+}
+
+// Content digests must identify logical file content, not checkout line endings:
+// a git working tree (autocrlf CRLF), the npm tarball and a local tgz must agree.
+// Generated caches (__pycache__) are skipped so dirty working trees cannot poison digests.
+const normalizeEol = (contents) => Buffer.from(contents.toString("utf8").replaceAll("\r\n", "\n").replaceAll("\r", "\n"), "utf8");
+const GENERATED_DIRS = new Set(["__pycache__"]);
+
+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))) {
+      if (entry.isDirectory() && GENERATED_DIRS.has(entry.name)) continue;
+      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(normalizeEol(contents));
+  }
+  return hash.digest("hex");
+}
+
 export function workflowRuntimeSource() { return path.join(packageRoot, "src", "workflow.js"); }
 export function workflowTransactionSource() { return path.join(packageRoot, "src", "workflow-transaction.js"); }
 export function mattCatalogSource() { return path.join(packageRoot, "src", "matt-catalog.mjs"); }
-
+
 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(", ")}`);
+  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 transaction = fs.readFileSync(workflowTransactionSource());
   const mattCatalog = fs.readFileSync(mattCatalogSource());

package/src/cli.js

@@ -2,22 +2,22 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { PLATFORMS } from "./catalog.js";
-import { createDistribution, installedIntent } from "./distribution.js";
-import { createMattAdapter, inspectMattInstallation } from "./matt.js";
+import { PLATFORMS } from "./catalog.js";
+import { createDistribution, installedIntent } from "./distribution.js";
+import { createMattAdapter, inspectMattInstallation } from "./matt.js";
 import { text } from "./messages.js";
 import { createUi } from "./ui.js";
 import { invoke } from "./workflow.js";
-import { compareVersions, globalBinPath, latestVersion, selfUpdate } from "./self-update.js";
-import { resolveProjectRuntime } from "./runtime-resolver.js";
-import { MATT_COMPATIBILITY } from "./matt-catalog.mjs";
+import { compareVersions, globalBinPath, latestVersion, selfUpdate } from "./self-update.js";
+import { resolveProjectRuntime } from "./runtime-resolver.js";
+import { MATT_COMPATIBILITY } from "./matt-catalog.mjs";
 
 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 update [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-matt\n  --default-orchestration <prim|arch>\n  --skip-self-update  --force  --yes, -y  --dry-run  --json  --no-color`;
+const version = JSON.parse(fs.readFileSync(packagePath, "utf8")).version;
+const HELP = `Matrix ${version}\n\nUsage: matrix init [directory] [options]\n       matrix update [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-matt\n  --default-orchestration <prim|arch>\n  --skip-self-update  --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, mattPolicy: "preserve", defaultOrchestration: null, matrixPolicy: "safe", yes: false, dryRun: false, json: false, color: true, skipSelfUpdate: false, reexec: false };
+function parse(argv) {
+  const result = { command: null, directory: null, scope: null, language: null, platforms: [], mode: "copy", matt: null, mattPolicy: "preserve", defaultOrchestration: null, matrixPolicy: "safe", yes: false, dryRun: false, json: false, color: true, skipSelfUpdate: false, reexec: false };
   const values = [...argv];
   if (values[0] && !values[0].startsWith("-")) result.command = values.shift();
   while (values.length) {
@@ -27,9 +27,9 @@ function parse(argv) {
     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-matt") result.mattPolicy = "replace";
+    else if (token === "--with-mattpocock") result.matt = "missing";
+    else if (token === "--without-mattpocock") result.matt = "none";
+    else if (token === "--force-matt") result.mattPolicy = "replace";
     else if (token === "--default-orchestration") result.defaultOrchestration = values.shift();
     else if (token === "--force") result.matrixPolicy = "replace";
     else if (["--yes", "-y"].includes(token)) result.yes = true;
@@ -53,8 +53,8 @@ function projectRoot(directory) {
 
 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", "safe-update": "stateSafeUpdate", adoptable: "stateAdoptable", unreadable: "stateUnreadable", compatible: "stateCompatible", "update-required": "stateUpdateRequired", "unsupported-newer": "stateUnsupportedNewer", unverified: "stateUnverified", unknown: "stateUnknown", incomplete: "statePartial" })[state] ?? state);
+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", "safe-update": "stateSafeUpdate", adoptable: "stateAdoptable", unreadable: "stateUnreadable", compatible: "stateCompatible", "update-required": "stateUpdateRequired", "unsupported-newer": "stateUnsupportedNewer", unverified: "stateUnverified", unknown: "stateUnknown", incomplete: "statePartial" })[state] ?? state);
 }
 
 function localizedAction(language, action) {
@@ -71,20 +71,20 @@ async function intentFrom(options, ui) {
   const defaultOrchestration = options.defaultOrchestration ?? (interactive && !options.yes && matt === "missing"
     ? await ui.select(text(language, "orchestrationQuestion"), [{ label: "Arch", value: "arch" }, { label: "Prim", value: "prim" }])
     : null);
-  return { projectRoot: projectRoot(options.directory), language, scope, platforms, mode: options.mode, matt, mattPolicy: options.mattPolicy, defaultOrchestration, nonInteractive: options.yes || !interactive, matrixPolicy: options.matrixPolicy, dryRun: options.dryRun };
+  return { projectRoot: projectRoot(options.directory), language, scope, platforms, mode: options.mode, matt, mattPolicy: options.mattPolicy, defaultOrchestration, nonInteractive: options.yes || !interactive, 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);
-  if (evaluation.intent?.defaultOrchestration) ui.muted(`${text(language, "defaultOrchestration")}: ${evaluation.intent.defaultOrchestration}`);
-  for (const item of evaluation.observations ?? []) {
-    const mattStates = Object.entries(item.matt.classificationCounts ?? {}).map(([state, count]) => `${localizedState(language, state)}=${count}`).join(", ");
-    ui.muted(`${item.name}: ${text(language, "matrix")} ${localizedState(language, item.matrix)}；${text(language, "matt")} ${localizedState(language, item.matt.state)}${mattStates ? ` (${mattStates})` : ""}`);
-  }
+  if (evaluation.intent?.defaultOrchestration) ui.muted(`${text(language, "defaultOrchestration")}: ${evaluation.intent.defaultOrchestration}`);
+  for (const item of evaluation.observations ?? []) {
+    const mattStates = Object.entries(item.matt.classificationCounts ?? {}).map(([state, count]) => `${localizedState(language, state)}=${count}`).join(", ");
+    ui.muted(`${item.name}: ${text(language, "matrix")} ${localizedState(language, item.matrix)}；${text(language, "matt")} ${localizedState(language, item.matt.state)}${mattStates ? ` (${mattStates})` : ""}`);
+  }
   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_GLOBAL_IGNORED" ? ui.muted : ui.warn)(item.message ?? item.code);
+  for (const item of evaluation.diagnosis ?? []) (item.code === "MATT_GLOBAL_IGNORED" ? ui.muted : ui.warn)(item.message ?? item.code);
 }
 
 async function init(options) {
@@ -94,42 +94,42 @@ async function init(options) {
   return refresh(intent, options, ui);
 }
 
-async function refresh(intent, options, ui) {
-  const distribution = createDistribution({ mattAdapter: createMattAdapter({ stdio: options.json ? "pipe" : "inherit" }) });
-  let evaluation = distribution.evaluate(intent);
-  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY && !options.json);
-  let reevaluated = false;
-  if (!options.json) render(ui, evaluation);
-  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" }); reevaluated = true;
-  }
-  if (!evaluation.ok && evaluation.code === "MATT_USER_MODIFIED" && interactive && !options.yes
-    && await ui.confirm(text(intent.language, "mattReplaceQuestion"), false, labelsFor(intent.language))) {
-    evaluation = distribution.evaluate({ ...intent, mattPolicy: "replace" }); reevaluated = true;
-  }
-  if (options.json) {
-    if (!evaluation.ok || options.dryRun) {
-      const output = options.updateMode ? { ...evaluation, matt: inspectMattInstallation({ projectRoot: intent.projectRoot, home: intent.home, platforms: intent.platforms }) } : evaluation;
-      console.log(JSON.stringify(output)); return evaluation.ok ? 0 : 2;
-    }
-    const result = distribution.commit(evaluation.plan);
-    const output = { ...evaluation, ...result, intent: evaluation.intent, observations: evaluation.observations, actions: evaluation.actions,
-      ...(options.updateMode ? { matt: inspectMattInstallation({ projectRoot: intent.projectRoot, home: intent.home, platforms: intent.platforms }) } : {}) };
-    console.log(JSON.stringify(output));
-    return !result.ok ? 2 : result.code === "PARTIAL" ? 1 : 0;
-  }
-  if (reevaluated) render(ui, evaluation);
+async function refresh(intent, options, ui) {
+  const distribution = createDistribution({ mattAdapter: createMattAdapter({ stdio: options.json ? "pipe" : "inherit" }) });
+  let evaluation = distribution.evaluate(intent);
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY && !options.json);
+  let reevaluated = false;
+  if (!options.json) render(ui, evaluation);
+  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" }); reevaluated = true;
+  }
+  if (!evaluation.ok && evaluation.code === "MATT_USER_MODIFIED" && interactive && !options.yes
+    && await ui.confirm(text(intent.language, "mattReplaceQuestion"), false, labelsFor(intent.language))) {
+    evaluation = distribution.evaluate({ ...intent, mattPolicy: "replace" }); reevaluated = true;
+  }
+  if (options.json) {
+    if (!evaluation.ok || options.dryRun) {
+      const output = options.updateMode ? { ...evaluation, matt: inspectMattInstallation({ projectRoot: intent.projectRoot, home: intent.home, platforms: intent.platforms }) } : evaluation;
+      console.log(JSON.stringify(output)); return evaluation.ok ? 0 : 2;
+    }
+    const result = distribution.commit(evaluation.plan);
+    const output = { ...evaluation, ...result, intent: evaluation.intent, observations: evaluation.observations, actions: evaluation.actions,
+      ...(options.updateMode ? { matt: inspectMattInstallation({ projectRoot: intent.projectRoot, home: intent.home, platforms: intent.platforms }) } : {}) };
+    console.log(JSON.stringify(output));
+    return !result.ok ? 2 : result.code === "PARTIAL" ? 1 : 0;
+  }
+  if (reevaluated) 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);
+  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"));
-  if (!options.updateMode && intent.matt === "missing" && !options.dryRun) ui.muted(text(intent.language, "mattSetupHint").replace("{release}", MATT_COMPATIBILITY.release));
-  if (options.updateMode) {
-    const matt = inspectMattInstallation({ projectRoot: intent.projectRoot, home: intent.home, platforms: intent.platforms });
-    ui.muted(`${text(intent.language, "mattCompatibilityStatus").replace("{release}", matt.supported.release).replace("{status}", localizedState(intent.language, matt.status))}${matt.action ? `; ${matt.action}` : ""}`);
-  }
+  ui.success(options.dryRun ? text(intent.language, "dryRunComplete") : text(intent.language, "ready"));
+  if (!options.updateMode && intent.matt === "missing" && !options.dryRun) ui.muted(text(intent.language, "mattSetupHint").replace("{release}", MATT_COMPATIBILITY.release));
+  if (options.updateMode) {
+    const matt = inspectMattInstallation({ projectRoot: intent.projectRoot, home: intent.home, platforms: intent.platforms });
+    ui.muted(`${text(intent.language, "mattCompatibilityStatus").replace("{release}", matt.supported.release).replace("{status}", localizedState(intent.language, matt.status))}${matt.action ? `; ${matt.action}` : ""}`);
+  }
   ui.muted(evaluation.intent.platforms.map((id) => `${PLATFORMS[id].name}: $matrix <request>`).join("\n"));
   return 0;
 }
@@ -143,7 +143,7 @@ async function update(options) {
     if (options.json) console.log(JSON.stringify(result)); else ui.warn(result.message);
     return 2;
   }
-  const forbidden = options.language || options.scope || options.platforms.length || options.matt || options.mattPolicy === "replace" || options.defaultOrchestration || options.mode !== "copy";
+  const forbidden = options.language || options.scope || options.platforms.length || options.matt || options.mattPolicy === "replace" || options.defaultOrchestration || options.mode !== "copy";
   if (forbidden) throw new Error("matrix update inherits installation settings. Use matrix init to change language, scope, platform, mode, Matt skills, or orchestration.");
   const intent = { ...installed.intent, dryRun: options.dryRun };
   let npm = { status: "skipped", current: version, target: version, reason: options.skipSelfUpdate ? "disabled by --skip-self-update" : null };
@@ -158,7 +158,7 @@ async function update(options) {
       return 2;
     }
   }
-  if (options.json && options.dryRun) { console.log(JSON.stringify({ ok: true, code: "DRY_RUN", npm, intent, matt: inspectMattInstallation({ projectRoot: root, home: intent.home, platforms: intent.platforms }) })); return 0; }
+  if (options.json && options.dryRun) { console.log(JSON.stringify({ ok: true, code: "DRY_RUN", npm, intent, matt: inspectMattInstallation({ projectRoot: root, home: intent.home, platforms: intent.platforms }) })); return 0; }
   if (!options.json) {
     await ui.banner(); ui.info(`Matrix update: CLI ${npm.current}${npm.status === "available" ? ` → ${npm.target}` : ""}`);
     ui.muted(`Assets: ${intent.scope}, ${intent.language}, ${intent.platforms.join(", ")}`);
@@ -166,7 +166,7 @@ async function update(options) {
   const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY && !options.json);
   if (npm.status === "available") {
     if (!options.yes && interactive && !await ui.confirm(`Upgrade Matrix CLI ${npm.current} → ${npm.target} and then refresh these assets?`, true, labelsFor(intent.language))) return 0;
-    if (options.dryRun) { if (options.json) console.log(JSON.stringify({ ok: true, code: "DRY_RUN", npm, intent, matt: inspectMattInstallation({ projectRoot: root, home: intent.home, platforms: intent.platforms }) })); else ui.success(text(intent.language, "dryRunComplete")); return 0; }
+    if (options.dryRun) { if (options.json) console.log(JSON.stringify({ ok: true, code: "DRY_RUN", npm, intent, matt: inspectMattInstallation({ projectRoot: root, home: intent.home, platforms: intent.platforms }) })); else ui.success(text(intent.language, "dryRunComplete")); return 0; }
     const updated = selfUpdate(version, npm.target);
     if (!updated.ok) { const result = { ok: false, code: "SELF_UPDATE_FAILED", npm: { ...npm, status: "failed", reason: updated.reason }, recovery_command: "matrix update --skip-self-update" }; if (options.json) console.log(JSON.stringify(result)); else ui.warn(`${result.code}: ${updated.reason}`); return 2; }
     const args = [globalBinPath(), "update", root, "--skip-self-update", "--_reexec", "--yes"];
@@ -174,51 +174,51 @@ async function update(options) {
     const rerun = spawnSync(process.execPath, args, { stdio: "inherit" });
     return Number.isInteger(rerun.status) ? rerun.status : 2;
   }
-  if (options.json) return refresh(intent, { ...options, yes: true, updateMode: true }, ui);
-  return refresh(intent, { ...options, updateMode: true }, ui);
-}
-
-function recoveryArgument(value) {
-  const argument = String(value);
-  if (/^[A-Za-z0-9_./:@=-]+$/.test(argument)) return argument;
-  if (process.platform === "win32") return `"${argument.replaceAll('"', '\\"')}"`;
-  return `'${argument.replaceAll("'", "'\\''")}'`;
-}
-
-function runtimeRecovery(projectRuntime, argv) {
-  const argumentsWithoutJson = argv.slice(1).filter((value) => value !== "--json");
-  return { ...projectRuntime, recovery_command: [projectRuntime.recovery_command, ...argumentsWithoutJson.map(recoveryArgument)].join(" ") };
-}
+  if (options.json) return refresh(intent, { ...options, yes: true, updateMode: true }, ui);
+  return refresh(intent, { ...options, updateMode: true }, ui);
+}
 
-async function doctor(options) {
-  const ui = createUi({ color: options.color && !options.json });
-  const root = projectRoot(options.directory);
-  const installed = installedIntent({ projectRoot: root });
-  const intent = installed.ok
-    ? { ...installed.intent, dryRun: true }
-    : await intentFrom({ ...options, directory: root, yes: true }, ui);
-  const evaluation = createDistribution().diagnose(intent);
-  const matt = inspectMattInstallation({ projectRoot: intent.projectRoot, home: intent.home, platforms: intent.platforms });
-  if (options.json) console.log(JSON.stringify({ ...evaluation, matt }));
-  else { await ui.banner(); ui.info(text(intent.language, "doctor")); render(ui, evaluation); ui.muted(`${text(intent.language, "mattCompatibilityStatus").replace("{release}", matt.supported.release).replace("{status}", localizedState(intent.language, matt.status))}${matt.action ? `; ${matt.action}` : ""}`); }
-  return evaluation.ok ? 0 : 2;
-}
+function recoveryArgument(value) {
+  const argument = String(value);
+  if (/^[A-Za-z0-9_./:@=-]+$/.test(argument)) return argument;
+  if (process.platform === "win32") return `"${argument.replaceAll('"', '\\"')}"`;
+  return `'${argument.replaceAll("'", "'\\''")}'`;
+}
 
-export async function main(argv) {
-  if (argv[0] === "workflow") {
-    const json = argv.includes("--json");
-    const projectRuntime = resolveProjectRuntime({ projectRoot: process.cwd() });
-    if (!projectRuntime.ok) {
-      const failure = projectRuntime.recovery_command ? runtimeRecovery(projectRuntime, argv) : projectRuntime;
-      if (json) console.log(JSON.stringify(failure));
-      else console.log(`MATRIX ERROR [${failure.code}]: ${failure.message}${failure.recovery_command ? `\nRun ${failure.recovery_command}` : ""}`);
-      return 2;
-    }
-    if (projectRuntime.runtime) {
-      const delegated = spawnSync(process.execPath, [projectRuntime.runtime, ...argv.slice(1).filter((value) => value !== "--json")], { stdio: "inherit" });
-      return Number.isInteger(delegated.status) ? delegated.status : 2;
-    }
-    const result = invoke(argv.slice(1).filter((value) => value !== "--json"));
+function runtimeRecovery(projectRuntime, argv) {
+  const argumentsWithoutJson = argv.slice(1).filter((value) => value !== "--json");
+  return { ...projectRuntime, recovery_command: [projectRuntime.recovery_command, ...argumentsWithoutJson.map(recoveryArgument)].join(" ") };
+}
+
+async function doctor(options) {
+  const ui = createUi({ color: options.color && !options.json });
+  const root = projectRoot(options.directory);
+  const installed = installedIntent({ projectRoot: root });
+  const intent = installed.ok
+    ? { ...installed.intent, dryRun: true }
+    : await intentFrom({ ...options, directory: root, yes: true }, ui);
+  const evaluation = createDistribution().diagnose(intent);
+  const matt = inspectMattInstallation({ projectRoot: intent.projectRoot, home: intent.home, platforms: intent.platforms });
+  if (options.json) console.log(JSON.stringify({ ...evaluation, matt }));
+  else { await ui.banner(); ui.info(text(intent.language, "doctor")); render(ui, evaluation); ui.muted(`${text(intent.language, "mattCompatibilityStatus").replace("{release}", matt.supported.release).replace("{status}", localizedState(intent.language, matt.status))}${matt.action ? `; ${matt.action}` : ""}`); }
+  return evaluation.ok ? 0 : 2;
+}
+
+export async function main(argv) {
+  if (argv[0] === "workflow") {
+    const json = argv.includes("--json");
+    const projectRuntime = resolveProjectRuntime({ projectRoot: process.cwd() });
+    if (!projectRuntime.ok) {
+      const failure = projectRuntime.recovery_command ? runtimeRecovery(projectRuntime, argv) : projectRuntime;
+      if (json) console.log(JSON.stringify(failure));
+      else console.log(`MATRIX ERROR [${failure.code}]: ${failure.message}${failure.recovery_command ? `\nRun ${failure.recovery_command}` : ""}`);
+      return 2;
+    }
+    if (projectRuntime.runtime) {
+      const delegated = spawnSync(process.execPath, [projectRuntime.runtime, ...argv.slice(1).filter((value) => value !== "--json")], { stdio: "inherit" });
+      return Number.isInteger(delegated.status) ? delegated.status : 2;
+    }
+    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;