@rosenfan/matrix 0.1.3 → 0.1.5

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

@@ -0,0 +1,89 @@
+---
+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.
+
+Review findings are inputs to Matrix Verify; a companion cannot decide the phase outcome, broaden approved architecture, transition, or archive. Do not invoke post-review architecture wrappers. A correctly installed review capability gets at most one same-capability Matrix fallback; installation-integrity failure stops verification.
+
+Under `## Review evidence`, preserve two substantive subsections named `### Standards` and `### Spec`. Arch must then ask the project Runtime to bind those results to the current revision:
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs review --source code-review --fixed-point <ref> --standards <passed|failed> --spec <passed|failed>
+```
+
+If `code-review` cannot run because the Git baseline is unavailable, the committed HEAD diff is empty, staged/unstaged/untracked candidate files exist, or the capability actually fails, document that limitation and use the single bounded fallback for this revision:
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs review --source matrix-fallback --reason <git-baseline-unavailable|empty-head-diff|uncommitted-worktree|capability-execution-failed> [--fixed-point <ref-for-empty-head-diff-or-uncommitted-worktree>] --standards <passed|failed> --spec <passed|failed>
+```
+
+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`.
+
+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)
+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
+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`.

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

@@ -3,28 +3,24 @@ name: matrix
 description: 启动、恢复并治理持久化的 Matrix 开发工作流。
 ---
 
-# Matrix
-
-以当前仓库的 `.matrix/` 为唯一状态来源；不得从聊天记录推断阶段。
-
-读取 `matrix workflow inspect` 的 `artifact_language`。规范 Markdown 标题 token 必须保持不变；面向用户的产物正文、说明和 handoff 在 `zh-CN` 时写中文，在 `en` 时写英文。
+# Matrix
 
-先执行：
+以当前仓库的 `.matrix/` 为唯一状态来源；不得从聊天记录推断阶段。
 
-```powershell
-matrix workflow inspect
-```
+读取 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` 的 `artifact_language`。规范 Markdown 标题 token 必须保持不变；面向用户的产物正文、说明和 handoff 在 `zh-CN` 时写中文，在 `en` 时写英文。
 
-只有系统明确报告 `matrix` 命令不存在时，才使用当前 Matrix Skill 目录中的 bundled runtime：
+所有 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
-matrix workflow init <change-id> --workflow <full|hotfix|tweak> --orchestration <prim|arch> --title "<title>"
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs init <change-id> --workflow <full|hotfix|tweak> --orchestration <prim|arch> --title "<title>"
 ```
 
 显式模式优先，否则使用项目 `default_orchestration`。解析后的模式在整个 change 生命周期中不可切换。
@@ -32,9 +28,9 @@ matrix workflow init <change-id> --workflow <full|hotfix|tweak> --orchestration
 ## 编排模式
 
 - **Prim**：各阶段使用 Matrix 自身能力，不依赖 Matt Skills。
-- **Arch**：仅在任务事实满足触发条件时，调用初始化阶段已验证的十项原子能力。
+- **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 状态、推进阶段、提交、归档或创建竞争工作流。
+两种编排模式使用已选定的 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。
 
@@ -43,10 +39,10 @@ matrix workflow init <change-id> --workflow <full|hotfix|tweak> --orchestration
 只能通过 Runtime 恢复，不得手工修改状态：
 
 ```powershell
-matrix workflow return design --reason design-gap
-matrix workflow return build --reason verification-failed
-matrix workflow return design --reason acceptance-or-design-gap
-matrix workflow abort --reason <requirement-cancelled|superseded|no-longer-valuable|blocked|other>
+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/`，但不会撤销工作区代码。
@@ -54,30 +50,34 @@ Return 会把当前 `verification.md` 轮换至按 revision 编号的证据历
 任何 mutation 返回 `WORKFLOW_RECOVERY_REQUIRED` 时，停止正常阶段操作并先执行只读诊断：
 
 ```powershell
-matrix workflow doctor
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor
 ```
 
 不得推断恢复目标或策略，只能执行 doctor 返回的精确命令：
 
 ```powershell
-matrix workflow doctor --repair --transaction <id> --strategy <continue|rollback>
-matrix workflow doctor --repair --lock <id>
+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 后续漂移都会阻断推进。
+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 内不得建议使用。
+
 ## 规则
 
-- 阶段只能经 `matrix workflow transition` 正向推进。
-- 只能经上述明确的 `matrix workflow return` 反向推进。
-- 成功 Archive 必须使用两步乐观提交：先运行 `matrix workflow archive --dry-run`，再将其精确 hash 传给 `matrix workflow archive --expect-preflight <sha256>`；不得绕过预演。
-- `matrix workflow doctor` 始终只读；transaction 与陈旧锁 repair 必须显式绑定 doctor 报告的 identity，不得手工编辑或删除 `.matrix/transactions/`、`.matrix/workflow.lock`。
-- 重大架构/范围决定和 archive/commit 前应暂停等待用户确认。
-- shortcut 范围扩大时执行 `matrix workflow 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 前应暂停等待用户确认。
+- shortcut 范围扩大时执行 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap`；Runtime 将其升级为 full。

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

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

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

@@ -3,16 +3,18 @@ name: matrix-build
 description: 用测试优先的纵向切片实现冻结的 Matrix 计划。仅在活动 Matrix 阶段为 build 时使用。
 ---
 
-# Matrix Build
-
-读取 `matrix workflow inspect` 与已批准 Contract。full/legacy-full 读取 proposal/design/plan；lightweight 只读取紧凑 proposal，不补写 Design 产物。
-
-Build 证据与面向用户的说明使用 `artifact_language`；Runtime 所需英文标题 token 保持不变。
+# Matrix Build
+
+读取 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` 与已批准 Contract。full/legacy-full 读取 proposal/design/plan；lightweight 只读取紧凑 proposal，不补写 Design 产物。
+
+Build 证据与面向用户的说明使用 `artifact_language`；Runtime 所需英文标题 token 保持不变。
 
 ## 编排
 
 - **Prim**：使用 Matrix 自身实现与测试能力。
-- **Arch**：可测试行为变化时调用 `tdd`；真实失败且根因未知时调用 `diagnosing-bugs`；仅在进行中的 merge/rebase 冲突时调用 `resolving-merge-conflicts`。
+- **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 与证据；安装完整性问题必须停止并修复。
 
@@ -21,19 +23,19 @@ Build 证据与面向用户的说明使用 `artifact_language`；Runtime 所需
 若实现暴露范围或设计变化，停止并执行：
 
 ```powershell
-matrix workflow return design --reason design-gap
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap
 ```
 
 回到 Design 会清除既有 Contract 批准并轮换当前验证证据；重新进入 Build 必须生成新的批准与新证据。
 
 ## 流程
 
-1. 用 `tdd` 以纵向切片实现。
-2. 在 `## Build evidence` 记录共同事实；hotfix 另写 `## Reproduction evidence`、`## Root cause`，tweak 另写 `## Scope evidence`。
+1. 对可测试的行为变化使用 `tdd` 纵向切片；纯文档或不可观察的机械变更使用相称的静态检查。
+2. 在 `## Build evidence` 记录共同事实；hotfix 另写 `## Reproduction evidence`、`## Root cause`，tweak 另写 `## Scope evidence`。
 3. 运行 Build guard；它同时确认批准的 Contract 仍精确匹配。
 4. 通过后推进至 Verify，并进入 `$matrix-verify`。
 
 ```powershell
-matrix workflow guard build
-matrix workflow transition verify
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
 ```

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

@@ -3,31 +3,31 @@ name: matrix-claude
 description: 将已批准的 Matrix Contract 导出为受边界约束的 Claude Code 任务包，不改变 Matrix 工作流状态。
 ---
 
-# Matrix Claude Handoff
-
-这是可选旁路，不是 Matrix phase。它不得执行 `transition`、`archive`，也不得写入 `matrix.yaml` 或 `events.jsonl`。它只支持匹配的 full 或 legacy-full 三产物 Contract；新的 lightweight hotfix/tweak 不支持导出。
-
-人类可读 handoff 内容使用 inspect 的 `artifact_language`；稳定的机器可读标题和 metadata key 保持不变。
+# Matrix Claude Handoff
+
+这是可选旁路，不是 Matrix phase。它不得执行 `transition`、`archive`，也不得写入 `matrix.yaml` 或 `events.jsonl`。它只支持匹配的 full 或 legacy-full 三产物 Contract；新的 lightweight hotfix/tweak 不支持导出。
+
+人类可读 handoff 内容使用 inspect 的 `artifact_language`；稳定的机器可读标题和 metadata key 保持不变。
 
 仅当变更已进入 Build、`design -> build` 已批准精确 Contract，并且用户明确选择 Claude Code 实现时使用。先检查：
 
 ```powershell
-matrix workflow guard build
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
 ```
 
 若结果为 `CONTRACT_CHANGED`、`CONTRACT_UNAPPROVED` 或 `CONTRACT_READ_FAILED`，回到 `$matrix-design`，修订后重新进入 Build 取得新批准。导出只读取批准快照中的 `proposal.md`、`design.md` 与 `plan.md`。
 
 ```powershell
 # 通用项目：只导出 Matrix 产物
-matrix workflow export --task-id <ID> --target generic
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --target generic
 
 # FnSec：仅在 active.md 含有 NO_ACTIVE_OBJECTIVE 时更新看板
-matrix workflow export --task-id <ID> --target fnsec --apply-fnsec-board
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --target fnsec --apply-fnsec-board
 ```
 
 任务包包含批准的 Contract hash 与 revision，以及同一快照的 proposal、design、plan。导出本身不改变 Build 阶段；Claude 完成后，补齐 `## Build evidence`，然后继续：
 
 ```powershell
-matrix workflow guard build
-matrix workflow transition verify
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
 ```

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

@@ -3,20 +3,22 @@ name: matrix-design
 description: 在实现前设计并冻结活动 Matrix 变更。
 ---
 
-# Matrix Design
-
-Design 只用于 full 和可恢复的旧 shortcut change。新的 lightweight hotfix/tweak 从 Open 直接进入 Build，不得为满足 full guard 补写 Design 产物。
-
-design 和 plan 正文使用 `matrix workflow inspect` 的 `artifact_language`；Runtime 所需英文标题 token 保持不变。
-
-读取 `matrix workflow inspect`、proposal 与冻结 `orchestration`，写入 `design.md`（`## Decisions`、`## Boundaries`、`## Test seams`、`## Risks`）与 `plan.md`（`## Steps`、`## Validation`、`## Stop conditions`）。
+# 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`、`wayfinder`、`prototype`、`codebase-design`，不得机械执行固定序列。每次调用前说明能力与原因。
+- **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
-matrix workflow guard design
-matrix workflow transition build
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard design
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build
 ```

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

@@ -5,4 +5,4 @@ description: 为可复现的小型缺陷运行受约束的 Matrix 工作流。
 
 # Matrix Hotfix
 
-从 `$matrix` 以 `hotfix` 启动，共用 `open → build → verify → archive` lightweight 生命周期，不维护独立 hotfix 状态机。Build 前记录预期/实际行为和可复现失败信号，展示紧凑 Contract 并等待确认；Build 记录复现与根因，Verify 记录回归证据。若影响架构、公开 API、数据模式或多模块协调，受控 Return 后升级为 full。
+从 `$matrix` 以 `hotfix` 启动，共用 `open → build → verify → archive` lightweight 生命周期，不维护独立 hotfix 状态机。Build 前记录预期/实际行为和可复现失败信号，展示紧凑 Contract 并等待确认；Build 记录复现与根因，Verify 记录回归证据。若影响架构、公开 API、数据模式或多模块协调，受控 Return 后升级为 full。

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

@@ -3,26 +3,28 @@ name: matrix-open
 description: 将开发请求澄清为有证据的 Matrix 提案。
 ---
 
-# Matrix Open
-
-读取 `matrix workflow inspect` 返回的 `profile` 与 `evidence_policy`。
-
-proposal 正文使用其中的 `artifact_language`；Runtime 所需的英文标题 token 必须原样保留，仅标题下内容本地化。
-
-- full proposal 包含 `## Goal`、`## Scope`、`## Non-goals`、`## Acceptance`、`## Risks`，随后进入 Design。
-- lightweight proposal 在修改项目实现前完整定义 `## Goal`、`## Scope`、`## Non-goals`、`## Approach`、`## Acceptance`、`## Validation`、`## Risks`、`## Upgrade conditions`。
-- hotfix 额外包含 `## Expected behavior`、`## Actual behavior`、`## Reproduction`。
-- tweak 额外包含 `## Current behavior`、`## Preserved behavior`、`## Diff boundary`。
+# Matrix Open
+
+读取 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` 返回的 `profile` 与 `evidence_policy`。
+
+proposal 正文使用其中的 `artifact_language`；Runtime 所需的英文标题 token 必须原样保留，仅标题下内容本地化。
+
+- full proposal 包含 `## Goal`、`## Scope`、`## Non-goals`、`## Acceptance`、`## Risks`，随后进入 Design。
+- lightweight proposal 在修改项目实现前完整定义 `## Goal`、`## Scope`、`## Non-goals`、`## Approach`、`## Acceptance`、`## Validation`、`## Risks`、`## Upgrade conditions`。
+- hotfix 额外包含 `## Expected behavior`、`## Actual behavior`、`## Reproduction`。
+- tweak 额外包含 `## Current behavior`、`## Preserved behavior`、`## Diff boundary`。
 
 - **Prim**：使用 Matrix 自身能力澄清并编写提案。
 - **Arch**：仅在存在重大歧义或用户要求压力测试时调用 `grilling`；仅在领域词汇、不变量或架构决定不清晰时调用 `domain-modeling`。调用前说明能力与原因。
 
+若进展被另一人掌握的事实或决定阻塞，说明 `to-questionnaire` 适用的原因并让用户显式调用；Matrix 不得自行嵌套该 wrapper。
+
 companion 输出只能作为当前 proposal 的证据，不得创建第二套工作流、提案、确认状态或阶段转换。正确安装的能力失败时最多执行一次同能力 Matrix fallback；安装完整性问题必须修复。
 
 ```powershell
-matrix workflow guard open
-# full
-matrix workflow transition design
-# hotfix/tweak，仅在用户明确确认后
-matrix workflow transition build --confirmed
-```
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard open
+# full
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition design
+# hotfix/tweak，仅在用户明确确认后
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build --confirmed
+```

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

@@ -8,8 +8,8 @@ description: 检查活动 Matrix 工作流的磁盘状态、守卫与恢复命
 执行：
 
 ```powershell
-matrix workflow inspect
-matrix workflow doctor
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor
 ```
 
-报告变更 ID、工作流、`profile`、`evidence_policy`、冻结 `orchestration`、阶段、守卫结果、`next_skill`、Workflow health、未完成 transaction、可用策略和精确恢复命令。Arch 完整性失败时列出平台/Skill 事实并报告 `matrix init --with-mattpocock`，不得把 change 解释为 Prim。两条命令都只读；不得推断恢复策略、运行 `--repair` 或修改状态。
+报告变更 ID、工作流、`profile`、`evidence_policy`、冻结 `orchestration`、阶段、守卫结果、`next_skill`、Workflow health、未完成 transaction、可用策略和精确恢复命令。Arch 完整性失败时列出平台/Skill 事实并报告 `matrix init --with-mattpocock`，不得把 change 解释为 Prim。两条命令都只读；不得推断恢复策略、运行 `--repair` 或修改状态。

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

@@ -5,4 +5,4 @@ description: 为边界清晰的小改动运行轻量 Matrix 工作流。
 
 # Matrix Tweak
 
-从 `$matrix` 以 `tweak` 启动，共用 `open → build → verify → archive` lightweight 生命周期，不维护独立 tweak 状态机或 Design 阶段。修改实现前，在紧凑 proposal 中定义当前/保留行为、diff 边界、验收与验证，展示后等待确认；Build 与 Verify 必须证明范围和 diff 一致。若涉及 API、模式、架构或跨模块协调，受控 Return 后升级为 full。
+从 `$matrix` 以 `tweak` 启动，共用 `open → build → verify → archive` lightweight 生命周期，不维护独立 tweak 状态机或 Design 阶段。修改实现前，在紧凑 proposal 中定义当前/保留行为、diff 边界、验收与验证，展示后等待确认；Build 与 Verify 必须证明范围和 diff 一致。若涉及 API、模式、架构或跨模块协调，受控 Return 后升级为 full。

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

@@ -3,27 +3,43 @@ name: matrix-verify
 description: 依据计划验证 Matrix 变更并审查差异。
 ---
 
-# Matrix Verify
-
-运行已批准 Contract 的验证命令，在 `verification.md` 写入 `## Test evidence`。hotfix 另写 `## Regression evidence`；tweak 另写 `## Scope review evidence`。读取冻结 `orchestration`：
-
-验证正文使用 `artifact_language`；上述 Runtime 所需英文证据标题保持不变。
+# Matrix Verify
+
+运行已批准 Contract 的验证命令，在 `verification.md` 写入 `## Test evidence`。hotfix 另写 `## Regression evidence`；tweak 另写 `## Scope review evidence`。所有模式都必须写入 `## Review evidence`，并在其中保留内容充分的 `### Standards` 与 `### Spec` 两个子节。读取冻结 `orchestration`：
+
+验证正文使用 `artifact_language`；上述 Runtime 所需英文证据标题保持不变。
 
 - **Prim**：Matrix 自行完成 Standards 与 Spec 双轴审查。
 - **Arch**：调用 `code-review` 产生双轴证据，并说明调用原因。
 
 审查结果只是 Matrix Verify 的输入；companion 不得决定阶段结果、扩大已批准架构、推进或归档。不得调用事后架构改进 wrapper。正确安装的审查能力失败时最多执行一次同能力 Matrix fallback；安装完整性问题必须停止。
 
+Arch 正常执行 `code-review` 后，使用项目 Runtime 把 fixed point、HEAD/diff、Contract、审查正文和工作区绑定为当前 revision 的回执：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs review --source code-review --fixed-point <ref> --standards <passed|failed> --spec <passed|failed>
+```
+
+只有在无 Git 基线、已提交的 HEAD diff 为空、仍存在 staged/unstaged/untracked 候选，或 capability 真实执行失败时，才记录限制并使用一次有界 fallback：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs review --source matrix-fallback --reason <git-baseline-unavailable|empty-head-diff|uncommitted-worktree|capability-execution-failed> [--fixed-point <ref-for-empty-head-diff-or-uncommitted-worktree>] --standards <passed|failed> --spec <passed|failed>
+```
+
+不得把 fallback 写成 `code-review` 成功。`empty-head-diff` 必须提供 fixed point，由 Runtime 核实三点 diff 确实为空。`uncommitted-worktree` 也必须提供 fixed point，Runtime 会把 staged、unstaged 与 untracked 候选内容绑定为 `candidate_hash`，之后任意变化都会使回执过期。当前 revision 已有回执或任一审查轴失败时，必须先受控 Return，不能覆盖回执后继续。
+
 失败时使用受控 Return：
 
 ```powershell
-matrix workflow return build --reason verification-failed
-matrix workflow return design --reason acceptance-or-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
 ```
 
 Return 会轮换旧 `verification.md`；不得把旧结论直接复制为新的当前证据。
 
+Arch 的 Return 也会轮换 `review-receipt.json`；新 revision 必须重新审查并生成新回执。仅有 Markdown 标题、旧回执或与当前工作区不匹配的回执都不能通过 guard。
+
 ```powershell
-matrix workflow guard verify
-matrix workflow transition archive
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard verify
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition archive
 ```

package/bin/matrix.js

@@ -1,15 +1,15 @@
-#!/usr/bin/env node
-
-import { main } from "../src/cli.js";
-
-main(process.argv.slice(2)).then((exitCode) => {
-  if (Number.isInteger(exitCode) && exitCode !== 0) process.exitCode = exitCode;
-}).catch((error) => {
-  if (error.code === "CANCELLED") {
-    console.log("\nCancelled.");
-    process.exitCode = 0;
-  } else {
-    console.error(`\nMatrix error: ${error.message}`);
-    process.exitCode = 1;
-  }
-});
+#!/usr/bin/env node
+
+import { main } from "../src/cli.js";
+
+main(process.argv.slice(2)).then((exitCode) => {
+  if (Number.isInteger(exitCode) && exitCode !== 0) process.exitCode = exitCode;
+}).catch((error) => {
+  if (error.code === "CANCELLED") {
+    console.log("\nCancelled.");
+    process.exitCode = 0;
+  } else {
+    console.error(`\nMatrix error: ${error.message}`);
+    process.exitCode = 1;
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rosenfan/matrix",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Evidence-driven development workflow with Prim and Arch agent-skill orchestration.",
   "license": "MIT",
   "type": "module",
@@ -10,19 +10,10 @@
   "files": [
     "bin/",
     "src/",
+    "assets/skills",
     "assets/skills-zh-CN",
-    ".claude/skills/matrix",
-    ".claude/skills/matrix-open",
-    ".claude/skills/matrix-design",
-    ".claude/skills/matrix-build",
-    ".claude/skills/matrix-verify",
-    ".claude/skills/matrix-archive",
-    ".claude/skills/matrix-hotfix",
-    ".claude/skills/matrix-tweak",
-    ".claude/skills/matrix-status",
-    ".claude/skills/matrix-claude",
-    "!.claude/skills/**/__pycache__",
-    "!.claude/skills/**/scripts/test_*.py",
+    "!assets/skills/**/__pycache__",
+    "!assets/skills-zh-CN/**/__pycache__",
     "README.md",
     "README.zh-CN.md",
     "LICENSE"