@rosenfan/matrix 0.1.1 → 0.1.3

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

@@ -3,47 +3,49 @@ 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`, `run-state.json`, 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 design phase guard has passed (design is frozen)
+- The active change is in Build and the Design -> Build transition has approved the contract
 - You want Claude Code (instead of Codex) to implement the design
 - You need a bounded task package with all implementation details
 
 ## Preconditions
 
-The exporter performs this read-only check before writing anything:
+The exporter performs this read-only check before writing anything:
 
-```powershell
-matrix workflow guard design
-```
-
-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.
+```powershell
+matrix workflow guard build
+```
 
-If the design guard fails, stop and return to `$matrix-design`. The exporter reads the active change's `proposal.md`, `design.md`, and `plan.md`; it does not invent missing facts.
+If `matrix` is genuinely absent from PATH, use the bundled runtime from the installed root Matrix Skill. Do not fall back when the primary command starts and returns an error.
+
+If the build guard reports `CONTRACT_CHANGED` or `CONTRACT_UNAPPROVED`, return to `$matrix-design` and approve a new contract through Build. The exporter reads the approved bytes of `proposal.md`, `design.md`, and `plan.md`; it does not invent missing facts.
 
 ## Export
 
-Treat explicit invocation of `$matrix-claude` as the user's choice of Claude Code as the implementation actor. Generate the package with the deterministic exporter; it refuses a missing design guard 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.
-matrix workflow export --task-id <ID> --target generic
-
-# FnSec: exports its formal task package. Add --apply-fnsec-board only when
-# active.md is NO_ACTIVE_OBJECTIVE; an existing task is never overwritten.
-matrix workflow export --task-id <ID> --target fnsec --apply-fnsec-board
-```
+```powershell
+# Generic project: only exports a Matrix artifact.
+matrix workflow export --task-id <ID> --target generic
+
+# FnSec: exports its formal task package. Add --apply-fnsec-board only when
+# active.md is NO_ACTIVE_OBJECTIVE; an existing task is never overwritten.
+matrix workflow export --task-id <ID> --target fnsec --apply-fnsec-board
+```
 
 ## Task Package Contents
 
 The exported package (`artifacts/claude-task.md`) contains everything Claude Code needs to implement and produce evidence for `$matrix-verify`:
 
-1. **Task ID and execution actor**: Claude Code
+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)
@@ -76,12 +78,12 @@ After Claude Code completes and evidence is present:
 
 1. Run build guard to verify evidence:
    ```powershell
-   matrix workflow guard build
+   matrix workflow guard build
    ```
 
 2. If guard passes, transition to verify:
    ```powershell
-   matrix workflow transition verify
+   matrix workflow transition verify
    ```
 
 3. Enter `$matrix-verify` to继续验证流程
@@ -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 `design` phase until explicitly transitioned
+- 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,37 +3,41 @@ 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
+# 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 `matrix workflow inspect` for all design and plan prose. Keep Runtime-required English heading tokens unchanged.
+
+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`.
 
-Read the active proposal. Write `artifacts/design.md` with `## Decisions`, `## Boundaries`, `## Test seams`, and `## Risks`; write `artifacts/plan.md` with `## Steps`, `## Validation`, and `## Stop conditions`.
+## Prim
 
-## Skills to Use (Recommended Order)
+Use Matrix's own capability to investigate the repository and design the change.
 
-1. **`domain-modeling`** — First, establish or refine the domain vocabulary. Update `CONTEXT.md` with any new terms from the proposal. This ensures all subsequent design work uses consistent language.
+## Arch
 
-2. **`research`** — If the design requires investigating external APIs, documentation, or specifications, spawn a background research agent. It will investigate primary sources and write findings to a Markdown file.
+Invoke only capabilities whose task-fact trigger is proven:
 
-3. **`wayfinder`** — For complex codebases, use this to explore and understand existing module structure, seams, and dependencies before making design decisions.
+- `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.
 
-4. **`prototype`** — When a design question needs empirical validation (e.g., "does this state model feel right?" or "what should this UI look like?"), build a throwaway prototype. Two modes:
-   - **Logic prototype**: interactive terminal app to test state machines
-   - **UI prototype**: multiple UI variations on a single route
+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.
 
-5. **`codebase-design`** — Finally, define module boundaries, interfaces, and test seams. Use its "design-it-twice" pattern to explore alternative approaches before committing.
+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. Start with `domain-modeling` to ground the vocabulary
-2. Use `research` for external dependencies (runs in background)
-3. Use `wayfinder` to explore complex existing code
-4. Use `prototype` to validate key design questions
-5. Use `codebase-design` to finalize module boundaries
-6. Confirm material architecture choices with the user before freezing
-7. Run the guard
-8. If guard passes, ask the user to choose implementation method:
+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
+matrix workflow guard design
 ```
 
 ## Implementation Decision Point
@@ -45,24 +49,23 @@ After the design guard passes, the user chooses:
 Run transition and enter `$matrix-build`:
 
 ```powershell
-matrix workflow transition build
+matrix workflow transition build
 ```
 
 Then enter `$matrix-build` to implement directly in this session.
 
 ### Option B: Use Claude Code for implementation
 
-Run `$matrix-claude` to export the frozen design as a bounded task package. This:
-- Does NOT change Matrix phase or state
+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 transition and enter `$matrix-verify`:
+After Claude Code completes and returns results, run the Build guard and enter `$matrix-verify`:
 
 ```powershell
-matrix workflow transition build
-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

@@ -1,8 +1,8 @@
----
-name: matrix-hotfix
-description: Run a constrained Matrix workflow for a reproducible small bug. Use for a bug fix that has no material architecture, API, schema, or multi-module coordination impact.
----
-
-# Matrix Hotfix
-
-Start through `$matrix` with workflow `hotfix`, then use `diagnosing-bugs` to establish a red-capable feedback loop before changing code. Write the compact proposal, then continue through Matrix gates. If the bug requires architecture change, a new public API, schema work, or broad coordination, pause and ask whether to upgrade to full `$matrix`.
+---
+name: matrix-hotfix
+description: Run a constrained Matrix workflow for a reproducible small bug. Use for a bug fix that has no material architecture, API, schema, or multi-module coordination impact.
+---
+
+# Matrix Hotfix
+
+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,31 +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
+# Matrix Open
+
+Run `matrix workflow inspect` and follow its `profile` and `evidence_policy`.
+
+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.
+
+- **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`.
 
-Read the active Matrix change with `matrix workflow inspect`. Produce `artifacts/proposal.md` containing exactly these substantive sections: `## Goal`, `## Scope`, `## Non-goals`, `## Acceptance`, and `## Risks`.
+## Prim
 
-## Skills to Use
+Use Matrix's own capability to clarify the request and write the proposal.
 
-For a **full workflow**, use `grill-with-docs` to resolve ambiguity before writing the proposal. This skill automatically:
+## Arch
 
-1. Runs a `/grilling` session to stress-test the plan through relentless Q&A
-2. Invokes `/domain-modeling` to establish shared vocabulary
-3. Creates or updates `CONTEXT.md` with domain terms
-4. Creates ADRs (Architecture Decision Records) for significant decisions
+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.
 
-For **hotfix/tweak**, use `grilling` directly (without docs) — keep it concise but preserve acceptance criteria.
+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. Run `grill-with-docs` (or `grilling` for hotfix/tweak)
-2. Write `proposal.md` with all required sections
-3. Ask the user to confirm when scope or risk is material
-4. Run the guard
-5. If guard passes, run transition to advance to design phase
-6. **Then enter `$matrix-design` to continue the workflow**
-
-```powershell
+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
+```

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

@@ -8,7 +8,8 @@ description: Inspect the active Matrix workflow and report its disk-backed phase
 Run the same Matrix state kernel used by the main entry and every phase Skill:
 
 ```powershell
-matrix workflow inspect
+matrix workflow inspect
+matrix workflow doctor
 ```
 
-Report the returned change id, workflow, phase, guard result, and `next_skill`. Do not infer status from conversation history and do not modify state. If the guard is failing, name the missing evidence and direct the user to the current phase Skill.
+Report the returned change id, workflow, `profile`, `evidence_policy`, frozen `orchestration`, phase, guard result, `next_skill`, Workflow health, unfinished transactions, available strategies, and exact recovery commands. If Arch integrity fails, identify the affected platform/Skill facts and report `matrix init --with-mattpocock`; do not reinterpret the change as Prim. Both commands are read-only. Do not infer status from conversation history, run `--repair`, or modify state. If the guard is failing, name the missing evidence and direct the user to the current phase Skill.

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

@@ -1,8 +1,8 @@
----
-name: matrix-tweak
-description: Run a lightweight Matrix workflow for a bounded small development change. Use for a small request with no schema, public API, architecture, or cross-module coordination impact.
----
-
-# Matrix Tweak
-
-Start through `$matrix` with workflow `tweak`. Keep proposal and design concise, but still define acceptance criteria and test seams. Upgrade to full `$matrix` when the change crosses module, API, schema, or architecture boundaries.
+---
+name: matrix-tweak
+description: Run a lightweight Matrix workflow for a bounded small development change. Use for a small request with no schema, public API, architecture, or cross-module coordination impact.
+---
+
+# Matrix Tweak
+
+Start through `$matrix` with workflow `tweak`. It uses the shared lightweight lifecycle `open → build → verify → archive`; there is no separate tweak state machine or Design phase. Before editing implementation, define current/preserved behavior, the diff boundary, acceptance, and validation in the compact proposal, present it, and wait for confirmation. Build and Verify must prove scope and diff alignment. Use controlled Return to upgrade to full when the change crosses module, API, schema, or architecture boundaries.

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

@@ -3,9 +3,11 @@ name: matrix-verify
 description: Verify the active Matrix change against its plan and review its diff. Use when the active Matrix phase is verify.
 ---
 
-# Matrix Verify
-
-Run the plan's acceptance commands and record their output summaries under `## Test evidence` in `artifacts/verification.md`.
+# Matrix Verify
+
+Run the approved Contract's acceptance commands and record their output summaries under `## Test evidence` in `artifacts/verification.md`.
+
+Write verification prose in `artifact_language` from inspect while preserving the required English evidence headings.
 
 ## Input Sources
 
@@ -27,49 +29,38 @@ Before starting verification, ensure:
 
 If these are missing (e.g., Claude Code didn't produce complete evidence), return to `$matrix-build` or ask Claude Code to补充.
 
-## Skills to Use
-
-### Primary: `code-review`
-
-Use the `code-review` skill to perform a two-axis review of the diff:
+## Orchestration
 
-1. **Standards axis** — Does the code conform to this repo's documented coding standards? Includes a "smell baseline" (Fowler code smells) even when no standards are documented.
+Run `matrix workflow inspect` and read the frozen mode.
 
-2. **Spec axis** — Does the code faithfully implement the originating issue/PRD/spec? Checks for:
-   - Missing or partial requirements
-   - Scope creep (behavior not asked for)
-   - Wrong implementations of required behavior
+- **Prim**: Matrix performs the Standards and Spec review itself.
+- **Arch**: invoke `code-review` to produce both review axes; announce the invocation and reason.
 
-Both axes run as parallel sub-agents and report separately. Record findings under `## Review evidence` in `artifacts/verification.md`.
-
-### Optional: `improve-codebase-architecture`
-
-After verification passes, if the change touched modules that could be deepened, use `improve-codebase-architecture` to scan for shallow-module opportunities. This is advisory — skip it for simple changes or when time is constrained.
+Review findings are inputs to Matrix Verify; a companion cannot decide the phase outcome, broaden approved architecture, transition, or archive. Do not invoke post-review architecture wrappers. A correctly installed review capability gets at most one same-capability Matrix fallback; installation-integrity failure stops verification.
 
 ## Failure Handling
 
 If verification or review fails:
-- If the issue is in the implementation → **return to `$matrix-build`** or ask Claude Code to fix
-- If the issue is in the plan/design → return to `$matrix-design`
+- If the issue is in the implementation, run `matrix workflow return build --reason verification-failed`, then enter `$matrix-build` or ask Claude Code to fix.
+- If the issue is in the acceptance criteria or design, run `matrix workflow return design --reason acceptance-or-design-gap`, then enter `$matrix-design`.
+
+Both Return paths rotate the current `verification.md` into revisioned evidence history. Do not copy stale conclusions back into the new current evidence.
 
 If documents or public behavior changed, record the required synchronization work before the guard.
 
 ## Process
 
 1. Check that `artifacts/verification.md` exists with `## Build evidence`
-2. Run the plan's acceptance commands (from `plan.md` `## Validation` section)
+2. Run the approved validation commands (full plan or lightweight proposal)
 3. Record test output under `## Test evidence`
-4. Load `code-review` skill
-5. Run both axes (Standards + Spec) in parallel
+4. Produce both Standards and Spec review axes through the selected orchestration mode
 6. Record findings under `## Review evidence`
-7. Optionally run `improve-codebase-architecture`
-8. Run the guard
-9. If guard passes, run transition to advance to archive phase
-10. **Then enter `$matrix-archive` to continue the workflow**
+7. Run the guard
+8. If it passes, transition to archive and enter `$matrix-archive`
 
 ```powershell
-matrix workflow guard verify
-matrix workflow transition archive
+matrix workflow guard verify
+matrix workflow transition archive
 ```
 
 ## Evidence Requirements
@@ -79,4 +70,4 @@ The guard checks for:
 1. **Test evidence** — Output from running the plan's validation commands
 2. **Review evidence** — Findings from the two-axis code review
 
-Both must be present and substantive (>40 chars each) to pass the guard.
+Full requires Test and Review evidence. Hotfix additionally requires `## Regression evidence`; tweak additionally requires `## Scope review evidence`.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Rosen
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Rosen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.