@rosenfan/matrix 0.1.4 → 0.1.5

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

@@ -1,73 +1,73 @@
----
-name: matrix-design
-description: Design and freeze the active Matrix change before implementation. Use when the active Matrix phase is design or when build scope requires redesign.
----
-
-# Matrix Design
-
-Design is used by `full` and resumable legacy shortcut changes only. A new lightweight hotfix/tweak moves directly from Open to Build and must not create Design artifacts merely to satisfy the full guard.
-
-Use `artifact_language` from `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` for all design and plan prose. Keep Runtime-required English heading tokens unchanged.
-
-Run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect`, read the active proposal and frozen `orchestration`, then write `artifacts/design.md` with `## Decisions`, `## Boundaries`, `## Test seams`, and `## Risks`; write `artifacts/plan.md` with `## Steps`, `## Validation`, and `## Stop conditions`.
-
-## Prim
-
-Use Matrix's own capability to investigate the repository and design the change.
-
-## Arch
-
-Invoke only capabilities whose task-fact trigger is proven:
-
+---
+name: matrix-design
+description: Design and freeze the active Matrix change before implementation. Use when the active Matrix phase is design or when build scope requires redesign.
+---
+
+# Matrix Design
+
+Design is used by `full` and resumable legacy shortcut changes only. A new lightweight hotfix/tweak moves directly from Open to Build and must not create Design artifacts merely to satisfy the full guard.
+
+Use `artifact_language` from `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` for all design and plan prose. Keep Runtime-required English heading tokens unchanged.
+
+Run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect`, read the active proposal and frozen `orchestration`, then write `artifacts/design.md` with `## Decisions`, `## Boundaries`, `## Test seams`, and `## Risks`; write `artifacts/plan.md` with `## Steps`, `## Validation`, and `## Stop conditions`.
+
+## Prim
+
+Use Matrix's own capability to investigate the repository and design the change.
+
+## Arch
+
+Invoke only capabilities whose task-fact trigger is proven:
+
 - `domain-modeling` for unclear vocabulary, invariants, or architectural decisions;
 - `research` when required external facts cannot be established from the repository;
 - `prototype` when a material design decision needs disposable empirical evidence;
 - `codebase-design` when a deep-module, interface, or test-seam decision remains;
 - `writing-for-agents` when the Contract creates or changes Skills, `AGENTS.md`, `CLAUDE.md`, or documents reached through agent pointers.
-
-Order follows actual dependencies; never run a fixed companion sequence. Announce each invocation and reason. A correctly installed capability gets at most one same-capability Matrix fallback; installation-integrity failure stops the phase.
-
+
+Order follows actual dependencies; never run a fixed companion sequence. Announce each invocation and reason. A correctly installed capability gets at most one same-capability Matrix fallback; installation-integrity failure stops the phase.
+
 Long-lived domain, ADR, or research artifacts follow repository conventions, and material conclusions must be synchronized into the canonical design or plan. Prototypes default to an OS temporary directory unless the approved design promotes a project path. Companion output cannot own Matrix state or create a competing plan.
 
 `wayfinder` and `improve-codebase-architecture` are explicit handoffs outside the active Design. Recommend one only when its purpose fits, then let the user invoke it; a selected result may enter a separate governed Change.
-
-## Process
-
-1. Establish repository facts and resolve only triggered design questions.
-2. Write and synchronize the canonical Matrix design and plan.
-3. Confirm material architecture choices with the user before freezing.
-4. Run the guard, then choose the implementation actor.
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard design
-```
-
-## Implementation Decision Point
-
-After the design guard passes, the user chooses:
-
-### Option A: Continue with Codex (default)
-
-Run transition and enter `$matrix-build`:
-
-```powershell
-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
-
-First approve the frozen contract by transitioning to Build, then run `$matrix-claude` to export a bounded task package. This:
-- Does not change the Build phase or state beyond the preceding transition
-- Creates `artifacts/claude-task.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`:
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
-```
-
-Then enter `$matrix-verify` to verify the implementation.
+
+## Process
+
+1. Establish repository facts and resolve only triggered design questions.
+2. Write and synchronize the canonical Matrix design and plan.
+3. Confirm material architecture choices with the user before freezing.
+4. Run the guard, then choose the implementation actor.
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard design
+```
+
+## Implementation Decision Point
+
+After the design guard passes, the user chooses:
+
+### Option A: Continue with Codex (default)
+
+Run transition and enter `$matrix-build`:
+
+```powershell
+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
+
+First approve the frozen contract by transitioning to Build, then run `$matrix-claude` to export a bounded task package. This:
+- Does not change the Build phase or state beyond the preceding transition
+- Creates `artifacts/claude-task.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`:
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
+```
+
+Then enter `$matrix-verify` to verify the implementation.

package/{.claude → assets}/skills/matrix-design/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-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,42 @@
----
-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
-
+---
+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.
 
 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

@@ -9,13 +9,13 @@ description: 启动、恢复并治理持久化的 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 入口。
+所有 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：
 
@@ -28,7 +28,7 @@ node <matrix-skill-directory>/scripts/matrix-runtime.mjs init <change-id> --work
 ## 编排模式
 
 - **Prim**：各阶段使用 Matrix 自身能力，不依赖 Matt Skills。
-- **Arch**：仅在任务事实满足触发条件时，调用活动 Change 冻结的十项自动能力。Matrix 0.1.4 审查 Matt Skills v1.2.3 官方 25 项角色，只把其中 23 项兼容 Skill 安装在项目本地；排除 `implement` 与 raw `resolving-merge-conflicts`。
+- **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 状态、推进阶段、提交、归档或创建竞争工作流。
 
@@ -64,14 +64,14 @@ node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor --repair --lock
 
 full 的 `design -> build` 会批准 proposal/design/plan；lightweight 的 `open -> build --confirmed` 只批准紧凑 proposal，并拒绝初始化后、批准前发生的项目实现改动。Contract 后续漂移都会阻断推进。
 
-## 可选 Claude 交接
+## 可选 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 内不得建议使用。
+只有用户明确选择“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 内不得建议使用。
 
 ## 规则
 

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`。

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

@@ -12,11 +12,11 @@ design 和 plan 正文使用 `node <matrix-skill-directory>/scripts/matrix-runti
 读取 `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`。不得机械执行固定序列；每次调用前说明能力与原因。
+- **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。
+长期有效的领域、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

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

@@ -15,9 +15,9 @@ proposal 正文使用其中的 `artifact_language`；Runtime 所需的英文标
 - tweak 额外包含 `## Current behavior`、`## Preserved behavior`、`## Diff boundary`。
 
 - **Prim**：使用 Matrix 自身能力澄清并编写提案。
-- **Arch**：仅在存在重大歧义或用户要求压力测试时调用 `grilling`；仅在领域词汇、不变量或架构决定不清晰时调用 `domain-modeling`。调用前说明能力与原因。
-
-若进展被另一人掌握的事实或决定阻塞，说明 `to-questionnaire` 适用的原因并让用户显式调用；Matrix 不得自行嵌套该 wrapper。
+- **Arch**：仅在存在重大歧义或用户要求压力测试时调用 `grilling`；仅在领域词汇、不变量或架构决定不清晰时调用 `domain-modeling`。调用前说明能力与原因。
+
+若进展被另一人掌握的事实或决定阻塞，说明 `to-questionnaire` 适用的原因并让用户显式调用；Matrix 不得自行嵌套该 wrapper。
 
 companion 输出只能作为当前 proposal 的证据，不得创建第二套工作流、提案、确认状态或阶段转换。正确安装的能力失败时最多执行一次同能力 Matrix fallback；安装完整性问题必须修复。