@rosenfan/matrix 0.1.4 → 0.1.6

package/{.claude → assets}/skills/matrix/scripts/matrix_state.py

@@ -1,38 +1,38 @@
-#!/usr/bin/env python3
-"""Compatibility adapter for the authoritative Node Workflow Runtime."""
-from __future__ import annotations
-
-import os
-import shutil
-import subprocess
-import sys
-from pathlib import Path
-
-
-def development_runtime() -> Path | None:
-    """Return an explicitly selected source runtime for repository tests only."""
-    configured = os.environ.get("MATRIX_DEVELOPMENT_RUNTIME")
-    return Path(configured).resolve() if configured else None
-
-
-def primary_runtime() -> str | None:
-    if os.name == "nt":
-        return shutil.which("matrix.cmd") or shutil.which("matrix.exe")
-    return shutil.which("matrix")
-
-
+#!/usr/bin/env python3
+"""Compatibility adapter for the authoritative Node Workflow Runtime."""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+def development_runtime() -> Path | None:
+    """Return an explicitly selected source runtime for repository tests only."""
+    configured = os.environ.get("MATRIX_DEVELOPMENT_RUNTIME")
+    return Path(configured).resolve() if configured else None
+
+
+def primary_runtime() -> str | None:
+    if os.name == "nt":
+        return shutil.which("matrix.cmd") or shutil.which("matrix.exe")
+    return shutil.which("matrix")
+
+
 def runtime_command(args: list[str]) -> list[str]:
     development = development_runtime()
     if development is not None:
-        if not development.is_file():
-            raise RuntimeError(f"Configured Matrix development runtime was not found: {development}")
-        node = shutil.which("node")
-        if node is None:
-            raise RuntimeError("Node.js is required to run the Matrix workflow.")
-        return [node, str(development), *args]
-
-    bundled = Path(__file__).with_name("matrix-runtime.mjs")
-    node = shutil.which("node")
+        if not development.is_file():
+            raise RuntimeError(f"Configured Matrix development runtime was not found: {development}")
+        node = shutil.which("node")
+        if node is None:
+            raise RuntimeError("Node.js is required to run the Matrix workflow.")
+        return [node, str(development), *args]
+
+    bundled = Path(__file__).with_name("matrix-runtime.mjs")
+    node = shutil.which("node")
     if node is not None and bundled.exists():
         return [node, str(bundled), *args]
 
@@ -41,20 +41,20 @@ def runtime_command(args: list[str]) -> list[str]:
         return [primary, "workflow", *args, "--json"]
 
     raise RuntimeError("Matrix CLI is absent and the bundled workflow runtime was not found.")
-
-
-def run_runtime(args: list[str]) -> int:
-    try:
-        completed = subprocess.run(runtime_command(args), cwd=Path.cwd(), check=False)
-    except (OSError, RuntimeError) as error:
-        print(f"MATRIX ERROR [RUNTIME_UNAVAILABLE]: {error}", file=sys.stderr)
-        return 2
-    return completed.returncode
-
-
-def main() -> int:
-    return run_runtime(sys.argv[1:])
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
+
+
+def run_runtime(args: list[str]) -> int:
+    try:
+        completed = subprocess.run(runtime_command(args), cwd=Path.cwd(), check=False)
+    except (OSError, RuntimeError) as error:
+        print(f"MATRIX ERROR [RUNTIME_UNAVAILABLE]: {error}", file=sys.stderr)
+        return 2
+    return completed.returncode
+
+
+def main() -> int:
+    return run_runtime(sys.argv[1:])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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-design/SKILL.md

@@ -1,73 +1,79 @@
----
-name: matrix-design
-description: Design and freeze the active Matrix change before implementation. Use when the active Matrix phase is design or when build scope requires redesign.
----
-
-# Matrix Design
-
-Design is used by `full` and resumable legacy shortcut changes only. A new lightweight hotfix/tweak moves directly from Open to Build and must not create Design artifacts merely to satisfy the full guard.
-
-Use `artifact_language` from `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` for all design and plan prose. Keep Runtime-required English heading tokens unchanged.
-
-Run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect`, read the active proposal and frozen `orchestration`, then write `artifacts/design.md` with `## Decisions`, `## Boundaries`, `## Test seams`, and `## Risks`; write `artifacts/plan.md` with `## Steps`, `## Validation`, and `## Stop conditions`.
-
-## Prim
-
-Use Matrix's own capability to investigate the repository and design the change.
-
-## Arch
-
-Invoke only capabilities whose task-fact trigger is proven:
-
+---
+name: matrix-design
+description: Design and freeze the active Matrix change before implementation. Use when the active Matrix phase is design or when build scope requires redesign.
+---
+
+# Matrix Design
+
+Design is used by `full` and resumable legacy shortcut changes only. A new lightweight hotfix/tweak moves directly from Open to Build and must not create Design artifacts merely to satisfy the full guard.
+
+Use `artifact_language` from `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` for all design and plan prose. Keep Runtime-required English heading tokens unchanged.
+
+Run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect`, read the active proposal and frozen `orchestration`, then write `artifacts/design.md` with `## Decisions`, `## Boundaries`, `## Test seams`, and `## Risks`; write `artifacts/plan.md` with `## Steps`, `## Validation`, and `## Stop conditions`.
+
+## Prim
+
+Use Matrix's own capability to investigate the repository and design the change.
+
+## Arch
+
+Invoke only capabilities whose task-fact trigger is proven:
+
 - `domain-modeling` for unclear vocabulary, invariants, or architectural decisions;
 - `research` when required external facts cannot be established from the repository;
 - `prototype` when a material design decision needs disposable empirical evidence;
 - `codebase-design` when a deep-module, interface, or test-seam decision remains;
 - `writing-for-agents` when the Contract creates or changes Skills, `AGENTS.md`, `CLAUDE.md`, or documents reached through agent pointers.
-
-Order follows actual dependencies; never run a fixed companion sequence. Announce each invocation and reason. A correctly installed capability gets at most one same-capability Matrix fallback; installation-integrity failure stops the phase.
-
+
+Order follows actual dependencies; never run a fixed companion sequence. Announce each invocation and reason. A correctly installed capability gets at most one same-capability Matrix fallback; installation-integrity failure stops the phase.
+
 Long-lived domain, ADR, or research artifacts follow repository conventions, and material conclusions must be synchronized into the canonical design or plan. Prototypes default to an OS temporary directory unless the approved design promotes a project path. Companion output cannot own Matrix state or create a competing plan.
 
 `wayfinder` and `improve-codebase-architecture` are explicit handoffs outside the active Design. Recommend one only when its purpose fits, then let the user invoke it; a selected result may enter a separate governed Change.
-
-## Process
-
-1. Establish repository facts and resolve only triggered design questions.
-2. Write and synchronize the canonical Matrix design and plan.
-3. Confirm material architecture choices with the user before freezing.
-4. Run the guard, then choose the implementation actor.
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard design
-```
-
-## Implementation Decision Point
-
-After the design guard passes, the user chooses:
-
-### Option A: Continue with Codex (default)
-
-Run transition and enter `$matrix-build`:
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build
-```
-
-Then enter `$matrix-build` to implement directly in this session.
-
-### Option B: Use Claude Code for implementation
-
-First approve the frozen contract by transitioning to Build, then run `$matrix-claude` to export a bounded task package. This:
-- Does not change the Build phase or state beyond the preceding transition
-- Creates `artifacts/claude-task.md` with all implementation details
-- Includes acceptance criteria, test seams, and required commands
-
-After Claude Code completes and returns results, run the Build guard and enter `$matrix-verify`:
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
-```
-
-Then enter `$matrix-verify` to verify the implementation.
+
+## Process
+
+1. Establish repository facts and resolve only triggered design questions.
+2. Write and synchronize the canonical Matrix design and plan.
+3. Confirm material architecture choices with the user before freezing.
+4. Run the guard, then choose the implementation actor.
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard design
+```
+
+## Implementation Decision Point
+
+After the design guard passes and before `transition build`, pause and present the implementation-actor choice to the user. Do not transition without an explicit choice:
+
+### Option A: Continue with the current agent / model (default)
+
+Run transition and enter `$matrix-build`:
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build
+```
+
+Then enter `$matrix-build` to implement directly in this session.
+
+### Option B: Switch the model, keep this agent
+
+The user switches the model in their own client (for example, a stronger model for design, an efficient one for implementation), returns to this session, and confirms. Then run transition exactly as in Option A. Matrix cannot see the client-side model; it provides the mandatory pause point only.
+
+### Option C: Switch the implementation agent
+
+First approve the frozen contract by transitioning to Build, then run `$matrix-handoff` to export a bounded task package for the chosen agent (for example Codex designs, Claude Code implements; or zcode designs, opencode implements). This:
+- Does not change the Build phase or state beyond the preceding transition
+- Creates `artifacts/handoff-task-<task-id>.md` with all implementation details
+- Includes acceptance criteria, test seams, and required commands
+
+After the implementation agent completes and returns results, run the Build guard and enter `$matrix-verify`:
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
+```
+
+Then enter `$matrix-verify` to verify the implementation.
+
+Record the chosen option in `design.md` under `## Decisions` so it freezes with the Contract.

package/{.claude → assets}/skills/matrix-design/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."