@rosenfan/matrix 0.1.2 → 0.1.3

package/.claude/skills/matrix/SKILL.md

@@ -3,9 +3,11 @@ 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.
+# 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
 
@@ -21,57 +23,57 @@ If and only if the `matrix` executable is reported as absent, run the bundled fa
 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 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.
-
-Both modes share the same Matrix phase graph, artifacts, guards, Return/Abort, Contract, transactions, and Archive protocol. Companion Skills never write Matrix state, transition, commit, archive, or create competing workflow artifacts. Announce each Arch capability and trigger before invoking it; do not ask for redundant per-Skill permission.
-
-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 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.
+
+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.
+`$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
 
@@ -80,11 +82,11 @@ When context is running low and work needs to continue in a fresh session, use `
 
 ## 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.
-- The Build transition approves the exact bytes of proposal, design, and plan. Any later byte change blocks Build, Verify, Archive, and Claude export until a controlled Return to Design and a new Build 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 scope expansion, run `matrix workflow return design --reason design-gap` and enter `$matrix-design`; never silently continue the old plan.
+- 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.
+- 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.

package/.claude/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/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]:
+    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())

package/.claude/skills/matrix-archive/SKILL.md

@@ -1,33 +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.
 
-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
+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>
 ```
 
 Bare Archive is rejected. Runtime reacquires the project Archive boundary and recomputes the entire protected change-directory manifest before committing.
-
-- `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.
+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.

package/.claude/skills/matrix-build/SKILL.md

@@ -3,38 +3,40 @@ 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 `matrix workflow inspect`. Read `plan.md`, `design.md`, the approved Contract, and repository instructions. Implement only the frozen scope.
-
-## Prim
-
-Use Matrix's own implementation and test discipline.
-
-## Arch
+# Matrix Build
 
-- 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 `resolving-merge-conflicts` only for an in-progress merge or rebase conflict.
+Run `matrix workflow 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.
 
-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.
+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 `resolving-merge-conflicts` only for an in-progress merge or rebase conflict.
+
+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**:
-
-```powershell
-matrix workflow 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.
+If implementation exposes a scope or design change, **stop and run**; a lightweight change is upgraded to full by this Return:
+
+```powershell
+matrix workflow 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 commands, outcomes, capability invocations and fallbacks under `## Build evidence`.
-4. Run the guard and transition, then enter `$matrix-verify`.
+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
 matrix workflow guard build

package/.claude/skills/matrix-claude/SKILL.md

@@ -3,14 +3,16 @@ 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`.
+# 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
+- 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
 
@@ -19,16 +21,16 @@ Use `$matrix-claude` when:
 The exporter performs this read-only check before writing anything:
 
 ```powershell
-matrix workflow guard build
+matrix workflow 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.
+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.
+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.
@@ -43,7 +45,7 @@ matrix workflow export --task-id <ID> --target fnsec --apply-fnsec-board
 
 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
+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)
@@ -91,6 +93,6 @@ 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
+- 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/skills/matrix-design/SKILL.md

@@ -3,34 +3,38 @@ 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
-
-Run `matrix workflow 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.
+# Matrix Design
 
-## Arch
+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.
 
-Invoke only capabilities whose task-fact trigger is proven:
+Use `artifact_language` from `matrix workflow inspect` for all design and plan prose. Keep Runtime-required English heading tokens unchanged.
 
-- `domain-modeling` for unclear vocabulary, invariants, or architectural decisions;
-- `research` when required external facts cannot be established from the repository;
-- `wayfinder` when module ownership or dependency seams are unknown;
-- `prototype` when a material design decision needs disposable empirical evidence;
-- `codebase-design` when a deep-module, interface, or test-seam decision remains.
-
-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.
+Run `matrix workflow 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;
+- `wayfinder` when module ownership or dependency seams are unknown;
+- `prototype` when a material design decision needs disposable empirical evidence;
+- `codebase-design` when a deep-module, interface, or test-seam decision remains.
+
+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.
 
 ## 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.
+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
 matrix workflow guard design
@@ -52,16 +56,16 @@ 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
+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`:
+After Claude Code completes and returns results, run the Build guard and enter `$matrix-verify`:
 
 ```powershell
-matrix workflow guard build
-matrix workflow transition verify
+matrix workflow guard build
+matrix workflow transition verify
 ```
 
 Then enter `$matrix-verify` to verify the implementation.

package/.claude/skills/matrix-hotfix/SKILL.md

@@ -5,4 +5,4 @@ description: Run a constrained Matrix workflow for a reproducible small bug. Use
 
 # Matrix Hotfix
 
-Start through `$matrix` with workflow `hotfix` and preserve its frozen Prim or Arch orchestration. Prim diagnoses directly. Arch invokes `diagnosing-bugs` only when an actual failure exists and root cause is not established. Write the compact proposal, continue through the normal Matrix gates, and keep all companion output subordinate to Matrix artifacts and state. If the bug requires architecture change, a new public API, schema work, or broad coordination, use controlled Return and upgrade the work to a full Matrix change.
+Start through `$matrix` with workflow `hotfix`. It uses the shared lightweight lifecycle `open → build → verify → archive`; there is no separate hotfix state machine. Before Build, record expected/actual behavior and a reproducible failure signal, present the compact Contract, and wait for confirmation. Build records reproduction and root-cause evidence; Verify records regression evidence. If the bug requires architecture, public API, schema, or broad coordination, use controlled Return to upgrade the change to full.

package/.claude/skills/matrix-open/SKILL.md

@@ -3,28 +3,38 @@ name: matrix-open
 description: Open or resume the Matrix open phase by clarifying a development request into an evidence-backed proposal. Use after $matrix initializes a change or when the active Matrix phase is open.
 ---
 
-# Matrix Open
-
-Run `matrix workflow inspect`, read the active change and its frozen `orchestration`, then produce `artifacts/proposal.md` containing exactly these substantive sections: `## Goal`, `## Scope`, `## Non-goals`, `## Acceptance`, and `## Risks`.
-
-## Prim
-
-Use Matrix's own capability to clarify the request and write the proposal.
+# Matrix Open
 
-## Arch
+Run `matrix workflow inspect` and follow its `profile` and `evidence_policy`.
 
-Invoke `grilling` only when material ambiguity remains or the user asks to stress-test the request. Invoke `domain-modeling` only when domain vocabulary, invariants, or an architectural decision is unclear. Announce the capability and reason before invoking it; selecting Arch already authorizes triggered capabilities.
+Use its `artifact_language` for all proposal prose. Keep the required English heading tokens exactly as specified for Runtime guards; only the text beneath them is localized.
 
-Companion output is evidence for the Matrix proposal. It must not create another workflow, proposal, confirmation state, or phase transition. If a correctly installed capability fails, perform at most one Matrix-owned fallback for that same capability and record the failure and evidence. Installation-integrity failures require `matrix init --with-mattpocock` and are not eligible for fallback.
+- **full**: produce `proposal.md` with `## Goal`, `## Scope`, `## Non-goals`, `## Acceptance`, and `## Risks`, then continue to Design.
+- **lightweight**: produce the complete compact Contract before editing project implementation. Include `## Goal`, `## Scope`, `## Non-goals`, `## Approach`, `## Acceptance`, `## Validation`, `## Risks`, and `## Upgrade conditions`.
+- **hotfix evidence**: also include `## Expected behavior`, `## Actual behavior`, and `## Reproduction`.
+- **tweak evidence**: also include `## Current behavior`, `## Preserved behavior`, and `## Diff boundary`.
 
-## Process
+## Prim
+
+Use Matrix's own capability to clarify the request and write the proposal.
 
-1. Resolve only ambiguities required by the active workflow.
-2. Write the canonical proposal and synchronize material companion conclusions into it.
-3. Ask the user to confirm when scope or risk is material.
-4. Run the guard and transition, then enter `$matrix-design`.
+## Arch
 
-```powershell
-matrix workflow guard open
-matrix workflow transition design
-```
+Invoke `grilling` only when material ambiguity remains or the user asks to stress-test the request. Invoke `domain-modeling` only when domain vocabulary, invariants, or an architectural decision is unclear. Announce the capability and reason before invoking it; selecting Arch already authorizes triggered capabilities.
+
+Companion output is evidence for the Matrix proposal. It must not create another workflow, proposal, confirmation state, or phase transition. If a correctly installed capability fails, perform at most one Matrix-owned fallback for that same capability and record the failure and evidence. Installation-integrity failures require `matrix init --with-mattpocock` and are not eligible for fallback.
+
+## Process
+
+1. Resolve only ambiguities required by the active workflow.
+2. Write the canonical proposal and synchronize material companion conclusions into it.
+3. For full, ask for confirmation when scope or risk is material, then enter Design.
+4. For lightweight, always present the compact Contract and wait for explicit confirmation before entering Build.
+
+```powershell
+matrix workflow guard open
+# full
+matrix workflow transition design
+# hotfix/tweak, only after explicit confirmation
+matrix workflow transition build --confirmed
+```