@rosenfan/matrix 0.1.5 → 0.1.6

package/README.md

@@ -131,9 +131,9 @@ matrix update --skip-self-update
 matrix update --yes
 ```
 
-`matrix update` preserves the installation's scope, platforms, language, mode, and orchestration. It first validates a newer npm package in isolation, then re-runs the new CLI to refresh Matrix assets. It never downloads, installs, repairs, or deletes Matt Skills; after the Matrix update it reports the local Matt compatibility status and, when needed, points to `matrix init . --with-mattpocock`. npm and project assets are separate transactions: if asset refresh fails after a CLI upgrade, run `matrix update --skip-self-update` to retry.
+`matrix update` preserves the installation's scope, platforms, language, mode, and orchestration. It first validates a newer npm package in isolation, then re-runs the new CLI to refresh Matrix assets. When the local Matt Skills are incomplete or outdated, an interactive `matrix update` asks once and repairs them to the supported release in the same run — CLI upgrade, asset refresh, and Matt repair complete in a single command (`--with-mattpocock` gives non-interactive/CI the same behavior; `--force-matt` additionally replaces locally modified Matt Skills and requires that flag; Matt Skills are never removed by `matrix update`). `--all` extends the run to every indexed project (`~/.matrix/projects.json`); each project updates in isolation and missing directories are pruned from the index. npm and project assets are separate transactions: if asset refresh fails after a CLI upgrade, run `matrix update --skip-self-update` to retry. On Windows the self-update chain runs npm through Node (no shell), so one-command upgrades work without manual steps.
 
-Matrix 0.1.5 is bound to Matt Skills v1.2.3 at commit `6acc160e4e0cd062dbbbd7a1b26ae92855edf07e`. `matrix init --with-mattpocock` always uses that exact archive and its reviewed 23-Skill compatible manifest, even if upstream has a newer release. The two official but incompatible Skills, `implement` and raw `resolving-merge-conflicts`, are not Matrix-managed or installed. Matrix scope controls Matrix Skill discovery only: Matt Skills and `.matrix/matt-installation.json` are always project-local. Global Matt copies are preserved but never used to complete project readiness.
+Matrix 0.1.6 is bound to Matt Skills v1.2.3 at commit `6acc160e4e0cd062dbbbd7a1b26ae92855edf07e`. `matrix init --with-mattpocock` always uses that exact archive and its reviewed 23-Skill compatible manifest, even if upstream has a newer release. The two official but incompatible Skills, `implement` and raw `resolving-merge-conflicts`, are not Matrix-managed or installed. Matrix scope controls Matrix Skill discovery only: Matt Skills and `.matrix/matt-installation.json` are always project-local. Global Matt copies are preserved but never used to complete project readiness.
 
 The language selected by `matrix init` controls the prose in new Matrix artifacts. Markdown headings required by Matrix guards remain stable English tokens; the artifact body is Chinese for `zh-CN` and English for `en`. A change freezes this language at creation time.
 
@@ -153,7 +153,7 @@ Matrix installs:
 - `matrix-hotfix/` — Shortcut for small bugs
 - `matrix-tweak/` — Shortcut for bounded changes
 - `matrix-status/` — Check current state
-- `matrix-claude/` — Optional: export for Claude Code
+- `matrix-handoff/` — Optional: export to any implementation agent (Claude Code, opencode, ...)
 
 ---
 
@@ -255,28 +255,29 @@ Hotfix and tweak reference the same internal `lightweight` transition profile. T
 
 ---
 
-## Special Feature: matrix-claude
+## Special Feature: matrix-handoff
 
-**Default usage**: Just use the main workflow (`$matrix`). Whether you're using Codex or Claude Code, the standard flow works for both:
+**Default usage**: Just use the main workflow (`$matrix`). Whether you're using Codex, Claude Code, zcode, or opencode, the standard flow works for all of them:
 
 ```
 $matrix → open → design → build → verify → archive
 ```
 
-**When to use `$matrix-claude`**: Only when you want to **split the work across tools** — use Codex for design, then hand off to Claude Code for implementation.
+**When to use `$matrix-handoff`**: Only when you want to **split the work across tools** — design in one agent, implement in another.
 
 | Scenario | What to Do |
 |----------|------------|
 | Use one tool for everything (default) | Just use `$matrix`, no extra steps |
-| Codex designs + Codex implements | Standard flow: design → build → verify |
-| Codex designs + Claude Code implements | design → `$matrix-claude` → Claude Code → verify |
+| Same agent designs and implements | Standard flow: design → build → verify |
+| Codex designs + Claude Code implements | design → `$matrix-handoff` → `export --agent claude-code` → Claude Code → verify |
+| zcode designs + opencode implements | design → `$matrix-handoff` → `export --agent opencode` → opencode → verify |
 
-### How matrix-claude Works
+### How matrix-handoff Works
 
-1. Design phase completes, guard passes
-2. Run `$matrix-claude` → exports frozen design as `artifacts/claude-task.md`
-3. Claude Code reads the task package and implements
-4. Claude Code produces evidence in `artifacts/verification.md`
+1. Design phase completes, guard passes, and you choose the implementation agent at the Design -> Build decision point
+2. Run `$matrix-handoff` → exports the frozen contract as `artifacts/handoff-task-<task-id>.md` (`export --agent <agent-id>`; `--target generic` remains as the legacy Claude Code form, `artifacts/claude-task.md`)
+3. The implementation agent reads the task package and implements
+4. The implementation agent produces evidence in `artifacts/verification.md`
 5. Return to Matrix: build guard → verify → archive
 
 The sidecar does NOT change Matrix state. It's a pure export — like taking a snapshot of the design for another tool to consume.

package/README.zh-CN.md

@@ -128,9 +128,9 @@ 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 update` 会保留既有安装的 scope、平台、语言、mode 与 orchestration。它先隔离验证 npm 新包，再由新 CLI 同步 Matrix 资产。当本地 Matt Skills 不完整或过期时，交互式 `matrix update` 会询问一次，并在同一轮把 Matt 修复到受支持 release——CLI 升级、资产刷新、Matt 修复一条命令完成（`--with-mattpocock` 为自动化/CI 提供等价的非交互行为；`--force-matt` 可额外替换被本地修改的 Matt Skills，且必须与 `--with-mattpocock` 同传；`matrix update` 绝不删除 Matt Skills）。`--all` 可将更新扩展到全部已索引项目（`~/.matrix/projects.json`），各项目隔离更新，失效目录自动从索引清理。npm 与项目资产是两个事务：若 CLI 已更新但资产同步失败，可运行 `matrix update --skip-self-update` 重试。Windows 上自升级链路经 Node 调用 npm（不经 shell），一条命令升级无需手动步骤。
 
-Matrix 0.1.5 固定对应 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 0.1.6 固定对应 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 在创建时冻结该语言。
 
@@ -150,7 +150,7 @@ Matrix 将安装：
 - `matrix-hotfix/` — 小型 Bug 快捷方式
 - `matrix-tweak/` — 有界变更快捷方式
 - `matrix-status/` — 检查当前状态
-- `matrix-claude/` — 可选：导出供 Claude Code 使用
+- `matrix-handoff/` — 可选：导出给任意实现 agent（Claude Code、opencode 等）
 
 ---
 
@@ -252,28 +252,29 @@ hotfix 与 tweak 引用同一个内部 `lightweight` 迁移 profile，只在入
 
 ---
 
-## 特别功能：matrix-claude
+## 特别功能：matrix-handoff
 
-**默认用法**：直接使用主流程即可。无论你用 Codex 还是 Claude Code，标准流程都适用：
+**默认用法**：直接使用主流程即可。无论你用 Codex、Claude Code、zcode 还是 opencode，标准流程都适用：
 
 ```
 $matrix → open → design → build → verify → archive
 ```
 
-**何时使用 `$matrix-claude`**：仅当你想**跨工具拆分工作**时 —— 用 Codex 设计，然后交给 Claude Code 实现。
+**何时使用 `$matrix-handoff`**：仅当你想**跨工具拆分工作**时 —— 用一个 agent 设计，交给另一个 agent 实现。
 
 | 场景 | 操作 |
 |------|------|
 | 一个工具完成所有工作（默认） | 直接用 `$matrix`，无需额外步骤 |
-| Codex 设计 + Codex 实现 | 标准流程：design → build → verify |
-| Codex 设计 + Claude Code 实现 | design → build（批准 Contract）→ `$matrix-claude` → Claude Code → verify |
+| 同一 agent 设计 + 实现 | 标准流程：design → build → verify |
+| Codex 设计 + Claude Code 实现 | design → build（批准 Contract）→ `$matrix-handoff` → `export --agent claude-code` → Claude Code → verify |
+| zcode 设计 + opencode 实现 | design → build（批准 Contract）→ `$matrix-handoff` → `export --agent opencode` → opencode → verify |
 
-### matrix-claude 工作原理
+### matrix-handoff 工作原理
 
-1. 设计阶段完成，守卫通过
-2. 运行 `$matrix-claude` → 导出冻结的设计为 `artifacts/claude-task.md`
-3. Claude Code 读取任务包并实现
-4. Claude Code 在 `artifacts/verification.md` 中产生证据
+1. 设计阶段完成，守卫通过，并在 design→build 决策点选择实现 agent
+2. 运行 `$matrix-handoff` → 导出冻结 Contract 为 `artifacts/handoff-task-<task-id>.md`（`export --agent <agent-id>`；`--target generic` 为兼容的 Claude Code 旧形态，产出 `artifacts/claude-task.md`）
+3. 实现 agent 读取任务包并实现
+4. 实现 agent 在 `artifacts/verification.md` 中产生证据
 5. 返回 Matrix：构建守卫 → 验证 → 归档
 
 此 sidecar 不会改变 Matrix 状态。它只是纯粹的导出 —— 就像为另一个工具拍一张设计快照。

package/assets/skills/matrix/SKILL.md

@@ -66,10 +66,10 @@ node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor --repair --trans
 node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor --repair --lock <id>
 ```
 
-## Optional Claude handoff
+## Optional implementation handoff
 
-`$matrix-claude` is an optional sidecar command used after the approved Design -> Build transition. It exports the matching approved contract to a Claude Code task package. It never changes the Matrix phase, workflow, guard result, or runtime state.
-Use it only when the user explicitly chooses Codex design with Claude Code implementation; never inject it into the standard path.
+`$matrix-handoff` is an optional sidecar command used after the approved Design -> Build transition. It exports the matching approved contract as a bounded task package for the implementation agent the user chooses (`export --agent <agent-id>`, for example Codex designing and Claude Code implementing, or zcode designing and opencode implementing). It never changes the Matrix phase, workflow, guard result, or runtime state.
+Use it only when the user explicitly chooses a different implementation agent; never inject it into the standard path.
 
 ## Cross-Cutting Skills
 
@@ -84,4 +84,5 @@ Matrix never nests user-invoked Matt Skills. When relevant, explain the reason a
 - `node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor` is read-only. Every transaction or stale-lock repair must explicitly bind the identity reported by doctor; do not edit or delete `.matrix/transactions/` or `.matrix/workflow.lock`.
 - Do not replace required evidence with an assertion that work is complete.
 - Pause for user confirmation at material architecture/scope decisions and before archive/commit.
+- Before entering Build (full: after the design guard; lightweight: merged into the `transition build --confirmed` pause), present the implementation-actor choice — continue with the current agent/model, switch the model in the user's client, or switch the implementation agent via `$matrix-handoff` — and record the decision with the Contract.
 - On shortcut scope expansion, run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap`; Runtime upgrades the change to `full`. Never silently continue the old contract.

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

@@ -44,9 +44,9 @@ node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard design
 
 ## Implementation Decision Point
 
-After the design guard passes, the user chooses:
+After the design guard passes and before `transition build`, pause and present the implementation-actor choice to the user. Do not transition without an explicit choice:
 
-### Option A: Continue with Codex (default)
+### Option A: Continue with the current agent / model (default)
 
 Run transition and enter `$matrix-build`:
 
@@ -56,14 +56,18 @@ node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build
 
 Then enter `$matrix-build` to implement directly in this session.
 
-### Option B: Use Claude Code for implementation
+### Option B: Switch the model, keep this agent
 
-First approve the frozen contract by transitioning to Build, then run `$matrix-claude` to export a bounded task package. This:
+The user switches the model in their own client (for example, a stronger model for design, an efficient one for implementation), returns to this session, and confirms. Then run transition exactly as in Option A. Matrix cannot see the client-side model; it provides the mandatory pause point only.
+
+### Option C: Switch the implementation agent
+
+First approve the frozen contract by transitioning to Build, then run `$matrix-handoff` to export a bounded task package for the chosen agent (for example Codex designs, Claude Code implements; or zcode designs, opencode implements). This:
 - Does not change the Build phase or state beyond the preceding transition
-- Creates `artifacts/claude-task.md` with all implementation details
+- Creates `artifacts/handoff-task-<task-id>.md` with all implementation details
 - Includes acceptance criteria, test seams, and required commands
 
-After Claude Code completes and returns results, run the Build guard and enter `$matrix-verify`:
+After the implementation agent completes and returns results, run the Build guard and enter `$matrix-verify`:
 
 ```powershell
 node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
@@ -71,3 +75,5 @@ node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
 ```
 
 Then enter `$matrix-verify` to verify the implementation.
+
+Record the chosen option in `design.md` under `## Decisions` so it freezes with the Contract.

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

@@ -0,0 +1,89 @@
+---
+name: matrix-handoff
+description: Export an approved Matrix Contract as a bounded task package for any implementation agent (Claude Code, opencode, or another agent), without changing Matrix workflow state.
+---
+
+# Matrix Handoff (Implementation Handoff)
+
+This is an optional Matrix sidecar, not a Matrix phase. It must not call `transition`, `archive`, or write `matrix.yaml` or `events.jsonl`. It supports only a matching full or legacy-full three-artifact Contract; new lightweight hotfix/tweak changes are intentionally unsupported.
+
+Human-readable handoff text uses `artifact_language` from inspect; stable machine-readable headings and metadata keys remain unchanged.
+
+## When to Use
+
+Use `$matrix-handoff` when:
+
+- The active change is in Build and the Design -> Build transition has approved the contract
+- You want a different agent than the designing one to implement the frozen plan — for example Codex designs and Claude Code implements, or zcode designs and opencode implements
+- You need a bounded task package with all implementation details
+
+## Preconditions
+
+The exporter performs this read-only check before writing anything:
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
+```
+
+If `matrix` is genuinely absent from PATH, use the bundled runtime from the installed root Matrix Skill. Do not fall back when the primary command starts and returns an error.
+
+If the build guard reports `CONTRACT_CHANGED` or `CONTRACT_UNAPPROVED`, return to `$matrix-design` and approve a new contract through Build. The exporter reads the approved bytes of `proposal.md`, `design.md`, and `plan.md`; it does not invent missing facts.
+
+## Export
+
+The user chooses the implementation agent explicitly. Pass it with `--agent <agent-id>` (kebab-case); optionally name the designing agent with `--from <agent-id>`.
+
+```powershell
+# Generic agent handoff: writes 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
+
+# Legacy compatibility form (Claude Code): writes artifacts/claude-task.md
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --target generic
+
+# FnSec: exports its formal task package. Add --apply-fnsec-board only when
+# active.md is NO_ACTIVE_OBJECTIVE; an existing task is never overwritten.
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --target fnsec --apply-fnsec-board
+```
+
+`--agent` and `--target` are mutually exclusive. Prefer `--agent` for new handoffs; `--target generic` remains for compatibility.
+
+## Task Package Contents
+
+The exported package (`artifacts/handoff-task-<task-id>.md`) metadata records `Implementation actor` (the `--agent` value) and `Decision owner` (the `--from` value, or "Matrix change owner"), plus the approved contract hash and revision and the same frozen snapshot of proposal, design, and plan. Objective, allowed work, prohibited work, and stop conditions travel unchanged — they are agent-independent.
+
+## After the Implementation Agent Completes
+
+Verify that the following evidence is present before proceeding to `$matrix-verify`:
+
+- [ ] `artifacts/verification.md` exists with a `## Build evidence` section
+- [ ] Build evidence includes concrete commands and outcomes
+- [ ] All tests in the plan's validation section have been run
+- [ ] Any `NEEDS_DECISION` items have been resolved or documented
+
+If evidence is missing, ask the implementation agent to complete it before proceeding.
+
+## Resuming Matrix Workflow
+
+After the implementation agent completes and evidence is present:
+
+1. Run build guard to verify evidence:
+   ```powershell
+   node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
+   ```
+
+2. If guard passes, transition to verify:
+   ```powershell
+   node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
+   ```
+
+3. Enter `$matrix-verify` to continue the verification flow
+
+If the build guard fails, return to the implementation agent to complete missing evidence.
+
+## Important Notes
+
+- This sidecar does NOT change Matrix phase, workflow, or guard result
+- The Matrix state remains in `build` phase; export itself does not advance it
+- The implementation agent must produce evidence that satisfies the build guard conditions
+- After successful transition to verify, the normal verify flow continues

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

@@ -16,11 +16,22 @@ Use its `artifact_language` for all proposal prose. Keep the required English he
 
 ## Prim
 
-Use Matrix's own capability to clarify the request and write the proposal.
+Use Matrix's own capability to run a structured clarification (goal, scope, non-goals, acceptance, risks, constraints) and write the proposal.
 
 ## Arch
 
-Invoke `grilling` only when material ambiguity remains or the user asks to stress-test the request. Invoke `domain-modeling` only when domain vocabulary, invariants, or an architectural decision is unclear. Announce the capability and reason before invoking it; selecting Arch already authorizes triggered capabilities.
+Announce the capability and reason, then invoke `grilling` by default at the start of Open to clarify the request. Invoke `domain-modeling` only when domain vocabulary, invariants, or an architectural decision is unclear. Selecting Arch already authorizes triggered capabilities.
+
+**Clarification exemption**: skip the clarification pass only when the user both (1) arrives with a clear execution plan and (2) explicitly states that no clarification is needed. Even then, write the exemption record into `clarification.md`.
+
+## Clarification artifact (mandatory)
+
+Before writing the proposal, produce `<change>/clarification.md` — on every path, clarification or exemption:
+
+- Clarified: `## Questions` / `## Answers` / `## Resolved scope` (English heading tokens fixed; body in `artifact_language`).
+- Exempted: `## Exemption record` (exemption reason + the user's plan highlights + how the proposal adopts it).
+
+lightweight (hotfix/tweak) applies too, with a single round of core questions. The file is Open-phase evidence: it does not participate in Contract identity and the Runtime does not check for it; changes left in open by 0.1.5 or earlier proceed without backfilling it.
 
 If progress is blocked by facts or decisions owned by another person, explain why `to-questionnaire` fits and ask the user to invoke it. Do not invoke the wrapper yourself.
 

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

@@ -1,83 +1,84 @@
----
-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
-```
-
-全局 `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 主流程。
-只有用户明确选择“Codex 设计、Claude Code 实现”时才使用，不得自动插入标准流程。
-
-## 显式 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。
+---
+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
+```
+
+全局 `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 后续漂移都会阻断推进。
+
+## 可选 agent 交接（Implementation Handoff）
+
+`$matrix-handoff` 只在已批准的 Build 中使用，通过 `export --agent <agent-id>` 将 Contract 快照导出为用户选择的实现 agent 的有界任务包（例如 Codex 设计、Claude Code 实现，或 zcode 设计、opencode 实现）。它不拥有阶段推进或验收；由当前 agent 继续实现仍使用原有 Matrix 主流程。
+只有用户明确选择切换实现 agent 时才使用，不得自动插入标准流程。
+
+## 显式 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 前应暂停等待用户确认。
+- 进入 Build 前（full 在 design guard 之后；lightweight 并入 `transition build --confirmed` 的暂停）必须呈现执行主体选择——当前 agent/原模型继续、用户客户端切换模型、或经 `$matrix-handoff` 切换实现 agent——并将决策随 Contract 记录。
+- shortcut 范围扩大时执行 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap`；Runtime 将其升级为 full。

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 自身能力调查并设计。
-- **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
-```
+---
+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
+```
+
+## 执行主体确认点（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 冻结。