@rosenfan/matrix 0.1.2 → 0.1.3

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.
+matrix workflow inspect
+matrix workflow 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

@@ -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,34 +29,34 @@ 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.
-
-- **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.
+## Orchestration
+
+Run `matrix workflow 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.
 
 ## 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 `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. Produce both Standards and Spec review axes through the selected orchestration mode
+4. Produce both Standards and Spec review axes through the selected orchestration mode
 6. Record findings under `## Review evidence`
-7. Run the guard
-8. If it passes, transition to archive and enter `$matrix-archive`
+7. Run the guard
+8. If it passes, transition to archive and enter `$matrix-archive`
 
 ```powershell
 matrix workflow guard verify
@@ -68,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/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:
+Matrix provides two capability-orchestration modes over two centrally defined workflow profiles:
 
 ```
-open → design → build → verify → archive
+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:
+```
+
+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.
 
 ---
 
@@ -89,31 +91,48 @@ cd /path/to/your/project
 matrix init
 ```
 
-The interactive setup lets you:
+The interactive setup lets you:
 
 - Choose English or Chinese, project or global 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
+- Install Matt Pocock's companion skills in the same flow
+- Choose **Prim** or **Arch** as the project default without disabling the other available mode
 
-For automation and CI:
+For automation and CI:
 
 ```bash
 # Safe non-interactive installation for both verified platforms
-matrix init --yes --platform claude-code --platform codex --with-mattpocock
-
-# Explicitly select the project default
-matrix init --yes --with-mattpocock --default-orchestration arch
+matrix init --yes --platform claude-code --platform codex --with-mattpocock
+
+# Explicitly select the project default
+matrix init --yes --with-mattpocock --default-orchestration arch
 
 # 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
-```
-
-Until the npm package is published, install directly from GitHub:
+# Inspect Matrix ownership, Matt Skills inheritance, 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
+```
+
+`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 project assets. npm and project assets are separate transactions: if asset refresh fails after a CLI upgrade, run `matrix update --skip-self-update` to retry. Use `matrix init` to change installation choices, and `matrix doctor` for read-only diagnosis.
+
+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 +140,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 +161,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 +171,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`, `/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 |
 
 ---
 
@@ -173,44 +192,49 @@ State is stored in `.matrix/`:
 ├── changes/
 │   └── <change-id>/
 │       ├── 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/
-```
+│       └── artifacts/
+│           ├── proposal.md
+│           ├── design.md
+│           ├── plan.md
+│           ├── verification.md
+│           └── evidence-history/
+└── archive/
+```
 
 The state machine enforces transitions:
 
 ```bash
-# Check guard
-matrix workflow guard open
-
+# 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
+# Lightweight: approve the compact proposal and enter Build
+matrix workflow transition build --confirmed
 
-# 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
+# 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.
+# 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.
 
 ---
 
@@ -220,8 +244,10 @@ matrix workflow doctor --repair --lock <id>
 |------|-------------|--------|
 | **full** | New features, architecture changes | All 5 phases |
 | **hotfix** | Reproducible small bugs | Simplified: open → build → verify → archive |
-| **tweak** | Bounded changes, no API/schema impact | 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 +278,30 @@ 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 |
-| design | `/prototype` | A material design question needs disposable evidence |
-| design | `/codebase-design` | A deep-module, interface, or test-seam decision remains |
-| 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 |
-| 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.
+## 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 |
+| design | `/prototype` | A material design question needs disposable evidence |
+| design | `/codebase-design` | A deep-module, interface, or test-seam decision remains |
+| 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 |
+| 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.
 
 ---
 
 **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