@rosenfan/matrix 0.1.2 → 0.1.4

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 # Matrix Workflow
 
-一个提供 Prim 与 Arch 编排的证据驱动开发工作流，灵感来自 [Comet](https://github.com/rpamis/comet)。Matrix 可以使用自身能力，也可以按事实调用已验证的 [Matt Pocock agent skills](https://github.com/mattpocock/skills)，但生命周期所有权始终由 Matrix 保持。
+一个提供 Prim 与 Arch 编排的证据驱动开发工作流，灵感来自 [Comet](https://github.com/rpamis/comet)。Matrix 可以使用自身能力，也可以按事实调用已验证的 [Matt Pocock agent skills](https://github.com/mattpocock/skills)，但生命周期所有权始终由 Matrix 保持。
 
 **[English](./README.md)** | 中文
 
@@ -27,38 +27,39 @@
 
 ## 为什么需要 Matrix
 
-[Matt Pocock 的 skills](https://github.com/mattpocock/skills) 提供 `/grilling`、`/tdd`、`/code-review` 等聚焦能力。但缺少统一生命周期所有者时会导致常见问题：
+[Matt Pocock 的 skills](https://github.com/mattpocock/skills) 提供 `/grilling`、`/tdd`、`/code-review` 等聚焦能力。但缺少统一生命周期所有者时会导致常见问题：
 
 - **无流程记忆**：你进行了 grilling，然后实现，但没有记录决策过程
 - **阶段混乱**：设计完成了吗？我们在构建阶段吗？上下文丢失后很难判断
 - **静默范围蔓延**：需求在构建过程中变更，却没有返回设计阶段
 - **缺少证据**："看起来完成了"却没有验证证明
 
-Matrix 通过唯一的确定性状态机解决这些问题 —— 包含明确的阶段、守卫条件和产物追踪。Skill 可以协助阶段，但生命周期始终由 Matrix 拥有。
+Matrix 通过唯一的确定性状态机解决这些问题 —— 包含明确的阶段、守卫条件和产物追踪。Skill 可以协助阶段，但生命周期始终由 Matrix 拥有。
 
 ---
 
 ## 它做了什么
 
-Matrix 在同一条工作流上提供两种能力编排：
+Matrix 在集中定义的两种 workflow profile 上提供两种能力编排：
 
 ```
-open → design → build → verify → archive
-
-Prim：Matrix 使用自身能力
-Arch：仅在任务事实满足触发条件时调用已验证的原子 Skill
-```
-
-恢复路径由 Runtime 受控执行：
-
-```text
-build  --design-gap--------------------> design
-verify --verification-failed-----------> build
-verify --acceptance-or-design-gap------> design
-任意活动阶段 --abort-------------------> aborted
-```
-
-每个阶段：
+full：                    open → design → build → verify → archive
+hotfix/tweak lightweight：open ─────────→ build → verify → archive
+
+Prim：Matrix 使用自身能力
+Arch：仅在任务事实满足触发条件时调用已验证的原子 Skill
+```
+
+恢复路径由 Runtime 受控执行：
+
+```text
+build  --design-gap--------------------> design
+verify --verification-failed-----------> build
+verify --acceptance-or-design-gap------> design
+任意活动阶段 --abort-------------------> aborted
+```
+
+每个阶段：
 - 有特定的交付物（产物）
 - 有必须通过的守卫条件
 - 记录所有转换
@@ -68,9 +69,10 @@ verify --acceptance-or-design-gap------> design
 
 ## 前置条件
 
-- 已安装 [Claude Code](https://docs.anthropic.com/claude-code)
-- Node.js 18+（用于运行安装器）
-- Python 3.8+ 已添加到 PATH
+- 已安装 [Claude Code](https://docs.anthropic.com/claude-code) 和/或 Codex，作为 Skill 宿主
+- Node.js 18+，且 `npm` 已加入 PATH（用于 Matrix CLI）
+- Python 仅在兼容窗口内的旧适配器路径使用；新安装使用内置 Node workflow runtime
+- Git 仅在从 GitHub 安装或参与 Matrix 开发时需要
 
 ---
 
@@ -91,26 +93,48 @@ matrix init
 
 交互式初始化支持：
 
-- 选择安装到当前项目或全局
+- 选择 Matrix Skill 发现入口安装到当前项目或全局
 - 复制 skills（推荐）或为本地开发创建符号链接
-- 更新已有安装，并自动备份被替换的 Matrix 文件
-- 在同一流程中安装 Matt Pocock 的配套 skills
-- 选择 Prim 或 Arch 作为项目默认值，且不禁用另一种可用模式
+- 安全地重新配置已有安装，并自动备份被替换的 Matrix 文件
+- 审查 Matt Skills v1.2.3 官方 25 项角色，并在目标项目安装其中 23 项兼容 Skill
+- 选择 Prim 或 Arch 作为项目默认值，且不禁用另一种可用模式
 
 自动化或 CI 环境可以使用：
 
 ```bash
 # 使用推荐的项目级默认值，不显示交互问题
-matrix init --yes --with-mattpocock
-
+matrix init --yes --with-mattpocock
+
 # 显式选择项目默认编排
 matrix init --yes --with-mattpocock --default-orchestration arch
+
+# 只有明确授权备份后才替换被本地修改的 Matt Skills
+matrix init --yes --with-mattpocock --force-matt
 
 # 检查安装完整性和运行环境
 matrix doctor
 ```
 
-npm 包正式发布前，也可以直接从 GitHub 安装：
+更新已经初始化的项目：
+
+```bash
+# 检查新版 Matrix CLI，确认计划后更新 CLI 并同步当前项目资产
+matrix update
+
+# 离线或本地开发：不访问 npm registry，只用当前 CLI 同步资产
+matrix update --skip-self-update
+
+# 已在自动化中明确授权写入
+matrix update --yes
+```
+
+`matrix update` 会保留既有安装的 scope、平台、语言、mode 与 orchestration。它先隔离验证 npm 新包，再由新 CLI 同步 Matrix 资产；它绝不下载、安装、修复或删除 Matt Skills。Matrix 更新完成后只读报告项目 Matt 兼容状态，必要时提示 `matrix init . --with-mattpocock`。npm 与项目资产是两个事务：若 CLI 已更新但资产同步失败，可运行 `matrix update --skip-self-update` 重试。
+
+Matrix 0.1.4 固定对应 Matt Skills v1.2.3，commit 为 `6acc160e4e0cd062dbbbd7a1b26ae92855edf07e`。即使上游已有新版，`matrix init --with-mattpocock` 仍使用该确切 archive 与经过审查的 23 项兼容 manifest。官方角色中的 `implement` 与 raw `resolving-merge-conflicts` 不兼容，因此 Matrix 不安装也不管理它们。Matrix scope 只控制 Matrix Skill 的发现位置；Matt Skills 与 `.matrix/matt-installation.json` 始终属于目标项目。全局 Matt 副本会保留，但绝不用于补齐项目 readiness。
+
+`matrix init` 选择的语言决定新 Matrix 产物的正文语言：`zh-CN` 使用中文、`en` 使用英文。Runtime 守卫依赖的 Markdown 英文标题 token 保持不变；每个 change 在创建时冻结该语言。
+
+也可以直接从 GitHub 安装，而不是 npm：
 
 ```bash
 npm install --global github:Rosenfan/Matrix
@@ -118,10 +142,10 @@ npm install --global github:Rosenfan/Matrix
 
 Matrix 将安装：
 - `matrix/` — 入口点和状态管理
-- `matrix-open/` — Open 阶段与 canonical proposal
-- `matrix-design/` — Design、plan 与 Contract 批准
-- `matrix-build/` — 有界实现与构建证据
-- `matrix-verify/` — 测试和双轴审查证据
+- `matrix-open/` — Open 阶段与 canonical proposal
+- `matrix-design/` — Design、plan 与 Contract 批准
+- `matrix-build/` — 有界实现与构建证据
+- `matrix-verify/` — 测试和双轴审查证据
 - `matrix-archive/` — 归档阶段
 - `matrix-hotfix/` — 小型 Bug 快捷方式
 - `matrix-tweak/` — 有界变更快捷方式
@@ -139,8 +163,8 @@ $matrix 我想给 API 添加用户认证
 ```
 
 Matrix 将会：
-1. 用工作流类型 `full` 和冻结的 `prim|arch` 编排初始化变更
-2. 进入 `open`；Prim 直接处理，Arch 只调用已证明的需求触发能力
+1. 用工作流类型 `full` 和冻结的 `prim|arch` 编排初始化变更
+2. 进入 `open`；Prim 直接处理，Arch 只调用已证明的需求触发能力
 3. 创建 `proposal.md`，包含目标、范围、验收标准、风险
 4. 守卫检查：所有章节是否内容充实？
 5. 如果通过 → 转换到 `design`
@@ -149,13 +173,13 @@ Matrix 将会：
 
 ## 工作流阶段
 
-| 阶段 | Arch 能力（按事实触发，不是固定序列） | 交付物 | 守卫条件 |
-|------|----------------------------------------|--------|----------|
-| **open** | `/grilling`、`/domain-modeling` | `proposal.md`；可选仓库约定的 context/ADR 证据 | 目标、范围、验收标准、风险存在 |
-| **design** | `/domain-modeling`、`/research`、`/wayfinder`、`/prototype`、`/codebase-design` | `design.md`、`plan.md` | 决策、测试点、步骤已记录 |
-| **build** | `/tdd`、`/diagnosing-bugs`、`/resolving-merge-conflicts` | 代码、`verification.md` | 已批准的精确 Contract 匹配，且已记录构建证据 |
-| **verify** | `/code-review` | 测试和审查证据 | 测试和审查证据存在 |
-| **archive** | 无；两种模式均由 Matrix 拥有 | 归档记录 | 验证守卫通过 |
+| 阶段 | Arch 能力（按事实触发，不是固定序列） | 交付物 | 守卫条件 |
+|------|----------------------------------------|--------|----------|
+| **open** | `/grilling`、`/domain-modeling` | `proposal.md`；可选仓库约定的 context/ADR 证据 | 目标、范围、验收标准、风险存在 |
+| **design** | `/domain-modeling`、`/research`、`/prototype`、`/codebase-design`、条件触发的 `/writing-for-agents` | `design.md`、`plan.md` | 决策、测试点、步骤已记录 |
+| **build** | `/tdd`、`/diagnosing-bugs`、条件触发的 `/writing-for-agents` 与仅生成的 `/wizard` | 代码、`verification.md` | 已批准的精确 Contract 匹配，且已记录构建证据 |
+| **verify** | `/code-review` | 测试证据、双轴审查、Arch 回执 | 证据内容充分；Arch 回执匹配当前 Contract、审查正文和工作区 |
+| **archive** | 无；两种模式均由 Matrix 拥有 | 归档记录 | 验证守卫通过 |
 
 ---
 
@@ -169,45 +193,50 @@ Matrix 将会：
 ├── config.yaml
 ├── changes/
 │   └── <change-id>/
-│       ├── matrix.yaml      # 唯一 workflow、orchestration、阶段、状态与 revision 事实
-│       ├── events.jsonl
-│       └── artifacts/
-│           ├── proposal.md
-│           ├── design.md
-│           ├── plan.md
-│           ├── verification.md
-│           └── evidence-history/
-└── archive/
-```
+│       ├── matrix.yaml      # 唯一 workflow、orchestration、阶段、状态与 revision 事实
+│       ├── workspace-baseline.json # lightweight 的实施顺序边界
+│       ├── events.jsonl
+│       └── artifacts/
+│           ├── proposal.md
+│           ├── design.md
+│           ├── plan.md
+│           ├── verification.md
+│           └── evidence-history/
+└── archive/
+```
 
 状态机强制执行转换：
 
 ```bash
-# 检查守卫
-matrix workflow guard open
-
-# 推进（仅在守卫通过时）
-matrix workflow transition design
-
-# 验证失败时返回 Build；旧证据保留在历史目录
-matrix workflow return build --reason verification-failed
-
-# 终止变更但保留产物，不撤销工作区代码
-matrix workflow abort --reason requirement-cancelled
-
-# 最终归档强制使用两步乐观提交
-matrix workflow archive --dry-run
-matrix workflow archive --expect-preflight <dry-run-返回的-sha256>
-
-# 只读诊断中断的 Workflow
-matrix workflow doctor
-
-# 只恢复 doctor 明确报告的 transaction 或陈旧锁
-matrix workflow doctor --repair --transaction <id> --strategy <continue|rollback>
-matrix workflow doctor --repair --lock <id>
-```
-
-`matrix.yaml` 是 workflow、orchestration、阶段、状态与 revision 的唯一事实来源，schema 为 `matrix/change/v2`；初始化解析出的 `prim|arch` 在整个 change 中冻结。旧 schema 会被拒绝且不会发生写入。`design -> build` 会记录 `proposal.md`、`design.md`、`plan.md` 精确字节的 SHA-256 身份；任一字节改动都会阻断 Build、Verify、Archive 和 Claude 导出，必须受控 Return 到 Design 后重新批准。最终 Archive 必须先只读 dry-run，再携带该 hash 提交；Runtime 在 Archive 事务边界内重算整个受保护 change 目录 manifest，发生漂移即拒绝。所有多文件 Workflow mutation 都由 `.matrix/transactions/` 下的持久 journal 保护；`matrix workflow doctor` 始终只读，恢复必须显式绑定其报告的 transaction/strategy 或 lock identity。终态 journal 会收缩为有界审计 receipt，未完成或冲突 journal 永不自动删除。
+# 检查守卫
+matrix workflow guard open
+
+# 推进（仅在守卫通过时）
+matrix workflow transition design
+
+# lightweight：确认紧凑 proposal 后进入 Build
+matrix workflow transition build --confirmed
+
+# 验证失败时返回 Build；旧证据保留在历史目录
+matrix workflow return build --reason verification-failed
+
+# 终止变更但保留产物，不撤销工作区代码
+matrix workflow abort --reason requirement-cancelled
+
+# 最终归档强制使用两步乐观提交
+matrix workflow archive --dry-run
+matrix workflow archive --expect-preflight <dry-run-返回的-sha256>
+# hotfix/tweak 的提交命令还必须带 --confirmed
+
+# 只读诊断中断的 Workflow
+matrix workflow doctor
+
+# 只恢复 doctor 明确报告的 transaction 或陈旧锁
+matrix workflow doctor --repair --transaction <id> --strategy <continue|rollback>
+matrix workflow doctor --repair --lock <id>
+```
+
+`matrix.yaml` 仍是 workflow、orchestration、阶段、状态与 revision 的唯一事实来源。full 批准 proposal/design/plan 的精确字节；lightweight 批准紧凑 proposal，要求明确确认，并与初始化工作区基线比较，阻止先实现后补方案。Contract 漂移会阻断后续阶段。最终 Archive 仍使用只读 dry-run 与 hash-bound commit，shortcut 还要求明确确认；所有多文件 mutation 继续受持久 journal 保护。
 
 ---
 
@@ -219,6 +248,8 @@ matrix workflow doctor --repair --lock <id>
 | **hotfix** | 可复现的小型 Bug | 简化：open → build → verify → archive |
 | **tweak** | 有界变更，无 API/架构影响 | 简化：open → build → verify → archive |
 
+hotfix 与 tweak 引用同一个内部 `lightweight` 迁移 profile，只在入口和证据上区分：hotfix 要求复现、根因、回归证据；tweak 要求行为边界、diff 与范围审查证据。
+
 ---
 
 ## 特别功能：matrix-claude
@@ -235,7 +266,7 @@ $matrix → open → design → build → verify → archive
 |------|------|
 | 一个工具完成所有工作（默认） | 直接用 `$matrix`，无需额外步骤 |
 | Codex 设计 + Codex 实现 | 标准流程：design → build → verify |
-| Codex 设计 + Claude Code 实现 | design → build（批准 Contract）→ `$matrix-claude` → Claude Code → verify |
+| Codex 设计 + Claude Code 实现 | design → build（批准 Contract）→ `$matrix-claude` → Claude Code → verify |
 
 ### matrix-claude 工作原理
 
@@ -249,30 +280,34 @@ $matrix → open → design → build → verify → archive
 
 ---
 
-## 与 Matt Pocock Skills 的集成
-
-Prim 使用 Matrix 自身能力。Arch 使用初始化时验证的十项原子能力：
-
-| 阶段 | 能力 | 触发条件 |
-|---|---|---|
-| open | `/grilling` | 存在重大歧义或用户明确要求压力测试 |
-| open/design | `/domain-modeling` | 词汇、不变量或架构决定不清晰 |
-| design | `/research` | 仓库内无法获得必需的外部事实 |
-| design | `/wayfinder` | 模块归属或依赖接缝未知 |
+## 与 Matt Pocock Skills 的集成
+
+Prim 使用 Matrix 自身能力。Matrix 会审查 Matt v1.2.3 官方 25 项角色，安装其中 23 项兼容 Skill，但 Arch 只自动调用以下十项经过审查的能力：
+
+| 阶段 | 能力 | 触发条件 |
+|---|---|---|
+| open | `/grilling` | 存在重大歧义或用户明确要求压力测试 |
+| open/design | `/domain-modeling` | 词汇、不变量或架构决定不清晰 |
+| design | `/research` | 仓库内无法获得必需的外部事实 |
 | design | `/prototype` | 重大设计问题需要一次性实验证据 |
 | design | `/codebase-design` | 深模块、接口或测试接缝决定尚未完成 |
+| design/build | `/writing-for-agents` | Contract 修改 agent-facing 指令或指针可达文档 |
 | build | `/tdd` | 可测试接缝上的可观察行为发生变化 |
 | build | `/diagnosing-bugs` | 存在真实失败且根因未知 |
-| build | `/resolving-merge-conflicts` | 正在发生 merge/rebase 冲突 |
+| build | `/wizard` | Contract 需要生成人工执行的 shell 步骤；Matrix 不端到端运行 |
 | verify | `/code-review` | 需要 Standards 与 Spec 双轴证据 |
 
-`grill-with-docs`、`implement`、`improve-codebase-architecture` 不受 Matrix 管理，也不会自动调用。用户已安装的副本会作为非受管额外 Skill 保留。companion 不得推进、提交、归档或写 Matrix 状态。
+Matrix 可以推荐但绝不嵌套以下 user-invoked handoff：`setup-matt-pocock-skills`、`improve-codebase-architecture`、`wayfinder`、`handoff`、`to-questionnaire`。它们由用户在活动阶段外显式运行，选中的结果可以再进入受治理 Change。
+
+Arch 在 `code-review` 后记录由 Runtime 管理的审查回执，把 fixed point 与已提交的 HEAD diff 绑定到当前 Contract、审查正文和工作区。正常的 `code-review` 回执要求 Matrix 管理资产之外的候选工作区是干净的。无可用 Git 基线、已提交 diff 为空、仍存在 staged/unstaged/untracked 候选，或正确安装的 capability 真实失败时，Matrix 可为该 revision 执行一次明确标记的同能力 fallback；其中 `uncommitted-worktree` 会同时绑定 fixed point 与完整工作区候选的内容 hash。安装完整性失败不得 fallback。只有标题或自述、但没有匹配回执时，Verify 不能推进。
+
+安装但保持 standalone 的 Skill 是 `ask-matt`、`grill-with-docs`、`triage`、`to-spec`、`to-tickets`、`grill-me`、`teach`、`wait-what`。`implement` 与 raw `resolving-merge-conflicts` 可能接管 Matrix 所有的 TDD、review、stage 或 commit 副作用，因此 0.1.4 不安装也不管理它们；已有副本会被保留并报告为未管理额外项。安装不代表自动调用；任何 companion 都不得推进、提交、归档、恢复或写 Matrix 状态。
 
 ---
 
 **关键区别**：Matt Pocock 的 skills 是独立工具。Matrix 增加了：
 - **状态持久化**：可承受上下文丢失
-- **阶段强制**：不能跳过设计直接进入构建
+- **阶段强制**：full 不能跳过 Design；lightweight 不能在确认 Open Contract 前修改实现
 - **证据要求**：守卫检查产物，而非断言
 - **转换日志**：完整的阶段变更审计记录
 

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

@@ -1,80 +1,83 @@
----
-name: matrix
-description: 启动、恢复并治理持久化的 Matrix 开发工作流。
----
-
-# Matrix
-
-以当前仓库的 `.matrix/` 为唯一状态来源；不得从聊天记录推断阶段。
-
-先执行：
-
-```powershell
-matrix workflow inspect
-```
-
-只有系统明确报告 `matrix` 命令不存在时，才使用当前 Matrix Skill 目录中的 bundled runtime：
+---
+name: matrix
+description: 启动、恢复并治理持久化的 Matrix 开发工作流。
+---
+
+# Matrix
+
+以当前仓库的 `.matrix/` 为唯一状态来源；不得从聊天记录推断阶段。
+
+读取 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` 的 `artifact_language`。规范 Markdown 标题 token 必须保持不变；面向用户的产物正文、说明和 handoff 在 `zh-CN` 时写中文，在 `en` 时写英文。
+
+所有 workflow 命令都先执行当前项目 Matrix Skill 自带的 Runtime，使项目兼容性权威优先于不同版本的全局启动器：
 
 ```powershell
 node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect
 ```
 
-有活动变更时，报告其 phase、冻结的 `orchestration` 以及 Arch 安装完整性，再按 Runtime 结果进入 `next_skill`。没有活动变更时，为开发请求创建简短 kebab-case ID：
-
-```powershell
-matrix workflow init <change-id> --workflow <full|hotfix|tweak> --orchestration <prim|arch> --title "<title>"
-```
-
-显式模式优先，否则使用项目 `default_orchestration`。解析后的模式在整个 change 生命周期中不可切换。
-
-## 编排模式
-
-- **Prim**：各阶段使用 Matrix 自身能力，不依赖 Matt Skills。
-- **Arch**：仅在任务事实满足触发条件时，调用初始化阶段已验证的十项原子能力。
-
-两种模式共用同一套 Matrix phase graph、产物、守卫、Return/Abort、Contract、事务与归档协议。Arch 能力不得写 Matrix 状态、推进阶段、提交、归档或创建竞争工作流。调用前说明能力与触发原因，无需重复请求 Skill 权限。
-
-正确安装的 Arch 能力执行失败时，最多允许一次同能力的 Matrix fallback，并记录失败与证据。缺失、修改或不完整的 Arch 安装必须通过 `matrix init --with-mattpocock` 修复，不得切换活动 change 到 Prim。
-
-## 恢复
-
-只能通过 Runtime 恢复，不得手工修改状态：
-
-```powershell
-matrix workflow return design --reason design-gap
-matrix workflow return build --reason verification-failed
-matrix workflow return design --reason acceptance-or-design-gap
-matrix workflow abort --reason <requirement-cancelled|superseded|no-longer-valuable|blocked|other>
-```
-
-Return 会把当前 `verification.md` 轮换至按 revision 编号的证据历史。Archive 等待确认期间若验收或设计改变，只能使用 `archive -> design` 的 `acceptance-or-design-gap` Return。Abort 将终态变更移入 `.matrix/archive/`，但不会撤销工作区代码。
-
-任何 mutation 返回 `WORKFLOW_RECOVERY_REQUIRED` 时，停止正常阶段操作并先执行只读诊断：
-
-```powershell
-matrix workflow doctor
-```
-
-不得推断恢复目标或策略，只能执行 doctor 返回的精确命令：
-
-```powershell
-matrix workflow doctor --repair --transaction <id> --strategy <continue|rollback>
-matrix workflow doctor --repair --lock <id>
-```
-
-## 精确 Contract
-
-`design -> build` 会批准 `proposal.md`、`design.md`、`plan.md` 的精确字节 SHA-256 身份。任何后续字节变动都会阻断 Build、Verify、Archive 和 Claude 导出；必须受控 Return 至 Design 后重新批准。旧 schema 会被拒绝且不发生写入。
-
+全局 `matrix` 命令只负责 init、update 和 bootstrap。受信任的 0.1.4 启动器只会自动委派给版本与 hash 都精确匹配的 0.1.4 项目 Runtime。项目 Runtime 属于不同版本或无法识别版本时仍是项目权威，但必须执行启动器返回的精确直连命令；旧版启动器不具备这项跨版本检查，不能作为项目 workflow 入口。
+
+有活动变更时，报告其 phase、冻结的 `orchestration` 以及 Arch 安装完整性，再按 Runtime 结果进入 `next_skill`。没有活动变更时，为开发请求创建简短 kebab-case ID：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs init <change-id> --workflow <full|hotfix|tweak> --orchestration <prim|arch> --title "<title>"
+```
+
+显式模式优先，否则使用项目 `default_orchestration`。解析后的模式在整个 change 生命周期中不可切换。
+
+## 编排模式
+
+- **Prim**：各阶段使用 Matrix 自身能力，不依赖 Matt Skills。
+- **Arch**：仅在任务事实满足触发条件时，调用活动 Change 冻结的十项自动能力。Matrix 0.1.4 审查 Matt Skills v1.2.3 官方 25 项角色，只把其中 23 项兼容 Skill 安装在项目本地；排除 `implement` 与 raw `resolving-merge-conflicts`。
+
+两种编排模式使用已选定的 workflow profile：`full` 走 `open → design → build → verify → archive`；`hotfix` 与 `tweak` 共用内部 `lightweight` profile，走 `open → build → verify → archive`，仅证据策略不同。Arch 能力不得写 Matrix 状态、推进阶段、提交、归档或创建竞争工作流。
+
+正确安装的 Arch 能力执行失败时，最多允许一次同能力的 Matrix fallback，并记录失败与证据。缺失、修改或不完整的 Arch 安装必须通过 `matrix init --with-mattpocock` 修复，不得切换活动 change 到 Prim。
+
+## 恢复
+
+只能通过 Runtime 恢复，不得手工修改状态：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs return build --reason verification-failed
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason acceptance-or-design-gap
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs abort --reason <requirement-cancelled|superseded|no-longer-valuable|blocked|other>
+```
+
+Return 会把当前 `verification.md` 轮换至按 revision 编号的证据历史。Archive 等待确认期间若验收或设计改变，只能使用 `archive -> design` 的 `acceptance-or-design-gap` Return。Abort 将终态变更移入 `.matrix/archive/`，但不会撤销工作区代码。
+
+任何 mutation 返回 `WORKFLOW_RECOVERY_REQUIRED` 时，停止正常阶段操作并先执行只读诊断：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor
+```
+
+不得推断恢复目标或策略，只能执行 doctor 返回的精确命令：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor --repair --transaction <id> --strategy <continue|rollback>
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor --repair --lock <id>
+```
+
+## 精确 Contract
+
+full 的 `design -> build` 会批准 proposal/design/plan；lightweight 的 `open -> build --confirmed` 只批准紧凑 proposal，并拒绝初始化后、批准前发生的项目实现改动。Contract 后续漂移都会阻断推进。
+
 ## 可选 Claude 交接
-
-`$matrix-claude` 只在已批准的 Build 中使用，导出同一 Contract 快照给 Claude Code。它不拥有阶段推进或验收；直接由 Codex 实现仍使用原有 Matrix 主流程。
+
+`$matrix-claude` 只在已批准的 Build 中使用，导出同一 Contract 快照给 Claude Code。它不拥有阶段推进或验收；直接由 Codex 实现仍使用原有 Matrix 主流程。
 只有用户明确选择“Codex 设计、Claude Code 实现”时才使用，不得自动插入标准流程。
 
-## 规则
-
-- 阶段只能经 `matrix workflow transition` 正向推进。
-- 只能经上述明确的 `matrix workflow return` 反向推进。
-- 成功 Archive 必须使用两步乐观提交：先运行 `matrix workflow archive --dry-run`，再将其精确 hash 传给 `matrix workflow archive --expect-preflight <sha256>`；不得绕过预演。
-- `matrix workflow doctor` 始终只读；transaction 与陈旧锁 repair 必须显式绑定 doctor 报告的 identity，不得手工编辑或删除 `.matrix/transactions/`、`.matrix/workflow.lock`。
-- 重大架构/范围决定和 archive/commit 前应暂停等待用户确认。
+## 显式 Matt handoff
+
+Matrix 不嵌套 user-invoked Skill。适用时只解释原因，并让用户显式调用：一次性配置使用 `setup-matt-pocock-skills`，工作流外架构扫描使用 `improve-codebase-architecture`，独立大型候选生成使用 `wayfinder`，上下文边界使用 `handoff`，他人掌握阻塞事实时使用 `to-questionnaire`。`ask-matt`、`grill-with-docs`、`triage`、`to-spec`、`to-tickets`、`grill-me`、`teach`、`wait-what` 保持 standalone。Matrix 不安装也不管理 `implement` 或 raw `resolving-merge-conflicts`；已有副本保留为未管理额外项，活动 Change 内不得建议使用。
+
+## 规则
+
+- 阶段只能经 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition` 正向推进。
+- 只能经上述明确的 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return` 反向推进。
+- 成功 Archive 必须使用两步乐观提交：先运行 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs archive --dry-run`，再将其精确 hash 传给 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs archive --expect-preflight <sha256>`；不得绕过预演。
+- `node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor` 始终只读；transaction 与陈旧锁 repair 必须显式绑定 doctor 报告的 identity，不得手工编辑或删除 `.matrix/transactions/`、`.matrix/workflow.lock`。
+- 重大架构/范围决定和 archive/commit 前应暂停等待用户确认。
+- shortcut 范围扩大时执行 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap`；Runtime 将其升级为 full。

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

@@ -1,33 +1,36 @@
----
-name: matrix-archive
-description: 关闭并归档已经验证的 Matrix 变更。
----
-
-# Matrix Archive
-
-这是 Matrix 最终阶段。读取 proposal、plan 与验证证据，汇总行为变化、验证结果、残留风险和后续工作；提交归档前必须取得用户明确确认。
-
-Prim 与 Arch 的 Archive 均完全由 Matrix 拥有；本阶段不调用 companion 实现、审查或架构能力。
-
-## 强制两步归档
-
-先运行只读预演并复核影响摘要，再原样提交该次预演返回的 hash：
-
-```powershell
-matrix workflow archive --dry-run
-matrix workflow archive --expect-preflight <dry-run-返回的-sha256>
-```
-
-裸 Archive 会被拒绝。Runtime 会重新取得项目 Archive 互斥权，并在提交前重算整个受保护 change 目录 manifest。
-
-- `ARCHIVE_PREFLIGHT_CHANGED`：重新 dry-run 并复核新摘要。
-- `ARCHIVE_BUSY`：稍后重试；不得移除或接管锁，陈旧锁恢复属于后续 doctor/repair change。
-- Guard 或 Contract 失败：使用 Runtime 返回的恢复命令，不得提交。
-
-若最终确认前发现验收或设计需要调整，使用唯一 Archive 回退路径：
-
-```powershell
-matrix workflow return design --reason acceptance-or-design-gap
-```
-
-提交成功后，变更位于 `.matrix/archive/`，工作流完成。
+---
+name: matrix-archive
+description: 关闭并归档已经验证的 Matrix 变更。
+---
+
+# Matrix Archive
+
+这是 Matrix 最终阶段。读取 proposal、plan 与验证证据，汇总行为变化、验证结果、残留风险和后续工作；提交归档前必须取得用户明确确认。
+
+归档摘要和 handoff 正文使用 `artifact_language`；Runtime 所需英文标题 token 保持不变。
+
+Prim 与 Arch 的 Archive 均完全由 Matrix 拥有；本阶段不调用 companion 实现、审查或架构能力。
+
+## 强制两步归档
+
+先运行只读预演并复核影响摘要，再原样提交该次预演返回的 hash：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs archive --dry-run
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs archive --expect-preflight <dry-run-返回的-sha256>
+```
+
+裸 Archive 会被拒绝。Runtime 会重新取得项目 Archive 互斥权，并在提交前重算整个受保护 change 目录 manifest。
+hotfix/tweak 在复核 preflight 后必须再次取得用户明确确认，并执行 Runtime 返回的带 `--confirmed` 命令；缺少确认会被拒绝。
+
+- `ARCHIVE_PREFLIGHT_CHANGED`：重新 dry-run 并复核新摘要。
+- `ARCHIVE_BUSY`：稍后重试；不得移除或接管锁，陈旧锁恢复属于后续 doctor/repair change。
+- Guard 或 Contract 失败：使用 Runtime 返回的恢复命令，不得提交。
+
+若最终确认前发现验收或设计需要调整，使用唯一 Archive 回退路径：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason acceptance-or-design-gap
+```
+
+提交成功后，变更位于 `.matrix/archive/`，工作流完成。