@rosenfan/matrix 0.1.3 → 0.1.5

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

@@ -1,92 +1,87 @@
----
-name: matrix
-description: Route, initialize, resume, and govern a persistent Matrix development workflow. Use when the user starts a feature, change, bug fix, or asks to resume managed development.
----
-
+---
+name: matrix
+description: Route, initialize, resume, and govern a persistent Matrix development workflow. Use when the user starts a feature, change, bug fix, or asks to resume managed development.
+---
+
 # Matrix
 
 Use Matrix as the development-workflow entrypoint. Its source of truth is the current repository's `.matrix/`; never infer a phase from chat history.
 
-Read `artifact_language` from `matrix workflow inspect`. Keep required Markdown heading tokens unchanged, but write every user-facing artifact body, explanation, and handoff in that language: English for `en`, Chinese for `zh-CN`.
-
-## Route
-
-First run:
-
-```powershell
-matrix workflow inspect
-```
-
-If and only if the `matrix` executable is reported as absent, run the bundled fallback from this Skill directory instead:
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect
-```
-
-- If an active change exists, show its phase and frozen `orchestration`, report any Arch installation-integrity failure, and enter the returned `next_skill` only when the Runtime permits continuation.
-- If no active change exists, classify the request: reproducible small bug → `$matrix-hotfix` with workflow `hotfix`; bounded small change with no public API/schema/architecture impact → `$matrix-tweak` with workflow `tweak`; otherwise full Matrix with workflow `full`.
-- Do not create Matrix state for questions, read-only investigation, or requests outside software development.
-- Before `init`, derive a short kebab-case change id and an accurate title. Start with `full` unless a shortcut clearly applies.
-
-```powershell
-matrix workflow init <change-id> --workflow <full|hotfix|tweak> --orchestration <prim|arch> --title "<title>"
-```
-
-An explicit mode wins; otherwise Runtime uses the project `default_orchestration`. The resolved value is immutable for the change and is shown in init, inspect, and the initialized Event. Then enter `$matrix-open`.
-
-## Orchestration
-
-- **Prim** uses Matrix's own capability in every phase and never requires Matt Skills.
-- **Arch** conditionally invokes the initialization-verified ten-Skill cohort when documented task-fact triggers are present.
-
+Read `artifact_language` from `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect`. Keep required Markdown heading tokens unchanged, but write every user-facing artifact body, explanation, and handoff in that language: English for `en`, Chinese for `zh-CN`.
+
+## Route
+
+For every workflow command, run the Runtime bundled with this project Skill so the project compatibility authority wins over a different global launcher:
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect
+```
+
+Use the global `matrix` command for `init`, `update`, and bootstrap only. A trusted 0.1.4 launcher auto-delegates only to an exact, hash-verified 0.1.4 project Runtime. A different or unidentified project release remains authoritative but must be invoked through the exact direct command returned by the launcher. Older launchers cannot provide this cross-release check and must not be used as the project workflow entrypoint.
+
+- If an active change exists, show its phase and frozen `orchestration`, report any Arch installation-integrity failure, and enter the returned `next_skill` only when the Runtime permits continuation.
+- If no active change exists, classify the request: reproducible small bug → `$matrix-hotfix` with workflow `hotfix`; bounded small change with no public API/schema/architecture impact → `$matrix-tweak` with workflow `tweak`; otherwise full Matrix with workflow `full`.
+- Do not create Matrix state for questions, read-only investigation, or requests outside software development.
+- Before `init`, derive a short kebab-case change id and an accurate title. Start with `full` unless a shortcut clearly applies.
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs init <change-id> --workflow <full|hotfix|tweak> --orchestration <prim|arch> --title "<title>"
+```
+
+An explicit mode wins; otherwise Runtime uses the project `default_orchestration`. The resolved value is immutable for the change and is shown in init, inspect, and the initialized Event. Then enter `$matrix-open`.
+
+## Orchestration
+
+- **Prim** uses Matrix's own capability in every phase and never requires Matt Skills.
+- **Arch** conditionally invokes the ten reviewed automatic capabilities frozen by the active Change. Matrix 0.1.4 reviews all 25 official Matt Skills v1.2.3 roles and installs only the 23 compatible Skills project-locally; `implement` and raw `resolving-merge-conflicts` are excluded.
+
 Both orchestration modes use the same selected workflow profile. `full` uses `open → design → build → verify → archive`; `hotfix` and `tweak` share one internal `lightweight` profile, `open → build → verify → archive`, with different evidence policies. Companion Skills never write Matrix state, transition, commit, archive, or create competing workflow artifacts.
-
-A correctly installed Arch capability that fails gets at most one Matrix-owned fallback for the same bounded capability, with failure and evidence recorded. A missing, modified, or incomplete Arch installation must be repaired with `matrix init --with-mattpocock`; never switch the active change to Prim.
-
-## Recovery
-
-Use Runtime commands instead of editing Matrix state:
-
-```powershell
-matrix workflow return design --reason design-gap
-matrix workflow return build --reason verification-failed
-matrix workflow return design --reason acceptance-or-design-gap
-matrix workflow return design --reason acceptance-or-design-gap # from Archive, before terminal archive
-matrix workflow abort --reason <requirement-cancelled|superseded|no-longer-valuable|blocked|other>
-```
-
-Return preserves the change but moves the current `verification.md` into revisioned evidence history, so the returned phase must produce fresh current evidence. Abort preserves the last phase and moves the terminal change into `.matrix/archive/`; it never undoes worktree changes.
-
-If any mutation reports `WORKFLOW_RECOVERY_REQUIRED`, stop normal phase work and run the read-only diagnosis:
-
-```powershell
-matrix workflow doctor
-```
-
-Never infer a repair target or strategy. Use only the exact command returned by doctor:
-
-```powershell
-matrix workflow doctor --repair --transaction <id> --strategy <continue|rollback>
-matrix workflow doctor --repair --lock <id>
-```
-
-## Optional Claude handoff
-
-`$matrix-claude` is an optional sidecar command used after the approved Design -> Build transition. It exports the matching approved contract to a Claude Code task package. It never changes the Matrix phase, workflow, guard result, or runtime state.
-Use it only when the user explicitly chooses Codex design with Claude Code implementation; never inject it into the standard path.
-
-## Cross-Cutting Skills
-
-### Handoff (`handoff`)
-When context is running low and work needs to continue in a fresh session, use `handoff` at any stage boundary. It compacts the conversation into a handoff document with suggested skills for the next agent. Save to the OS temp directory, not the workspace.
-
-## Rules
-
-- A phase can advance only through `matrix workflow transition`; run its guard first.
-- A phase can move backward only through one of the documented `matrix workflow return` intents.
+
+A correctly installed Arch capability that fails gets at most one Matrix-owned fallback for the same bounded capability, with failure and evidence recorded. A missing, modified, or incomplete Arch installation must be repaired with `matrix init --with-mattpocock`; never switch the active change to Prim.
+
+## Recovery
+
+Use Runtime commands instead of editing Matrix state:
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs return build --reason verification-failed
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason acceptance-or-design-gap
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason acceptance-or-design-gap # from Archive, before terminal archive
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs abort --reason <requirement-cancelled|superseded|no-longer-valuable|blocked|other>
+```
+
+Return preserves the change but moves the current `verification.md` into revisioned evidence history, so the returned phase must produce fresh current evidence. Abort preserves the last phase and moves the terminal change into `.matrix/archive/`; it never undoes worktree changes.
+
+If any mutation reports `WORKFLOW_RECOVERY_REQUIRED`, stop normal phase work and run the read-only diagnosis:
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor
+```
+
+Never infer a repair target or strategy. Use only the exact command returned by doctor:
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor --repair --transaction <id> --strategy <continue|rollback>
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor --repair --lock <id>
+```
+
+## Optional Claude handoff
+
+`$matrix-claude` is an optional sidecar command used after the approved Design -> Build transition. It exports the matching approved contract to a Claude Code task package. It never changes the Matrix phase, workflow, guard result, or runtime state.
+Use it only when the user explicitly chooses Codex design with Claude Code implementation; never inject it into the standard path.
+
+## Cross-Cutting Skills
+
+Matrix never nests user-invoked Matt Skills. When relevant, explain the reason and ask the user to invoke one explicitly: `setup-matt-pocock-skills` for one-time setup, `improve-codebase-architecture` for an out-of-band scan, `wayfinder` for generating a separate large-effort candidate, `handoff` at a context boundary, or `to-questionnaire` when another person owns blocking facts. `ask-matt`, `grill-with-docs`, `triage`, `to-spec`, `to-tickets`, `grill-me`, `teach`, and `wait-what` remain standalone. Matrix does not install or manage `implement` or raw `resolving-merge-conflicts`; preserve pre-existing copies as unmanaged extras and never suggest them inside an active Change.
+
+## Rules
+
+- A phase can advance only through `node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition`; run its guard first.
+- A phase can move backward only through one of the documented `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return` intents.
 - Full Build approval binds proposal, design, and plan. Lightweight Build approval binds its compact proposal, requires `transition build --confirmed`, and rejects project implementation changes made after initialization but before approval.
-- A successful Archive is always a two-step optimistic commit: run `matrix workflow archive --dry-run`, then pass its exact hash to `matrix workflow archive --expect-preflight <sha256>`. Never bypass the preflight.
-- `matrix workflow doctor` is read-only. Every transaction or stale-lock repair must explicitly bind the identity reported by doctor; do not edit or delete `.matrix/transactions/` or `.matrix/workflow.lock`.
-- Do not replace required evidence with an assertion that work is complete.
-- Pause for user confirmation at material architecture/scope decisions and before archive/commit.
-- On shortcut scope expansion, run `matrix workflow return design --reason design-gap`; Runtime upgrades the change to `full`. Never silently continue the old contract.
+- A successful Archive is always a two-step optimistic commit: run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs archive --dry-run`, then pass its exact hash to `node <matrix-skill-directory>/scripts/matrix-runtime.mjs archive --expect-preflight <sha256>`. Never bypass the preflight.
+- `node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor` is read-only. Every transaction or stale-lock repair must explicitly bind the identity reported by doctor; do not edit or delete `.matrix/transactions/` or `.matrix/workflow.lock`.
+- Do not replace required evidence with an assertion that work is complete.
+- Pause for user confirmation at material architecture/scope decisions and before archive/commit.
+- On shortcut scope expansion, run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap`; Runtime upgrades the change to `full`. Never silently continue the old contract.

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

@@ -1,4 +1,4 @@
-interface:
-  display_name: "Matrix"
-  short_description: "Route, resume, and govern development changes"
-  default_prompt: "Use $matrix to start or resume a development change."
+interface:
+  display_name: "Matrix"
+  short_description: "Route, resume, and govern development changes"
+  default_prompt: "Use $matrix to start or resume a development change."

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

@@ -1,11 +1,11 @@
-#!/usr/bin/env python3
-"""Compatibility adapter for the authoritative Node workflow exporter."""
-from __future__ import annotations
-
-import sys
-
-from matrix_state import run_runtime
-
-
-if __name__ == "__main__":
-    raise SystemExit(run_runtime(sys.argv[1:]))
+#!/usr/bin/env python3
+"""Compatibility adapter for the authoritative Node workflow exporter."""
+from __future__ import annotations
+
+import sys
+
+from matrix_state import run_runtime
+
+
+if __name__ == "__main__":
+    raise SystemExit(run_runtime(sys.argv[1:]))

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

@@ -1,60 +1,60 @@
-#!/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]:
-    primary = primary_runtime()
-    if primary is not None:
-        return [primary, "workflow", *args, "--json"]
-
-    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 node is not None and bundled.exists():
-        return [node, str(bundled), *args]
-
-    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())
+#!/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 node is not None and bundled.exists():
+        return [node, str(bundled), *args]
+
+    primary = primary_runtime()
+    if primary is not None:
+        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())

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.
----
-
+---
+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
-matrix workflow archive --dry-run
-matrix workflow archive --expect-preflight <sha256-returned-by-dry-run>
+
+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
-matrix workflow return design --reason acceptance-or-design-gap
-```
-
-After successful commit, the change is under `.matrix/archive/` and the workflow is complete.
+
+- `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."