@rosenfan/matrix 0.1.4 → 0.1.5

package/assets/skills/matrix/scripts/test_matrix_claude.py

@@ -0,0 +1,69 @@
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+STATE = Path(__file__).with_name("matrix_state.py")
+CLAUDE = Path(__file__).with_name("matrix_claude.py")
+RUNTIME = Path(__file__).resolve().parents[4] / "src" / "workflow.js"
+NODE_DIRECTORY = str(Path(shutil.which("node") or "").parent)
+
+
+class MatrixClaudeTests(unittest.TestCase):
+    def invoke(self, script, *args, cwd):
+        env = {**os.environ, "PATH": NODE_DIRECTORY, "MATRIX_DEVELOPMENT_RUNTIME": str(RUNTIME)}
+        return subprocess.run([sys.executable, str(script), *args], cwd=cwd, env=env, text=True, capture_output=True)
+
+    def inspect(self, cwd):
+        return json.loads(self.invoke(STATE, "inspect", cwd=cwd).stdout)
+
+    def make_design_change(self, cwd):
+        self.assertEqual(self.invoke(STATE, "init", "bridge", "--title", "Bridge", cwd=cwd).returncode, 0)
+        artifacts = cwd / ".matrix/changes/bridge/artifacts"
+        (artifacts / "proposal.md").write_text("## Goal\nBuild a bounded feature.\n\n## Scope\nOne module only.\n\n## Non-goals\nNo extra work.\n\n## Acceptance\nA focused test passes.\n\n## Risks\nKnown risk.\n")
+        self.assertEqual(self.invoke(STATE, "transition", "design", cwd=cwd).returncode, 0)
+        (artifacts / "design.md").write_text("## Decisions\nKeep one public seam.\n\n## Boundaries\nOne public seam only.\n\n## Test seams\nUse the public interface.\n\n## Risks\nKnown risk.\n")
+        (artifacts / "plan.md").write_text("## Steps\n1. Add a failing test.\n\n## Validation\nRun the focused test.\n\n## Stop conditions\nStop on scope change.\n")
+        self.assertEqual(self.invoke(STATE, "transition", "build", cwd=cwd).returncode, 0)
+
+    def test_generic_export_does_not_change_matrix_state(self):
+        with tempfile.TemporaryDirectory() as temp:
+            cwd = Path(temp)
+            self.make_design_change(cwd)
+            result = self.invoke(CLAUDE, "export", "--task-id", "GEN-001", cwd=cwd)
+            self.assertEqual(result.returncode, 0, result.stderr)
+            task = cwd / ".matrix/changes/bridge/artifacts/claude-task.md"
+            self.assertIn("## Prohibited work", task.read_text(encoding="utf-8"))
+            self.assertEqual(self.inspect(cwd)["phase"], "build")
+
+    def test_fnsec_board_refuses_existing_objective(self):
+        with tempfile.TemporaryDirectory() as temp:
+            cwd = Path(temp)
+            self.make_design_change(cwd)
+            tasks = cwd / "docs/tasks"
+            tasks.mkdir(parents=True)
+            (tasks / "active.md").write_text("# Active task\n", encoding="utf-8")
+            result = self.invoke(CLAUDE, "export", "--task-id", "FNSEC-X", "--target", "fnsec", "--apply-fnsec-board", cwd=cwd)
+            self.assertNotEqual(result.returncode, 0)
+            self.assertFalse((tasks / "claude-task-FNSEC-X.md").exists(), result.stdout + result.stderr)
+
+    def test_fnsec_export_updates_empty_board_only(self):
+        with tempfile.TemporaryDirectory() as temp:
+            cwd = Path(temp)
+            self.make_design_change(cwd)
+            tasks = cwd / "docs/tasks"
+            tasks.mkdir(parents=True)
+            (tasks / "active.md").write_text("# NO_ACTIVE_OBJECTIVE\n", encoding="utf-8")
+            result = self.invoke(CLAUDE, "export", "--task-id", "FNSEC-Y", "--target", "fnsec", "--apply-fnsec-board", cwd=cwd)
+            self.assertEqual(result.returncode, 0, result.stderr)
+            self.assertIn("## Prohibited work", (tasks / "claude-task-FNSEC-Y.md").read_text(encoding="utf-8"))
+            self.assertIn("CLAUDE_QUEUED", (tasks / "active.md").read_text(encoding="utf-8"))
+            self.assertEqual(self.inspect(cwd)["phase"], "build")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/assets/skills/matrix/scripts/test_matrix_state.py

@@ -0,0 +1,69 @@
+import json
+import importlib.util
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from unittest import mock
+from pathlib import Path
+
+SCRIPT = Path(__file__).with_name("matrix_state.py")
+RUNTIME = Path(__file__).resolve().parents[4] / "src" / "workflow.js"
+NODE_DIRECTORY = str(Path(shutil.which("node") or "").parent)
+class MatrixStateTests(unittest.TestCase):
+    def invoke(self, *args, cwd):
+        env = {**os.environ, "PATH": NODE_DIRECTORY, "MATRIX_DEVELOPMENT_RUNTIME": str(RUNTIME)}
+        return subprocess.run([sys.executable, str(SCRIPT), *args], cwd=cwd, env=env, text=True, capture_output=True)
+    def load_adapter(self, directory):
+        script = directory / "matrix_state.py"
+        shutil.copyfile(SCRIPT, script)
+        spec = importlib.util.spec_from_file_location(f"matrix_state_{directory.name}", script)
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        return module
+    def test_runtime_precedence_is_bundled_then_global(self):
+        with tempfile.TemporaryDirectory() as temp:
+            directory = Path(temp)
+            adapter = self.load_adapter(directory)
+            bundled = directory / "matrix-runtime.mjs"
+            bundled.write_text("// project runtime\n", encoding="utf-8")
+            with mock.patch.object(adapter, "development_runtime", return_value=None), mock.patch.object(adapter, "primary_runtime", return_value="global-matrix"):
+                command = adapter.runtime_command(["inspect"])
+                self.assertEqual(Path(command[1]), bundled)
+            bundled.unlink()
+            with mock.patch.object(adapter, "development_runtime", return_value=None), mock.patch.object(adapter, "primary_runtime", return_value="global-matrix"):
+                self.assertEqual(adapter.runtime_command(["inspect"]), ["global-matrix", "workflow", "inspect", "--json"])
+    def test_phase_guard_and_recovery(self):
+        with tempfile.TemporaryDirectory() as temp:
+            cwd = Path(temp); result = self.invoke("init", "sample", "--title", "Sample", cwd=cwd); self.assertEqual(result.returncode, 0)
+            self.assertTrue((cwd / ".matrix" / "active.json").exists())
+            self.assertFalse((cwd / ".codex").exists())
+            self.assertNotEqual(self.invoke("transition", "design", cwd=cwd).returncode, 0)
+            p = cwd / ".matrix/changes/sample/artifacts"
+            (p / "proposal.md").write_text("## Goal\nBuild a bounded feature.\n\n## Scope\nOne module only.\n\n## Non-goals\nNo extra work.\n\n## Acceptance\nA focused test passes.\n\n## Risks\nKnown risk.\n")
+            self.assertEqual(self.invoke("transition", "design", cwd=cwd).returncode, 0)
+            self.assertEqual(json.loads(self.invoke("inspect", cwd=cwd).stdout)["phase"], "design")
+
+    def test_full_lifecycle_requires_evidence(self):
+        with tempfile.TemporaryDirectory() as temp:
+            cwd = Path(temp); self.assertEqual(self.invoke("init", "full", "--title", "Full", cwd=cwd).returncode, 0)
+            p = cwd / ".matrix/changes/full/artifacts"
+            (p / "proposal.md").write_text("## Goal\nBuild a bounded feature.\n\n## Scope\nOne module only.\n\n## Non-goals\nNo extra work.\n\n## Acceptance\nA focused test passes.\n\n## Risks\nKnown risk.\n")
+            self.assertEqual(self.invoke("transition", "design", cwd=cwd).returncode, 0)
+            self.assertNotEqual(self.invoke("transition", "build", cwd=cwd).returncode, 0)
+            (p / "design.md").write_text("## Decisions\nKeep one public seam.\n\n## Boundaries\nOne public seam only.\n\n## Test seams\nUse the public interface.\n\n## Risks\nKnown risk.\n")
+            (p / "plan.md").write_text("## Steps\n1. Add a failing test.\n\n## Validation\nRun the focused test.\n\n## Stop conditions\nStop on scope change.\n")
+            self.assertEqual(self.invoke("transition", "build", cwd=cwd).returncode, 0)
+            (p / "verification.md").write_text("## Build evidence\nThe focused implementation test command completed successfully with an expected result.\n")
+            self.assertEqual(self.invoke("transition", "verify", cwd=cwd).returncode, 0)
+            self.assertNotEqual(self.invoke("transition", "archive", cwd=cwd).returncode, 0)
+            (p / "verification.md").write_text("## Build evidence\nThe focused implementation test command completed successfully with an expected result.\n\n## Test evidence\nThe acceptance command passed and its output was reviewed for the requested behavior.\n\n## Review evidence\nThe fixed-baseline standards and specification review found no blocking issue.\n")
+            self.assertEqual(self.invoke("transition", "archive", cwd=cwd).returncode, 0)
+            preflight = self.invoke("archive", "--dry-run", cwd=cwd)
+            self.assertEqual(preflight.returncode, 0)
+            token = json.loads(preflight.stdout)["preflight_hash"]
+            self.assertEqual(self.invoke("archive", "--expect-preflight", token, cwd=cwd).returncode, 0)
+            self.assertTrue((cwd / ".matrix/archive/full/matrix.yaml").exists())
+if __name__ == "__main__": unittest.main()

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

@@ -1,36 +1,36 @@
----
-name: matrix-archive
-description: Close and archive a verified Matrix change. Use when the active Matrix phase is archive.
----
-
-# Matrix Archive
-
-This is the final Matrix phase. Read the proposal, plan, and verification evidence; summarize changed behavior, verification, residual risks, and follow-up work. Ask for explicit confirmation before committing or archiving.
-
-Write archive summaries and handoff prose in `artifact_language`; keep Runtime-required English heading tokens unchanged.
-
-Archive is Matrix-owned in both Prim and Arch. Do not invoke companion implementation, review, or architecture capabilities here.
-
-## Mandatory two-step Archive
-
-Run the read-only preflight and review its bounded effect summary. Then submit exactly the hash returned by that preflight:
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs archive --dry-run
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs archive --expect-preflight <sha256-returned-by-dry-run>
-```
-
-Bare Archive is rejected. Runtime reacquires the project Archive boundary and recomputes the entire protected change-directory manifest before committing.
-For hotfix/tweak, ask for explicit confirmation after reviewing the preflight, then use the returned command with `--confirmed`. Runtime rejects a shortcut Archive without it.
-
-- `ARCHIVE_PREFLIGHT_CHANGED`: run dry-run again and review the new summary.
-- `ARCHIVE_BUSY`: retry later. Do not remove or take over the lock; stale-lock recovery belongs to the later doctor/repair change.
-- Guard or Contract failure: use the returned recovery command and do not submit.
-
-If acceptance criteria or design must change while awaiting confirmation, use the sole Archive recovery path:
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason acceptance-or-design-gap
-```
-
-After successful commit, the change is under `.matrix/archive/` and the workflow is complete.
+---
+name: matrix-archive
+description: Close and archive a verified Matrix change. Use when the active Matrix phase is archive.
+---
+
+# Matrix Archive
+
+This is the final Matrix phase. Read the proposal, plan, and verification evidence; summarize changed behavior, verification, residual risks, and follow-up work. Ask for explicit confirmation before committing or archiving.
+
+Write archive summaries and handoff prose in `artifact_language`; keep Runtime-required English heading tokens unchanged.
+
+Archive is Matrix-owned in both Prim and Arch. Do not invoke companion implementation, review, or architecture capabilities here.
+
+## Mandatory two-step Archive
+
+Run the read-only preflight and review its bounded effect summary. Then submit exactly the hash returned by that preflight:
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs archive --dry-run
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs archive --expect-preflight <sha256-returned-by-dry-run>
+```
+
+Bare Archive is rejected. Runtime reacquires the project Archive boundary and recomputes the entire protected change-directory manifest before committing.
+For hotfix/tweak, ask for explicit confirmation after reviewing the preflight, then use the returned command with `--confirmed`. Runtime rejects a shortcut Archive without it.
+
+- `ARCHIVE_PREFLIGHT_CHANGED`: run dry-run again and review the new summary.
+- `ARCHIVE_BUSY`: retry later. Do not remove or take over the lock; stale-lock recovery belongs to the later doctor/repair change.
+- Guard or Contract failure: use the returned recovery command and do not submit.
+
+If acceptance criteria or design must change while awaiting confirmation, use the sole Archive recovery path:
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason acceptance-or-design-gap
+```
+
+After successful commit, the change is under `.matrix/archive/` and the workflow is complete.

package/{.claude/skills/matrix-hotfix → assets/skills/matrix-archive}/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-build/SKILL.md

@@ -1,47 +1,47 @@
----
-name: matrix-build
-description: Implement the frozen active Matrix plan with test-first vertical slices. Use when the active Matrix phase is build.
----
-
-# Matrix Build
-
-Run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` and implement only its approved Contract. Full and `legacy-full` read proposal/design/plan. `lightweight` reads the approved compact proposal and must not backfill Design artifacts.
-
-Write build evidence and user-facing explanations in `artifact_language`; preserve any Runtime-required English heading tokens.
-
-## Prim
-
-Use Matrix's own implementation and test discipline.
-
-## Arch
-
+---
+name: matrix-build
+description: Implement the frozen active Matrix plan with test-first vertical slices. Use when the active Matrix phase is build.
+---
+
+# Matrix Build
+
+Run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` and implement only its approved Contract. Full and `legacy-full` read proposal/design/plan. `lightweight` reads the approved compact proposal and must not backfill Design artifacts.
+
+Write build evidence and user-facing explanations in `artifact_language`; preserve any Runtime-required English heading tokens.
+
+## Prim
+
+Use Matrix's own implementation and test discipline.
+
+## Arch
+
 - invoke `tdd` when the change modifies observable behavior at a testable seam;
 - invoke `diagnosing-bugs` only when an actual failure exists and root cause is not established;
 - invoke `writing-for-agents` when the approved Contract changes agent-facing instructions;
 - invoke `wizard` only to generate and statically verify human-run shell steps required by the Contract; never execute the wizard end-to-end or collect secrets.
 
 Resolve an in-progress merge/rebase through Matrix-owned conflict handling. Do not invoke raw `resolving-merge-conflicts`, because it can stage, continue, and commit outside Matrix lifecycle ownership. Never invoke `implement` inside an active Change.
-
-Announce each triggered capability and reason. No companion may commit, review, transition, archive, or broaden scope. A correctly installed capability gets at most one Matrix-owned fallback for that same capability; record the Skill, failure, fallback, and evidence. Installation-integrity failure stops the phase.
-
-## Scope Discipline
-
-If implementation exposes a scope or design change, **stop and run**; a lightweight change is upgraded to full by this Return:
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap
-```
-
-Then enter `$matrix-design`; do not amend the plan silently. The Runtime preserves old verification evidence in revision history and requires fresh evidence after the redesigned plan returns to Build.
-
-## Process
-
-1. Implement the approved plan in bounded vertical slices.
-2. Use only triggered Arch capabilities.
-3. Record common facts under `## Build evidence`. Hotfix also requires `## Reproduction evidence` and `## Root cause`; tweak also requires `## Scope evidence`.
-4. Run the guard and transition, then enter `$matrix-verify`.
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
-```
+
+Announce each triggered capability and reason. No companion may commit, review, transition, archive, or broaden scope. A correctly installed capability gets at most one Matrix-owned fallback for that same capability; record the Skill, failure, fallback, and evidence. Installation-integrity failure stops the phase.
+
+## Scope Discipline
+
+If implementation exposes a scope or design change, **stop and run**; a lightweight change is upgraded to full by this Return:
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap
+```
+
+Then enter `$matrix-design`; do not amend the plan silently. The Runtime preserves old verification evidence in revision history and requires fresh evidence after the redesigned plan returns to Build.
+
+## Process
+
+1. Implement the approved plan in bounded vertical slices.
+2. Use only triggered Arch capabilities.
+3. Record common facts under `## Build evidence`. Hotfix also requires `## Reproduction evidence` and `## Root cause`; tweak also requires `## Scope evidence`.
+4. Run the guard and transition, then enter `$matrix-verify`.
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
+```

package/{.claude/skills/matrix-archive → assets/skills/matrix-build}/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-claude/SKILL.md

@@ -1,98 +1,98 @@
----
-name: matrix-claude
-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.
----
-
-# Matrix Claude Handoff
-
-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.
-
-Use `artifact_language` from inspect for human-readable handoff text while retaining the stable machine-readable headings and metadata keys.
-
-## When to Use
-
-Use `$matrix-claude` when:
-- The active change is in Build and the Design -> Build transition has approved the contract
-- You want Claude Code (instead of Codex) to implement the design
-- You need a bounded task package with all implementation details
-
-## Preconditions
-
-The exporter performs this read-only check before writing anything:
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
-```
-
-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.
-
-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.
-
-## Export
-
-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.
-
-```powershell
-# Generic project: only exports a Matrix artifact.
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --target generic
-
-# FnSec: exports its formal task package. Add --apply-fnsec-board only when
-# active.md is NO_ACTIVE_OBJECTIVE; an existing task is never overwritten.
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --target fnsec --apply-fnsec-board
-```
-
-## Task Package Contents
-
-The exported package (`artifacts/claude-task.md`) contains everything Claude Code needs to implement and produce evidence for `$matrix-verify`:
-
-1. **Task ID, execution actor, and approved contract hash**: Claude Code and the exact approved snapshot
-2. **Objective and acceptance criteria** — copied from `proposal.md`
-3. **In-scope and out-of-scope boundaries** — from `proposal.md`
-4. **Frozen design decisions** — from `design.md` (Decisions, Boundaries, Test seams)
-5. **Ordered implementation plan** — from `plan.md` (Steps, Validation)
-6. **Allowed and prohibited files/actions** — to prevent scope creep
-7. **Required commands** — test, lint, typecheck, build commands to run
-8. **Stop conditions** — ambiguity, scope expansion, failing acceptance, design conflict
-9. **Required evidence for verify**:
-   - Changed files list
-   - Commands and their outputs
-   - Test results (pass/fail)
-   - Build evidence
-   - Residual risks
-   - `NEEDS_DECISION` items (if any)
-
-## After Claude Code Completes
-
-When Claude Code returns results, verify that the following evidence is present before proceeding to `$matrix-verify`:
-
-- [ ] `artifacts/verification.md` exists with `## Build evidence` section
-- [ ] Build evidence includes concrete commands and outcomes
-- [ ] All tests in the plan's validation section have been run
-- [ ] Any `NEEDS_DECISION` items have been resolved or documented
-
-If evidence is missing, ask Claude Code to补充 before proceeding.
-
-## Resuming Matrix Workflow
-
-After Claude Code completes and evidence is present:
-
-1. Run build guard to verify evidence:
-   ```powershell
-   node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
-   ```
-
-2. If guard passes, transition to verify:
-   ```powershell
-   node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
-   ```
-
-3. Enter `$matrix-verify` to继续验证流程
-
-If the build guard fails, return to Claude Code to补充 missing evidence.
-
-## Important Notes
-
-- This sidecar does NOT change Matrix phase, workflow, or guard result
-- The Matrix state remains in `build` phase; export itself does not advance it
-- Claude Code must produce evidence that satisfies the build guard conditions
-- After successful transition to verify, the normal verify流程 continues
+---
+name: matrix-claude
+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.
+---
+
+# Matrix Claude Handoff
+
+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.
+
+Use `artifact_language` from inspect for human-readable handoff text while retaining the stable machine-readable headings and metadata keys.
+
+## When to Use
+
+Use `$matrix-claude` when:
+- The active change is in Build and the Design -> Build transition has approved the contract
+- You want Claude Code (instead of Codex) to implement the design
+- You need a bounded task package with all implementation details
+
+## Preconditions
+
+The exporter performs this read-only check before writing anything:
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
+```
+
+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.
+
+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.
+
+## Export
+
+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.
+
+```powershell
+# Generic project: only exports a Matrix artifact.
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --target generic
+
+# FnSec: exports its formal task package. Add --apply-fnsec-board only when
+# active.md is NO_ACTIVE_OBJECTIVE; an existing task is never overwritten.
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --target fnsec --apply-fnsec-board
+```
+
+## Task Package Contents
+
+The exported package (`artifacts/claude-task.md`) contains everything Claude Code needs to implement and produce evidence for `$matrix-verify`:
+
+1. **Task ID, execution actor, and approved contract hash**: Claude Code and the exact approved snapshot
+2. **Objective and acceptance criteria** — copied from `proposal.md`
+3. **In-scope and out-of-scope boundaries** — from `proposal.md`
+4. **Frozen design decisions** — from `design.md` (Decisions, Boundaries, Test seams)
+5. **Ordered implementation plan** — from `plan.md` (Steps, Validation)
+6. **Allowed and prohibited files/actions** — to prevent scope creep
+7. **Required commands** — test, lint, typecheck, build commands to run
+8. **Stop conditions** — ambiguity, scope expansion, failing acceptance, design conflict
+9. **Required evidence for verify**:
+   - Changed files list
+   - Commands and their outputs
+   - Test results (pass/fail)
+   - Build evidence
+   - Residual risks
+   - `NEEDS_DECISION` items (if any)
+
+## After Claude Code Completes
+
+When Claude Code returns results, verify that the following evidence is present before proceeding to `$matrix-verify`:
+
+- [ ] `artifacts/verification.md` exists with `## Build evidence` section
+- [ ] Build evidence includes concrete commands and outcomes
+- [ ] All tests in the plan's validation section have been run
+- [ ] Any `NEEDS_DECISION` items have been resolved or documented
+
+If evidence is missing, ask Claude Code to补充 before proceeding.
+
+## Resuming Matrix Workflow
+
+After Claude Code completes and evidence is present:
+
+1. Run build guard to verify evidence:
+   ```powershell
+   node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
+   ```
+
+2. If guard passes, transition to verify:
+   ```powershell
+   node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
+   ```
+
+3. Enter `$matrix-verify` to继续验证流程
+
+If the build guard fails, return to Claude Code to补充 missing evidence.
+
+## Important Notes
+
+- This sidecar does NOT change Matrix phase, workflow, or guard result
+- The Matrix state remains in `build` phase; export itself does not advance it
+- Claude Code must produce evidence that satisfies the build guard conditions
+- After successful transition to verify, the normal verify流程 continues

package/{.claude → assets}/skills/matrix-claude/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "Matrix Claude Handoff"
-  short_description: "Export frozen Matrix design as a Claude Code task"
-  default_prompt: "Use $matrix-claude to prepare a Claude Code task package."
+interface:
+  display_name: "Matrix Claude Handoff"
+  short_description: "Export frozen Matrix design as a Claude Code task"
+  default_prompt: "Use $matrix-claude to prepare a Claude Code task package."