@rosenfan/matrix 0.1.3 → 0.1.5

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Rosen
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Rosen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -40,14 +40,14 @@ Matrix solves this with one deterministic state machine, explicit phases, guard
 
 ## What It Does
 
-Matrix provides two capability-orchestration modes over two centrally defined workflow profiles:
-
-```
-full:                    open → design → build → verify → archive
-hotfix/tweak lightweight: open ─────────→ build → verify → archive
-
-Prim: Matrix performs phase work itself
-Arch: Matrix invokes verified atomic Skills only when task facts trigger them
+Matrix provides two capability-orchestration modes over two centrally defined workflow profiles:
+
+```
+full:                    open → design → build → verify → archive
+hotfix/tweak lightweight: open ─────────→ build → verify → archive
+
+Prim: Matrix performs phase work itself
+Arch: Matrix invokes verified atomic Skills only when task facts trigger them
 ```
 
 Recovery paths are controlled Runtime intents:
@@ -69,10 +69,10 @@ Each phase:
 
 ## Prerequisites
 
-- [Claude Code](https://docs.anthropic.com/claude-code) and/or Codex installed as the Skill host
-- Node.js 18+ and `npm` on `PATH` (for the Matrix CLI)
-- Python is optional during the compatibility window; new installations use the bundled Node workflow runtime.
-- Git is only needed when installing from GitHub or contributing to Matrix.
+- [Claude Code](https://docs.anthropic.com/claude-code) and/or Codex installed as the Skill host
+- Node.js 18+ and `npm` on `PATH` (for the Matrix CLI)
+- Python is optional during the compatibility window; new installations use the bundled Node workflow runtime.
+- Git is only needed when installing from GitHub or contributing to Matrix.
 
 ---
 
@@ -91,15 +91,15 @@ cd /path/to/your/project
 matrix init
 ```
 
-The interactive setup lets you:
+The interactive setup lets you:
 
-- Choose English or Chinese, project or global scope, and Claude Code, Codex, or both
+- Choose English or Chinese, project or global Matrix discovery scope, and Claude Code, Codex, or both
 - Copy skills (recommended) or symlink them for local development
-- Safely reconfigure an existing installation with an automatic backup
-- Install Matt Pocock's companion skills in the same flow
+- Safely reconfigure an existing installation with an automatic backup
+- Review all 25 official Matt Skills v1.2.3 roles and install the 23 compatible Skills into the target project
 - Choose **Prim** or **Arch** as the project default without disabling the other available mode
 
-For automation and CI:
+For automation and CI:
 
 ```bash
 # Safe non-interactive installation for both verified platforms
@@ -108,31 +108,36 @@ matrix init --yes --platform claude-code --platform codex --with-mattpocock
 # Explicitly select the project default
 matrix init --yes --with-mattpocock --default-orchestration arch
 
+# Replace locally modified Matt Skills only after an explicit backup authorization
+matrix init --yes --with-mattpocock --force-matt
+
 # Preview exactly what would change (including backups) without writing
 matrix init --platform codex --dry-run --json
 
-# Inspect Matrix ownership, Matt Skills inheritance, and the selected platform
-matrix doctor --platform codex
-```
-
-Update an initialized project:
-
-```bash
-# Check for a newer Matrix CLI, confirm the plan, then refresh this project's installed assets
-matrix update
-
-# Offline or local-development refresh: skip the npm registry and use the current CLI package
-matrix update --skip-self-update
-
-# Non-interactive update after CI has explicitly authorized writes
-matrix update --yes
-```
-
-`matrix update` preserves the installation's scope, platforms, language, mode, and orchestration. It first validates a newer npm package in isolation, then re-runs the new CLI to refresh project assets. npm and project assets are separate transactions: if asset refresh fails after a CLI upgrade, run `matrix update --skip-self-update` to retry. Use `matrix init` to change installation choices, and `matrix doctor` for read-only diagnosis.
-
-The language selected by `matrix init` controls the prose in new Matrix artifacts. Markdown headings required by Matrix guards remain stable English tokens; the artifact body is Chinese for `zh-CN` and English for `en`. A change freezes this language at creation time.
-
-To install directly from GitHub instead of npm:
+# Inspect Matrix ownership, project-local Matt compatibility, and the selected platform
+matrix doctor --platform codex
+```
+
+Update an initialized project:
+
+```bash
+# Check for a newer Matrix CLI, confirm the plan, then refresh this project's installed assets
+matrix update
+
+# Offline or local-development refresh: skip the npm registry and use the current CLI package
+matrix update --skip-self-update
+
+# Non-interactive update after CI has explicitly authorized writes
+matrix update --yes
+```
+
+`matrix update` preserves the installation's scope, platforms, language, mode, and orchestration. It first validates a newer npm package in isolation, then re-runs the new CLI to refresh Matrix assets. It never downloads, installs, repairs, or deletes Matt Skills; after the Matrix update it reports the local Matt compatibility status and, when needed, points to `matrix init . --with-mattpocock`. npm and project assets are separate transactions: if asset refresh fails after a CLI upgrade, run `matrix update --skip-self-update` to retry.
+
+Matrix 0.1.5 is bound to Matt Skills v1.2.3 at commit `6acc160e4e0cd062dbbbd7a1b26ae92855edf07e`. `matrix init --with-mattpocock` always uses that exact archive and its reviewed 23-Skill compatible manifest, even if upstream has a newer release. The two official but incompatible Skills, `implement` and raw `resolving-merge-conflicts`, are not Matrix-managed or installed. Matrix scope controls Matrix Skill discovery only: Matt Skills and `.matrix/matt-installation.json` are always project-local. Global Matt copies are preserved but never used to complete project readiness.
+
+The language selected by `matrix init` controls the prose in new Matrix artifacts. Markdown headings required by Matrix guards remain stable English tokens; the artifact body is Chinese for `zh-CN` and English for `en`. A change freezes this language at creation time.
+
+To install directly from GitHub instead of npm:
 
 ```bash
 npm install --global github:Rosenfan/Matrix
@@ -174,9 +179,9 @@ Matrix will:
 | Phase | Arch capabilities (triggered, not a fixed sequence) | Deliverables | Guard Condition |
 |-------|------------------------------------------------------|--------------|-----------------|
 | **open** | `/grilling`, `/domain-modeling` | `proposal.md`; optional repository-standard context/ADR evidence | Goal, Scope, Non-goals, Acceptance, Risks present |
-| **design** | `/domain-modeling`, `/research`, `/wayfinder`, `/prototype`, `/codebase-design` | `design.md`, `plan.md` | Decisions, Test seams, Steps documented |
-| **build** | `/tdd`, `/diagnosing-bugs`, `/resolving-merge-conflicts` | Code, `verification.md` | Exact approved Contract matches; build evidence recorded |
-| **verify** | `/code-review` | Test & review evidence | Test and review evidence present |
+| **design** | `/domain-modeling`, `/research`, `/prototype`, `/codebase-design`, conditional `/writing-for-agents` | `design.md`, `plan.md` | Decisions, Test seams, Steps documented |
+| **build** | `/tdd`, `/diagnosing-bugs`, conditional `/writing-for-agents` and generate-only `/wizard` | Code, `verification.md` | Exact approved Contract matches; build evidence recorded |
+| **verify** | `/code-review` | Test evidence, two-axis review, Arch receipt | Evidence is substantive; Arch receipt matches the current Contract, review, and workspace |
 | **archive** | None; Matrix-owned in both modes | Archive record | Verify guard passed |
 
 ---
@@ -191,9 +196,9 @@ State is stored in `.matrix/`:
 ├── config.yaml
 ├── changes/
 │   └── <change-id>/
-│       ├── matrix.yaml      # Canonical workflow, orchestration, phase, status, revision
-│       ├── workspace-baseline.json # Lightweight implementation-order boundary
-│       ├── events.jsonl
+│       ├── matrix.yaml      # Canonical workflow, orchestration, phase, status, revision
+│       ├── workspace-baseline.json # Lightweight implementation-order boundary
+│       ├── events.jsonl
 │       └── artifacts/
 │           ├── proposal.md
 │           ├── design.md
@@ -209,12 +214,12 @@ The state machine enforces transitions:
 # Check guard
 matrix workflow guard open
 
-# Advance (only if guard passes)
-matrix workflow transition design
-
-# Lightweight: approve the compact proposal and enter Build
-matrix workflow transition build --confirmed
-
+# Advance (only if guard passes)
+matrix workflow transition design
+
+# Lightweight: approve the compact proposal and enter Build
+matrix workflow transition build --confirmed
+
 # Return from verification failure; stale evidence is retained in history
 matrix workflow return build --reason verification-failed
 
@@ -223,8 +228,8 @@ matrix workflow abort --reason requirement-cancelled
 
 # Final Archive is a mandatory two-step optimistic commit
 matrix workflow archive --dry-run
-matrix workflow archive --expect-preflight <sha256-returned-by-dry-run>
-# hotfix/tweak commit command additionally carries --confirmed
+matrix workflow archive --expect-preflight <sha256-returned-by-dry-run>
+# hotfix/tweak commit command additionally carries --confirmed
 
 # Diagnose an interrupted Workflow without writing
 matrix workflow doctor
@@ -234,7 +239,7 @@ matrix workflow doctor --repair --transaction <id> --strategy <continue|rollback
 matrix workflow doctor --repair --lock <id>
 ```
 
-`matrix.yaml` is the only canonical workflow/orchestration/phase/status/revision record, using `matrix/change/v2`. Full approval binds the exact bytes of proposal/design/plan. Lightweight approval binds the compact proposal, requires explicit confirmation, and compares the project with its initialization baseline so implementation cannot precede approval. Contract drift blocks later phases. Final Archive uses a read-only dry-run and hash-bound commit; shortcut workflows additionally require explicit confirmation. Multi-file mutations remain protected by durable journals.
+`matrix.yaml` is the only canonical workflow/orchestration/phase/status/revision record, using `matrix/change/v2`. Full approval binds the exact bytes of proposal/design/plan. Lightweight approval binds the compact proposal, requires explicit confirmation, and compares the project with its initialization baseline so implementation cannot precede approval. Contract drift blocks later phases. Final Archive uses a read-only dry-run and hash-bound commit; shortcut workflows additionally require explicit confirmation. Multi-file mutations remain protected by durable journals.
 
 ---
 
@@ -244,10 +249,10 @@ matrix workflow doctor --repair --lock <id>
 |------|-------------|--------|
 | **full** | New features, architecture changes | All 5 phases |
 | **hotfix** | Reproducible small bugs | Simplified: open → build → verify → archive |
-| **tweak** | Bounded changes, no API/schema impact | Simplified: open → build → verify → archive |
-
-Hotfix and tweak reference the same internal `lightweight` transition profile. They differ only in routing and evidence: hotfix requires reproduction/root-cause/regression evidence; tweak requires behavior-boundary, diff, and scope-review evidence.
-
+| **tweak** | Bounded changes, no API/schema impact | Simplified: open → build → verify → archive |
+
+Hotfix and tweak reference the same internal `lightweight` transition profile. They differ only in routing and evidence: hotfix requires reproduction/root-cause/regression evidence; tweak requires behavior-boundary, diff, and scope-review evidence.
+
 ---
 
 ## Special Feature: matrix-claude
@@ -280,28 +285,32 @@ The sidecar does NOT change Matrix state. It's a pure export — like taking a s
 
 ## Integration with Matt Pocock's Skills
 
-Prim uses Matrix's own capability. Arch uses one initialization-verified cohort of ten atomic capabilities:
+Prim uses Matrix's own capability. Matrix reviews all 25 official Matt v1.2.3 roles, installs the 23 compatible Skills, and lets Arch automatically invoke only this reviewed ten-capability cohort:
 
 | Phase | Capability | Trigger |
 |---|---|---|
 | open | `/grilling` | Material ambiguity or explicit stress-test request |
 | open/design | `/domain-modeling` | Unclear vocabulary, invariants, or architectural decisions |
 | design | `/research` | Required external facts are unavailable in the repository |
-| design | `/wayfinder` | Module ownership or dependency seams are unknown |
 | design | `/prototype` | A material design question needs disposable evidence |
 | design | `/codebase-design` | A deep-module, interface, or test-seam decision remains |
+| design/build | `/writing-for-agents` | The Contract changes agent-facing instructions or pointer-reached documents |
 | build | `/tdd` | Observable behavior changes at a testable seam |
 | build | `/diagnosing-bugs` | An actual failure exists and root cause is unknown |
-| build | `/resolving-merge-conflicts` | A merge or rebase conflict is in progress |
+| build | `/wizard` | The Contract requires generated human-run shell steps; Matrix never runs them end-to-end |
 | verify | `/code-review` | Standards and Spec review evidence is required |
 
-`grill-with-docs`, `implement`, and `improve-codebase-architecture` are not Matrix-managed or automatically invoked. Existing user-installed copies are preserved as unmanaged extras. A companion never transitions, commits, archives, or writes Matrix state.
+Matrix may recommend but never nest these user-invoked handoffs: `setup-matt-pocock-skills`, `improve-codebase-architecture`, `wayfinder`, `handoff`, and `to-questionnaire`. The user explicitly runs them outside the active phase; selected output may enter a governed Change.
+
+Arch records a Runtime-managed review receipt after `code-review`, binding its fixed point and committed HEAD diff to the current Contract, review evidence, and workspace. A normal `code-review` receipt requires a clean candidate worktree outside Matrix-managed assets. When Git has no usable baseline, the committed diff is empty, staged/unstaged/untracked candidate files still exist, or the correctly installed capability fails, Matrix may perform one explicitly labelled same-capability fallback for that revision. The `uncommitted-worktree` fallback binds both the fixed point and a content hash of the complete worktree candidate. Installation-integrity failures never fall back. A heading or self-description without the matching receipt cannot advance Verify.
+
+Installed standalone Skills are `ask-matt`, `grill-with-docs`, `triage`, `to-spec`, `to-tickets`, `grill-me`, `teach`, and `wait-what`. `implement` and raw `resolving-merge-conflicts` are incompatible because they can take over TDD/review/staging/commit effects owned by Matrix, so 0.1.5 neither installs nor manages them. Pre-existing copies are preserved and reported as unmanaged extras. Installation never grants automatic invocation, and no companion may transition, commit, archive, recover, or write Matrix state.
 
 ---
 
 **Key difference**: Matt Pocock's skills are individual tools. Matrix adds:
 - **State persistence**: Survives context loss
-- **Phase enforcement**: Full cannot skip Design; lightweight cannot edit implementation before its confirmed Open Contract
+- **Phase enforcement**: Full cannot skip Design; lightweight cannot edit implementation before its confirmed Open Contract
 - **Evidence requirements**: Guards check for artifacts, not assertions
 - **Transition logging**: Full audit trail of phase changes
 

package/README.zh-CN.md

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