@rosenfan/matrix 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +41 -40
  3. package/README.zh-CN.md +39 -38
  4. package/{.claude → assets}/skills/matrix/SKILL.md +79 -78
  5. package/{.claude → assets}/skills/matrix/agents/openai.yaml +4 -4
  6. package/{.claude → assets}/skills/matrix/scripts/matrix_claude.py +11 -11
  7. package/{.claude → assets}/skills/matrix/scripts/matrix_state.py +49 -49
  8. package/assets/skills/matrix/scripts/test_matrix_claude.py +69 -0
  9. package/assets/skills/matrix/scripts/test_matrix_state.py +69 -0
  10. package/{.claude → assets}/skills/matrix-archive/SKILL.md +36 -36
  11. package/{.claude/skills/matrix-hotfix → assets/skills/matrix-archive}/agents/openai.yaml +4 -4
  12. package/{.claude → assets}/skills/matrix-build/SKILL.md +41 -41
  13. package/{.claude/skills/matrix-archive → assets/skills/matrix-build}/agents/openai.yaml +4 -4
  14. package/{.claude → assets}/skills/matrix-design/SKILL.md +71 -65
  15. package/{.claude → assets}/skills/matrix-design/agents/openai.yaml +4 -4
  16. package/assets/skills/matrix-handoff/SKILL.md +89 -0
  17. package/{.claude/skills/matrix-claude → assets/skills/matrix-handoff}/agents/openai.yaml +4 -4
  18. package/{.claude → assets}/skills/matrix-hotfix/SKILL.md +8 -8
  19. package/{.claude/skills/matrix-build → assets/skills/matrix-hotfix}/agents/openai.yaml +4 -4
  20. package/{.claude → assets}/skills/matrix-open/SKILL.md +51 -40
  21. package/assets/skills/matrix-open/agents/openai.yaml +4 -0
  22. package/{.claude → assets}/skills/matrix-status/SKILL.md +15 -15
  23. package/{.claude → assets}/skills/matrix-status/agents/openai.yaml +4 -4
  24. package/{.claude → assets}/skills/matrix-tweak/SKILL.md +8 -8
  25. package/assets/skills/matrix-tweak/agents/openai.yaml +4 -0
  26. package/{.claude → assets}/skills/matrix-verify/SKILL.md +62 -62
  27. package/assets/skills/matrix-verify/agents/openai.yaml +4 -0
  28. package/assets/skills-zh-CN/matrix/SKILL.md +72 -71
  29. package/assets/skills-zh-CN/matrix-build/SKILL.md +4 -4
  30. package/assets/skills-zh-CN/matrix-design/SKILL.md +37 -20
  31. package/assets/skills-zh-CN/matrix-handoff/SKILL.md +79 -0
  32. package/assets/skills-zh-CN/matrix-open/SKILL.md +38 -28
  33. package/assets/skills-zh-CN/matrix-verify/SKILL.md +19 -19
  34. package/bin/matrix.js +15 -15
  35. package/package.json +4 -13
  36. package/src/catalog.js +79 -72
  37. package/src/cli.js +211 -141
  38. package/src/distribution.js +182 -179
  39. package/src/installer.js +10 -10
  40. package/src/matt-catalog.mjs +1 -1
  41. package/src/matt.js +9 -14
  42. package/src/messages.js +32 -23
  43. package/src/npm-invocation.js +23 -0
  44. package/src/project-index.js +43 -0
  45. package/src/runtime-resolver.js +76 -76
  46. package/src/self-update.js +88 -81
  47. package/src/ui.js +97 -89
  48. package/src/workflow-transaction.js +13 -13
  49. package/src/workflow.js +734 -705
  50. package/.claude/skills/matrix-claude/SKILL.md +0 -98
  51. package/.claude/skills/matrix-open/agents/openai.yaml +0 -4
  52. package/.claude/skills/matrix-tweak/agents/openai.yaml +0 -4
  53. package/.claude/skills/matrix-verify/agents/openai.yaml +0 -4
  54. package/assets/skills-zh-CN/matrix-claude/SKILL.md +0 -33
@@ -1,98 +0,0 @@
1
- ---
2
- name: matrix-claude
3
- description: Export a frozen Matrix design as a bounded Claude Code task package without changing Matrix workflow state. Use when Codex should design and Claude Code should implement.
4
- ---
5
-
6
- # Matrix Claude Handoff
7
-
8
- This is an optional Matrix sidecar, not a Matrix phase. It must not call `transition`, `archive`, or write `matrix.yaml` or `events.jsonl`. It supports only a matching full or legacy-full three-artifact Contract; new lightweight hotfix/tweak changes are intentionally unsupported.
9
-
10
- Use `artifact_language` from inspect for human-readable handoff text while retaining the stable machine-readable headings and metadata keys.
11
-
12
- ## When to Use
13
-
14
- Use `$matrix-claude` when:
15
- - The active change is in Build and the Design -> Build transition has approved the contract
16
- - You want Claude Code (instead of Codex) to implement the design
17
- - You need a bounded task package with all implementation details
18
-
19
- ## Preconditions
20
-
21
- The exporter performs this read-only check before writing anything:
22
-
23
- ```powershell
24
- node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
25
- ```
26
-
27
- If `matrix` is genuinely absent from PATH, use the bundled runtime from the installed root Matrix Skill. Do not fall back when the primary command starts and returns an error.
28
-
29
- If the build guard reports `CONTRACT_CHANGED` or `CONTRACT_UNAPPROVED`, return to `$matrix-design` and approve a new contract through Build. The exporter reads the approved bytes of `proposal.md`, `design.md`, and `plan.md`; it does not invent missing facts.
30
-
31
- ## Export
32
-
33
- Treat explicit invocation of `$matrix-claude` as the user's choice of Claude Code as the implementation actor. Generate the package with the deterministic exporter; it refuses a non-matching approved contract and does not alter Matrix state.
34
-
35
- ```powershell
36
- # Generic project: only exports a Matrix artifact.
37
- node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --target generic
38
-
39
- # FnSec: exports its formal task package. Add --apply-fnsec-board only when
40
- # active.md is NO_ACTIVE_OBJECTIVE; an existing task is never overwritten.
41
- node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --target fnsec --apply-fnsec-board
42
- ```
43
-
44
- ## Task Package Contents
45
-
46
- The exported package (`artifacts/claude-task.md`) contains everything Claude Code needs to implement and produce evidence for `$matrix-verify`:
47
-
48
- 1. **Task ID, execution actor, and approved contract hash**: Claude Code and the exact approved snapshot
49
- 2. **Objective and acceptance criteria** — copied from `proposal.md`
50
- 3. **In-scope and out-of-scope boundaries** — from `proposal.md`
51
- 4. **Frozen design decisions** — from `design.md` (Decisions, Boundaries, Test seams)
52
- 5. **Ordered implementation plan** — from `plan.md` (Steps, Validation)
53
- 6. **Allowed and prohibited files/actions** — to prevent scope creep
54
- 7. **Required commands** — test, lint, typecheck, build commands to run
55
- 8. **Stop conditions** — ambiguity, scope expansion, failing acceptance, design conflict
56
- 9. **Required evidence for verify**:
57
- - Changed files list
58
- - Commands and their outputs
59
- - Test results (pass/fail)
60
- - Build evidence
61
- - Residual risks
62
- - `NEEDS_DECISION` items (if any)
63
-
64
- ## After Claude Code Completes
65
-
66
- When Claude Code returns results, verify that the following evidence is present before proceeding to `$matrix-verify`:
67
-
68
- - [ ] `artifacts/verification.md` exists with `## Build evidence` section
69
- - [ ] Build evidence includes concrete commands and outcomes
70
- - [ ] All tests in the plan's validation section have been run
71
- - [ ] Any `NEEDS_DECISION` items have been resolved or documented
72
-
73
- If evidence is missing, ask Claude Code to补充 before proceeding.
74
-
75
- ## Resuming Matrix Workflow
76
-
77
- After Claude Code completes and evidence is present:
78
-
79
- 1. Run build guard to verify evidence:
80
- ```powershell
81
- node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
82
- ```
83
-
84
- 2. If guard passes, transition to verify:
85
- ```powershell
86
- node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
87
- ```
88
-
89
- 3. Enter `$matrix-verify` to继续验证流程
90
-
91
- If the build guard fails, return to Claude Code to补充 missing evidence.
92
-
93
- ## Important Notes
94
-
95
- - This sidecar does NOT change Matrix phase, workflow, or guard result
96
- - The Matrix state remains in `build` phase; export itself does not advance it
97
- - Claude Code must produce evidence that satisfies the build guard conditions
98
- - After successful transition to verify, the normal verify流程 continues
@@ -1,4 +0,0 @@
1
- interface:
2
- display_name: "Matrix Workflow"
3
- short_description: "Persistent development workflow stage"
4
- default_prompt: "Use $name to continue a Matrix development workflow."
@@ -1,4 +0,0 @@
1
- interface:
2
- display_name: "Matrix Workflow"
3
- short_description: "Persistent development workflow stage"
4
- default_prompt: "Use $name to continue a Matrix development workflow."
@@ -1,4 +0,0 @@
1
- interface:
2
- display_name: "Matrix Workflow"
3
- short_description: "Persistent development workflow stage"
4
- default_prompt: "Use $name to continue a Matrix development workflow."
@@ -1,33 +0,0 @@
1
- ---
2
- name: matrix-claude
3
- description: 将已批准的 Matrix Contract 导出为受边界约束的 Claude Code 任务包,不改变 Matrix 工作流状态。
4
- ---
5
-
6
- # Matrix Claude Handoff
7
-
8
- 这是可选旁路,不是 Matrix phase。它不得执行 `transition`、`archive`,也不得写入 `matrix.yaml` 或 `events.jsonl`。它只支持匹配的 full 或 legacy-full 三产物 Contract;新的 lightweight hotfix/tweak 不支持导出。
9
-
10
- 人类可读 handoff 内容使用 inspect 的 `artifact_language`;稳定的机器可读标题和 metadata key 保持不变。
11
-
12
- 仅当变更已进入 Build、`design -> build` 已批准精确 Contract,并且用户明确选择 Claude Code 实现时使用。先检查:
13
-
14
- ```powershell
15
- node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
16
- ```
17
-
18
- 若结果为 `CONTRACT_CHANGED`、`CONTRACT_UNAPPROVED` 或 `CONTRACT_READ_FAILED`,回到 `$matrix-design`,修订后重新进入 Build 取得新批准。导出只读取批准快照中的 `proposal.md`、`design.md` 与 `plan.md`。
19
-
20
- ```powershell
21
- # 通用项目:只导出 Matrix 产物
22
- node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --target generic
23
-
24
- # FnSec:仅在 active.md 含有 NO_ACTIVE_OBJECTIVE 时更新看板
25
- node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --target fnsec --apply-fnsec-board
26
- ```
27
-
28
- 任务包包含批准的 Contract hash 与 revision,以及同一快照的 proposal、design、plan。导出本身不改变 Build 阶段;Claude 完成后,补齐 `## Build evidence`,然后继续:
29
-
30
- ```powershell
31
- node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
32
- node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
33
- ```