@rosenfan/matrix 0.1.4 → 0.1.6

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/{.claude/skills/matrix-claude → assets/skills/matrix-handoff}/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "Matrix Claude Handoff"
-  short_description: "Export frozen Matrix design as a Claude Code task"
-  default_prompt: "Use $matrix-claude to prepare a Claude Code task package."
+interface:
+  display_name: "Matrix Claude Handoff"
+  short_description: "Export frozen Matrix design as a Claude Code task"
+  default_prompt: "Use $matrix-claude to prepare a Claude Code task package."

package/{.claude → assets}/skills/matrix-hotfix/SKILL.md

@@ -1,8 +1,8 @@
----
-name: matrix-hotfix
-description: Run a constrained Matrix workflow for a reproducible small bug. Use for a bug fix that has no material architecture, API, schema, or multi-module coordination impact.
----
-
-# Matrix Hotfix
-
-Start through `$matrix` with workflow `hotfix`. It uses the shared lightweight lifecycle `open → build → verify → archive`; there is no separate hotfix state machine. Before Build, record expected/actual behavior and a reproducible failure signal, present the compact Contract, and wait for confirmation. Build records reproduction and root-cause evidence; Verify records regression evidence. If the bug requires architecture, public API, schema, or broad coordination, use controlled Return to upgrade the change to full.
+---
+name: matrix-hotfix
+description: Run a constrained Matrix workflow for a reproducible small bug. Use for a bug fix that has no material architecture, API, schema, or multi-module coordination impact.
+---
+
+# Matrix Hotfix
+
+Start through `$matrix` with workflow `hotfix`. It uses the shared lightweight lifecycle `open → build → verify → archive`; there is no separate hotfix state machine. Before Build, record expected/actual behavior and a reproducible failure signal, present the compact Contract, and wait for confirmation. Build records reproduction and root-cause evidence; Verify records regression evidence. If the bug requires architecture, public API, schema, or broad coordination, use controlled Return to upgrade the change to full.

package/{.claude/skills/matrix-build → assets/skills/matrix-hotfix}/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "Matrix Workflow"
-  short_description: "Persistent development workflow stage"
-  default_prompt: "Use $name to continue a Matrix development workflow."
+interface:
+  display_name: "Matrix Workflow"
+  short_description: "Persistent development workflow stage"
+  default_prompt: "Use $name to continue a Matrix development workflow."

package/{.claude → assets}/skills/matrix-open/SKILL.md

@@ -1,42 +1,53 @@
----
-name: matrix-open
-description: Open or resume the Matrix open phase by clarifying a development request into an evidence-backed proposal. Use after $matrix initializes a change or when the active Matrix phase is open.
----
-
-# Matrix Open
-
-Run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` and follow its `profile` and `evidence_policy`.
-
-Use its `artifact_language` for all proposal prose. Keep the required English heading tokens exactly as specified for Runtime guards; only the text beneath them is localized.
-
-- **full**: produce `proposal.md` with `## Goal`, `## Scope`, `## Non-goals`, `## Acceptance`, and `## Risks`, then continue to Design.
-- **lightweight**: produce the complete compact Contract before editing project implementation. Include `## Goal`, `## Scope`, `## Non-goals`, `## Approach`, `## Acceptance`, `## Validation`, `## Risks`, and `## Upgrade conditions`.
-- **hotfix evidence**: also include `## Expected behavior`, `## Actual behavior`, and `## Reproduction`.
-- **tweak evidence**: also include `## Current behavior`, `## Preserved behavior`, and `## Diff boundary`.
-
-## Prim
-
-Use Matrix's own capability to clarify the request 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.
+---
+name: matrix-open
+description: Open or resume the Matrix open phase by clarifying a development request into an evidence-backed proposal. Use after $matrix initializes a change or when the active Matrix phase is open.
+---
+
+# Matrix Open
+
+Run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` and follow its `profile` and `evidence_policy`.
+
+Use its `artifact_language` for all proposal prose. Keep the required English heading tokens exactly as specified for Runtime guards; only the text beneath them is localized.
+
+- **full**: produce `proposal.md` with `## Goal`, `## Scope`, `## Non-goals`, `## Acceptance`, and `## Risks`, then continue to Design.
+- **lightweight**: produce the complete compact Contract before editing project implementation. Include `## Goal`, `## Scope`, `## Non-goals`, `## Approach`, `## Acceptance`, `## Validation`, `## Risks`, and `## Upgrade conditions`.
+- **hotfix evidence**: also include `## Expected behavior`, `## Actual behavior`, and `## Reproduction`.
+- **tweak evidence**: also include `## Current behavior`, `## Preserved behavior`, and `## Diff boundary`.
+
+## Prim
+
+Use Matrix's own capability to run a structured clarification (goal, scope, non-goals, acceptance, risks, constraints) and write the proposal.
+
+## Arch
+
+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.
-
-Companion output is evidence for the Matrix proposal. It must not create another workflow, proposal, confirmation state, or phase transition. If a correctly installed capability fails, perform at most one Matrix-owned fallback for that same capability and record the failure and evidence. Installation-integrity failures require `matrix init --with-mattpocock` and are not eligible for fallback.
-
-## Process
-
-1. Resolve only ambiguities required by the active workflow.
-2. Write the canonical proposal and synchronize material companion conclusions into it.
-3. For full, ask for confirmation when scope or risk is material, then enter Design.
-4. For lightweight, always present the compact Contract and wait for explicit confirmation before entering Build.
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard open
-# full
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition design
-# hotfix/tweak, only after explicit confirmation
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build --confirmed
-```
+
+Companion output is evidence for the Matrix proposal. It must not create another workflow, proposal, confirmation state, or phase transition. If a correctly installed capability fails, perform at most one Matrix-owned fallback for that same capability and record the failure and evidence. Installation-integrity failures require `matrix init --with-mattpocock` and are not eligible for fallback.
+
+## Process
+
+1. Resolve only ambiguities required by the active workflow.
+2. Write the canonical proposal and synchronize material companion conclusions into it.
+3. For full, ask for confirmation when scope or risk is material, then enter Design.
+4. For lightweight, always present the compact Contract and wait for explicit confirmation before entering Build.
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard open
+# full
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition design
+# hotfix/tweak, only after explicit confirmation
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build --confirmed
+```

package/assets/skills/matrix-open/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Matrix Workflow"
+  short_description: "Persistent development workflow stage"
+  default_prompt: "Use $name to continue a Matrix development workflow."

package/{.claude → assets}/skills/matrix-status/SKILL.md

@@ -1,15 +1,15 @@
----
-name: matrix-status
-description: Inspect the active Matrix workflow and report its disk-backed phase, guard result, and recovery command. Use when the user asks for Matrix status, next step, or to resume interrupted Matrix work.
----
-
-# Matrix Status
-
-Run the same Matrix state kernel used by the main entry and every phase Skill:
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor
-```
-
-Report the returned change id, workflow, `profile`, `evidence_policy`, frozen `orchestration`, phase, guard result, `next_skill`, Workflow health, unfinished transactions, available strategies, and exact recovery commands. If Arch integrity fails, identify the affected platform/Skill facts and report `matrix init --with-mattpocock`; do not reinterpret the change as Prim. Both commands are read-only. Do not infer status from conversation history, run `--repair`, or modify state. If the guard is failing, name the missing evidence and direct the user to the current phase Skill.
+---
+name: matrix-status
+description: Inspect the active Matrix workflow and report its disk-backed phase, guard result, and recovery command. Use when the user asks for Matrix status, next step, or to resume interrupted Matrix work.
+---
+
+# Matrix Status
+
+Run the same Matrix state kernel used by the main entry and every phase Skill:
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor
+```
+
+Report the returned change id, workflow, `profile`, `evidence_policy`, frozen `orchestration`, phase, guard result, `next_skill`, Workflow health, unfinished transactions, available strategies, and exact recovery commands. If Arch integrity fails, identify the affected platform/Skill facts and report `matrix init --with-mattpocock`; do not reinterpret the change as Prim. Both commands are read-only. Do not infer status from conversation history, run `--repair`, or modify state. If the guard is failing, name the missing evidence and direct the user to the current phase Skill.

package/{.claude → assets}/skills/matrix-status/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "Matrix Status"
-  short_description: "Inspect and recover active Matrix workflow state"
-  default_prompt: "Use $matrix-status to inspect the active Matrix workflow."
+interface:
+  display_name: "Matrix Status"
+  short_description: "Inspect and recover active Matrix workflow state"
+  default_prompt: "Use $matrix-status to inspect the active Matrix workflow."

package/{.claude → assets}/skills/matrix-tweak/SKILL.md

@@ -1,8 +1,8 @@
----
-name: matrix-tweak
-description: Run a lightweight Matrix workflow for a bounded small development change. Use for a small request with no schema, public API, architecture, or cross-module coordination impact.
----
-
-# Matrix Tweak
-
-Start through `$matrix` with workflow `tweak`. It uses the shared lightweight lifecycle `open → build → verify → archive`; there is no separate tweak state machine or Design phase. Before editing implementation, define current/preserved behavior, the diff boundary, acceptance, and validation in the compact proposal, present it, and wait for confirmation. Build and Verify must prove scope and diff alignment. Use controlled Return to upgrade to full when the change crosses module, API, schema, or architecture boundaries.
+---
+name: matrix-tweak
+description: Run a lightweight Matrix workflow for a bounded small development change. Use for a small request with no schema, public API, architecture, or cross-module coordination impact.
+---
+
+# Matrix Tweak
+
+Start through `$matrix` with workflow `tweak`. It uses the shared lightweight lifecycle `open → build → verify → archive`; there is no separate tweak state machine or Design phase. Before editing implementation, define current/preserved behavior, the diff boundary, acceptance, and validation in the compact proposal, present it, and wait for confirmation. Build and Verify must prove scope and diff alignment. Use controlled Return to upgrade to full when the change crosses module, API, schema, or architecture boundaries.

package/assets/skills/matrix-tweak/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Matrix Workflow"
+  short_description: "Persistent development workflow stage"
+  default_prompt: "Use $name to continue a Matrix development workflow."

package/{.claude → assets}/skills/matrix-verify/SKILL.md

@@ -1,38 +1,38 @@
----
-name: matrix-verify
-description: Verify the active Matrix change against its plan and review its diff. Use when the active Matrix phase is verify.
----
-
-# Matrix Verify
-
-Run the approved Contract's acceptance commands and record their output summaries under `## Test evidence` in `artifacts/verification.md`.
-
-Write verification prose in `artifact_language` from inspect while preserving the required English evidence headings.
-
-## Input Sources
-
-This phase can receive implementation from two sources:
-
-1. **Direct Codex implementation** — from `$matrix-build` phase
-2. **Claude Code implementation** — from `$matrix-claude` sidecar
-
-Regardless of source, the verification process is the same: check that implementation evidence meets the plan's requirements.
-
-## Prerequisites
-
-Before starting verification, ensure:
-
-- [ ] `artifacts/verification.md` exists
-- [ ] `## Build evidence` section is present and substantive
-- [ ] All commands from the plan's `## Validation` section have been run
-- [ ] Test results are recorded
-
-If these are missing (e.g., Claude Code didn't produce complete evidence), return to `$matrix-build` or ask Claude Code to补充.
-
-## Orchestration
-
-Run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` and read the frozen mode.
-
+---
+name: matrix-verify
+description: Verify the active Matrix change against its plan and review its diff. Use when the active Matrix phase is verify.
+---
+
+# Matrix Verify
+
+Run the approved Contract's acceptance commands and record their output summaries under `## Test evidence` in `artifacts/verification.md`.
+
+Write verification prose in `artifact_language` from inspect while preserving the required English evidence headings.
+
+## Input Sources
+
+This phase can receive implementation from two sources:
+
+1. **Direct Codex implementation** — from `$matrix-build` phase
+2. **Claude Code implementation** — from `$matrix-claude` sidecar
+
+Regardless of source, the verification process is the same: check that implementation evidence meets the plan's requirements.
+
+## Prerequisites
+
+Before starting verification, ensure:
+
+- [ ] `artifacts/verification.md` exists
+- [ ] `## Build evidence` section is present and substantive
+- [ ] All commands from the plan's `## Validation` section have been run
+- [ ] Test results are recorded
+
+If these are missing (e.g., Claude Code didn't produce complete evidence), return to `$matrix-build` or ask Claude Code to补充.
+
+## Orchestration
+
+Run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` and read the frozen mode.
+
 - **Prim**: Matrix performs the Standards and Spec review itself.
 - **Arch**: invoke `code-review` to produce both review axes; announce the invocation and reason.
 
@@ -51,39 +51,39 @@ node <matrix-skill-directory>/scripts/matrix-runtime.mjs review --source matrix-
 ```
 
 Never label fallback output as a successful `code-review` run. `empty-head-diff` requires the fixed point so Runtime can verify the empty three-dot diff. `uncommitted-worktree` requires a fixed point and Runtime binds the staged, unstaged, and untracked candidate content into `candidate_hash`; any later change makes the receipt stale. If a receipt already exists or either axis failed, use a controlled Return before another attempt.
-
-## Failure Handling
-
-If verification or review fails:
-- If the issue is in the implementation, run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return build --reason verification-failed`, then enter `$matrix-build` or ask Claude Code to fix.
-- If the issue is in the acceptance criteria or design, run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason acceptance-or-design-gap`, then enter `$matrix-design`.
-
+
+## Failure Handling
+
+If verification or review fails:
+- If the issue is in the implementation, run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return build --reason verification-failed`, then enter `$matrix-build` or ask Claude Code to fix.
+- If the issue is in the acceptance criteria or design, run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason acceptance-or-design-gap`, then enter `$matrix-design`.
+
 Both Return paths rotate the current `verification.md` and any `review-receipt.json` into revisioned evidence history. Do not copy stale conclusions or receipts back into the new current evidence.
-
-If documents or public behavior changed, record the required synchronization work before the guard.
-
-## Process
-
-1. Check that `artifacts/verification.md` exists with `## Build evidence`
-2. Run the approved validation commands (full plan or lightweight proposal)
+
+If documents or public behavior changed, record the required synchronization work before the guard.
+
+## Process
+
+1. Check that `artifacts/verification.md` exists with `## Build evidence`
+2. Run the approved validation commands (full plan or lightweight proposal)
 3. Record test output under `## Test evidence`
 4. Produce both Standards and Spec review axes through the selected orchestration mode
 5. Record findings under `## Review evidence` with `### Standards` and `### Spec`
 6. In Arch, record the Runtime review receipt for the current revision
 7. Run the guard
 8. If it passes, transition to archive and enter `$matrix-archive`
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard verify
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition archive
-```
-
-## Evidence Requirements
-
-The guard checks for:
-
-1. **Test evidence** — Output from running the plan's validation commands
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard verify
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition archive
+```
+
+## Evidence Requirements
+
+The guard checks for:
+
+1. **Test evidence** — Output from running the plan's validation commands
 2. **Review evidence** — Separate Standards and Spec findings from the selected review path
 3. **Arch review receipt** — Runtime-bound identity for the current Contract, evidence, workspace, and normal or fallback source
-
-Full requires Test and Review evidence. Hotfix additionally requires `## Regression evidence`; tweak additionally requires `## Scope review evidence`.
+
+Full requires Test and Review evidence. Hotfix additionally requires `## Regression evidence`; tweak additionally requires `## Scope review evidence`.

package/assets/skills/matrix-verify/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Matrix Workflow"
+  short_description: "Persistent development workflow stage"
+  default_prompt: "Use $name to continue a Matrix development workflow."

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

@@ -1,14 +1,14 @@
----
-name: matrix
-description: 启动、恢复并治理持久化的 Matrix 开发工作流。
----
-
-# Matrix
-
-以当前仓库的 `.matrix/` 为唯一状态来源；不得从聊天记录推断阶段。
-
-读取 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` 的 `artifact_language`。规范 Markdown 标题 token 必须保持不变；面向用户的产物正文、说明和 handoff 在 `zh-CN` 时写中文，在 `en` 时写英文。
-
+---
+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
@@ -16,68 +16,69 @@ 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。
+
+有活动变更时，报告其 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 实现”时才使用，不得自动插入标准流程。
+
+两种编排模式使用已选定的 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 前应暂停等待用户确认。
-- shortcut 范围扩大时执行 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap`；Runtime 将其升级为 full。
+
+## 规则
+
+- 阶段只能经 `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-build/SKILL.md

@@ -12,9 +12,9 @@ Build 证据与面向用户的说明使用 `artifact_language`；Runtime 所需
 ## 编排
 
 - **Prim**：使用 Matrix 自身实现与测试能力。
-- **Arch**：可测试行为变化时调用 `tdd`；真实失败且根因未知时调用 `diagnosing-bugs`；批准 Contract 修改 agent-facing 指令时调用 `writing-for-agents`；只有 Contract 需要人工执行 shell 步骤时，才用 `wizard` 生成并静态验证脚本，绝不端到端执行或收集秘密。
-
-进行中的 merge/rebase 冲突由 Matrix 自身治理，不调用会 stage、continue 或 commit 的 raw `resolving-merge-conflicts`。活动 Change 内不得调用 `implement`。
+- **Arch**：可测试行为变化时调用 `tdd`；真实失败且根因未知时调用 `diagnosing-bugs`；批准 Contract 修改 agent-facing 指令时调用 `writing-for-agents`；只有 Contract 需要人工执行 shell 步骤时，才用 `wizard` 生成并静态验证脚本，绝不端到端执行或收集秘密。
+
+进行中的 merge/rebase 冲突由 Matrix 自身治理，不调用会 stage、continue 或 commit 的 raw `resolving-merge-conflicts`。活动 Change 内不得调用 `implement`。
 
 调用前说明能力与原因。companion 不得 commit、review、transition、archive 或扩大范围。正确安装的能力失败时最多执行一次同能力 Matrix fallback，并记录调用、失败、fallback 与证据；安装完整性问题必须停止并修复。
 
@@ -30,7 +30,7 @@ node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason
 
 ## 流程
 
-1. 对可测试的行为变化使用 `tdd` 纵向切片；纯文档或不可观察的机械变更使用相称的静态检查。
+1. 对可测试的行为变化使用 `tdd` 纵向切片；纯文档或不可观察的机械变更使用相称的静态检查。
 2. 在 `## Build evidence` 记录共同事实；hotfix 另写 `## Reproduction evidence`、`## Root cause`，tweak 另写 `## Scope evidence`。
 3. 运行 Build guard；它同时确认批准的 Contract 仍精确匹配。
 4. 通过后推进至 Verify，并进入 `$matrix-verify`。