@yeison.restrepo.r/code-conductor 1.50.0 → 1.51.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -141,6 +141,7 @@ Useful variations:
141
141
 
142
142
  - `--auto` skips the pause between role dispatches. The spec and plan approvals always pause.
143
143
  - `--ticket 42` (or an issue URL) binds the run to a GitHub issue. `start` fetches it once through `gh`, halts on a pull request, a closed issue, or an empty or over-65536-byte body, and writes the body into a fenced, hashed snapshot at `.conductor/ticket/<ITEM>.md`, which **only the spec role reads, as untrusted requirement input**. After release, the owner runs `node .claude/scripts/ticket.mjs writeback <ITEM> --version <v> --pr <N|url> [--changelog <file>] [--close]`, which posts one outcome comment to the bound issue, never twice for the same version, and closes it only with `--close`.
144
+ - `- Role models: default` in the project `CLAUDE.md` puts each role on the model its profile ships as `default-model:` (`opus` for `spec`, `plan`, `audit`, `security` and the `define-review` reviewer, `sonnet` for `code`, `haiku` for `qa`), so the auditor reviews on another model than the author. `<role>=<opus|sonnet|haiku|inherit>` tokens override single roles (`- Role models: default, qa=sonnet`) or set only some. `start` freezes the map in the run file and every dispatch carries the model the script prints. When an audit returns a plan task a second time, that fix round runs on `opus`, and the audit entry records why. Without the line, every role inherits the session's model, as before.
144
145
 
145
146
  What it needs: agent definitions named `spec`, `plan`, `code`, `audit`, and `qa` in `.claude/agents/` or `~/.claude/agents/` (they ship from `1.37.0`); a resolvable test command, as above; and plans in the writing-plans format (`### Task N` with a `**Files:**` block). A failed validation halts the run, terminally in this version: recover with `end`, then `start`.
146
147
 
@@ -504,6 +505,7 @@ The backup and temp rules keep the installer's own backups and crash-stranded te
504
505
  - **`[BUG-076]`, open:** `scripts/orchestrate.mjs` lets `approve` pass once a role's review loop has recorded any outcome, without checking that the loop's recorded hash matches the document being approved, and `review <role> --round` accepts a document outside the role's docs scope, so a run record can show a clean review for a document no reviewer read; your approval itself stays bound to the hash you were shown. Until it is fixed, check that the review loop's recorded document and hash match the document you approve before trusting its outcome.
505
506
  - **`[BUG-077]`, open:** `scripts/orchestrate.mjs` lets `approve spec <path> <sha256>` accept any file path relative to the run root, without checking that it is the spec the `spec` role handed back or that it sits under the run's `docs.specs` folder, so approving the wrong path makes the post-approval hash check in `install` protect that file while later edits to the real spec go undetected. Until it is fixed, confirm that the path you approve is the spec the `spec` role handed back, under the run's recorded specs folder.
506
507
  - **`[BUG-078]`, open:** `scripts/orchestrate.mjs` builds a fix round's write scope with the approved plan included, so Guard 5 lets the fix-round `code` agent write to the plan and only the brief's instruction stops it; any change other than checkbox ticks still halts the run with `ORCH_APPROVED_DOC_CHANGED` on the next `install audit` or fix round, and ticks do not affect `tasks.done`. Until it is fixed, check after a fix round that the approved plan's checkboxes are unchanged.
508
+ - **`[BUG-079]`, open:** `scripts/orchestrate.mjs` stores every non-security hand-back's full SNAP in `.claude/memory/orchestrator-run.json` with a 64 KiB cap per SNAP but no cap on the total, so a plan of roughly 80 or more tasks with maximally sized hand-backs can push the run file past the hook's 10 MiB read cap, after which `readRunFile` returns null and Guard 6 downgrades from deny to warn for the rest of the run. Until it is fixed, keep orchestrated plans well under 80 tasks, or split a larger item into several runs.
507
509
  - **The `P7` false positive** described under [Guard 3, and what it learned](#guard-3-and-what-it-learned) is still live.
508
510
  - **A re-run against an untouched `project.md` prints a recovery hint it cannot prove is needed.** If you install, never write anything into `.claude/memory/project.md`, and install again, you get a line suggesting the file may have been overwritten by a pre-`1.30.0` re-run. It was not; it equals the stub because it was seeded and never edited. The check compares content and **cannot distinguish "seeded and untouched" from "clobbered"**, which is why the wording is hedged to "may have been" rather than "was". This residual is named and accepted in [`BUG-039`'s spec at `:129`](docs/superpowers/specs/2026-09-27-bug039-installer-host-owned-state-design.md), where the alternative (restoring from the host's own git history) was rejected as writing host files out of the host's history with new failure modes. A **fresh** install is silent, which the Quickstart shows.
509
511
  - **Three open dossiers**, which are the evidence-collection pipeline working rather than a backlog: a session denial tally, one for interleaved-artifact reports, and an intermittent commit-hook hang in the `snap-build` suite. A dossier holds specimens until a mechanism is characterized by probe; an id is minted only when the written condition is met. `[BUG-047]` is what that pipeline produces when it completes: an out-of-scope note, then a dossier, then four specimens across four sessions, then a mint, then a release.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yeison.restrepo.r/code-conductor",
3
- "version": "1.50.0",
3
+ "version": "1.51.0",
4
4
  "description": "A governance layer for Claude Code sessions: hooks that check an agent's commands before they run, a spec-first workflow, and project memory the next session reads.",
5
5
  "keywords": [
6
6
  "agentic-development",
@@ -2,6 +2,7 @@
2
2
  name: audit
3
3
  description: Verify-band role of a /cc-orchestrate run. Reviews the item's changes statically against its spec and plan, read-only, and hands back build_executed with its findings and one verdict. No shell. Dispatched by /cc-orchestrate during a run, or by /cc-review outside one.
4
4
  tools: Read, Grep, Glob
5
+ default-model: opus
5
6
  ---
6
7
 
7
8
  You are the `audit` role of a code-conductor orchestrated run. The orchestrator during a run, or a phase command outside one, dispatched you with a brief naming the item, its spec and its plan, and installed your band envelope at `.claude/memory/band-envelope.json`. Read the envelope first. If your brief says no envelope was installed for you, there is none to read; leave the scope key out of the hand-back.
@@ -2,6 +2,7 @@
2
2
  name: code
3
3
  description: Build-band role of a /cc-orchestrate run. Implements one plan task inside the files it names, runs the run's recorded test command, and hands back build_executed. Dispatched by /cc-orchestrate during a run.
4
4
  tools: Read, Grep, Glob, Write, Edit, Bash
5
+ default-model: sonnet
5
6
  ---
6
7
 
7
8
  You are the `code` role of a code-conductor orchestrated run. The orchestrator dispatched you with a brief naming one task of the approved plan, and installed your band envelope at `.claude/memory/band-envelope.json`. Read the envelope first: its `ops.scope` is the task's files plus the plan file.
@@ -2,6 +2,7 @@
2
2
  name: define-review
3
3
  description: Reviewer in the Define band's review loop of a /cc-orchestrate run (FEAT-041). Checks a spec or plan against the checklist rows in its brief, read-only, and reports open rows in a fixed format. Not a band role. No shell. Dispatched by /cc-orchestrate during a run.
4
4
  tools: Read, Grep, Glob
5
+ default-model: opus
5
6
  ---
6
7
 
7
8
  You are the `define-review` reviewer of a code-conductor orchestrated run. The orchestrator dispatched you, fresh for this round, with a brief naming the item, the round, the document under review, its source, and the checklist rows.
@@ -2,6 +2,7 @@
2
2
  name: plan
3
3
  description: Define-band role of a /cc-orchestrate run. Writes the implementation plan for the approved spec under the folder its envelope's `ops.scope` names and hands back boundary_routed. No shell. Dispatched by /cc-orchestrate during a run, or by /cc-plan --delegate outside one.
4
4
  tools: Read, Grep, Glob, Write, Edit
5
+ default-model: opus
5
6
  ---
6
7
 
7
8
  You are the `plan` role of a code-conductor orchestrated run. The orchestrator during a run, or a phase command outside one, dispatched you with a brief naming the item and its approved spec, and installed your band envelope at `.claude/memory/band-envelope.json`. Read the envelope first.
@@ -2,6 +2,7 @@
2
2
  name: qa
3
3
  description: Verify-band role of a /cc-orchestrate run. Re-runs the run's recorded test command as a non-author and hands back verify_pass only when the suite passes. No write tools. Dispatched by /cc-orchestrate during a run, or by /cc-test outside one.
4
4
  tools: Read, Grep, Glob, Bash
5
+ default-model: haiku
5
6
  ---
6
7
 
7
8
  You are the `qa` role of a code-conductor orchestrated run. The orchestrator during a run, or a phase command outside one, dispatched you with a brief naming the item, and installed your band envelope at `.claude/memory/band-envelope.json`. Read the envelope first. If your brief says no envelope was installed for you, there is none to read; leave the scope key out of the hand-back.
@@ -2,6 +2,7 @@
2
2
  name: security
3
3
  description: Verify-band role of a /cc-orchestrate run. Runs the run's recorded dependency audit and local security scan, lists every finding with its severity, and ends in one verdict line. No write tools; it fixes nothing. Dispatched by /cc-orchestrate during a run.
4
4
  tools: Read, Grep, Glob, Bash
5
+ default-model: opus
5
6
  ---
6
7
 
7
8
  You are the `security` role of a code-conductor orchestrated run. The orchestrator dispatched you with a brief naming the item, and installed your band envelope at `.claude/memory/band-envelope.json`. Read the envelope first, then the `security` object of `.claude/memory/orchestrator-run.json`.
@@ -2,6 +2,7 @@
2
2
  name: spec
3
3
  description: Define-band role of a /cc-orchestrate run. Writes the spec for one backlog item under the folder its envelope's `ops.scope` names and hands back boundary_routed. No shell. Dispatched by /cc-orchestrate during a run, or by /cc-spec --delegate outside one.
4
4
  tools: Read, Grep, Glob, Write, Edit
5
+ default-model: opus
5
6
  ---
6
7
 
7
8
  You are the `spec` role of a code-conductor orchestrated run. The orchestrator during a run, or a phase command outside one, dispatched you with a brief naming the item and installed your band envelope at `.claude/memory/band-envelope.json`. Read the envelope first.
@@ -42,22 +42,23 @@ A halt stops the run (D12, amended by FEAT-055). Recovery is `node "$S/orchestra
42
42
 
43
43
  ## Steps
44
44
 
45
- 1. **Start.** Run `node "$S/orchestrate.mjs" start $ARGUMENTS`. It resolves the run's test command and its spec and plan folders before it writes anything, and its stdout ends with `docs: specs <dir>, plans <dir> (<source>)[; group <group>]; test command: <command>; audit rounds: <n>; security: threshold <level>, dependency scan <command | not covered for <reason> | disabled (--no-dependency-audit)>`.
45
+ 1. **Start.** Run `node "$S/orchestrate.mjs" start $ARGUMENTS`. It resolves the run's test command and its spec and plan folders before it writes anything, and its stdout ends with `docs: specs <dir>, plans <dir> (<source>)[; group <group>]; test command: <command>; audit rounds: <n>; security: threshold <level>, dependency scan <command | not covered for <reason> | disabled (--no-dependency-audit)>`. With a `- Role models:` line in the project `CLAUDE.md`, it then ends with `; role models: spec=<m>, plan=<m>, code=<m>, audit=<m>, security=<m>, qa=<m>, define-review=<m>`, each `<m>` one of `opus`, `sonnet`, `haiku` or `inherit`, followed by `; note: audit and code share <m>` when both name the same model (FEAT-053).
46
46
  - If stdout names a replaced stale run, report its item and start time.
47
47
  - On `ORCH_RUN_ACTIVE`, report it, offer `end`, and stop.
48
48
  - On `ORCH_TEST_COMMAND_UNRESOLVED` or `ORCH_TEST_COMMAND_UNSAFE`, report it and stop. No run file was written, so there is nothing to `end`. The owner adds a `test` script to `package.json`, or removes the chaining from the command it names, before a fresh `start`.
49
49
  - On `ORCH_SECURITY_COMMAND_UNSAFE`, report it and stop in the same way: a recorded security command carries chaining, and no run file was written.
50
50
  - On `ORCH_DOC_LOCATION_INVALID`, report it and stop. No run file was written. The owner fixes the named `- Specs:` / `- Plans:` line in `CLAUDE.md` (add the missing one, fix the value, or use two disjoint folders) before a fresh `start`.
51
+ - On `ORCH_ROLE_MODELS_INVALID`, report it and stop. No run file was written. The owner fixes or removes the `- Role models:` line in `CLAUDE.md` that the reason names (an unknown role, a model outside `opus`, `sonnet`, `haiku` and `inherit`, a role set twice, an empty token, `default` twice, more than one line, or a profile's `default-model:` outside that list) before a fresh `start`.
51
52
  - On an intake halt (`TICKET_FLAG_INVALID`, `TICKET_UNREACHABLE`, `TICKET_NOT_ISSUE`, `TICKET_CLOSED`, `TICKET_BODY_EMPTY` or `TICKET_BODY_OVER_CAP`), report it and stop. No run file and no snapshot were written; the halt names its remedy.
52
53
  - With `--ticket`, stdout also names the ticket, its title, the snapshot `.conductor/ticket/<ITEM>.md` and its sha256. The run is bound.
53
54
 
54
- Print the run header: the item, the mode (`step` unless `--auto` was given), the test command, the audit rounds, the security threshold and the dependency scan from the start line, the spec and plan folders (and group) from `docs:`, the ticket and snapshot for a bound run, and the first role, `spec`.
55
+ Print the run header: the item, the mode (`step` unless `--auto` was given), the test command, the audit rounds, the security threshold and the dependency scan from the start line, the spec and plan folders (and group) from `docs:`, the role models and their note from `role models:` when the start line has them, the ticket and snapshot for a bound run, and the first role, `spec`.
55
56
  Add one line: `Review loop: fresh Agent dispatches over review files, no SendMessage; it needs no launch settings and runs in every permission mode.`
56
57
  2. **Each dispatch.** Take the roles in band order: `spec`, `plan`, then `code` once per plan task, then `audit`; after an audit that the script answers with a fix round, `code` once for that fix and then `audit` again; then `security`; then `qa`. For each one:
57
58
  1. **Check.** Run `node "$S/orchestrate.mjs" install <role> --check`. Print the role and the envelope it prints, and state that `--to <role>` passed.
58
59
  2. **Pause.** In step mode, ask the owner for a go. On a decline, stop: the run stays at its position, and nothing is installed. Under `--auto`, skip this pause.
59
60
  3. **Install.** Run `node "$S/orchestrate.mjs" install <role>`.
60
- 4. **Dispatch.** Use the `Agent` tool with `subagent_type: <role>` and the brief below. Dispatch one agent at a time, never in parallel (D8).
61
+ 4. **Dispatch.** Use the `Agent` tool with `subagent_type: <role>` and the brief below. Dispatch one agent at a time, never in parallel (D8). **Model (FEAT-053).** When `install` printed a last line `model: <alias>`, pass that alias as the `Agent` call's `model` parameter; on `model: inherit`, or when `install` printed no `model:` line, pass no `model`. Take the model from that line only: never choose a model yourself, and never retry a failed dispatch on another one.
61
62
  5. **Wait.** Dispatch returns before the agent finishes, and an agent can keep acting after its hand-back. Wait for the agent's completion notice. Run nothing for this position until it arrives (D8).
62
63
  6. **Hand back.**
63
64
  1. Write the agent's **delivered `SubagentHandback` report** with the Write tool, verbatim, to `.conductor/handback/<role>.txt`. That is the one report the binary delivered, never a later message. For code, use `.conductor/handback/code-<N>.txt`, where `<N>` is the task number, and `.conductor/handback/code-fix-<r>.txt` for fix round `<r>`. For audit, use `.conductor/handback/audit-<round>.txt`, where `<round>` counts the audit passes from 1. For security, use `.conductor/handback/security.txt`.
@@ -72,10 +73,11 @@ A halt stops the run (D12, amended by FEAT-055). Recovery is `node "$S/orchestra
72
73
  - **After spec:** show the owner the spec path from the hand-back, and for a bound run the snapshot path and sha256 from the start line: the owner reviews the spec against that snapshot. On approval, run `node "$S/orchestrate.mjs" approve spec <spec path> <sha256>` with the path and hash you showed.
73
74
  - **After plan:** show the owner the plan path named in the hand-back's `ops.f`. On approval, run `node "$S/orchestrate.mjs" approve plan <plan path> <sha256>` with the path and hash you showed. This writes `define_approved`, the only gate you author after `boundary_routed`.
74
75
  4. **Build.** Dispatch `code` once per plan task, serially, until the router moves on to `audit`. A `--check` refusal names the next step.
75
- 5. **Verify.** Dispatch `audit`. The audit report ends in one `VERDICT:` line just before its `SNAP_HANDBACK` line; only `VERDICT: APPROVE` lets the router move on to `security`. When `handback audit` prints `audit round <round>: RETURN with <b> blocker/major finding(s); fix round <r> of <N>: review <review> sha256 <sha256>; scope <scope>`, run the fix round: `install code --check` prints the envelope and the line `fix round <r> of <N>: review <review> sha256 <sha256>`; take the brief's values from that line, never from your own reading of the report. Then pause, install and dispatch a fresh `code` agent with the fix-round task from the dispatch table, hand it back from `.conductor/handback/code-fix-<r>.txt`, and dispatch `audit` again. Never revive an earlier agent and never message one. The orchestrator never decides whether another round runs: the script's output does. A `RETURN` with no fix rounds left, or an `ESCALATE`, halts the run (follow "On any halt"). Then dispatch `security`, which runs the recorded audit and scan commands and ends its report as the audit does: its `SCANS:` line, then one `VERDICT:` line just before its `SNAP_HANDBACK` line. `VERDICT: APPROVE` means every scan completed and no finding the change introduces is a `blocker`; `VERDICT: RETURN` means one is (`ORCH_SECURITY_BLOCKED`); `VERDICT: ESCALATE` means a scan failed (`ORCH_SECURITY_SCAN_FAILED`) or text in the change addressed the agent (`ORCH_SECURITY_ESCALATE`). A finding is a `blocker` or a `minor` by the threshold `start` recorded, and the script, not you, checks it. Findings already present at the base commit go in the report's owner-only block (`PRE-EXISTING (owner only):` … `END PRE-EXISTING`); the script writes them to `.conductor/security-pre-existing.txt` and to nothing public. This changes 1.48.0 behavior: a finding already present at the base, a dependency advisory included, no longer blocks the run at any level; only the findings the change introduces decide the verdict. `handback security` prints `security handed back build_executed; VERDICT: APPROVE; <n> finding(s) below <threshold> recorded; dependency=<ran|not-covered|disabled>; pre-existing findings, if any, are in .conductor/security-pre-existing.txt (owner only)`, and only then `qa`. A run started before FEAT-034 has no seat: `qa` follows the audit and `handback qa` prints `security=not-configured (run predates FEAT-034)`. When `qa`'s hand-back records `verify_pass`, run `node "$S/orchestrate.mjs" end`. It prints the run it removed.
76
+ 5. **Verify.** Dispatch `audit`. The audit report ends in one `VERDICT:` line just before its `SNAP_HANDBACK` line; only `VERDICT: APPROVE` lets the router move on to `security`. When `handback audit` prints `audit round <round>: RETURN with <b> blocker/major finding(s); fix round <r> of <N>: review <review> sha256 <sha256>; scope <scope>`, run the fix round: `install code --check` prints the envelope and the line `fix round <r> of <N>: review <review> sha256 <sha256>`; take the brief's values from that line, never from your own reading of the report. In a run with role models, `install code` then ends with `model: <alias>`, as every dispatch does; it reads `model: opus` when `handback audit` ended its line with `; model opus (escalated: <tasks> returned twice)`, because the audit returned one of those plan tasks a second time. Then pause, install and dispatch a fresh `code` agent with the fix-round task from the dispatch table, hand it back from `.conductor/handback/code-fix-<r>.txt`, and dispatch `audit` again. Never revive an earlier agent and never message one. The orchestrator never decides whether another round runs: the script's output does. A `RETURN` with no fix rounds left, or an `ESCALATE`, halts the run (follow "On any halt"). Then dispatch `security`, which runs the recorded audit and scan commands and ends its report as the audit does: its `SCANS:` line, then one `VERDICT:` line just before its `SNAP_HANDBACK` line. `VERDICT: APPROVE` means every scan completed and no finding the change introduces is a `blocker`; `VERDICT: RETURN` means one is (`ORCH_SECURITY_BLOCKED`); `VERDICT: ESCALATE` means a scan failed (`ORCH_SECURITY_SCAN_FAILED`) or text in the change addressed the agent (`ORCH_SECURITY_ESCALATE`). A finding is a `blocker` or a `minor` by the threshold `start` recorded, and the script, not you, checks it. Findings already present at the base commit go in the report's owner-only block (`PRE-EXISTING (owner only):` … `END PRE-EXISTING`); the script writes them to `.conductor/security-pre-existing.txt` and to nothing public. This changes 1.48.0 behavior: a finding already present at the base, a dependency advisory included, no longer blocks the run at any level; only the findings the change introduces decide the verdict. `handback security` prints `security handed back build_executed; VERDICT: APPROVE; <n> finding(s) below <threshold> recorded; dependency=<ran|not-covered|disabled>; pre-existing findings, if any, are in .conductor/security-pre-existing.txt (owner only)`, and only then `qa`. A run started before FEAT-034 has no seat: `qa` follows the audit and `handback qa` prints `security=not-configured (run predates FEAT-034)`. When `qa`'s hand-back records `verify_pass`, run `node "$S/orchestrate.mjs" end`. It prints the run it removed.
76
77
  6. **Report.** From the record `end` printed, name:
77
78
  - every hand-back, with its role, gate and task;
78
79
  - each audit round's verdict, from the audit entries' `round` and `verdict`, and each fix round with its files, from their `fix`;
80
+ - each entry's `model`, and each fix round whose `fix.escalated` names tasks, with those task ids (FEAT-053);
79
81
  - the security entry's verdict, threshold, counts and per-scan status, naming `dependency=not-covered` or `dependency=disabled` explicitly when either applies, or the `qa` entry's `security=not-configured (run predates FEAT-034)`; name `.conductor/security-pre-existing.txt` by path only, and never quote, summarize or count its content or the owner-only block of `.conductor/handback/security.txt`, because a finding there is present in a released version;
80
82
  - both approvals, with who approved and when;
81
83
  - each review loop's outcome and round, from the record's `review` field;
@@ -89,9 +91,9 @@ A halt stops the run (D12, amended by FEAT-055). Recovery is `node "$S/orchestra
89
91
  After `spec` and after `plan` hand back, and before that role's approval, run this loop. It never halts the run and never replaces the owner's approval, but `approve` refuses with `ORCH_REVIEW_OPEN` until the loop records an outcome, so a skipped loop is always on the record. `<role>` is `spec` or `plan`; `<doc>` is the document path from the hand-back's `ops.f`. No step messages an agent: every revision is a fresh dispatch over files, so the loop needs no launch settings and runs in every permission mode, headless included.
90
92
 
91
93
  1. **Open a round.** Run `node "$S/orchestrate.mjs" review <role> --round <doc>`. It prints `review <role> round <n> of 3: <doc> sha256 <doc sha256>`. On `review <role> closed unchanged at round <n>`, the last revision left the document as it was, a failed round: the loop is over, go to the approval.
92
- 2. **Review.** Dispatch a fresh `define-review` agent with the `Agent` tool and the reviewer brief below. Never revive an earlier reviewer, and never pass it an earlier round's findings. Wait for its completion notice.
94
+ 2. **Review.** Dispatch a fresh `define-review` agent with the `Agent` tool and the reviewer brief below. Never revive an earlier reviewer, and never pass it an earlier round's findings. Wait for its completion notice. When the round line ends `; model <alias>`, pass that model to the reviewer's dispatch by the rule of step 2.4.
93
95
  3. **Record.** Write its report verbatim with the Write tool to `.conductor/review/<role>-<n>.md`, then run `review <role> --record`. The script reads the verdict from the file's last non-blank line, `REVIEW <role> round <n>: CLEAN` or `REVIEW <role> round <n>: OPEN <k>`. On `closed clean` or `closed cap`, go to the approval. No revision follows the third pass, so the document at the approval is always the one the last reviewer read.
94
- 4. **Revise.** On `OPEN <k>; revise <doc> sha256 <doc sha256> from <review path> sha256 <review sha256>`, dispatch a fresh `<role>` agent with the `Agent` tool and the revision brief below, filled with those four values. Never revive the author that handed back, and never message any agent. Wait for the first delivery on any channel (a hand-back frame or a completion notice) whose last line is `REVISION <role> round <n>: done` or `REVISION <role> round <n>: blocked <reason>`, and ignore later copies. On `done`, go back to 1: the script decides whether the revision changed the document.
96
+ 4. **Revise.** On `OPEN <k>; revise <doc> sha256 <doc sha256> from <review path> sha256 <review sha256>`, dispatch a fresh `<role>` agent with the `Agent` tool and the revision brief below, filled with those four values. Never revive the author that handed back, and never message any agent. Wait for the first delivery on any channel (a hand-back frame or a completion notice) whose last line is `REVISION <role> round <n>: done` or `REVISION <role> round <n>: blocked <reason>`, and ignore later copies. On `done`, go back to 1: the script decides whether the revision changed the document. When the `OPEN` line ends `; model <alias>`, pass that model to the author's dispatch by the rule of step 2.4.
95
97
 
96
98
  A revision report is never passed to `handback`. If one carries a `SNAP_HANDBACK` line, run `review <role> --close skipped:snap-in-revision` and flag the report at the approval.
97
99
 
@@ -34,6 +34,13 @@ export const AUDIT_ROUNDS_DEFAULT = 2;
34
34
  const AUDIT_ROUNDS_MAX = 5;
35
35
  const SNAP_STORE_MAX_BYTES = 64 * 1024;
36
36
  const isAuditRounds = (n) => Number.isInteger(n) && n >= 0 && n <= AUDIT_ROUNDS_MAX;
37
+ // FEAT-053: the Agent tool's model aliases plus inherit; the one list start, the profiles and isValidRun are checked against.
38
+ export const MODEL_ALIASES = ['opus', 'sonnet', 'haiku', 'inherit'];
39
+ export const MODEL_ROLES = ['spec', 'plan', 'code', 'audit', 'security', 'qa', 'define-review'];
40
+ const ESCALATION_MODEL = 'opus';
41
+ const ROLE_MODELS_PREFIX = '- Role models:';
42
+ const ROLE_MODELS_LINE = /^- Role models: (.+)$/;
43
+ const isModel = (m) => MODEL_ALIASES.includes(m);
37
44
  // Every outcome a closed loop can carry; only the skip is the orchestrator's to record (FEAT-058).
38
45
  const REVIEW_OUTCOME = /^(clean|cap|unchanged|skipped:[a-z][a-z0-9-]{0,39})$/;
39
46
  const SKIP_OUTCOME = /^skipped:[a-z][a-z0-9-]{0,39}$/;
@@ -110,13 +117,24 @@ function isSecurity(s) {
110
117
  return typeof s.scan_command === 'string' && s.scan_command.endsWith(` ${s.threshold}`);
111
118
  }
112
119
 
120
+ // FEAT-053: a hand-edited model would let the run file, not the project, choose what a dispatch runs on.
121
+ function isModelRecord(run) {
122
+ const m = run.models;
123
+ const keys = isPlainObject(m) ? Object.keys(m).sort().join() : null;
124
+ if (m !== undefined && (keys !== [...MODEL_ROLES].sort().join() || !MODEL_ROLES.every((r) => isModel(m[r])))) return false;
125
+ if (run.dispatch_model !== undefined && !isModel(run.dispatch_model)) return false;
126
+ return run.handbacks.every((h) => !isPlainObject(h?.fix) || h.fix.model === undefined || isModel(h.fix.model));
127
+ }
128
+
113
129
  // FEAT-057: a present audit_rounds that is not 0-5 would let a hand-edited run buy fix rounds without limit.
130
+ // FEAT-053: and models, dispatch_model and fix.model hold only the allow-list.
114
131
  export function isValidRun(run) {
115
132
  return isPlainObject(run) && run.v === 1 && typeof run.session_id === 'string' && run.session_id !== ''
116
133
  && typeof run.item === 'string' && GATES.includes(run.gate) && isPlainObject(run.approvals)
117
134
  && Array.isArray(run.handbacks) && Array.isArray(run.tasks?.ids) && Number.isInteger(run.tasks?.done)
118
135
  && (run.audit_rounds === undefined || isAuditRounds(run.audit_rounds))
119
- && (run.security === undefined || isSecurity(run.security));
136
+ && (run.security === undefined || isSecurity(run.security))
137
+ && isModelRecord(run);
120
138
  }
121
139
 
122
140
  function readRun(root) {
@@ -278,6 +296,64 @@ export function findAgent(role, root, home = homedir()) {
278
296
  return null;
279
297
  }
280
298
 
299
+ const modelsInvalid = (reason) => new Halt('ORCH_ROLE_MODELS_INVALID', reason);
300
+
301
+ // FEAT-053: the one CLAUDE.md opt-in line, or null; a prefix without a value halts rather than inheriting silently.
302
+ function roleModelsValue(root) {
303
+ let text = '';
304
+ try { text = readFileSync(join(root, 'CLAUDE.md'), 'utf8').replace(/\r\n/g, '\n'); } catch { return null; }
305
+ const lines = text.split('\n').filter((l) => l.startsWith(ROLE_MODELS_PREFIX));
306
+ if (lines.length === 0) return null;
307
+ if (lines.length > 1) throw modelsInvalid(`CLAUDE.md has ${lines.length} "${ROLE_MODELS_PREFIX}" lines; keep one`);
308
+ const m = ROLE_MODELS_LINE.exec(lines[0]);
309
+ if (!m) throw modelsInvalid(`"${lines[0]}" has no value; write default or <role>=<model> tokens`);
310
+ return m[1];
311
+ }
312
+
313
+ // An explicit token wins over default whatever the order, so the parse only collects.
314
+ function parseRoleModels(value) {
315
+ const explicit = {};
316
+ let defaults = false;
317
+ for (const token of value.split(',').map((t) => t.trim())) {
318
+ if (token === '') throw modelsInvalid(`empty token in "${ROLE_MODELS_PREFIX} ${value}"`);
319
+ if (token === 'default') {
320
+ if (defaults) throw modelsInvalid('"default" appears twice');
321
+ defaults = true;
322
+ continue;
323
+ }
324
+ const parts = token.split('=');
325
+ if (parts.length !== 2) throw modelsInvalid(`token "${token}" is neither default nor <role>=<model>`);
326
+ const [role, model] = parts;
327
+ if (!MODEL_ROLES.includes(role)) throw modelsInvalid(`unknown role "${role}" in "${token}"; the roles are ${MODEL_ROLES.join(', ')}`);
328
+ if (!isModel(model)) throw modelsInvalid(`model "${model}" in "${token}" is not one of ${MODEL_ALIASES.join(', ')}`);
329
+ if (role in explicit) throw modelsInvalid(`role "${role}" is set twice`);
330
+ explicit[role] = model;
331
+ }
332
+ return { defaults, explicit };
333
+ }
334
+
335
+ // The shipped default sits under a key Claude Code does not read; no profile, or no key, inherits.
336
+ function profileDefault(role, root) {
337
+ const path = findAgent(role, root);
338
+ if (!path) return 'inherit';
339
+ const front = readFileSync(path, 'utf8').match(/^---\r?\n([\s\S]*?)\r?\n---/);
340
+ const value = front?.[1].match(/^default-model:[ \t]*(\S*)[ \t]*\r?$/m)?.[1];
341
+ if (value === undefined) return 'inherit';
342
+ if (!isModel(value)) throw modelsInvalid(`${path} sets default-model: ${value}, not one of ${MODEL_ALIASES.join(', ')}`);
343
+ return value;
344
+ }
345
+
346
+ // Fixed at start, like audit_rounds; null keeps a run without the line exactly as it was before FEAT-053.
347
+ function resolveRoleModels(root) {
348
+ const value = roleModelsValue(root);
349
+ if (value === null) return null;
350
+ const { defaults, explicit } = parseRoleModels(value);
351
+ return Object.fromEntries(MODEL_ROLES.map((r) => [r, explicit[r] ?? (defaults ? profileDefault(r, root) : 'inherit')]));
352
+ }
353
+
354
+ const shareNote = (m) => (m.audit === m.code && m.code !== 'inherit' ? `; note: audit and code share ${m.code}` : '');
355
+ const modelsNote = (m) => (m ? `; role models: ${MODEL_ROLES.map((r) => `${r}=${m[r]}`).join(', ')}${shareNote(m)}` : '');
356
+
281
357
  function runScript(name, args, input = '') {
282
358
  const r = spawnSync(process.execPath, [join(HERE, name), ...args], { input, encoding: 'utf8' });
283
359
  return { status: r.status, out: r.stdout, err: (r.stderr || '').trim() };
@@ -425,6 +501,12 @@ function checkApprovedDocs(root, run) {
425
501
 
426
502
  const fixNote = (run) => { const f = fixDue(run); return `fix round ${f.round} of ${run.audit_rounds ?? 0}: review ${f.review} sha256 ${f.sha256}`; };
427
503
 
504
+ // FEAT-053: what the script says this dispatch runs on, never the orchestrator's choice; null in a run without models.
505
+ function dispatchModel(run, step) {
506
+ if (!isPlainObject(run.models)) return null;
507
+ return step.fix === undefined ? run.models[step.role] : fixDue(run).model ?? run.models.code;
508
+ }
509
+
428
510
  // Builds and validates the next envelope with --to; installs it unless only checking.
429
511
  function install(root, sessionId, role, check) {
430
512
  const run = liveRun(root, sessionId);
@@ -438,10 +520,11 @@ function install(root, sessionId, role, check) {
438
520
  if (built.status !== 0) throw new Halt('SNAP_ERROR', built.err);
439
521
  const error = validate(built.out, role);
440
522
  if (error) throw new Halt(error.includes('SNAP_GATE_MISMATCH') ? 'SNAP_GATE_MISMATCH' : 'SNAP_ERROR', error);
441
- const out = built.out.trim() + (step.fix === undefined ? '' : `\n${fixNote(run)}`);
523
+ const model = dispatchModel(run, step);
524
+ const out = built.out.trim() + (step.fix === undefined ? '' : `\n${fixNote(run)}`) + (model ? `\nmodel: ${model}` : '');
442
525
  if (check) return out;
443
526
  writeAtomic(join(root, ENVELOPE_FILE), built.out);
444
- saveRun(root, { ...run, band: ROLE_BAND[role], role });
527
+ saveRun(root, { ...run, band: ROLE_BAND[role], role, ...(model ? { dispatch_model: model } : {}) });
445
528
  return out;
446
529
  }
447
530
 
@@ -466,10 +549,12 @@ function entryFields(run, role) {
466
549
  return {};
467
550
  }
468
551
 
552
+ // FEAT-053: an entry carries the model install recorded, read from the run file and never from the report.
469
553
  export function recordHandback(run, role, gate, verdict, extra = {}) {
470
554
  if (role === 'qa' && gate === 'verify_pass') withholdUnlessApproved(run);
471
555
  const fields = entryFields(run, role);
472
- const entry = { role, gate, at: new Date().toISOString(), ...fields, ...(verdict ? { verdict } : {}), ...extra };
556
+ const model = isPlainObject(run.models) && isModel(run.dispatch_model) ? { model: run.dispatch_model } : {};
557
+ const entry = { role, gate, at: new Date().toISOString(), ...fields, ...(verdict ? { verdict } : {}), ...model, ...extra };
473
558
  const tasks = role === 'code' && !('fix' in fields) ? { ...run.tasks, done: run.tasks.done + 1 } : run.tasks;
474
559
  return { ...run, role: null, gate: forwardGate(run, role, gate), tasks, handbacks: [...run.handbacks, entry] };
475
560
  }
@@ -496,6 +581,20 @@ function auditStop({ verdict, blockers }, round, cap) {
496
581
  return new Halt('ORCH_AUDIT_ESCALATE', `audit escalated a decision only the owner takes; see ${report}`);
497
582
  }
498
583
 
584
+ // FEAT-053: a plan task the audit returns a second time goes to the most capable model, and the record names the trigger.
585
+ function fixModel(root, run, paths) {
586
+ if (!isPlainObject(run.models)) return { fields: {}, note: '' };
587
+ const tasks = extractTasks(readDoc(root, run.plan, `cannot read ${run.plan}`).toString('utf8'))
588
+ .filter((t) => t.files.some((f) => paths.includes(f))).map((t) => t.id);
589
+ const earlier = new Set(run.handbacks.slice(0, -1).flatMap((h) => (h.role === 'audit' && Array.isArray(h.fix?.tasks) ? h.fix.tasks : [])));
590
+ const escalated = tasks.filter((id) => earlier.has(id));
591
+ if (escalated.length === 0) return { fields: { tasks, model: run.models.code }, note: `; model ${run.models.code}` };
592
+ return {
593
+ fields: { tasks, model: ESCALATION_MODEL, escalated },
594
+ note: `; model ${ESCALATION_MODEL} (escalated: ${escalated.join(', ')} returned twice)`,
595
+ };
596
+ }
597
+
499
598
  // FEAT-057: the cap is read from the run file, never from the orchestrator, so its prompt cannot buy a round (E2).
500
599
  // Every halt here lands on top of the audit entry handback already saved.
501
600
  function auditFix(root, run, verdict, bytes) {
@@ -506,8 +605,9 @@ function auditFix(root, run, verdict, bytes) {
506
605
  checkApprovedDocs(root, run);
507
606
  const fix = { round: used + 1, files: verdict.paths, review: `${HANDBACK_DIR}/audit-${entry.round}.txt`, sha256: createHash('sha256').update(bytes).digest('hex') };
508
607
  const scope = fixScope(root, run, fix.files, fix.round);
509
- saveRun(root, { ...run, handbacks: [...run.handbacks.slice(0, -1), { ...entry, fix }] });
510
- return `audit round ${entry.round}: RETURN with ${verdict.blockers} blocker/major finding(s); fix round ${fix.round} of ${cap}: review ${fix.review} sha256 ${fix.sha256}; scope ${scope.join(', ')}`;
608
+ const { fields, note } = fixModel(root, run, verdict.paths);
609
+ saveRun(root, { ...run, handbacks: [...run.handbacks.slice(0, -1), { ...entry, fix: { ...fix, ...fields } }] });
610
+ return `audit round ${entry.round}: RETURN with ${verdict.blockers} blocker/major finding(s); fix round ${fix.round} of ${cap}: review ${fix.review} sha256 ${fix.sha256}; scope ${scope.join(', ')}${note}`;
511
611
  }
512
612
 
513
613
  // FEAT-060: a candidate is wider than the valid form, so a near-miss halts by name instead of passing unseen.
@@ -915,6 +1015,9 @@ const reviewWellFormed = (flag, arg, extra) => extra === undefined
915
1015
 
916
1016
  // FEAT-041 (e), reworked by FEAT-058: the loop revises through files, and its outcomes come
917
1017
  // from the script's own reads of the review file and the document, never from the orchestrator's word.
1018
+ // FEAT-053: the two lines that trigger a dispatch name its model; a closing line triggers none.
1019
+ const modelSegment = (run, role) => (isPlainObject(run.models) ? `; model ${run.models[role]}` : '');
1020
+
918
1021
  function review(root, sessionId, [role, flag, arg, extra]) {
919
1022
  const run = liveRun(root, sessionId);
920
1023
  if (!reviewWellFormed(flag, arg, extra)) throw new Refusal(REVIEW_USAGE);
@@ -923,8 +1026,8 @@ function review(root, sessionId, [role, flag, arg, extra]) {
923
1026
  const loops = isPlainObject(run.review) ? run.review : {};
924
1027
  const loop = isPlainObject(loops[role]) && Number.isInteger(loops[role].round) ? loops[role] : { round: 0, outcome: null };
925
1028
  if (loop.outcome) throw new Refusal(`review ${role}: the loop closed ${loop.outcome}; a closed loop does not reopen`);
926
- const { next, say } = flag === '--round' ? openRound(root, role, loop, arg)
927
- : flag === '--record' ? recordRound(root, role, loop)
1029
+ const { next, say } = flag === '--round' ? openRound(root, role, loop, arg, modelSegment(run, 'define-review'))
1030
+ : flag === '--record' ? recordRound(root, role, loop, modelSegment(run, role))
928
1031
  : { next: closedLoop(loop, arg), say: `review ${role} closed ${arg} at round ${loop.round}` };
929
1032
  saveRun(root, { ...run, review: { ...loops, [role]: next } });
930
1033
  if (next.outcome) clearReviewDir(root);
@@ -935,7 +1038,7 @@ function review(root, sessionId, [role, flag, arg, extra]) {
935
1038
  const closedLoop = (loop, outcome) => ({ round: loop.round, outcome, sha256: loop.sha256 ?? null });
936
1039
  const clearReviewDir = (root) => rmSync(join(root, REVIEW_DIR), { recursive: true, force: true });
937
1040
 
938
- function openRound(root, role, loop, rel) {
1041
+ function openRound(root, role, loop, rel, model) {
939
1042
  if (loop.round > 0 && loop.await !== 'revision') throw new Refusal(`review ${role}: round ${loop.round} awaits its review record`);
940
1043
  if (loop.round >= REVIEW_CAP) {
941
1044
  throw new Refusal(`ORCH_REVIEW_CAP: review ${role} has run ${REVIEW_CAP} rounds; close it with --close skipped:<reason>`);
@@ -946,10 +1049,10 @@ function openRound(root, role, loop, rel) {
946
1049
  if (loop.round > 0 && sha256 === loop.sha256) {
947
1050
  return { next: closedLoop({ ...loop, round }, 'unchanged'), say: `review ${role} closed unchanged at round ${round}: ${rel} still hashes ${sha256}` };
948
1051
  }
949
- return { next: { round, outcome: null, sha256, doc: rel, await: 'review' }, say: `review ${role} round ${round} of ${REVIEW_CAP}: ${rel} sha256 ${sha256}` };
1052
+ return { next: { round, outcome: null, sha256, doc: rel, await: 'review' }, say: `review ${role} round ${round} of ${REVIEW_CAP}: ${rel} sha256 ${sha256}${model}` };
950
1053
  }
951
1054
 
952
- function recordRound(root, role, loop) {
1055
+ function recordRound(root, role, loop, model) {
953
1056
  if (loop.await !== 'review') throw new Refusal(`review ${role} --record: no reviewer pass is open`);
954
1057
  const path = `${REVIEW_DIR}/${role}-${loop.round}.md`;
955
1058
  let bytes = null;
@@ -965,7 +1068,7 @@ function recordRound(root, role, loop) {
965
1068
  const reviewSha = createHash('sha256').update(bytes).digest('hex');
966
1069
  return {
967
1070
  next: { ...loop, await: 'revision' },
968
- say: `review ${role} round ${loop.round}: OPEN ${verdict.open}; revise ${loop.doc} sha256 ${loop.sha256} from ${path} sha256 ${reviewSha}`,
1071
+ say: `review ${role} round ${loop.round}: OPEN ${verdict.open}; revise ${loop.doc} sha256 ${loop.sha256} from ${path} sha256 ${reviewSha}${model}`,
969
1072
  };
970
1073
  }
971
1074
 
@@ -1022,6 +1125,7 @@ function start(root, sessionId, args) {
1022
1125
  const stack = () => (detected ??= detectStack(root));
1023
1126
  const testCommand = checkTestCommand(resolveTestCommand(root, stack));
1024
1127
  const docs = resolveDocs(root, item);
1128
+ const models = resolveRoleModels(root);
1025
1129
  const security = resolveSecurity(root, stack(), { threshold, dependencyAudit });
1026
1130
  const bound = ticket === undefined ? null : ticketIntake(root, item, ticket);
1027
1131
  if (old) clearRunFiles(root);
@@ -1032,10 +1136,11 @@ function start(root, sessionId, args) {
1032
1136
  v: 1, session_id: sessionId, item, mode: auto ? 'auto' : 'step', started: new Date().toISOString(),
1033
1137
  band: 'boundary', role: null, gate: 'boundary_routed', approvals: { spec: null, plan: null },
1034
1138
  plan: null, tasks: { ids: [], done: 0 }, handbacks: [], halt: null, test_command: testCommand, audit_rounds: auditRounds, security, docs,
1139
+ ...(models ? { models } : {}),
1035
1140
  ...(bound ? { ticket: { ...bound.binding, snapshot: bound.path } } : {}),
1036
1141
  });
1037
1142
  const begun = old ? `replaced the stale run ${old.item} started ${old.started}` : `run ${item} started`;
1038
- return `${begun}; ${bound ? ticketNote(bound) : ''}${docsNote(docs)}test command: ${testCommand}; audit rounds: ${auditRounds}${securityNote(security, root, stack())}`;
1143
+ return `${begun}; ${bound ? ticketNote(bound) : ''}${docsNote(docs)}test command: ${testCommand}; audit rounds: ${auditRounds}${securityNote(security, root, stack())}${modelsNote(models)}`;
1039
1144
  }
1040
1145
 
1041
1146
  function clearRunFiles(root) {