@rosenfan/matrix 0.1.7 → 0.1.8

package/README.md

@@ -219,8 +219,8 @@ 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
+# Lightweight: approve the compact proposal and enter Build (executor choice merged into the same pause)
+matrix workflow transition build --confirmed --executor <current|model|handoff:<agent-id>>
 
 # Return from verification failure; stale evidence is retained in history
 matrix workflow return build --reason verification-failed

package/README.zh-CN.md

@@ -216,8 +216,8 @@ matrix workflow guard open
 # 推进（仅在守卫通过时）
 matrix workflow transition design
 
-# lightweight：确认紧凑 proposal 后进入 Build
-matrix workflow transition build --confirmed
+# lightweight：确认紧凑 proposal 后进入 Build（执行主体选择并入同一次暂停）
+matrix workflow transition build --confirmed --executor <current|model|handoff:<agent-id>>
 
 # 验证失败时返回 Build；旧证据保留在历史目录
 matrix workflow return build --reason verification-failed

package/assets/skills/matrix/SKILL.md

@@ -84,5 +84,5 @@ Matrix never nests user-invoked Matt Skills. When relevant, explain the reason a
 - `node <matrix-skill-directory>/scripts/matrix-runtime.mjs 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.
-- Before entering Build (full: after the design guard; lightweight: merged into the `transition build --confirmed` pause), present the implementation-actor choice — continue with the current agent/model, switch the model in the user's client, or switch the implementation agent via `$matrix-handoff` — and record the decision with the Contract.
+- Before entering Build (full: after the design guard; lightweight: merged into the `transition build --confirmed` pause), present the implementation-actor choice — continue with the current agent/model, switch the model in the user's client, or switch the implementation agent via `$matrix-handoff` — and pass the recorded choice to the Runtime with `transition build --executor <current|model|handoff:<agent-id>>` (lightweight also carries `--confirmed`). The Runtime rejects Build entry without it and stores the choice as `implementation_actor`.
 - On shortcut scope expansion, run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap`; Runtime upgrades the change to `full`. Never silently continue the old contract.

package/assets/skills/matrix-design/SKILL.md

@@ -44,25 +44,25 @@ node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard design
 
 ## Implementation Decision Point
 
-After the design guard passes and before `transition build`, pause and present the implementation-actor choice to the user. Do not transition without an explicit choice:
+After the design guard passes and before `transition build`, pause and present the implementation-actor choice to the user. Do not transition without an explicit choice. The Runtime enforces this gate: `transition build` fails with `EXECUTOR_CONFIRMATION_REQUIRED` unless it carries the recorded choice, which is stored as `implementation_actor` in the change state.
 
 ### Option A: Continue with the current agent / model (default)
 
 Run transition and enter `$matrix-build`:
 
 ```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build --executor current
 ```
 
 Then enter `$matrix-build` to implement directly in this session.
 
 ### Option B: Switch the model, keep this agent
 
-The user switches the model in their own client (for example, a stronger model for design, an efficient one for implementation), returns to this session, and confirms. Then run transition exactly as in Option A. Matrix cannot see the client-side model; it provides the mandatory pause point only.
+The user switches the model in their own client (for example, a stronger model for design, an efficient one for implementation), returns to this session, and confirms. Then run the transition with `--executor model`. Matrix cannot see the client-side model; it provides the mandatory pause point only.
 
 ### Option C: Switch the implementation agent
 
-First approve the frozen contract by transitioning to Build, then run `$matrix-handoff` to export a bounded task package for the chosen agent (for example Codex designs, Claude Code implements; or zcode designs, opencode implements). This:
+First approve the frozen contract by transitioning to Build with the chosen agent recorded (`--executor handoff:<agent-id>`), then run `$matrix-handoff` to export a bounded task package for that agent (for example Codex designs, Claude Code implements; or zcode designs, opencode implements). This:
 - Does not change the Build phase or state beyond the preceding transition
 - Creates `artifacts/handoff-task-<task-id>.md` with all implementation details
 - Includes acceptance criteria, test seams, and required commands

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

@@ -48,6 +48,6 @@ Companion output is evidence for the Matrix proposal. It must not create another
 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
+# hotfix/tweak, only after explicit confirmation (actor choice merged into the same pause)
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build --confirmed --executor <choice>
 ```

package/assets/skills-zh-CN/matrix/SKILL.md

@@ -80,5 +80,5 @@ Matrix 不嵌套 user-invoked Skill。适用时只解释原因，并让用户显
 - 成功 Archive 必须使用两步乐观提交：先运行 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs archive --dry-run`，再将其精确 hash 传给 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs archive --expect-preflight <sha256>`；不得绕过预演。
 - `node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor` 始终只读；transaction 与陈旧锁 repair 必须显式绑定 doctor 报告的 identity，不得手工编辑或删除 `.matrix/transactions/`、`.matrix/workflow.lock`。
 - 重大架构/范围决定和 archive/commit 前应暂停等待用户确认。
-- 进入 Build 前（full 在 design guard 之后；lightweight 并入 `transition build --confirmed` 的暂停）必须呈现执行主体选择——当前 agent/原模型继续、用户客户端切换模型、或经 `$matrix-handoff` 切换实现 agent——并将决策随 Contract 记录。
+- 进入 Build 前（full 在 design guard 之后；lightweight 并入 `transition build --confirmed` 的暂停）必须呈现执行主体选择——当前 agent/原模型继续、用户客户端切换模型、或经 `$matrix-handoff` 切换实现 agent——并以 `transition build --executor <current|model|handoff:<agent-id>>` 把选择传给 Runtime（lightweight 同时携带 `--confirmed`）。缺省时 Runtime 拒绝进入 Build，并把选择存为 `implementation_actor`。
 - shortcut 范围扩大时执行 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap`；Runtime 将其升级为 full。

package/assets/skills-zh-CN/matrix-design/SKILL.md

@@ -24,15 +24,15 @@ node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard design
 
 ## 执行主体确认点（Build 前）
 
-`guard design` 通过后、`transition build` 之前，必须暂停并向用户确认执行主体，未确认不得推进：
+`guard design` 通过后、`transition build` 之前，必须暂停并向用户确认执行主体，未确认不得推进。该闸门由 Runtime 强制执行：`transition build` 未携带所记录的选择时报 `EXECUTOR_CONFIRMATION_REQUIRED`，选择会以 `implementation_actor` 写入 change 状态：
 
 - **选项 A：当前 agent / 原模型继续（默认）**——直接推进：
   ```powershell
-  node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build
+  node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build --executor current
   ```
   随后进入 `$matrix-build` 在本会话内实现。
-- **选项 B：切换模型、保留本 agent**——用户在自己的客户端完成模型切换（例如设计用强模型、实现用高性价比模型），回到会话确认后按选项 A 推进。Matrix 无法感知客户端模型，只提供强制暂停点。
-- **选项 C：切换执行 agent**——先推进进 Build 批准冻结 Contract，再用 `$matrix-handoff` 为目标 agent 导出有界任务包（例如 Codex 设计、Claude Code 实现，或 zcode 设计、opencode 实现）。实现 agent 完成并补齐 `## Build evidence` 后：
+- **选项 B：切换模型、保留本 agent**——用户在自己的客户端完成模型切换（例如设计用强模型、实现用高性价比模型），回到会话确认后以 `--executor model` 推进。Matrix 无法感知客户端模型，只提供强制暂停点。
+- **选项 C：切换执行 agent**——先以 `--executor handoff:<agent-id>` 记录所选 agent 并推进 Build 批准冻结 Contract，再用 `$matrix-handoff` 为目标 agent 导出有界任务包（例如 Codex 设计、Claude Code 实现，或 zcode 设计、opencode 实现）。实现 agent 完成并补齐 `## Build evidence` 后：
   ```powershell
   node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
   node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify

package/assets/skills-zh-CN/matrix-open/SKILL.md

@@ -35,6 +35,6 @@ companion 输出只能作为当前 proposal 的证据，不得创建第二套工
 node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard open
 # full
 node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition design
-# hotfix/tweak，仅在用户明确确认后
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build --confirmed
+# hotfix/tweak，仅在用户明确确认后（执行主体选择并入同一次暂停）
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build --confirmed --executor <choice>
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rosenfan/matrix",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Evidence-driven development workflow with Prim and Arch agent-skill orchestration.",
   "license": "MIT",
   "type": "module",

package/src/distribution.js

@@ -40,12 +40,12 @@ const configContent = (existing, defaultOrchestration, scope, language) => {
   const values = {
     ...existing,
     schema: "matrix/config/v1",
-    auto_transition: existing.auto_transition === "false" ? "false" : "true",
     default_orchestration: defaultOrchestration,
     installation_scope: scope,
     language
   };
-  const preferred = ["schema", "auto_transition", "default_orchestration", "installation_scope", "language"];
+  delete values.auto_transition;
+  const preferred = ["schema", "default_orchestration", "installation_scope", "language"];
   const keys = [...preferred, ...Object.keys(values).filter((key) => !preferred.includes(key)).sort()];
   return `${keys.map((key) => `${key}: ${values[key]}`).join("\n")}\n`;
 };

package/src/matt-catalog.mjs

@@ -1,7 +1,7 @@
 import crypto from "node:crypto";
 
 export const MATT_COMPATIBILITY = Object.freeze({
-  matrixVersion: "0.1.7",
+  matrixVersion: "0.1.8",
   release: "v1.3.1",
   commit: "24fe0ef7737efae15c87225755e9f6f5965e4888",
   archive: "https://github.com/mattpocock/skills/archive/24fe0ef7737efae15c87225755e9f6f5965e4888.tar.gz",

package/src/workflow.js

@@ -337,8 +337,8 @@ function readFlow(p) {
   return normalizeFlow(parsed);
 }
 function flowContent(flow) {
-  const order = ["schema", "id", "workflow", "workflow_profile", "orchestration", "artifact_language", "arch_catalog_digest", "matt_release", "status", "phase", "revision", "approved_contract_hash", "contract_approved_revision", "title", "created_at", "updated_at", "acceptance", "scope"];
-  return `${order.filter((key) => (!["workflow_profile", "artifact_language", "arch_catalog_digest", "matt_release"].includes(key) || flow[key])).map((key) => `${key}: ${flow[key] ?? ""}`).join("\n")}\n`;
+  const order = ["schema", "id", "workflow", "workflow_profile", "orchestration", "artifact_language", "arch_catalog_digest", "matt_release", "status", "phase", "revision", "approved_contract_hash", "contract_approved_revision", "implementation_actor", "title", "created_at", "updated_at", "acceptance", "scope"];
+  return `${order.filter((key) => (!["workflow_profile", "artifact_language", "arch_catalog_digest", "matt_release", "implementation_actor"].includes(key) || flow[key])).map((key) => `${key}: ${flow[key] ?? ""}`).join("\n")}\n`;
 }
 function active(cwd) { const activeFile = path.join(rootFor(cwd), "active.json"); if (!fs.existsSync(activeFile)) return null; return read(activeFile).change_id; }
 function meaningful(file, headings) {
@@ -705,7 +705,7 @@ export function invoke(argv, { cwd = process.cwd(), failAfterOperation = null, m
     const operations = [
       ...(!fs.existsSync(path.join(p.root, "archive")) ? [workflowMkdirOperation(cwd, path.join(p.root, "archive"))] : []),
       workflowMkdirOperation(cwd, p.artifacts),
-      ...(!fs.existsSync(path.join(p.root, "config.yaml")) ? [workflowWriteOperation(cwd, path.join(p.root, "config.yaml"), `schema: matrix/config/v1\nauto_transition: true\ndefault_orchestration: ${configured.defaultOrchestration}\ninstallation_scope: project\nlanguage: ${configured.artifactLanguage}\n`)] : []),
+      ...(!fs.existsSync(path.join(p.root, "config.yaml")) ? [workflowWriteOperation(cwd, path.join(p.root, "config.yaml"), `schema: matrix/config/v1\ndefault_orchestration: ${configured.defaultOrchestration}\ninstallation_scope: project\nlanguage: ${configured.artifactLanguage}\n`)] : []),
       ...(!fs.existsSync(path.join(p.root, ".gitignore")) ? [workflowWriteOperation(cwd, path.join(p.root, ".gitignore"), "active.json\ninstallation.json\nmatt-installation.json\nchanges/*/events.jsonl\nchanges/*/artifacts/handoff.md\n")] : []),
       workflowWriteOperation(cwd, p.flow, flowContent(flow)),
       ...(workspaceBaseline ? [workflowWriteOperation(cwd, p.workspaceBaseline, `${JSON.stringify(workspaceBaseline, null, 2)}\n`)] : []),
@@ -867,7 +867,13 @@ export function invoke(argv, { cwd = process.cwd(), failAfterOperation = null, m
   if (command === "transition") {
     const to = args[0];
     const confirmed = args.includes("--confirmed");
-    if (args.slice(1).some((arg) => arg !== "--confirmed")) return fail("INVALID_INTENT", "Transition accepts only a target phase and optional --confirmed.");
+    const executorFlag = args.indexOf("--executor");
+    const executor = executorFlag >= 0 ? args[executorFlag + 1] : null;
+    if (args.slice(1).some((arg, offset) => {
+      const index = offset + 1;
+      if (index === executorFlag || index === executorFlag + 1) return false;
+      return arg !== "--confirmed";
+    })) return fail("INVALID_INTENT", "Transition accepts only a target phase, optional --confirmed, and optional --executor <choice>.");
     if (flow.status !== "active") return fail("CHANGE_NOT_ACTIVE", `Matrix change is ${flow.status}.`);
     const profile = workflowProfile(p, flow);
     if (profile.next[flow.phase] !== to) return fail("ILLEGAL_TRANSITION", `Illegal ${profile.id} transition ${flow.phase} -> ${to}.`);
@@ -877,14 +883,24 @@ export function invoke(argv, { cwd = process.cwd(), failAfterOperation = null, m
       const order = workspaceOrderGuard(cwd, p);
       if (!order.ok) return order;
     }
+    // The implementation-actor gate is runtime-enforced, not prompt-level: Build
+    // may not be entered until the actor choice is recorded explicitly.
+    if (to === "build") {
+      if (executor != null && !/^(current|model|handoff:[a-z0-9]+(?:-[a-z0-9]+)*)$/.test(executor)) {
+        return fail("INVALID_INTENT", "Executor choice must be current, model, or handoff:<agent-id>.");
+      }
+      if (!executor) {
+        return fail("EXECUTOR_CONFIRMATION_REQUIRED", "Present the implementation-actor choice to the user before Build: continue with the current agent/model, switch the model in the user's client, or hand off to another agent. Then rerun with --executor <current|model|handoff:<agent-id>>.");
+      }
+    }
     const before = flow.phase;
     const approval = to === "build" ? contractState(p, flow) : null;
     if (approval && approval.status !== "approved-and-matching" && approval.status !== "unapproved") return { ...contractFailure(flow, approval), change_id: id };
     if (to === "build" && approval.snapshot.missing) return { ...fail("GUARD_FAILED", "Workflow contract artifacts are incomplete."), change_id: id };
-    const next = { ...flow, schema: "matrix/change/v2", phase: to, revision: flow.revision + 1, updated_at: stamp(), ...(to === "build" ? { approved_contract_hash: approval.snapshot.hash, contract_approved_revision: flow.revision + 1 } : {}) };
+    const next = { ...flow, schema: "matrix/change/v2", phase: to, revision: flow.revision + 1, updated_at: stamp(), ...(to === "build" ? { approved_contract_hash: approval.snapshot.hash, contract_approved_revision: flow.revision + 1, implementation_actor: executor } : {}) };
     const nextProfile = workflowProfile(p, next);
     const details = to === "build"
-      ? { approved_contract_hash: next.approved_contract_hash, contract_approved_revision: next.contract_approved_revision, ...(shortcut(flow) ? { confirmed, profile: nextProfile.id } : {}) }
+      ? { approved_contract_hash: next.approved_contract_hash, contract_approved_revision: next.contract_approved_revision, implementation_actor: next.implementation_actor, ...(shortcut(flow) ? { confirmed, profile: nextProfile.id } : {}) }
       : shortcut(flow) ? { profile: nextProfile.id } : {};
     const resultFields = { ok: true, code: "OK", change_id: id, workflow: next.workflow, profile: nextProfile.id, evidence_policy: evidencePolicy(next, nextProfile), orchestration: next.orchestration, artifact_language: next.artifact_language ?? artifactLanguage, status: next.status, phase: to, revision: next.revision, next_skill: skill(to), ...contractFields(next, contractState(p, next)) };
     return runWorkflowTransaction({