@rosenfan/matrix 0.1.1 → 0.1.3

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

@@ -3,38 +3,77 @@ 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
-
+# Matrix
+
 Use Matrix as the development-workflow entrypoint. Its source of truth is the current repository's `.matrix/`; never infer a phase from chat history.
+
+Read `artifact_language` from `matrix workflow inspect`. Keep required Markdown heading tokens unchanged, but write every user-facing artifact body, explanation, and handoff in that language: English for `en`, Chinese for `zh-CN`.
 
 ## Route
 
-First run:
+First run:
 
 ```powershell
-matrix workflow inspect
-```
-
-If and only if the `matrix` executable is reported as absent, run the bundled fallback from this Skill directory instead:
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect
-```
+matrix workflow inspect
+```
+
+If and only if the `matrix` executable is reported as absent, run the bundled fallback from this Skill directory instead:
 
-- If an active change exists, show its phase and enter the returned `next_skill`.
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect
+```
+
+- If an active change exists, show its phase and frozen `orchestration`, report any Arch installation-integrity failure, and enter the returned `next_skill` only when the Runtime permits continuation.
 - If no active change exists, classify the request: reproducible small bug → `$matrix-hotfix` with workflow `hotfix`; bounded small change with no public API/schema/architecture impact → `$matrix-tweak` with workflow `tweak`; otherwise full Matrix with workflow `full`.
 - Do not create Matrix state for questions, read-only investigation, or requests outside software development.
 - Before `init`, derive a short kebab-case change id and an accurate title. Start with `full` unless a shortcut clearly applies.
 
 ```powershell
-matrix workflow init <change-id> --workflow <full|hotfix|tweak> --title "<title>"
+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
 ```
 
-Then enter `$matrix-open`. State initialization creates tracked design artifacts and ignores machine-only state without changing the repository's existing `.gitignore`.
+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 that exports a frozen Matrix design to a Claude Code task package. It never changes the Matrix phase, workflow, guard result, or runtime state.
+`$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
 
@@ -43,7 +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 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 scope expansion, return to `$matrix-design`; never silently continue the old plan.
+- 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/agents/openai.yaml

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

package/.claude/skills/matrix/scripts/matrix_claude.py

@@ -1,166 +1,11 @@
 #!/usr/bin/env python3
-"""Export a frozen Matrix design to a Claude Code task package without changing Matrix state."""
+"""Compatibility adapter for the authoritative Node workflow exporter."""
 from __future__ import annotations
 
-import argparse
-import re
 import sys
-from pathlib import Path
 
-from matrix_state import active_path, artifact, get_active, guard, parse_flow, root
-
-
-def fail(message: str) -> None:
-    print(f"MATRIX CLAUDE ERROR: {message}", file=sys.stderr)
-    raise SystemExit(2)
-
-
-def read_artifact(change: str, name: str) -> str:
-    path = artifact(change, name)
-    if not path.exists():
-        fail(f"Required Matrix artifact is missing: {path}")
-    return path.read_text(encoding="utf-8").strip()
-
-
-def task_content(change: str, task_id: str, proposal: str, design: str, plan: str, result_path: str) -> str:
-    return f"""# Claude Code 执行任务包：{task_id}
-
-## 元数据
-
-| 字段 | 内容 |
-| --- | --- |
-| 状态 | CLAUDE_QUEUED |
-| Codex 决策人 | Codex |
-| Claude Code 执行人 | Claude Code |
-| Matrix Change | `{change}` |
-| 回执 | `{result_path}` |
-
-## 目标
-
-以下目标来自已冻结的 Matrix proposal，不得扩展：
-
-{proposal}
-
-## 范围
-
-### 允许修改
-
-- 仅修改为完成下列 Matrix 设计与计划所必需的文件。
-- 先阅读仓库级指令与现有测试，再开始实施。
-
-### 禁止修改
-
-- 不得修改 Matrix 状态文件或推进 Matrix phase。
-- 不得自行改变架构、公开接口、数据模型、依赖或任务范围。
-- 不得执行未获授权的网络、部署、破坏性或外部副作用动作。
-
-## 禁止事项
-
-- 不得把设计外的发现直接实现为额外功能。
-- 遇到范围扩大、设计冲突或验收不清时必须停止并写 `NEEDS_DECISION`。
-
-## 已冻结的设计决定
-
-{design}
-
-## 执行步骤
-
-{plan}
-
-## 验收
-
-- 执行 `plan.md` 中的全部验证命令。
-- 为每项行为变化提供测试或可复现验证证据。
-- 完成后保留可供 Codex 固定基线审查的 diff。
-
-## 停止并上报的条件
-
-- 需要修改范围外文件或改变冻结设计。
-- 验收失败且不能在既定范围内修复。
-- 发现安全、授权或项目指令冲突。
-
-## 回执路径
-
-在 `{result_path}` 创建结构化回执，至少包含：
-
-- `## 元数据`：执行状态与任务 ID。
-- `## 改动清单`：实际改动文件和理由。
-- `## 测试结果`：命令与输出摘要。
-- `## 边界确认`：未越界声明，或 `NEEDS_DECISION`。
-- `## 未解决项`：如有。
-
-Codex 才能验收；Claude Code 不得自行宣告任务已接受或完成。
-"""
-
-
-def active_board(task_id: str, task_path: str, result_path: str, change: str) -> str:
-    return f"""# 活跃任务看板
-
-> 这里是唯一实时任务面板：只放当前任务的状态、执行主体、范围、完成条件和下一步。
-
-## 当前状态
-
-| 字段 | 内容 |
-| --- | --- |
-| ID | {task_id} |
-| 状态 | CLAUDE_QUEUED |
-| 执行主体 | Claude Code（由用户通过 `$matrix-claude` 明确选择） |
-| 目标 | 执行 Matrix Change `{change}` 的冻结任务包。 |
-| 冻结设计 | `.matrix/changes/{change}/artifacts/{{proposal,design,plan}}.md` |
-| 任务包 | `{task_path}` |
-| 回执 | `{result_path}` |
-| 完成条件 | 任务包验收命令通过、Claude 回执齐全，并经 Codex 审查实际 diff 和证据。 |
-| 下一步 | Claude Code 按冻结任务包实施；范围冲突时写 `NEEDS_DECISION`。 |
-"""
-
-
-def export(args: argparse.Namespace) -> None:
-    change = get_active()
-    flow = parse_flow(root() / "changes" / change / "matrix.yaml")
-    if flow.get("phase") != "design":
-        fail(f"Matrix change '{change}' is in phase '{flow.get('phase')}', not design.")
-    if not guard(change, "design", output=True):
-        fail("Design guard failed; no Claude task package was written.")
-    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9-]*", args.task_id):
-        fail("Task id must use letters, digits, and hyphens.")
-    proposal, design, plan = (read_artifact(change, n) for n in ("proposal.md", "design.md", "plan.md"))
-
-    if args.target == "generic":
-        output = artifact(change, "claude-task.md")
-        result = artifact(change, "claude-result.md")
-        output.write_text(task_content(change, args.task_id, proposal, design, plan, str(result.relative_to(Path.cwd())).replace("\\", "/")), encoding="utf-8")
-        print(output)
-        return
-
-    tasks = Path.cwd() / "docs" / "tasks"
-    if not tasks.is_dir() or not (tasks / "active.md").is_file():
-        fail("FnSec target requires docs/tasks/active.md in the current project.")
-    output = tasks / f"claude-task-{args.task_id}.md"
-    result = tasks / f"claude-result-{args.task_id}.md"
-    if output.exists() or result.exists():
-        fail(f"FnSec task or result path already exists for {args.task_id}.")
-    output.write_text(task_content(change, args.task_id, proposal, design, plan, str(result.relative_to(Path.cwd())).replace("\\", "/")), encoding="utf-8")
-    if args.apply_fnsec_board:
-        board = tasks / "active.md"
-        current = board.read_text(encoding="utf-8")
-        if "NO_ACTIVE_OBJECTIVE" not in current:
-            output.unlink()
-            fail("FnSec active.md already has an objective; refused to overwrite it.")
-        board.write_text(active_board(args.task_id, str(output.relative_to(Path.cwd())).replace("\\", "/"), str(result.relative_to(Path.cwd())).replace("\\", "/"), change), encoding="utf-8")
-    print(output)
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser()
-    subs = parser.add_subparsers(dest="command", required=True)
-    command = subs.add_parser("export")
-    command.add_argument("--task-id", required=True)
-    command.add_argument("--target", choices=("generic", "fnsec"), default="generic")
-    command.add_argument("--apply-fnsec-board", action="store_true")
-    command.set_defaults(func=export)
-    args = parser.parse_args()
-    args.func(args)
+from matrix_state import run_runtime
 
 
 if __name__ == "__main__":
-    main()
+    raise SystemExit(run_runtime(sys.argv[1:]))

package/.claude/skills/matrix/scripts/matrix_state.py

@@ -1,114 +1,60 @@
 #!/usr/bin/env python3
-"""Deterministic state and guard kernel shared by every Matrix Skill."""
+"""Compatibility adapter for the authoritative Node Workflow Runtime."""
 from __future__ import annotations
 
-import argparse
-import json
-import re
+import os
 import shutil
+import subprocess
 import sys
-from datetime import datetime, timezone
 from pathlib import Path
 
-PHASES = ("open", "design", "build", "verify", "archive")
-NEXT = {"open": "design", "design": "build", "build": "verify", "verify": "archive"}
-SKILLS = {phase: f"$matrix-{phase}" for phase in PHASES}
-
-def now(): return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
-def root(): return Path.cwd() / ".matrix"
-def active_path(): return root() / "active.json"
-def fail(message): print(f"MATRIX ERROR: {message}", file=sys.stderr); raise SystemExit(2)
-def write_json(path, value): path.write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-def load_json(path): return json.loads(path.read_text(encoding="utf-8"))
-def flow_path(change): return root() / "changes" / change / "matrix.yaml"
-def parse_flow(path):
-    values = {}
-    for line in path.read_text(encoding="utf-8").splitlines():
-        if ":" in line and not line.startswith(" "):
-            key, value = line.split(":", 1); values[key.strip()] = value.strip().strip('"')
-    return values
-def write_flow(path, values):
-    order = ("schema", "id", "workflow", "status", "phase", "title", "created_at", "updated_at", "acceptance", "scope")
-    path.write_text("\n".join(f"{key}: {values.get(key, '')}" for key in order) + "\n", encoding="utf-8")
-def get_active():
-    if not active_path().exists(): fail("No active Matrix change. Start with $matrix <request>.")
-    change = load_json(active_path()).get("change_id")
-    if not isinstance(change, str) or not flow_path(change).exists(): fail("active.json does not reference a valid Matrix change.")
-    return change
-def artifact(change, name): return root() / "changes" / change / "artifacts" / name
-def meaningful(path, headings=()):
-    if not path.exists(): return False
-    text = path.read_text(encoding="utf-8").strip()
-    if len(text) < 40: return False
-    return all(h in text for h in headings)
-def checks(change, phase):
-    base = root() / "changes" / change / "artifacts"
-    if phase == "open":
-        return [("proposal.md has goal, scope, and acceptance", meaningful(base / "proposal.md", ("## Goal", "## Scope", "## Acceptance")))]
-    if phase == "design":
-        return [("design.md has decisions and test seams", meaningful(base / "design.md", ("## Decisions", "## Test seams"))), ("plan.md has ordered implementation steps", meaningful(base / "plan.md", ("## Steps", "## Validation")))]
-    if phase == "build":
-        return [("plan.md exists", meaningful(base / "plan.md", ("## Steps",))), ("verification.md has build evidence", meaningful(base / "verification.md", ("## Build evidence",)))]
-    if phase == "verify":
-        return [("verification.md has test evidence", meaningful(base / "verification.md", ("## Test evidence",))), ("verification.md has review evidence", meaningful(base / "verification.md", ("## Review evidence",)))]
-    return [("verify guard passed before archive", meaningful(base / "verification.md", ("## Test evidence", "## Review evidence")))]
-def guard(change, phase, output=True):
-    results = checks(change, phase)
-    ok = all(result for _, result in results)
-    if output:
-        print(f"Matrix guard: {change} / {phase}")
-        for label, result in results: print(f"[{'PASS' if result else 'FAIL'}] {label}")
-    return ok
-def event(change, event_name, before, after):
-    p = root() / "changes" / change / "events.jsonl"
-    with p.open("a", encoding="utf-8") as handle: handle.write(json.dumps({"at": now(), "event": event_name, "from": before, "to": after}, ensure_ascii=False) + "\n")
-def init(args):
-    change = re.sub(r"[^a-z0-9]+", "-", args.change.lower()).strip("-")
-    if not change: fail("Change id must contain letters or digits.")
-    if active_path().exists(): fail(f"Active Matrix change already exists: {get_active()}.")
-    directory = root() / "changes" / change
-    if directory.exists() or (root() / "archive" / change).exists(): fail(f"Matrix change already exists: {change}.")
-    (directory / "artifacts").mkdir(parents=True)
-    root().mkdir(exist_ok=True); (root() / "archive").mkdir(exist_ok=True)
-    (root() / "config.yaml").write_text("schema: matrix/config/v1\nauto_transition: true\n", encoding="utf-8") if not (root() / "config.yaml").exists() else None
-    gitignore = root() / ".gitignore"
-    ignored = "active.json\ninstallation.json\nchanges/*/run-state.json\nchanges/*/events.jsonl\nchanges/*/artifacts/handoff.md\n"
-    gitignore.write_text(ignored, encoding="utf-8") if not gitignore.exists() else None
-    values = {"schema":"matrix/change/v1", "id":change, "workflow":args.workflow, "status":"active", "phase":"open", "title":args.title, "created_at":now(), "updated_at":now(), "acceptance":"pending", "scope":"pending"}
-    write_flow(directory / "matrix.yaml", values)
-    write_json(directory / "run-state.json", {"schema":"matrix/run/v1", "current_step":"open", "iteration":0, "pending_gate":None, "updated_at":now()})
-    write_json(active_path(), {"change_id":change})
-    event(change, "initialized", None, "open")
-    print(f"Initialized Matrix change '{change}'. Next: {SKILLS['open']}")
-def inspect(_):
-    change = get_active(); flow = parse_flow(flow_path(change)); phase = flow.get("phase", "invalid")
-    if phase not in PHASES: fail(f"Invalid phase '{phase}'.")
-    print(json.dumps({"change_id":change, "workflow":flow.get("workflow"), "phase":phase, "next_skill":SKILLS[phase], "guard_pass":guard(change, phase, False)}, ensure_ascii=False, indent=2))
-def transition(args):
-    change = get_active(); flow = parse_flow(flow_path(change)); before = flow.get("phase")
-    expected = NEXT.get(before)
-    if args.to != expected: fail(f"Illegal transition {before} -> {args.to}; expected {expected or 'archive command' }.")
-    if not guard(change, before): fail("Current phase guard failed; state was not changed.")
-    flow["phase"] = args.to; flow["updated_at"] = now(); write_flow(flow_path(change), flow); event(change, "transition", before, args.to)
-    print(f"Transitioned {change}: {before} -> {args.to}. Next: {SKILLS[args.to]}")
-def archive(_):
-    change = get_active(); flow = parse_flow(flow_path(change))
-    if flow.get("phase") != "archive": fail("Only an archive-phase change can be archived.")
-    if not guard(change, "archive"): fail("Archive guard failed; state was not changed.")
-    flow["status"] = "archived"; flow["updated_at"] = now(); write_flow(flow_path(change), flow); event(change, "archived", "archive", "archived")
-    source = root() / "changes" / change; target = root() / "archive" / change; shutil.move(str(source), str(target)); active_path().unlink()
-    print(f"Archived Matrix change '{change}'.")
-def handoff(_):
-    change = get_active(); flow = parse_flow(flow_path(change)); phase = flow["phase"]
-    p = artifact(change, "handoff.md")
-    p.write_text(f"# Matrix handoff: {change}\n\n- Workflow: {flow['workflow']}\n- Current phase: {phase}\n- Resume with: `{SKILLS[phase]}`\n- Guard passes: {guard(change, phase, False)}\n", encoding="utf-8")
-    print(p)
-def main():
-    parser = argparse.ArgumentParser(); subs = parser.add_subparsers(dest="command", required=True)
-    p = subs.add_parser("init"); p.add_argument("change"); p.add_argument("--workflow", choices=("full","hotfix","tweak"), default="full"); p.add_argument("--title", required=True); p.set_defaults(func=init)
-    subs.add_parser("inspect").set_defaults(func=inspect)
-    p = subs.add_parser("guard"); p.add_argument("phase", choices=PHASES); p.set_defaults(func=lambda a: sys.exit(0 if guard(get_active(), a.phase) else 1))
-    p = subs.add_parser("transition"); p.add_argument("to", choices=PHASES[1:]); p.set_defaults(func=transition)
-    subs.add_parser("archive").set_defaults(func=archive); subs.add_parser("handoff").set_defaults(func=handoff)
-    args = parser.parse_args(); args.func(args)
-if __name__ == "__main__": main()
+
+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

@@ -3,24 +3,34 @@ name: matrix-archive
 description: Close and archive a verified Matrix change. Use when the active Matrix phase is archive.
 ---
 
-# Matrix Archive
+# Matrix Archive
+
+This is the final Matrix phase. Read the proposal, plan, and verification evidence; summarize changed behavior, verification, residual risks, and follow-up work. Ask for explicit confirmation before committing or archiving.
+
+Write archive summaries and handoff prose in `artifact_language`; keep Runtime-required English heading tokens unchanged.
 
-This is the **final phase** of the Matrix workflow. After archiving, the workflow is complete.
+Archive is Matrix-owned in both Prim and Arch. Do not invoke companion implementation, review, or architecture capabilities here.
 
-## Process
+## Mandatory two-step Archive
 
-1. Read the proposal, plan, and verification evidence
-2. Summarize changed behavior, verification, residual risks, and follow-up work in `artifacts/verification.md` or the project's normal delivery document
-3. Ask for explicit confirmation before committing or archiving
-4. Run the archive command (this also runs the verify guard)
-5. **Workflow complete** — no further phase transitions needed
+Run the read-only preflight and review its bounded effect summary. Then submit exactly the hash returned by that preflight:
 
 ```powershell
-matrix workflow archive
-```
+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.
+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.
 
-Do not archive if the verify guard fails.
+If acceptance criteria or design must change while awaiting confirmation, use the sole Archive recovery path:
 
-## After Archive
+```powershell
+matrix workflow return design --reason acceptance-or-design-gap
+```
 
-The change is moved to `.matrix/archive/`. To start a new change, run `$matrix` again.
+After successful commit, the change is under `.matrix/archive/` and the workflow is complete.

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

@@ -3,53 +3,42 @@ 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
+# Matrix Build
+
+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.
+
+Write build evidence and user-facing explanations in `artifact_language`; preserve any Runtime-required English heading tokens.
 
-Read `plan.md`, `design.md`, and repository instructions. Implement only the frozen scope.
+## Prim
 
-## Skills to Use
+Use Matrix's own implementation and test discipline.
 
-### Primary: `implement`
+## Arch
 
-Use the `implement` skill to execute the plan. It automatically:
+- 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.
 
-1. Uses `/tdd` at pre-agreed seams for red-green-refactor cycles
-2. Runs typechecking regularly
-3. Runs single test files regularly during development
-4. Runs the full test suite once at the end
-5. Uses `/code-review` to review the work when done
-6. Commits work to the current branch
+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.
 
-### On Failure: `diagnosing-bugs`
-
-When encountering crashes, test failures, or build failures:
-
-1. **Stop** — do not propose source code fixes before root cause is located
-2. Load the `diagnosing-bugs` skill
-3. Follow its feedback-loop discipline: build a tight red/pass signal first
-4. Only after root cause is identified, implement the fix through `implement` + `tdd`
-5. Record the diagnosis and fix in `artifacts/verification.md` under `## Build evidence`
-
-### On Merge Conflicts: `resolving-merge-conflicts`
+## Scope Discipline
 
-If merge conflicts occur during implementation, use the `resolving-merge-conflicts` skill to resolve them systematically.
+If implementation exposes a scope or design change, **stop and run**; a lightweight change is upgraded to full by this Return:
 
-## Scope Discipline
+```powershell
+matrix workflow return design --reason design-gap
+```
 
-If implementation exposes a scope or design change, **stop and return to `$matrix-design`**; do not amend the plan silently.
+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. Load `implement` skill
-2. Implement through vertical slices with TDD
-3. On failure: load `diagnosing-bugs` skill
-4. On merge conflicts: load `resolving-merge-conflicts` skill
-5. Record concrete commands and outcomes under `## Build evidence` in `artifacts/verification.md`
-6. Run the guard
-7. If guard passes, run transition to advance to verify phase
-8. **Then enter `$matrix-verify` to continue the workflow**
+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
-matrix workflow transition verify
+matrix workflow guard build
+matrix workflow transition verify
 ```