@rosenfan/matrix 0.1.4 → 0.1.6

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

@@ -1,24 +1,41 @@
----
-name: matrix-design
-description: 在实现前设计并冻结活动 Matrix 变更。
----
-
-# Matrix Design
-
-Design 只用于 full 和可恢复的旧 shortcut change。新的 lightweight hotfix/tweak 从 Open 直接进入 Build，不得为满足 full guard 补写 Design 产物。
-
-design 和 plan 正文使用 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` 的 `artifact_language`；Runtime 所需英文标题 token 保持不变。
-
-读取 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect`、proposal 与冻结 `orchestration`，写入 `design.md`（`## Decisions`、`## Boundaries`、`## Test seams`、`## Risks`）与 `plan.md`（`## Steps`、`## Validation`、`## Stop conditions`）。
-
-- **Prim**：使用 Matrix 自身能力调查并设计。
+---
+name: matrix-design
+description: 在实现前设计并冻结活动 Matrix 变更。
+---
+
+# Matrix Design
+
+Design 只用于 full 和可恢复的旧 shortcut change。新的 lightweight hotfix/tweak 从 Open 直接进入 Build，不得为满足 full guard 补写 Design 产物。
+
+design 和 plan 正文使用 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` 的 `artifact_language`；Runtime 所需英文标题 token 保持不变。
+
+读取 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect`、proposal 与冻结 `orchestration`，写入 `design.md`（`## Decisions`、`## Boundaries`、`## Test seams`、`## Risks`）与 `plan.md`（`## Steps`、`## Validation`、`## Stop conditions`）。
+
+- **Prim**：使用 Matrix 自身能力调查并设计。
 - **Arch**：仅按事实触发 `domain-modeling`、`research`、`prototype`、`codebase-design`；当 Contract 修改 Skill、`AGENTS.md`、`CLAUDE.md` 或 agent 指针可达文档时触发 `writing-for-agents`。不得机械执行固定序列；每次调用前说明能力与原因。
-
+
 长期有效的领域、ADR 或研究产物遵循仓库约定，关键结论必须同步进入 Matrix design/plan。prototype 默认写入系统临时目录。companion 不得拥有 Matrix 状态或创建竞争计划。重大范围或架构决策须先由用户确认。
 
 `wayfinder` 与 `improve-codebase-architecture` 只能作为活动 Design 外的显式 handoff；说明原因后由用户调用，选中的结果可另行进入受治理 Change。
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard design
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build
-```
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard design
+```
+
+## 执行主体确认点（Build 前）
+
+`guard design` 通过后、`transition build` 之前，必须暂停并向用户确认执行主体，未确认不得推进：
+
+- **选项 A：当前 agent / 原模型继续（默认）**——直接推进：
+  ```powershell
+  node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build
+  ```
+  随后进入 `$matrix-build` 在本会话内实现。
+- **选项 B：切换模型、保留本 agent**——用户在自己的客户端完成模型切换（例如设计用强模型、实现用高性价比模型），回到会话确认后按选项 A 推进。Matrix 无法感知客户端模型，只提供强制暂停点。
+- **选项 C：切换执行 agent**——先推进进 Build 批准冻结 Contract，再用 `$matrix-handoff` 为目标 agent 导出有界任务包（例如 Codex 设计、Claude Code 实现，或 zcode 设计、opencode 实现）。实现 agent 完成并补齐 `## Build evidence` 后：
+  ```powershell
+  node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
+  node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
+  ```
+
+所选选项必须写入 `design.md` 的 `## Decisions`，随 Contract 冻结。

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

@@ -0,0 +1,79 @@
+---
+name: matrix-handoff
+description: 将已批准的 Matrix Contract 导出为受边界约束的通用 agent 任务包（Claude Code、opencode 或其他 agent），不改变 Matrix 工作流状态。
+---
+
+# Matrix Handoff（Implementation Handoff）
+
+这是可选旁路，不是 Matrix phase。它不得执行 `transition`、`archive`，也不得写入 `matrix.yaml` 或 `events.jsonl`。它只支持匹配的 full 或 legacy-full 三产物 Contract；新的 lightweight hotfix/tweak 不支持导出。
+
+人类可读 handoff 内容使用 inspect 的 `artifact_language`；稳定的机器可读标题和 metadata key 保持不变。
+
+## 何时使用
+
+满足以下条件时使用 `$matrix-handoff`：
+
+- 变更已进入 Build，且 `design -> build` 已批准精确 Contract；
+- 你希望由另一个 agent 实现冻结的设计——例如 Codex 设计、Claude Code 实现，或 zcode 设计、opencode 实现；
+- 你需要一份带全部实现细节的有界任务包。
+
+## 前置条件
+
+导出器写任何内容前先做只读检查：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
+```
+
+若结果为 `CONTRACT_CHANGED`、`CONTRACT_UNAPPROVED` 或 `CONTRACT_READ_FAILED`，回到 `$matrix-design`，修订后重新进入 Build 取得新批准。导出只读取批准快照中的 `proposal.md`、`design.md` 与 `plan.md`。
+
+## 导出
+
+实现 agent 由用户显式选择，通过 `--agent <agent-id>`（kebab-case）传入；可用 `--from <agent-id>` 标注设计方 agent。
+
+```powershell
+# 通用 agent 交接：写入 artifacts/handoff-task-<ID>.md
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --agent opencode
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --agent claude-code --from codex
+
+# 兼容形态（Claude Code）：写入 artifacts/claude-task.md
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --target generic
+
+# FnSec：仅在 active.md 含有 NO_ACTIVE_OBJECTIVE 时更新看板
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --target fnsec --apply-fnsec-board
+```
+
+`--agent` 与 `--target` 互斥。新交接推荐 `--agent`；`--target generic` 仅为兼容保留。
+
+## 任务包内容
+
+导出包（`artifacts/handoff-task-<task-id>.md`）的元数据记录 `Implementation actor`（`--agent` 值）与 `Decision owner`（`--from` 值，缺省为 "Matrix change owner"），并包含批准的 Contract hash 与 revision，以及同一冻结快照的 proposal、design、plan。Objective、Allowed/Prohibited work 与 Stop conditions 原样携带——它们与具体 agent 无关。
+
+## 实现 agent 完成后
+
+继续 `$matrix-verify` 前先核对以下证据：
+
+- [ ] `artifacts/verification.md` 存在且含 `## Build evidence`
+- [ ] Build evidence 含具体命令与结果
+- [ ] plan 的 Validation 命令全部执行
+- [ ] `NEEDS_DECISION` 项已解决或已记录
+
+证据缺失时，让实现 agent 补齐后再继续。
+
+## 恢复 Matrix 工作流
+
+实现 agent 完成且证据齐备后：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
+```
+
+guard 失败则退回实现 agent 补齐缺失证据；通过后进入 `$matrix-verify` 继续验证流程。
+
+## 重要约束
+
+- 本旁路不改变 Matrix 阶段、workflow 或 guard 结果
+- Matrix 状态停留在 `build`；导出本身不推进阶段
+- 实现 agent 产出的证据必须满足 build guard 条件
+- 成功 transition 到 verify 后，走正常验证流程

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

@@ -1,30 +1,40 @@
----
-name: matrix-open
-description: 将开发请求澄清为有证据的 Matrix 提案。
----
-
-# Matrix Open
-
-读取 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` 返回的 `profile` 与 `evidence_policy`。
-
-proposal 正文使用其中的 `artifact_language`；Runtime 所需的英文标题 token 必须原样保留，仅标题下内容本地化。
-
-- full proposal 包含 `## Goal`、`## Scope`、`## Non-goals`、`## Acceptance`、`## Risks`，随后进入 Design。
-- lightweight proposal 在修改项目实现前完整定义 `## Goal`、`## Scope`、`## Non-goals`、`## Approach`、`## Acceptance`、`## Validation`、`## Risks`、`## Upgrade conditions`。
-- hotfix 额外包含 `## Expected behavior`、`## Actual behavior`、`## Reproduction`。
-- tweak 额外包含 `## Current behavior`、`## Preserved behavior`、`## Diff boundary`。
-
-- **Prim**：使用 Matrix 自身能力澄清并编写提案。
-- **Arch**：仅在存在重大歧义或用户要求压力测试时调用 `grilling`；仅在领域词汇、不变量或架构决定不清晰时调用 `domain-modeling`。调用前说明能力与原因。
+---
+name: matrix-open
+description: 将开发请求澄清为有证据的 Matrix 提案。
+---
+
+# Matrix Open
+
+读取 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` 返回的 `profile` 与 `evidence_policy`。
+
+proposal 正文使用其中的 `artifact_language`；Runtime 所需的英文标题 token 必须原样保留，仅标题下内容本地化。
+
+- full proposal 包含 `## Goal`、`## Scope`、`## Non-goals`、`## Acceptance`、`## Risks`，随后进入 Design。
+- lightweight proposal 在修改项目实现前完整定义 `## Goal`、`## Scope`、`## Non-goals`、`## Approach`、`## Acceptance`、`## Validation`、`## Risks`、`## Upgrade conditions`。
+- hotfix 额外包含 `## Expected behavior`、`## Actual behavior`、`## Reproduction`。
+- tweak 额外包含 `## Current behavior`、`## Preserved behavior`、`## Diff boundary`。
+
+- **Prim**：使用 Matrix 自身能力进行结构化澄清（目标、范围、非目标、验收标准、风险、时限），并编写提案。
+- **Arch**：Open 开始即说明能力与原因，默认调用 `grilling` 澄清需求；仅在领域词汇、不变量或架构决定不清晰时调用 `domain-modeling`。
+- **豁免澄清**：仅当用户同时满足 (1) 自带清晰的执行计划，(2) 明确说明不需要澄清过程 时，才可跳过澄清；跳过仍必须生成 `clarification.md` 的豁免记录。
+
+## 澄清产物（强制）
+
+在编写 proposal 之前生成 `<change>/clarification.md`，无论澄清或豁免都必须落盘：
+
+- 正常澄清：`## Questions` / `## Answers` / `## Resolved scope`（英文标题 token 固定，正文使用 `artifact_language`）；
+- 豁免路径：`## Exemption record`（豁免原因 + 用户计划要点 + proposal 如何采纳该计划）。
+
+lightweight（hotfix/tweak）同样适用，但澄清精简为一轮核心问题。该文件是 Open 阶段的证据类产物：不参与 Contract identity 计算，Runtime 不校验其存在；0.1.5 及更早创建、停在 open 的 change 无需补写即可继续推进。
 
 若进展被另一人掌握的事实或决定阻塞，说明 `to-questionnaire` 适用的原因并让用户显式调用；Matrix 不得自行嵌套该 wrapper。
-
-companion 输出只能作为当前 proposal 的证据，不得创建第二套工作流、提案、确认状态或阶段转换。正确安装的能力失败时最多执行一次同能力 Matrix fallback；安装完整性问题必须修复。
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard open
-# full
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition design
-# hotfix/tweak，仅在用户明确确认后
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build --confirmed
-```
+
+companion 输出只能作为当前 proposal 的证据，不得创建第二套工作流、提案、确认状态或阶段转换。正确安装的能力失败时最多执行一次同能力 Matrix fallback；安装完整性问题必须修复。
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard open
+# full
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition design
+# hotfix/tweak，仅在用户明确确认后
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build --confirmed
+```

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.6",
   "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-handoff"
+];
 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());