@rosenfan/matrix 0.1.1 → 0.1.3

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

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

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

@@ -1,13 +1,39 @@
----
-name: matrix-build
-description: 用测试优先的纵向切片实现冻结的 Matrix 计划。
----
-
+---
+name: matrix-build
+description: 用测试优先的纵向切片实现冻结的 Matrix 计划。仅在活动 Matrix 阶段为 build 时使用。
+---
+
 # Matrix Build
 
-只实现冻结计划中的范围。使用 `implement` 与预先确认的 `tdd` 测试边界；持续记录 `artifacts/verification.md` 的 `## Build evidence`。如发现范围或设计变化，返回设计阶段。
+读取 `matrix workflow inspect` 与已批准 Contract。full/legacy-full 读取 proposal/design/plan；lightweight 只读取紧凑 proposal，不补写 Design 产物。
 
-```powershell
-matrix workflow guard build
-matrix workflow transition verify
-```
+Build 证据与面向用户的说明使用 `artifact_language`；Runtime 所需英文标题 token 保持不变。
+
+## 编排
+
+- **Prim**：使用 Matrix 自身实现与测试能力。
+- **Arch**：可测试行为变化时调用 `tdd`；真实失败且根因未知时调用 `diagnosing-bugs`；仅在进行中的 merge/rebase 冲突时调用 `resolving-merge-conflicts`。
+
+调用前说明能力与原因。companion 不得 commit、review、transition、archive 或扩大范围。正确安装的能力失败时最多执行一次同能力 Matrix fallback，并记录调用、失败、fallback 与证据；安装完整性问题必须停止并修复。
+
+## 范围纪律
+
+若实现暴露范围或设计变化，停止并执行：
+
+```powershell
+matrix workflow return design --reason design-gap
+```
+
+回到 Design 会清除既有 Contract 批准并轮换当前验证证据；重新进入 Build 必须生成新的批准与新证据。
+
+## 流程
+
+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
+```

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

@@ -1,30 +1,33 @@
----
-name: matrix-claude
-description: 将冻结的 Matrix 设计导出为受边界约束的 Claude Code 任务包，不改变 Matrix 工作流状态。
----
-
+---
+name: matrix-claude
+description: 将已批准的 Matrix Contract 导出为受边界约束的 Claude Code 任务包，不改变 Matrix 工作流状态。
+---
+
 # Matrix Claude Handoff
 
-这是可选的旁路操作，而不是 Matrix phase。它不得执行 `transition`、`archive`，也不得写入 `matrix.yaml`、`run-state.json` 或 `events.jsonl`。
-
-仅当设计阶段守卫已通过，并且用户明确选择由 Claude Code 实现时使用。先检查：
-
-```powershell
-matrix workflow guard design
-```
-
-如果主命令确实不在 PATH 中，才使用已安装根 Matrix Skill 中的 bundled runtime；主命令已启动但返回业务错误时不得回退。
-
-导出通用任务包：
-
-```powershell
-matrix workflow export --task-id <ID> --target generic
-```
-
-导出 FnSec 任务包时，只有在 `docs/tasks/active.md` 包含 `NO_ACTIVE_OBJECTIVE` 时才可使用 `--apply-fnsec-board`；现有任务绝不覆盖：
-
-```powershell
-matrix workflow export --task-id <ID> --target fnsec --apply-fnsec-board
-```
-
-任务包会包含冻结的 proposal、design、plan，以及 Claude Code 回执所需的改动、验证、边界确认和 `NEEDS_DECISION` 项目。
+这是可选旁路，不是 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
+```
+
+若结果为 `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
+
+# FnSec：仅在 active.md 含有 NO_ACTIVE_OBJECTIVE 时更新看板
+matrix workflow 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
+```

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

@@ -1,13 +1,22 @@
----
-name: matrix-design
-description: 在实现前设计并冻结活动 Matrix 变更。
----
-
+---
+name: matrix-design
+description: 在实现前设计并冻结活动 Matrix 变更。
+---
+
 # Matrix Design
 
-阅读 proposal，写入 `design.md`（`## Decisions`、`## Boundaries`、`## Test seams`、`## Risks`）与 `plan.md`（`## Steps`、`## Validation`、`## Stop conditions`）。重大范围或架构决策须先由用户确认。
+Design 只用于 full 和可恢复的旧 shortcut change。新的 lightweight hotfix/tweak 从 Open 直接进入 Build，不得为满足 full guard 补写 Design 产物。
+
+design 和 plan 正文使用 `matrix workflow inspect` 的 `artifact_language`；Runtime 所需英文标题 token 保持不变。
 
-```powershell
-matrix workflow guard design
-matrix workflow transition build
-```
+读取 `matrix workflow 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`，不得机械执行固定序列。每次调用前说明能力与原因。
+
+长期有效的领域、ADR 或研究产物遵循仓库约定，关键结论必须同步进入 Matrix design/plan。prototype 默认写入系统临时目录。companion 不得拥有 Matrix 状态或创建竞争计划。重大范围或架构决策须先由用户确认。
+
+```powershell
+matrix workflow guard design
+matrix workflow transition build
+```

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

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

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

@@ -1,13 +1,28 @@
----
-name: matrix-open
-description: 将开发请求澄清为有证据的 Matrix 提案。
----
-
+---
+name: matrix-open
+description: 将开发请求澄清为有证据的 Matrix 提案。
+---
+
 # Matrix Open
 
-读取 `matrix workflow inspect` 的活动变更。使用 `grill-with-docs` 澄清完整工作流请求；写入 `artifacts/proposal.md`，必须包含 `## Goal`、`## Scope`、`## Non-goals`、`## Acceptance`、`## Risks`。
+读取 `matrix workflow inspect` 返回的 `profile` 与 `evidence_policy`。
+
+proposal 正文使用其中的 `artifact_language`；Runtime 所需的英文标题 token 必须原样保留，仅标题下内容本地化。
 
-```powershell
+- 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`。调用前说明能力与原因。
+
+companion 输出只能作为当前 proposal 的证据，不得创建第二套工作流、提案、确认状态或阶段转换。正确安装的能力失败时最多执行一次同能力 Matrix fallback；安装完整性问题必须修复。
+
+```powershell
 matrix workflow guard open
+# full
 matrix workflow transition design
+# hotfix/tweak，仅在用户明确确认后
+matrix workflow transition build --confirmed
 ```

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

@@ -1,14 +1,15 @@
----
-name: matrix-status
-description: 检查活动 Matrix 工作流的磁盘状态、守卫与恢复命令。
----
-
-# Matrix Status
-
-执行：
-
-```powershell
-matrix workflow inspect
-```
-
-报告变更 ID、工作流、阶段、守卫结果和 `next_skill`；不得修改状态。
+---
+name: matrix-status
+description: 检查活动 Matrix 工作流的磁盘状态、守卫与恢复命令。
+---
+
+# Matrix Status
+
+执行：
+
+```powershell
+matrix workflow inspect
+matrix workflow doctor
+```
+
+报告变更 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

@@ -1,8 +1,8 @@
----
-name: matrix-tweak
-description: 为边界清晰的小改动运行轻量 Matrix 工作流。
----
-
-# Matrix Tweak
-
-从 `$matrix` 以 `tweak` 工作流启动。保持提案和设计简洁，但仍定义验收条件与测试边界。若涉及 API、模式、架构或跨模块协调，升级为完整工作流。
+---
+name: matrix-tweak
+description: 为边界清晰的小改动运行轻量 Matrix 工作流。
+---
+
+# Matrix Tweak
+
+从 `$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

@@ -1,13 +1,29 @@
----
-name: matrix-verify
-description: 依据计划验证 Matrix 变更并审查差异。
----
-
+---
+name: matrix-verify
+description: 依据计划验证 Matrix 变更并审查差异。
+---
+
 # Matrix Verify
 
-运行计划的验证命令，在 `verification.md` 写入 `## Test evidence`。使用 `code-review` 完成标准与规格双轴审查，并在 `## Review evidence` 记录结论。失败时回到产生问题的阶段。
+运行已批准 Contract 的验证命令，在 `verification.md` 写入 `## Test evidence`。hotfix 另写 `## Regression evidence`；tweak 另写 `## Scope review evidence`。读取冻结 `orchestration`：
 
-```powershell
-matrix workflow guard verify
-matrix workflow transition archive
-```
+验证正文使用 `artifact_language`；上述 Runtime 所需英文证据标题保持不变。
+
+- **Prim**：Matrix 自行完成 Standards 与 Spec 双轴审查。
+- **Arch**：调用 `code-review` 产生双轴证据，并说明调用原因。
+
+审查结果只是 Matrix Verify 的输入；companion 不得决定阶段结果、扩大已批准架构、推进或归档。不得调用事后架构改进 wrapper。正确安装的审查能力失败时最多执行一次同能力 Matrix fallback；安装完整性问题必须停止。
+
+失败时使用受控 Return：
+
+```powershell
+matrix workflow return build --reason verification-failed
+matrix workflow return design --reason acceptance-or-design-gap
+```
+
+Return 会轮换旧 `verification.md`；不得把旧结论直接复制为新的当前证据。
+
+```powershell
+matrix workflow guard verify
+matrix workflow 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,56 +1,56 @@
-{
-  "name": "@rosenfan/matrix",
-  "version": "0.1.1",
-  "description": "Install and manage the Matrix workflow for Matt Pocock's agent skills.",
-  "license": "MIT",
-  "type": "module",
-  "bin": {
-    "matrix": "bin/matrix.js"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "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",
-    "README.md",
-    "README.zh-CN.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "test": "node --test",
-    "pack:check": "npm pack --dry-run",
-    "prepublishOnly": "npm run test && npm run pack:check"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Rosenfan/Matrix.git"
-  },
-  "bugs": {
-    "url": "https://github.com/Rosenfan/Matrix/issues"
-  },
-  "homepage": "https://github.com/Rosenfan/Matrix#readme",
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "claude-code",
-    "agent-skills",
-    "workflow",
-    "tdd",
-    "ai"
-  ]
-}
+{
+  "name": "@rosenfan/matrix",
+  "version": "0.1.3",
+  "description": "Evidence-driven development workflow with Prim and Arch agent-skill orchestration.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "matrix": "bin/matrix.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "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",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm run test && npm run pack:check"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rosenfan/Matrix.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Rosenfan/Matrix/issues"
+  },
+  "homepage": "https://github.com/Rosenfan/Matrix#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "claude-code",
+    "agent-skills",
+    "workflow",
+    "tdd",
+    "ai"
+  ]
+}