@rosenfan/matrix 0.1.2 → 0.1.4

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

@@ -5,26 +5,38 @@ description: Open or resume the Matrix open phase by clarifying a development re
 
 # 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.
-
-## Arch
-
+Run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs 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`.
+
+## Prim
+
+Use Matrix's own capability to clarify the request and write the proposal.
+
+## Arch
+
 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.
+If progress is blocked by facts or decisions owned by another person, explain why `to-questionnaire` fits and ask the user to invoke it. Do not invoke the wrapper yourself.
+
+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. Ask the user to confirm when scope or risk is material.
-4. Run the guard and transition, then enter `$matrix-design`.
+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
-matrix workflow transition design
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard open
+# full
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition design
+# hotfix/tweak, only after explicit confirmation
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build --confirmed
 ```

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

@@ -8,8 +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 doctor
-```
-
-Report the returned change id, workflow, 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.
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor
+```
+
+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

@@ -5,4 +5,4 @@ description: Run a lightweight Matrix workflow for a bounded small development c
 
 # Matrix Tweak
 
-Start through `$matrix` with workflow `tweak` and preserve its frozen Prim or Arch orchestration. Keep proposal and design concise, but still define acceptance criteria and test seams. Arch invokes only capabilities whose normal task-fact triggers are present; shortcut workflows do not gain a fixed companion sequence or weaker evidence requirements. Use controlled Return and upgrade to full Matrix when the change crosses module, API, schema, or architecture boundaries.
+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

@@ -5,7 +5,9 @@ description: Verify the active Matrix change against its plan and review its dif
 
 # Matrix Verify
 
-Run the plan's acceptance commands and record their output summaries under `## Test evidence` in `artifacts/verification.md`.
+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,38 +29,53 @@ 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补充.
 
-## Orchestration
-
-Run `matrix workflow inspect` and read the frozen mode.
-
+## Orchestration
+
+Run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` and read the frozen mode.
+
 - **Prim**: Matrix performs the Standards and Spec review itself.
 - **Arch**: invoke `code-review` to produce both review axes; announce the invocation and reason.
 
 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.
+
+Under `## Review evidence`, preserve two substantive subsections named `### Standards` and `### Spec`. Arch must then ask the project Runtime to bind those results to the current revision:
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs review --source code-review --fixed-point <ref> --standards <passed|failed> --spec <passed|failed>
+```
+
+If `code-review` cannot run because the Git baseline is unavailable, the committed HEAD diff is empty, staged/unstaged/untracked candidate files exist, or the capability actually fails, document that limitation and use the single bounded fallback for this revision:
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs review --source matrix-fallback --reason <git-baseline-unavailable|empty-head-diff|uncommitted-worktree|capability-execution-failed> [--fixed-point <ref-for-empty-head-diff-or-uncommitted-worktree>] --standards <passed|failed> --spec <passed|failed>
+```
+
+Never label fallback output as a successful `code-review` run. `empty-head-diff` requires the fixed point so Runtime can verify the empty three-dot diff. `uncommitted-worktree` requires a fixed point and Runtime binds the staged, unstaged, and untracked candidate content into `candidate_hash`; any later change makes the receipt stale. If a receipt already exists or either axis failed, use a controlled Return before another attempt.
 
 ## Failure Handling
 
-If verification or review fails:
-- 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 verification or review fails:
+- If the issue is in the implementation, run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs 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 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason acceptance-or-design-gap`, then enter `$matrix-design`.
+
+Both Return paths rotate the current `verification.md` and any `review-receipt.json` into revisioned evidence history. Do not copy stale conclusions or receipts 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)
-3. Record test output under `## Test evidence`
+2. Run the approved validation commands (full plan or lightweight proposal)
+3. Record test output under `## Test evidence`
 4. Produce both Standards and Spec review axes through the selected orchestration mode
-6. Record findings under `## Review evidence`
+5. Record findings under `## Review evidence` with `### Standards` and `### Spec`
+6. In Arch, record the Runtime review receipt for the current revision
 7. Run the guard
 8. If it passes, transition to archive and enter `$matrix-archive`
 
 ```powershell
-matrix workflow guard verify
-matrix workflow transition archive
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard verify
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition archive
 ```
 
 ## Evidence Requirements
@@ -66,6 +83,7 @@ matrix workflow transition archive
 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
+2. **Review evidence** — Separate Standards and Spec findings from the selected review path
+3. **Arch review receipt** — Runtime-bound identity for the current Contract, evidence, workspace, and normal or fallback source
 
-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/README.md

@@ -1,6 +1,6 @@
 # Matrix Workflow
 
-An evidence-driven development workflow with Prim and Arch orchestration, inspired by [Comet](https://github.com/rpamis/comet). Matrix can work with its own capabilities or conditionally invoke a verified cohort of [Matt Pocock's agent skills](https://github.com/mattpocock/skills) without giving up lifecycle ownership.
+An evidence-driven development workflow with Prim and Arch orchestration, inspired by [Comet](https://github.com/rpamis/comet). Matrix can work with its own capabilities or conditionally invoke a verified cohort of [Matt Pocock's agent skills](https://github.com/mattpocock/skills) without giving up lifecycle ownership.
 
 English | **[中文](./README.zh-CN.md)**
 
@@ -27,38 +27,39 @@ English | **[中文](./README.zh-CN.md)**
 
 ## Why Matrix
 
-[Matt Pocock's skills](https://github.com/mattpocock/skills) provide focused capabilities such as `/grilling`, `/tdd`, and `/code-review`. Using independent tools without a lifecycle owner leads to common problems:
+[Matt Pocock's skills](https://github.com/mattpocock/skills) provide focused capabilities such as `/grilling`, `/tdd`, and `/code-review`. Using independent tools without a lifecycle owner leads to common problems:
 
 - **No process memory**: You grill, then implement, but there's no record of what was decided
 - **Phase confusion**: Did we finish design? Are we in build? Hard to tell after context loss
 - **Silent scope creep**: Requirements change mid-build without returning to design
 - **Missing evidence**: "Looks done" without verification proof
 
-Matrix solves this with one deterministic state machine, explicit phases, guard conditions, and artifact tracking — inspired by [Comet](https://github.com/rpamis/comet)'s phase-based approach. Skills can assist a phase, but Matrix always owns the lifecycle.
+Matrix solves this with one deterministic state machine, explicit phases, guard conditions, and artifact tracking — inspired by [Comet](https://github.com/rpamis/comet)'s phase-based approach. Skills can assist a phase, but Matrix always owns the lifecycle.
 
 ---
 
 ## What It Does
 
-Matrix provides two capability-orchestration modes over the same workflow:
-
-```
-open → design → build → verify → archive
-
-Prim: Matrix performs phase work itself
-Arch: Matrix invokes verified atomic Skills only when task facts trigger them
-```
-
-Recovery paths are controlled Runtime intents:
-
-```text
-build  --design-gap--------------------> design
-verify --verification-failed-----------> build
-verify --acceptance-or-design-gap------> design
-any active phase --abort--------------> aborted
-```
-
-Each phase:
+Matrix provides two capability-orchestration modes over two centrally defined workflow profiles:
+
+```
+full:                    open → design → build → verify → archive
+hotfix/tweak lightweight: open ─────────→ build → verify → archive
+
+Prim: Matrix performs phase work itself
+Arch: Matrix invokes verified atomic Skills only when task facts trigger them
+```
+
+Recovery paths are controlled Runtime intents:
+
+```text
+build  --design-gap--------------------> design
+verify --verification-failed-----------> build
+verify --acceptance-or-design-gap------> design
+any active phase --abort--------------> aborted
+```
+
+Each phase:
 - Has specific deliverables (artifacts)
 - Has guard conditions that must pass
 - Logs all transitions
@@ -68,9 +69,10 @@ Each phase:
 
 ## Prerequisites
 
-- [Claude Code](https://docs.anthropic.com/claude-code) and/or Codex installed
-- Node.js 18+ (for the installer)
-- Python is optional during the compatibility window; new installations run the bundled Node workflow runtime.
+- [Claude Code](https://docs.anthropic.com/claude-code) and/or Codex installed as the Skill host
+- Node.js 18+ and `npm` on `PATH` (for the Matrix CLI)
+- Python is optional during the compatibility window; new installations use the bundled Node workflow runtime.
+- Git is only needed when installing from GitHub or contributing to Matrix.
 
 ---
 
@@ -91,29 +93,51 @@ matrix init
 
 The interactive setup lets you:
 
-- Choose English or Chinese, project or global scope, and Claude Code, Codex, or both
+- Choose English or Chinese, project or global Matrix discovery scope, and Claude Code, Codex, or both
 - Copy skills (recommended) or symlink them for local development
-- Safely update an existing installation with an automatic backup
-- Install Matt Pocock's companion skills in the same flow
-- Choose **Prim** or **Arch** as the project default without disabling the other available mode
+- Safely reconfigure an existing installation with an automatic backup
+- Review all 25 official Matt Skills v1.2.3 roles and install the 23 compatible Skills into the target project
+- Choose **Prim** or **Arch** as the project default without disabling the other available mode
 
 For automation and CI:
 
 ```bash
 # Safe non-interactive installation for both verified platforms
-matrix init --yes --platform claude-code --platform codex --with-mattpocock
-
+matrix init --yes --platform claude-code --platform codex --with-mattpocock
+
 # Explicitly select the project default
 matrix init --yes --with-mattpocock --default-orchestration arch
+
+# Replace locally modified Matt Skills only after an explicit backup authorization
+matrix init --yes --with-mattpocock --force-matt
 
 # Preview exactly what would change (including backups) without writing
 matrix init --platform codex --dry-run --json
 
-# Inspect Matrix ownership, Matt Skills inheritance, and the selected platform
-matrix doctor --platform codex
+# Inspect Matrix ownership, project-local Matt compatibility, and the selected platform
+matrix doctor --platform codex
+```
+
+Update an initialized project:
+
+```bash
+# Check for a newer Matrix CLI, confirm the plan, then refresh this project's installed assets
+matrix update
+
+# Offline or local-development refresh: skip the npm registry and use the current CLI package
+matrix update --skip-self-update
+
+# Non-interactive update after CI has explicitly authorized writes
+matrix update --yes
 ```
 
-Until the npm package is published, install directly from GitHub:
+`matrix update` preserves the installation's scope, platforms, language, mode, and orchestration. It first validates a newer npm package in isolation, then re-runs the new CLI to refresh Matrix assets. It never downloads, installs, repairs, or deletes Matt Skills; after the Matrix update it reports the local Matt compatibility status and, when needed, points to `matrix init . --with-mattpocock`. npm and project assets are separate transactions: if asset refresh fails after a CLI upgrade, run `matrix update --skip-self-update` to retry.
+
+Matrix 0.1.4 is bound to Matt Skills v1.2.3 at commit `6acc160e4e0cd062dbbbd7a1b26ae92855edf07e`. `matrix init --with-mattpocock` always uses that exact archive and its reviewed 23-Skill compatible manifest, even if upstream has a newer release. The two official but incompatible Skills, `implement` and raw `resolving-merge-conflicts`, are not Matrix-managed or installed. Matrix scope controls Matrix Skill discovery only: Matt Skills and `.matrix/matt-installation.json` are always project-local. Global Matt copies are preserved but never used to complete project readiness.
+
+The language selected by `matrix init` controls the prose in new Matrix artifacts. Markdown headings required by Matrix guards remain stable English tokens; the artifact body is Chinese for `zh-CN` and English for `en`. A change freezes this language at creation time.
+
+To install directly from GitHub instead of npm:
 
 ```bash
 npm install --global github:Rosenfan/Matrix
@@ -121,10 +145,10 @@ npm install --global github:Rosenfan/Matrix
 
 Matrix installs:
 - `matrix/` — Entry point and state management
-- `matrix-open/` — Open phase and canonical proposal
-- `matrix-design/` — Design, plan, and Contract approval
-- `matrix-build/` — Bounded implementation and build evidence
-- `matrix-verify/` — Test and two-axis review evidence
+- `matrix-open/` — Open phase and canonical proposal
+- `matrix-design/` — Design, plan, and Contract approval
+- `matrix-build/` — Bounded implementation and build evidence
+- `matrix-verify/` — Test and two-axis review evidence
 - `matrix-archive/` — Archive phase
 - `matrix-hotfix/` — Shortcut for small bugs
 - `matrix-tweak/` — Shortcut for bounded changes
@@ -142,9 +166,9 @@ $matrix I want to add user authentication
 ```
 
 Matrix will:
-1. Initialize a change with workflow type `full` and frozen orchestration `prim|arch`
-2. Enter `open`; Prim works directly, while Arch invokes only proven requirement triggers
-3. Create `proposal.md` with Goal, Scope, Non-goals, Acceptance, Risks
+1. Initialize a change with workflow type `full` and frozen orchestration `prim|arch`
+2. Enter `open`; Prim works directly, while Arch invokes only proven requirement triggers
+3. Create `proposal.md` with Goal, Scope, Non-goals, Acceptance, Risks
 4. Guard check: are all sections substantive?
 5. If pass → transition to `design`
 
@@ -152,13 +176,13 @@ Matrix will:
 
 ## Workflow Phases
 
-| Phase | Arch capabilities (triggered, not a fixed sequence) | Deliverables | Guard Condition |
-|-------|------------------------------------------------------|--------------|-----------------|
-| **open** | `/grilling`, `/domain-modeling` | `proposal.md`; optional repository-standard context/ADR evidence | Goal, Scope, Non-goals, Acceptance, Risks present |
-| **design** | `/domain-modeling`, `/research`, `/wayfinder`, `/prototype`, `/codebase-design` | `design.md`, `plan.md` | Decisions, Test seams, Steps documented |
-| **build** | `/tdd`, `/diagnosing-bugs`, `/resolving-merge-conflicts` | Code, `verification.md` | Exact approved Contract matches; build evidence recorded |
-| **verify** | `/code-review` | Test & review evidence | Test and review evidence present |
-| **archive** | None; Matrix-owned in both modes | Archive record | Verify guard passed |
+| Phase | Arch capabilities (triggered, not a fixed sequence) | Deliverables | Guard Condition |
+|-------|------------------------------------------------------|--------------|-----------------|
+| **open** | `/grilling`, `/domain-modeling` | `proposal.md`; optional repository-standard context/ADR evidence | Goal, Scope, Non-goals, Acceptance, Risks present |
+| **design** | `/domain-modeling`, `/research`, `/prototype`, `/codebase-design`, conditional `/writing-for-agents` | `design.md`, `plan.md` | Decisions, Test seams, Steps documented |
+| **build** | `/tdd`, `/diagnosing-bugs`, conditional `/writing-for-agents` and generate-only `/wizard` | Code, `verification.md` | Exact approved Contract matches; build evidence recorded |
+| **verify** | `/code-review` | Test evidence, two-axis review, Arch receipt | Evidence is substantive; Arch receipt matches the current Contract, review, and workspace |
+| **archive** | None; Matrix-owned in both modes | Archive record | Verify guard passed |
 
 ---
 
@@ -172,45 +196,50 @@ State is stored in `.matrix/`:
 ├── config.yaml
 ├── changes/
 │   └── <change-id>/
-│       ├── matrix.yaml      # Canonical workflow, orchestration, phase, status, revision
-│       ├── events.jsonl
-│       └── artifacts/
-│           ├── proposal.md
-│           ├── design.md
-│           ├── plan.md
-│           ├── verification.md
-│           └── evidence-history/
-└── archive/
-```
+│       ├── matrix.yaml      # Canonical workflow, orchestration, phase, status, revision
+│       ├── workspace-baseline.json # Lightweight implementation-order boundary
+│       ├── events.jsonl
+│       └── artifacts/
+│           ├── proposal.md
+│           ├── design.md
+│           ├── plan.md
+│           ├── verification.md
+│           └── evidence-history/
+└── archive/
+```
 
 The state machine enforces transitions:
 
 ```bash
-# Check guard
-matrix workflow guard open
-
-# Advance (only if guard passes)
-matrix workflow transition design
-
-# Return from verification failure; stale evidence is retained in history
-matrix workflow return build --reason verification-failed
-
-# Abort without deleting artifacts or undoing worktree changes
-matrix workflow abort --reason requirement-cancelled
-
-# Final Archive is a mandatory two-step optimistic commit
-matrix workflow archive --dry-run
-matrix workflow archive --expect-preflight <sha256-returned-by-dry-run>
-
-# Diagnose an interrupted Workflow without writing
-matrix workflow doctor
-
-# Repair only the exact transaction or stale lock reported by doctor
-matrix workflow doctor --repair --transaction <id> --strategy <continue|rollback>
-matrix workflow doctor --repair --lock <id>
-```
-
-`matrix.yaml` is the only canonical workflow/orchestration/phase/status/revision record, using `matrix/change/v2`. The resolved `prim|arch` value is frozen at initialization. Older schemas are rejected without mutation. The Design -> Build transition records a SHA-256 identity of the exact bytes of `proposal.md`, `design.md`, and `plan.md`; any byte change blocks Build, Verify, Archive, and Claude export until a controlled Return to Design and a new approval. Final Archive requires a read-only dry-run and a hash-bound commit; Runtime recomputes the protected change-directory manifest inside the Archive boundary and rejects drift. Every multi-file Workflow mutation is protected by a durable journal under `.matrix/transactions/`. `matrix workflow doctor` is read-only, and recovery requires the exact transaction/strategy or lock identity it reports. Terminal journals become bounded audit receipts; unresolved or conflicting journals are never automatically deleted.
+# Check guard
+matrix workflow guard open
+
+# Advance (only if guard passes)
+matrix workflow transition design
+
+# Lightweight: approve the compact proposal and enter Build
+matrix workflow transition build --confirmed
+
+# Return from verification failure; stale evidence is retained in history
+matrix workflow return build --reason verification-failed
+
+# Abort without deleting artifacts or undoing worktree changes
+matrix workflow abort --reason requirement-cancelled
+
+# Final Archive is a mandatory two-step optimistic commit
+matrix workflow archive --dry-run
+matrix workflow archive --expect-preflight <sha256-returned-by-dry-run>
+# hotfix/tweak commit command additionally carries --confirmed
+
+# Diagnose an interrupted Workflow without writing
+matrix workflow doctor
+
+# Repair only the exact transaction or stale lock reported by doctor
+matrix workflow doctor --repair --transaction <id> --strategy <continue|rollback>
+matrix workflow doctor --repair --lock <id>
+```
+
+`matrix.yaml` is the only canonical workflow/orchestration/phase/status/revision record, using `matrix/change/v2`. Full approval binds the exact bytes of proposal/design/plan. Lightweight approval binds the compact proposal, requires explicit confirmation, and compares the project with its initialization baseline so implementation cannot precede approval. Contract drift blocks later phases. Final Archive uses a read-only dry-run and hash-bound commit; shortcut workflows additionally require explicit confirmation. Multi-file mutations remain protected by durable journals.
 
 ---
 
@@ -222,6 +251,8 @@ matrix workflow doctor --repair --lock <id>
 | **hotfix** | Reproducible small bugs | Simplified: open → build → verify → archive |
 | **tweak** | Bounded changes, no API/schema impact | Simplified: open → build → verify → archive |
 
+Hotfix and tweak reference the same internal `lightweight` transition profile. They differ only in routing and evidence: hotfix requires reproduction/root-cause/regression evidence; tweak requires behavior-boundary, diff, and scope-review evidence.
+
 ---
 
 ## Special Feature: matrix-claude
@@ -252,30 +283,34 @@ The sidecar does NOT change Matrix state. It's a pure export — like taking a s
 
 ---
 
-## Integration with Matt Pocock's Skills
-
-Prim uses Matrix's own capability. Arch uses one initialization-verified cohort of ten atomic capabilities:
-
-| Phase | Capability | Trigger |
-|---|---|---|
-| open | `/grilling` | Material ambiguity or explicit stress-test request |
-| open/design | `/domain-modeling` | Unclear vocabulary, invariants, or architectural decisions |
-| design | `/research` | Required external facts are unavailable in the repository |
-| design | `/wayfinder` | Module ownership or dependency seams are unknown |
+## Integration with Matt Pocock's Skills
+
+Prim uses Matrix's own capability. Matrix reviews all 25 official Matt v1.2.3 roles, installs the 23 compatible Skills, and lets Arch automatically invoke only this reviewed ten-capability cohort:
+
+| Phase | Capability | Trigger |
+|---|---|---|
+| open | `/grilling` | Material ambiguity or explicit stress-test request |
+| open/design | `/domain-modeling` | Unclear vocabulary, invariants, or architectural decisions |
+| design | `/research` | Required external facts are unavailable in the repository |
 | design | `/prototype` | A material design question needs disposable evidence |
 | design | `/codebase-design` | A deep-module, interface, or test-seam decision remains |
+| design/build | `/writing-for-agents` | The Contract changes agent-facing instructions or pointer-reached documents |
 | build | `/tdd` | Observable behavior changes at a testable seam |
 | build | `/diagnosing-bugs` | An actual failure exists and root cause is unknown |
-| build | `/resolving-merge-conflicts` | A merge or rebase conflict is in progress |
+| build | `/wizard` | The Contract requires generated human-run shell steps; Matrix never runs them end-to-end |
 | verify | `/code-review` | Standards and Spec review evidence is required |
 
-`grill-with-docs`, `implement`, and `improve-codebase-architecture` are not Matrix-managed or automatically invoked. Existing user-installed copies are preserved as unmanaged extras. A companion never transitions, commits, archives, or writes Matrix state.
+Matrix may recommend but never nest these user-invoked handoffs: `setup-matt-pocock-skills`, `improve-codebase-architecture`, `wayfinder`, `handoff`, and `to-questionnaire`. The user explicitly runs them outside the active phase; selected output may enter a governed Change.
+
+Arch records a Runtime-managed review receipt after `code-review`, binding its fixed point and committed HEAD diff to the current Contract, review evidence, and workspace. A normal `code-review` receipt requires a clean candidate worktree outside Matrix-managed assets. When Git has no usable baseline, the committed diff is empty, staged/unstaged/untracked candidate files still exist, or the correctly installed capability fails, Matrix may perform one explicitly labelled same-capability fallback for that revision. The `uncommitted-worktree` fallback binds both the fixed point and a content hash of the complete worktree candidate. Installation-integrity failures never fall back. A heading or self-description without the matching receipt cannot advance Verify.
+
+Installed standalone Skills are `ask-matt`, `grill-with-docs`, `triage`, `to-spec`, `to-tickets`, `grill-me`, `teach`, and `wait-what`. `implement` and raw `resolving-merge-conflicts` are incompatible because they can take over TDD/review/staging/commit effects owned by Matrix, so 0.1.4 neither installs nor manages them. Pre-existing copies are preserved and reported as unmanaged extras. Installation never grants automatic invocation, and no companion may transition, commit, archive, recover, or write Matrix state.
 
 ---
 
 **Key difference**: Matt Pocock's skills are individual tools. Matrix adds:
 - **State persistence**: Survives context loss
-- **Phase enforcement**: Can't skip design and jump to build
+- **Phase enforcement**: Full cannot skip Design; lightweight cannot edit implementation before its confirmed Open Contract
 - **Evidence requirements**: Guards check for artifacts, not assertions
 - **Transition logging**: Full audit trail of phase changes