5-phase-workflow 3.2.1 → 3.2.2

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.
@@ -55,10 +55,10 @@ A compact plan (1-2 files, no migration, security/auth, or public API change) is
55
55
 
56
56
  A full plan goes through four steps:
57
57
 
58
- 1. `step-orchestrator-agent` derives the execution graph — steps, execution mode, dependency edges, model choice, targeted pattern references, and verify commands. A component that needs a file another component creates goes into a later step.
59
- 2. Executor agents implement the components using an inline executor contract, independent ones in parallel. Each follows the repository standards and style skills that apply to its target. Mechanical work runs on `haiku`, ordinary logic on `sonnet`, complex work and every retry on `opus` at medium effort. With `advisor: true` in `.5/config.json` (opt-in, Claude Code only, off by default), executors consult Claude Code's advisor tool at hard decisions and the first retry stays on the planned model (at least `sonnet`); turn the advisor on with `/advisor opus`. When the session has no advisor tool, `/5:implement` says so and runs without it. A component that finds a needed project file missing reports `blocked` instead of failing; it reruns after the next step, not as a retry.
58
+ 1. `step-orchestrator-agent` derives the execution graph on `opus` at medium effort — an approach summary, steps, execution mode, dependency edges, model choice, targeted pattern references, and verify commands. A component groups one coherent change to one or a few tightly coupled files and carries acceptance criteria. A component that needs a file another component creates goes into a later step.
59
+ 2. Executor agents implement the components using an inline executor contract, independent ones in parallel. Each follows the repository standards and style skills that apply to its target. Mechanical work runs on `haiku`, ordinary logic on `sonnet`, complex work and every retry on `opus` at medium effort. With `advisor: true` in `.5/config.json` (opt-in, Claude Code only, off by default), only `opus` components consult Claude Code's advisor tool at hard decisions. All other agents are told not to call it. The first retry stays on the planned model (at least `sonnet`); turn the advisor on with `/advisor opus`. When the session has no advisor tool, `/5:implement` says so and runs without it. A component that finds a needed project file missing reports `blocked` instead of failing; it reruns after the next step, not as a retry. If a component still fails after its retries, the remaining steps are skipped and the run goes to verification and the report.
60
60
  3. When every component was mechanical and passed, build and tests run once plus the scope check. Otherwise `verification-agent` checks completeness, build/tests, the plan's acceptance criteria when it states any, and scope.
61
- 4. The run's files are reviewed and the findings fixed — `code-review`, `review-style`, `security-review` for security-sensitive plans, and a flow review that traces fresh installs, interrupted updates, missing directories, and ordering across files when the plan touches those paths. On Claude Code this happens inside the workflow: one fixer per file applies every clear finding, including a clearly better way a reviewer points out, and build, tests, e2e, and lint run again with up to two repair attempts. You are asked only about findings that need a product, API, data, or security decision, one at a time, after the workflow. On Codex and for compact plans, `/5:review` and `/5:address-review-findings` do the same. Auto-commit comes after, so the fixes land in the same commit.
61
+ 4. The run's files are reviewed and the findings fixed — `code-review`, `review-style`, `security-review` for security-sensitive plans, and a flow review that traces fresh installs, interrupted updates, missing directories, and ordering across files when the plan touches those paths. On Claude Code this happens inside the workflow: a Sonnet skeptic per reviewer tries to refute each finding by reading the code. Findings it cannot confirm are marked skip and are not fixed. One fixer then applies every clear finding, including a clearly better way a reviewer points out, and build, tests, e2e, and lint run again with up to two repair attempts. You are asked only about findings that need a product, API, data, or security decision, one at a time, after the workflow. On Codex and for compact plans, `/5:review` and `/5:address-review-findings` do the same. Auto-commit comes after, so the fixes land in the same commit.
62
62
 
63
63
  Nothing is persisted. If a run fails or is interrupted, fix the cause and rerun `/5:implement`; executors see work already in the files.
64
64
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "5-phase-workflow",
3
- "version": "3.2.1",
3
+ "version": "3.2.2",
4
4
  "description": "A dev-workflow for Claude Code and Codex",
5
5
  "bin": {
6
6
  "foifi": "bin/install.js"
@@ -12,21 +12,24 @@ You follow the plan, your component, and existing codebase patterns. You do not
12
12
  ## Process
13
13
 
14
14
  1. Read only the listed `patternRefs` ranges or symbols before editing. If a component only has legacy `patternFiles`, read the smallest relevant sections of those files instead of the whole file whenever possible.
15
- 2. For `modify`, read the target file first and make the smallest coherent change.
16
- 3. For `rename`, read both `sourceFile` and `file` first, then move content with the smallest coherent change.
17
- 4. For `create`, mirror naming, exports, layout, and test style from the pattern files. Nothing is persisted between runs, so the target may exist from an earlier run: read it first; if it already fulfils the intent, report success with no change, otherwise complete it — never overwrite it blindly.
18
- 5. Follow the standards `/5:implement` assigns: read the parts of the repository standards and style skills that apply to your target. Repository standards win over the style skills. If the target area has a local skill or rule, follow it too.
19
- 6. Run every verify command assigned to your component. If none is assigned, verify touched files exist and run the narrowest relevant test/build command you can infer.
20
- 7. Fix local mechanical issues you caused. Stop for architectural changes, auth gates, missing external services, or unclear product decisions.
21
- 8. When a project file or symbol your component needs does not exist yet, do not create it: stop with `STATUS: blocked` and name it under `BLOCKED_BY`. `/5:implement` reruns you after the next step instead of retrying.
15
+ 2. For `modify`, read the target files first and make the smallest coherent change.
16
+ 3. For `rename`, read both `sourceFile` and the destination in `files` first, then move content with the smallest coherent change.
17
+ 4. For `create`, mirror naming, exports, layout, and test style from the pattern files. Nothing is persisted between runs, so a target file may exist from an earlier run: read it first; if it already fulfils the intent, report success with no change, otherwise complete it — never overwrite it blindly.
18
+ 5. Follow the standards `/5:implement` assigns: read the parts of the repository standards and style skills that apply to your target files. Repository standards win over the style skills. If the target area has a local skill or rule, follow it too.
19
+ 6. Read the approach `summary` for context. Meet every item in the component's `acceptanceCriteria`.
20
+ 7. Run every verify command assigned to your component. If none is assigned, verify touched files exist and run the narrowest relevant test/build command you can infer.
21
+ 8. Fix local mechanical issues you caused. Stop for architectural changes, auth gates, missing external services, or unclear product decisions.
22
+ 9. When a project file or symbol your component needs does not exist yet, do not create it: stop with `STATUS: blocked` and name it under `BLOCKED_BY`. `/5:implement` reruns you after the next step instead of retrying.
22
23
 
23
24
  ## Advisor (opt-in)
24
25
 
25
- Only when `/5:implement` says the advisor is enabled (`.5/config.json` `advisor: true`, and the session has the advisor tool): consult it before committing to an approach when the intent is ambiguous or crosses modules, and when the same verify failure returns after a fix. Do not consult it for mechanical edits or to confirm work that already passes. On a retry, consult it before your first edit.
26
+ Only components planned as `opus`, and their retries, consult the advisor. Every other executor does not call the advisor tool.
27
+
28
+ The advisor must be enabled by `/5:implement` (`.5/config.json` `advisor: true`, and the session has the advisor tool). Then consult it before committing to an approach when the intent is ambiguous or crosses modules, and when the same verify failure returns after a fix. Do not consult it for mechanical edits or to confirm work that already passes. On a retry, consult it before your first edit.
26
29
 
27
30
  ## Simplicity
28
31
 
29
- Write the minimum that satisfies the component (the "smallest coherent change"): reuse what already exists in this codebase first, then prefer the standard library, a native framework feature, or an already-installed dependency over anything new. Add no new dependency, no abstraction for single-use code, no unrequested flexibility, and no error handling for impossible cases. Touch only the target file and what it strictly needs (its test, an import site). Follow `Simplicity First` in the project `AGENTS.md`.
32
+ Write the minimum that satisfies the component (the "smallest coherent change"): reuse what already exists in this codebase first, then prefer the standard library, a native framework feature, or an already-installed dependency over anything new. Add no new dependency, no abstraction for single-use code, no unrequested flexibility, and no error handling for impossible cases. Touch only the target files and what it strictly needs (its test, an import site). Follow `Simplicity First` in the project `AGENTS.md`.
30
33
 
31
34
  End with exactly:
32
35
 
@@ -10,21 +10,23 @@ You are a Step Orchestrator. You do not implement code and you do not write file
10
10
 
11
11
  ## Goal
12
12
 
13
- Turn the plan into execution state that `/5:implement` can run without rethinking the plan. The plan has no fixed shape; derive the components from whatever it describes, one per target file or tightly coupled file group. The graph is transient — it is derived fresh on every run.
13
+ Turn the plan into execution state that `/5:implement` can run without rethinking the plan. The plan has no fixed shape; derive the components from whatever it describes. One component is one coherent change to one or a few tightly coupled files, not one per file. The graph is transient — it is derived fresh on every run.
14
14
 
15
15
  ## Derivation Rules
16
16
 
17
17
  - Name each component in short kebab-case.
18
18
  - Group independent components into the same step with `mode: "parallel"`.
19
- - Use `mode: "sequential"` when components touch the same file, one imports another, or an explicit dependency exists.
19
+ - Use `mode: "sequential"` when components touch the same files, one imports another, or an explicit dependency exists.
20
20
  - For each component, list the project files and symbols it includes, requires, imports, calls, or tests. When another component creates one of them, add it to `dependsOn` and put it in an earlier step — never the same parallel step or a later one.
21
21
  - Prefer fewer steps when dependencies allow.
22
22
  - Tests normally run after the components they validate.
23
23
  - Choose `model: "haiku"` for mechanical work: localized UI changes, tests, docs, config edits, and simple single-file changes.
24
24
  - Choose `model: "sonnet"` for ordinary logic.
25
- - Choose `model: "opus"` only for complex logic, cross-module behavior, security/auth, data migrations, or public API contracts. `/5:implement` runs it at medium effort.
25
+ - Choose `model: "opus"` only for complex logic, cross-module behavior, security/auth, data migrations, or public API contracts. `/5:implement` runs it at medium effort. `/5:implement` also runs this orchestrator on opus at medium effort.
26
26
  - Pick `patternRefs` from patterns the plan names, or from nearby existing files found with Glob/Grep. Prefer one primary reference; use a second only when it adds a distinct convention. Include line ranges or symbols when known so executors avoid reading whole files.
27
27
  - Pick `verifyCommands` from `.5/config.json`, the plan, package scripts, and target-specific checks. Prefer narrow checks first, then project-level build/test.
28
+ - Return a short `summary` of the overall approach. Executors read it for context.
29
+ - Give each component `acceptanceCriteria`: a few short, checkable statements of what must be true when it is done. Take them from the plan where it states them.
28
30
  - Preserve user decisions exactly. Exclude work the plan defers or rules out.
29
31
  - Set `securitySensitive` when the plan touches auth, authorization, user input handling, secrets, cryptography, or SQL/shell/path construction, and `lifecycleSensitive` when it touches install, update, migration, deploy, or bootstrap paths, or the order in which files are written, uploaded, or loaded. They decide which reviewers run after the implementation.
30
32
 
@@ -34,6 +36,7 @@ Return this shape:
34
36
 
35
37
  ```json
36
38
  {
39
+ "summary": "short approach summary",
37
40
  "securitySensitive": false,
38
41
  "lifecycleSensitive": false,
39
42
  "steps": [
@@ -52,9 +55,10 @@ Return this shape:
52
55
  "step": 1,
53
56
  "mode": "parallel|sequential",
54
57
  "model": "haiku|sonnet|opus",
55
- "file": "path/to/file",
58
+ "files": ["path/to/file"],
56
59
  "sourceFile": null,
57
60
  "description": "one sentence",
61
+ "acceptanceCriteria": ["checkable statement"],
58
62
  "dependsOn": [],
59
63
  "patternRefs": [
60
64
  {
@@ -78,4 +82,4 @@ Before returning:
78
82
  - Every non-first-step dependency refers to an existing component name in an earlier step.
79
83
  - Every component has 1-2 high-signal `patternRefs`, or a note explaining why no pattern exists.
80
84
  - Every component has at least one verify command or a note explaining why verification is manual.
81
- - Rename components must set `sourceFile` to the original path and `file` to the destination path.
85
+ - Rename components must set `sourceFile` to the original path. `files` holds the destination path.
@@ -17,7 +17,7 @@ Read the plan `/5:implement` names and `.5/config.json` if present.
17
17
  ## Checks
18
18
 
19
19
  1. Completeness: every planned component is completed, none remain pending, and any acceptance criteria the plan states are addressed.
20
- 2. Files: every planned create/modify target exists unless action is `delete`; `rename` actions verify both that `sourceFile` is removed and `file` exists at the destination path.
20
+ 2. Files: every path in each planned component's `files` exists unless action is `delete`. For `rename`, verify that `sourceFile` is removed and the destination in `files` exists.
21
21
  3. Build: run the configured build command unless it is `none` or the baseline and component results already prove its status.
22
22
  4. Tests: run the configured test command unless it is `none` or the baseline and component results already prove its status.
23
23
  5. Scope: run `git status --short` and `git diff HEAD --stat`, and read untracked (`??`) files directly — `git diff HEAD` omits them. Every changed file traces to a planned component (its target, its test, or an import site it needs) or is a file a repository standard requires, such as a changelog entry. Flag files outside the plan, work the plan rules out or defers, new dependencies no component requires, and abstractions or configurability no acceptance criterion asks for. Report drift only in `SCOPE`; it does not change `STATUS` — the user decides what to revert.
@@ -70,11 +70,13 @@ It moves orchestration into deterministic JS, fires parallel components concurre
70
70
 
71
71
  - `standards` holds the repository standards and style skill paths from Step 1. Executors follow them while writing code.
72
72
  - `baseline` is the array from Step 2 (or `[]`); the workflow's verifier treats those failures as pre-existing and reuses passing results instead of rerunning them.
73
- - `advisor` is `true` only when the advisor is enabled (Step 1). It adds the advisor rule to the executors and keeps their first retry on the planned model, at least `sonnet`.
73
+ - `advisor` is `true` only when the advisor is enabled (Step 1). It adds the advisor rule only to executors planned as `opus` and keeps their first retry on the planned model. Every other agent is told not to call the advisor tool.
74
74
  - `fixedPoint` and `dirty` are the fixed point and the pre-run dirty files from Step 2. The workflow reviews only the run's files since the fixed point and never edits a dirty file.
75
75
  - The workflow reads the config **file** at `paths.config` itself; do not pass build/test/commit settings inline.
76
76
 
77
- The workflow also reviews and fixes: after verification it runs the correctness and standards reviewers — plus security and flow reviewers when the plan touches security or install/update/ordering paths — fixes every clear finding with one fixer per file, and reruns build, test, e2e, and lint with up to two repair attempts. It skips review and fix when verification failed.
77
+ The workflow also reviews and fixes. After verification it runs the correctness and standards reviewers. It adds security and flow reviewers when the plan touches security or install/update/ordering paths. One Sonnet skeptic checks each reviewer's findings and marks refuted ones as `skip`. One fixer then fixes every clear finding across files. Then it reruns build, test, e2e, and lint with up to two repair attempts. It skips review and fix when verification failed.
78
+
79
+ The workflow also returns `skippedSteps` when it stopped after a failed step. Each entry has a `number` and a `name`.
78
80
 
79
81
  2. If the returned `verification.inline` is `true` (every component was mechanical and passed, so no verification agent ran), run steps 2-4 of the **fast-path check** (3c) — the scope part. Build and test already ran in `review.checks`; take their result as the verification.
80
82
  3. Continue with Step 4.
@@ -85,7 +87,7 @@ It produces the same outcome.
85
87
 
86
88
  #### 3a. Derive the execution graph
87
89
 
88
- Spawn `step-orchestrator-agent` with the plan path and config. It returns steps, dependencies, a model per component, `patternRefs` (line ranges/symbols), and verify commands. Check the graph: non-empty steps, and each component carrying `step`, `mode`, `model`, `patternRefs`, and `verifyCommands`.
90
+ Spawn `step-orchestrator-agent` with the plan path and config, on `opus` at `effort: "medium"`. It returns a `summary` of the approach, steps, dependencies, and per component a model, `files`, `acceptanceCriteria`, `patternRefs` (line ranges/symbols), and verify commands. A component is one coherent change to one or a few tightly coupled files. Check the graph: a `summary`, non-empty steps, and each component carrying `step`, `mode`, `model`, `files`, `acceptanceCriteria`, `patternRefs`, and `verifyCommands`.
89
91
 
90
92
  #### 3b. Execute steps in waves
91
93
 
@@ -95,10 +97,11 @@ For each step:
95
97
  2. Spawn executors with the component's model. Run `opus` at `effort: "medium"`.
96
98
  - **Parallel step: emit all of the step's executor Agent calls in a single message so they run concurrently.**
97
99
  - Sequential step (same-file or dependency): one executor at a time.
98
- - Give each executor only its component block, required `patternRefs`, verify commands, the standards from Step 1, and the inline contract below — do not make it read `step-executor-agent.md`. When the advisor is enabled, append the advisor line after the contract.
100
+ - Give each executor only the plan `summary`, its component block with its acceptance criteria, required `patternRefs`, verify commands, the standards from Step 1, and the inline contract below. Do not make it read `step-executor-agent.md`.
101
+ - When the advisor is enabled, append the advisor line after the contract of components planned as `opus` only. Tell every other spawned agent: "Do not call the advisor tool."
99
102
 
100
103
  ```text
101
- Implement exactly the assigned component. Read only listed patternRefs ranges/symbols and the target file. Nothing is persisted between runs, so your work may already be done: for `create`, read the target first when it exists — if it already fulfils the intent, report success with no change; otherwise complete it, never overwrite it blindly. Read the parts of the repository standards and style skills that apply to your target and follow them; repository standards win over the styles. Make the smallest coherent change — reuse existing codebase code first, then stdlib, native platform features, and installed dependencies; touch only the target file and what it strictly needs (its test, an import site) — run assigned verify commands. When a project file or symbol your component needs does not exist yet, do not create it: stop with STATUS: blocked and name it under BLOCKED_BY. Stop (STATUS: failed) for a missing package, unplanned auth/schema/API changes, or unclear product decisions. If verify fails only from pre-existing unrelated issues, report it under DEVIATIONS with the exact evidence and keep STATUS: success — your change is complete. Do not make more than three attempts on the same failing issue.
104
+ Implement exactly the assigned component. Read only listed patternRefs ranges/symbols and the target files. Meet the acceptance criteria you are given. Nothing is persisted between runs, so your work may already be done: for `create`, read the target first when it exists — if it already fulfils the intent, report success with no change; otherwise complete it, never overwrite it blindly. Read the parts of the repository standards and style skills that apply to your target and follow them; repository standards win over the styles. Make the smallest coherent change — reuse existing codebase code first, then stdlib, native platform features, and installed dependencies; touch only the target files and what they strictly need (its test, an import site) — run assigned verify commands. When a project file or symbol your component needs does not exist yet, do not create it: stop with STATUS: blocked and name it under BLOCKED_BY. Stop (STATUS: failed) for a missing package, unplanned auth/schema/API changes, or unclear product decisions. If verify fails only from pre-existing unrelated issues, report it under DEVIATIONS with the exact evidence and keep STATUS: success — your change is complete. Do not make more than three attempts on the same failing issue.
102
105
 
103
106
  End with:
104
107
  ---RESULT---
@@ -113,7 +116,7 @@ ERROR: none | {error description}
113
116
  ---END---
114
117
  ```
115
118
 
116
- Advisor line (only when the advisor is enabled):
119
+ Advisor line (only when the advisor is enabled, and only for components planned as `opus`):
117
120
 
118
121
  ```text
119
122
  Advisor: if an advisor tool is available, consult it before committing to an approach when the intent is ambiguous or crosses modules, and when the same verify failure returns after a fix. Do not consult it for mechanical edits or to confirm work that already passes.
@@ -121,10 +124,12 @@ Advisor: if an advisor tool is available, consult it before committing to an app
121
124
 
122
125
  3. Parse only the `---RESULT---` block from each executor. Trust the executor's report — do not re-read files you did not change to confirm them.
123
126
 
124
- Retry a failed component up to twice, right after it fails (in a sequential step, before the next component starts), on `opus` at `effort: "medium"`. When the advisor is enabled, the first retry stays on the component's planned model — at least `sonnet` — and asks the executor to consult the advisor before its first edit; only the second escalates to `opus`.
127
+ Retry a failed component up to twice, right after it fails (in a sequential step, before the next component starts), on `opus` at `effort: "medium"`. When the advisor is enabled, the first retry of a component planned as `opus` stays on `opus` and asks the executor to consult the advisor before its first edit. For other components the first retry stays on the planned model, at least `sonnet`, with no advisor. Only the second retry escalates to `opus`.
125
128
 
126
129
  `STATUS: blocked` is no retry reason: the component needs a project file or symbol another component has not created yet, and no model can fix that. Rerun it on its planned model once the next step has finished; if it is still blocked, rerun it once more after the last step. Still blocked after that counts as failed. Give every retry the previous attempt's `STATUS`, `VERIFY`, `ERROR`, and `DEVIATIONS` (or that it returned no result). A `STATUS: success` with `VERIFY: failed` is no retry reason: it can come from pre-existing failures, which verification separates using the baseline. Never fix code in the orchestrator context.
127
130
 
131
+ **Stop after a failed step.** When a component of a step is still failed after its retries, do not run the remaining steps. Note them as skipped, then go to 3c and the report. Blocked reruns stay as they are for the steps that ran.
132
+
128
133
  #### 3c. Verify
129
134
 
130
135
  - **Fast path:** when every component reported `success` with `verify` `passed` or `skipped`, every component was planned as `haiku`, and none needed a retry, run the **fast-path check** below and skip `verification-agent`.
@@ -168,7 +173,7 @@ The code is **green** when `review.checks` is `null` or `passed` and the post-fi
168
173
 
169
174
  If `.5/config.json` `git.autoCommit` is `true`, verification passed, and Step 4 left the code green — commit, including the review fixes from Step 4 for those files, once per step for a full plan, once for a compact plan:
170
175
 
171
- 1. Stage only files that step owns: each component's `file` for create/modify/delete, both `sourceFile` and `file` for rename, plus the executors' reported `FILES_CREATED`/`FILES_MODIFIED`. For a compact plan, stage the files you changed. Do not stage unrelated changes. **Never stage a pre-run dirty file** (Step 2), on any plan: it holds the user's own unfinished work. Leave it uncommitted and list it in the report.
176
+ 1. Stage only files that step owns: each component's `files` for create/modify/delete, both `sourceFile` and `files` for rename, plus the executors' reported `FILES_CREATED`/`FILES_MODIFIED`. For a compact plan, stage the files you changed. Do not stage unrelated changes. **Never stage a pre-run dirty file** (Step 2), on any plan: it holds the user's own unfinished work. Leave it uncommitted and list it in the report.
172
177
  2. Build the message from `git.commitMessage.pattern`, replacing `{ticket-id}` with the ticket the plan or the branch name gives (or empty) and `{short-description}` with `step {number}: {step-name}` (compact plan: a short summary of the change); trim redundant whitespace/punctuation when the ticket is empty.
173
178
  3. Commit.
174
179
 
@@ -179,6 +184,7 @@ When a review fix left build, tests, e2e, or lint failing, do not commit; report
179
184
  Report: completed/failed component counts, verification status, auto-commit count and any failures, and any failed commands, missing tests, or unmet acceptance criteria. When verification failed, tell the user to fix the reported issues and rerun `/5:implement {feature-name}`. Also list, one line each:
180
185
 
181
186
  - **Review:** the findings count, how many were fixed without asking, how many you asked about, and every failed fix.
187
+ - **Skipped steps:** the steps not run because an earlier step failed, with their numbers and names.
182
188
  - **Blocked:** components that stayed blocked, with what they were waiting for — a sign the plan's step order is wrong.
183
189
  - **Not verified locally:** the line from Step 2, when build/test could not run here.
184
190
  - **Scope:** drift findings from verification, plus files an executor touched outside its planned target (the workflow returns these as `extraFiles`). Suggest `/5:lean-check {feature-name}` when there are any.
@@ -3,11 +3,11 @@ export const meta = {
3
3
  description: 'Execute a full plan: derive steps, run executors in parallel waves, verify, review, fix the findings. Claude Code only; Codex uses the prose loop.',
4
4
  whenToUse: 'Invoked by the /5:implement command for full plans when the Workflow tool is available. Compact plans never reach it; the command implements them inline.',
5
5
  phases: [
6
- { title: 'Orchestrate', detail: 'one orchestrator agent derives steps + components' },
7
- { title: 'Execute', detail: 'one executor agent per component; parallel components fire together per step; blocked components rerun after the next step' },
6
+ { title: 'Orchestrate', detail: 'one opus orchestrator agent derives the approach summary, steps + components' },
7
+ { title: 'Execute', detail: 'one executor agent per component; parallel components fire together per step; blocked components rerun after the next step; a failed step stops the run' },
8
8
  { title: 'Verify', detail: 'inline when all passed + mechanical, else one verification agent' },
9
- { title: 'Review', detail: 'correctness, standards, and — when the plan calls for them — security and flow reviewers in parallel' },
10
- { title: 'Fix', detail: 'one fixer per file for every clear finding, then build/test/lint with one repair round' }
9
+ { title: 'Review', detail: 'correctness, standards, and — when the plan calls for them — security and flow reviewers in parallel. One sonnet skeptic per reviewer tries to refute its findings as soon as that reviewer finishes' },
10
+ { title: 'Fix', detail: 'one fixer for every clear finding across files, then build/test/lint with one repair round' }
11
11
  ]
12
12
  }
13
13
 
@@ -25,10 +25,11 @@ export const meta = {
25
25
  // auto-commits after this returns. Nothing is persisted: a rerun starts over.
26
26
  //
27
27
  // Models: haiku for mechanical work, sonnet for ordinary logic, opus at effort
28
- // medium for complex work and for every retry. With args.advisor (opt-in, from
29
- // .5/config.json; the command sets it only when the advisor tool is available)
30
- // executors consult Claude Code's advisor tool at decision points and the first
31
- // retry stays on the planned model, at least sonnet.
28
+ // medium for complex work, for every retry, and for the orchestrator.
29
+ // args.advisor is opt-in from .5/config.json. The command sets it only when the
30
+ // advisor tool is available. Then executors planned as opus consult it at decision
31
+ // points, and the first retry stays on the planned model, at least sonnet.
32
+ // Every other agent is told not to call the advisor tool.
32
33
  // ─────────────────────────────────────────────────────────────────────────────
33
34
 
34
35
  const RESULT_SCHEMA = {
@@ -94,6 +95,27 @@ const FIX_SCHEMA = {
94
95
  }
95
96
  }
96
97
 
98
+ const VERDICTS_SCHEMA = {
99
+ type: 'object',
100
+ additionalProperties: false,
101
+ required: ['verdicts'],
102
+ properties: {
103
+ verdicts: {
104
+ type: 'array',
105
+ items: {
106
+ type: 'object',
107
+ additionalProperties: false,
108
+ required: ['number', 'real', 'reason'],
109
+ properties: {
110
+ number: { type: 'integer', description: 'number of the finding in the list' },
111
+ real: { type: 'boolean' },
112
+ reason: { type: 'string' }
113
+ }
114
+ }
115
+ }
116
+ }
117
+ }
118
+
97
119
  const CHECKS_SCHEMA = {
98
120
  type: 'object',
99
121
  additionalProperties: false,
@@ -148,8 +170,9 @@ const VERIFICATION_SCHEMA = {
148
170
  const STATE_SCHEMA = {
149
171
  type: 'object',
150
172
  additionalProperties: false,
151
- required: ['steps', 'pendingComponents'],
173
+ required: ['summary', 'steps', 'pendingComponents'],
152
174
  properties: {
175
+ summary: { type: 'string', description: 'short summary of the approach' },
153
176
  securitySensitive: { type: 'boolean', description: 'the change touches auth, authorization, user input, secrets, crypto, or SQL/shell/path construction' },
154
177
  lifecycleSensitive: { type: 'boolean', description: 'the change touches install, update, migration, deploy, or bootstrap paths, or ordering across files' },
155
178
  steps: {
@@ -172,16 +195,17 @@ const STATE_SCHEMA = {
172
195
  items: {
173
196
  type: 'object',
174
197
  additionalProperties: false,
175
- required: ['name', 'action', 'step', 'mode', 'model', 'file'],
198
+ required: ['name', 'action', 'step', 'mode', 'model', 'files'],
176
199
  properties: {
177
200
  name: { type: 'string' },
178
201
  action: { enum: ['create', 'modify', 'delete', 'rename'] },
179
202
  step: { type: 'integer' },
180
203
  mode: { enum: ['parallel', 'sequential'] },
181
204
  model: { enum: ['haiku', 'sonnet', 'opus'] },
182
- file: { type: 'string' },
183
- sourceFile: { type: ['string', 'null'] },
205
+ files: { type: 'array', items: { type: 'string' }, description: 'target files; for rename the destination' },
206
+ sourceFile: { type: ['string', 'null'], description: 'for rename: the origin' },
184
207
  description: { type: 'string' },
208
+ acceptanceCriteria: { type: 'array', items: { type: 'string' } },
185
209
  dependsOn: { type: 'array', items: { type: 'string' } },
186
210
  patternRefs: {
187
211
  type: 'array',
@@ -213,27 +237,40 @@ Feature: ${a.feature}
213
237
  Plan: ${a.paths.plan}
214
238
  Config: ${a.paths.config} (read only if present)
215
239
 
216
- The plan has no fixed shape. Derive the components from whatever it describes: one component per target file (or tightly coupled file group), named in short kebab-case, then turn them into steps + components:
217
- - Group independent components into one step with mode "parallel"; use "sequential" only when components touch the same file, one imports another, or there is an explicit dependency.
240
+ The plan has no fixed shape. Derive the components from whatever it describes, named in short kebab-case, then turn them into steps + components:
241
+ - One component is one coherent change to one or a few tightly coupled files. Do not split such a change into one component per file. List its target files in files. For a rename, sourceFile is the origin and files holds the destination.
242
+ - Group independent components into one step with mode "parallel"; use "sequential" only when components touch the same files, one imports another, or there is an explicit dependency.
218
243
  - Prefer fewer steps. Tests run after the components they validate.
219
244
  - model "haiku" for mechanical work (UI tweaks, tests, docs, config, simple single-file edits); "sonnet" for ordinary logic; "opus" only for complex logic, cross-module behavior, security/auth, data migrations, or public API contracts.
220
245
  - 1-2 high-signal patternRefs per component with line ranges or symbols so executors avoid whole-file reads. Take them from the plan where it names patterns, else find them with Glob/Grep.
221
246
  - verifyCommands: narrowest relevant check first, then project build/test.
222
247
  - Exclude work the plan defers or rules out. Represent every other component once. dependsOn must reference existing component names.
223
248
  - Dependencies: for each component, list the project files and symbols it includes, requires, imports, calls, or tests. When another component creates one of them, add that component to dependsOn and put it in an EARLIER step — never the same parallel step or a later one.
249
+ - acceptanceCriteria: per component, the checkable outcomes it must meet. Take them from the plan where it states them.
250
+ - summary: a short summary of the overall approach. Executors get it as context.
224
251
  - securitySensitive: true when the plan touches auth, authorization, user input handling, secrets, cryptography, or SQL/shell/path construction. lifecycleSensitive: true when it touches install, update, migration, deploy, or bootstrap paths, or the order in which files are written, uploaded, or loaded.
225
252
 
226
- Return an object matching the schema (securitySensitive, lifecycleSensitive, steps[] and pendingComponents[]).`
253
+ Return an object matching the schema (summary, securitySensitive, lifecycleSensitive, steps[] and pendingComponents[]).${noAdvisorBlock(a)}`
227
254
  }
228
255
 
229
256
  const ADVISOR_RULE = 'Advisor: if an advisor tool is available, consult it before committing to an approach when the intent is ambiguous or crosses modules, and when the same verify failure returns after a fix. Do not consult it for mechanical edits or to confirm work that already passes.'
230
257
 
231
- function retryContext(previous, a) {
258
+ // The session advisor reaches every subagent. Only executors planned as opus may use it.
259
+ // The advisor line goes at the end of a prompt as its own paragraph, or nothing when the advisor is off.
260
+ function advisorBlock(a, advised) {
261
+ if (!a.advisor) return ''
262
+ return `\n\n${advised ? ADVISOR_RULE : 'Do not call the advisor tool.'}`
263
+ }
264
+
265
+ // For every agent that is not an executor planned as opus.
266
+ const noAdvisorBlock = a => advisorBlock(a, false)
267
+
268
+ function retryContext(previous, a, advised) {
232
269
  const failure = previous
233
270
  ? `status ${previous.status}, verify ${previous.verify}, error: ${previous.error || 'none'}, deviations: ${previous.deviations || 'none'}`
234
271
  : 'the agent crashed without returning a result'
235
- const advisor = a.advisor ? ' Consult the advisor, if available, before your first edit.' : ''
236
- return `This is a RETRY of a failed attempt (${failure}). Read the target as the previous attempt left it, find the root cause, and correct it.${advisor}`
272
+ const advisor = a.advisor && advised ? ' Consult the advisor, if available, before your first edit.' : ''
273
+ return `This is a RETRY of a failed attempt (${failure}). Read the target files as the previous attempt left them, find the root cause, and correct it.${advisor}`
237
274
  }
238
275
 
239
276
  function executorPrompt(c, a, opts) {
@@ -242,35 +279,45 @@ function executorPrompt(c, a, opts) {
242
279
  const standards = a.standards || {}
243
280
  const repoStandards = (standards.repo || []).map(f => ` - ${f}`).join('\n') || ' - none found'
244
281
  const styles = (standards.styles || []).map(f => ` - ${f}`).join('\n') || ' - none found'
245
- const retry = opts && opts.retry ? `\n${retryContext(opts.result, a)}` : ''
246
- const advisor = a.advisor ? `\n\n${ADVISOR_RULE}` : ''
282
+ // An executor is advised only when it was planned as opus. That holds for its retries too.
283
+ const advised = c.model === 'opus'
284
+ const retry = opts && opts.retry ? `\n${retryContext(opts.result, a, advised)}` : ''
285
+ const advisor = advisorBlock(a, advised)
286
+ const criteria = (c.acceptanceCriteria || []).map(x => ` - ${x}`).join('\n') || ' - as described in the intent'
247
287
  return `You are a Step Executor. Implement EXACTLY this component and nothing more.${retry}
248
288
 
289
+ Approach (context only): ${a.summary || 'see the plan'}
290
+
249
291
  Component: ${c.name}
250
292
  Action: ${c.action}
251
- Target file: ${c.file}${c.sourceFile ? `\nSource file (rename from): ${c.sourceFile}` : ''}
293
+ Target files: ${(c.files || []).join(', ')}${c.sourceFile ? `\nSource file (rename from): ${c.sourceFile}` : ''}
252
294
  Intent: ${c.description || ''}
295
+ Acceptance criteria:
296
+ ${criteria}
253
297
 
254
- Read only these pattern references (ranges/symbols), plus the target file for modify/rename — and for create when it already exists:
298
+ Read only these pattern references (ranges/symbols), plus the target files for modify/rename — and for create when they already exist:
255
299
  ${refs}
256
300
 
257
- Standards — read the parts that apply to your target and follow them. Repository standards win over the style skills.
301
+ Standards — read the parts that apply to your target files and follow them. Repository standards win over the style skills.
258
302
  Repository standards:
259
303
  ${repoStandards}
260
304
  Style skills:
261
305
  ${styles}
262
306
 
263
- Rules: Nothing is persisted between runs, so your work may already be done: for \`create\`, read the target first when it exists — if it already fulfils the intent, report success with no change; otherwise complete it, never overwrite it blindly. Smallest coherent change; reuse what already exists in this codebase before writing new code, then prefer stdlib, native platform features, and installed dependencies; touch only the target file and what it strictly needs (its test, an import site); mirror existing naming/exports/layout/tests; follow any local skill or rule; add no new dependency; no abstraction or error handling beyond what the intent requires. Fix mechanical issues you cause (imports, types, lint). When a project file or symbol your component needs does not exist yet, do not create it: STOP and report status blocked with blockedBy — /5:implement reruns you after the next step. STOP and report failed for a missing package, unplanned auth/schema/API/contract changes, or unclear product decisions. If verify fails only from pre-existing unrelated issues, report that as a deviation with the exact evidence — do not mark the component failed. Do not make more than three attempts on the same failing issue.${advisor}
307
+ Rules: Nothing is persisted between runs, so your work may already be done: for \`create\`, read each target first when it exists — if it already fulfils the intent, report success with no change; otherwise complete it, never overwrite it blindly. Smallest coherent change; reuse what already exists in this codebase before writing new code, then prefer stdlib, native platform features, and installed dependencies; touch only the target files and what they strictly need (its test, an import site); mirror existing naming/exports/layout/tests; follow any local skill or rule; add no new dependency; no abstraction or error handling beyond what the intent requires. Fix mechanical issues you cause (imports, types, lint). When a project file or symbol your component needs does not exist yet, do not create it: STOP and report status blocked with blockedBy — /5:implement reruns you after the next step. STOP and report failed for a missing package, unplanned auth/schema/API/contract changes, or unclear product decisions. If verify fails only from pre-existing unrelated issues, report that as a deviation with the exact evidence — do not mark the component failed. Do not make more than three attempts on the same failing issue.${advisor}
264
308
 
265
309
  Then run: ${verify}
266
310
 
267
311
  Return structured output: status, blockedBy (only when blocked), filesCreated, filesModified, verify, deviations (none or brief), skipped (none, or what you deliberately did not build — add when ...), error (none or description). Keep it concise — no logs or diffs unless failed.`
268
312
  }
269
313
 
270
- function verifyPrompt(a, results) {
314
+ function verifyPrompt(a, results, skippedSteps) {
271
315
  const ran = results.flatMap(s => s.items.map(i =>
272
316
  ` step ${s.step} ${i.component.name}: ${i.result ? i.result.status : 'no result'}${i.result && i.result.blockedBy ? ` by ${i.result.blockedBy}` : ''} (verify ${i.result ? i.result.verify : '?'})${i.escalated ? ' [escalated to opus]' : i.retried ? ' [retried]' : ''}`))
273
317
  const summary = ran.join('\n') || ' (no components ran)'
318
+ const skipped = (skippedSteps || []).length
319
+ ? `\n\nSkipped steps — not run because an earlier step failed. Their components are not done, so completeness is not passed:\n${skippedSteps.map(s => ` step ${s.number} ${s.name}`).join('\n')}`
320
+ : ''
274
321
  const repoStandards = ((a.standards && a.standards.repo) || []).join(', ') || 'none found'
275
322
  const baseline = (a.baseline && a.baseline.length)
276
323
  ? a.baseline.map(b => ` ${b.command || b.details && b.details.command || '?'}: ${b.status}${b.summary ? ` — ${b.summary}` : ''}`).join('\n')
@@ -286,11 +333,11 @@ Baseline (pre-change) command results — treat any failure listed here as PRE-E
286
333
  ${baseline}
287
334
 
288
335
  Component results:
289
- ${summary}
336
+ ${summary}${skipped}
290
337
 
291
338
  Checks — only whether the plan was built and works; code quality and correctness belong to /5:review, which runs next: completeness (every planned component done, and any acceptance criteria the plan states addressed); files exist for create/modify, rename moved correctly, delete removed; build + test pass (reuse the baseline and component results above when they already prove status — rerun only the commands whose inputs changed, not identical passing ones); scope (run \`git status --short\` and \`git diff HEAD --stat\`, and read untracked files directly since \`git diff HEAD\` omits them: every changed file traces to a planned component — its target, its test, an import site, or a file a repository standard requires (such as a changelog entry); flag files outside the plan, work the plan rules out or defers, new dependencies no component requires, and unrequested abstractions — report drift only in scope; it does not change status). Prefer changed files over broad scanning.
292
339
 
293
- Return structured output: status, completeness, infrastructure, acceptanceCriteria ("satisfied/total"), scope, commands[], failures[] (one "drift: {path} — {why}" entry per drift finding).`
340
+ Return structured output: status, completeness, infrastructure, acceptanceCriteria ("satisfied/total"), scope, commands[], failures[] (one "drift: {path} — {why}" entry per drift finding).${noAdvisorBlock(a)}`
294
341
  }
295
342
 
296
343
  // The user should be asked as little as possible: "decide" is the exception, "fix" the default.
@@ -311,7 +358,7 @@ function correctnessPrompt(a, files) {
311
358
 
312
359
  If the built-in code-review skill is available, invoke Skill(skill: "code-review", args: "high") — never with --fix or --comment — and keep only its findings in these files. Otherwise review the diff blind, on its merits: triage files by risk; read full files only for high-risk changes, public API boundaries, security/auth, and data migrations. Report bugs, security, performance, code quality, API design, missing tests, and over-engineering (unnecessary abstractions, single-use indirection, speculative generality, reinventing stdlib or existing dependencies).
313
360
 
314
- ${TRIAGE_RULE}`
361
+ ${TRIAGE_RULE}${noAdvisorBlock(a)}`
315
362
  }
316
363
 
317
364
  function securityPrompt(a, files) {
@@ -319,13 +366,13 @@ function securityPrompt(a, files) {
319
366
 
320
367
  If the built-in security-review skill is available, invoke Skill(skill: "security-review") and keep only its findings in these files. Otherwise review them for authentication and authorization gaps, unvalidated input, leaked secrets, weak cryptography, and SQL/shell/path injection. Every security finding has severity error.
321
368
 
322
- ${TRIAGE_RULE}`
369
+ ${TRIAGE_RULE}${noAdvisorBlock(a)}`
323
370
  }
324
371
 
325
372
  function standardsPrompt(a, files) {
326
373
  return `You are a Standards Reviewer. Invoke Skill(skill: "review-style", args: "${a.fixedPoint || 'HEAD'} files: ${files.join(', ')} report only"); if it cannot be invoked, read .claude/skills/review-style/SKILL.md and follow it with the same arguments. Leave out its Suppressed findings. ⛔️ hard breaches of a repository standard are severity error, ⚠️ judgement calls severity suggestion; a judgement call whose fix is clearly better is fix, otherwise skip.
327
374
 
328
- ${TRIAGE_RULE}`
375
+ ${TRIAGE_RULE}${noAdvisorBlock(a)}`
329
376
  }
330
377
 
331
378
  function flowPrompt(a, files) {
@@ -339,18 +386,30 @@ A diff reviewer reads file by file; you trace behavior ACROSS these files and th
339
386
  - files and helpers the change relies on but does not check, and tests that assert the old order or state.
340
387
  Report only failures you can describe as a concrete sequence of states.
341
388
 
342
- ${TRIAGE_RULE}`
389
+ ${TRIAGE_RULE}${noAdvisorBlock(a)}`
343
390
  }
344
391
 
345
- function fixerPrompt(a, file, findings) {
346
- const list = findings.map(f => ` - ${f.id}${f.line ? ` (line ${f.line})` : ''}: ${f.description} → ${f.fix || 'fix as described'}`).join('\n')
392
+ // One skeptic checks all findings of one reviewer at once. Unsure counts as not real.
393
+ function skepticPrompt(a, findings) {
394
+ const list = findings.map((f, n) => `${n + 1}. ${f.file}${f.line ? `:${f.line}` : ''} — ${f.description}\n Fix: ${f.fix || 'as described'}`).join('\n')
395
+ return `You are a Review Skeptic. Try to refute each of these review findings by reading the code yourself. Do not edit any file.
396
+
397
+ ${list}
398
+
399
+ Judge every finding on its own. Do not let one verdict influence the next.
400
+ Set real=false when the finding cannot happen, is already handled, or is not a problem. If unsure, set real=false.
401
+ Return one verdict per finding with its number and a one-line reason.${noAdvisorBlock(a)}`
402
+ }
403
+
404
+ function fixerPrompt(a, findings) {
405
+ const list = findings.map(f => ` - ${f.id} ${f.file}${f.line ? `:${f.line}` : ''}: ${f.description} → ${f.fix || 'fix as described'}`).join('\n')
347
406
  const dirty = (a.dirty || []).join(', ') || 'none'
348
- return `You are a Review Fixer. Apply these review findings in ${file}:
407
+ return `You are a Review Fixer. Apply these review findings:
349
408
  ${list}
350
409
 
351
- Read the file first, then apply the fixes from the highest line to the lowest. Touch another file only when a fix strictly needs it (its test, a caller), and never one of these, which hold the user's own uncommitted work: ${dirty}. Make no unrelated change. When reading the code shows a finding's premise is wrong, mark it rejected with the reason — do not ask. Follow the repository standards first, then the style skills. Run the narrowest relevant test or build for the file.
410
+ Read each file first, then apply its fixes from the highest line to the lowest. Touch another file only when a fix strictly needs it (its test, a caller), and never one of these, which hold the user's own uncommitted work: ${dirty}. Make no unrelated change. When reading the code shows a finding's premise is wrong, mark it rejected with the reason — do not ask. Follow the repository standards first, then the style skills. Run the narrowest relevant test or build for the changed files.
352
411
 
353
- Return structured output: one item per finding id (applied, rejected, or failed, with a one-line note) and filesModified.`
412
+ Return structured output: one item per finding id (applied, rejected, or failed, with a one-line note) and filesModified.${noAdvisorBlock(a)}`
354
413
  }
355
414
 
356
415
  function checksPrompt(a, files) {
@@ -364,7 +423,7 @@ ${baseline}
364
423
 
365
424
  When a command fails because of this run's changes, fix the cause with the smallest change in these files only — ${files.join(', ')} — and rerun it. At most two repair attempts per command. Do not touch any other file.
366
425
 
367
- Return structured output: status (passed when every command passed, was skipped, or failed only pre-existing), commands[] with category, command, status, and a one-line summary, and filesModified (repairs only).`
426
+ Return structured output: status (passed when every command passed, was skipped, or failed only pre-existing), commands[] with category, command, status, and a one-line summary, and filesModified (repairs only).${noAdvisorBlock(a)}`
368
427
  }
369
428
 
370
429
  // ── Helpers ──────────────────────────────────────────────────────────────────
@@ -387,7 +446,7 @@ function isBlocked(item) {
387
446
  }
388
447
 
389
448
  // Retries escalate to opus. With the advisor available, the first retry stays on the planned model
390
- // (at least sonnet) and consults the advisor instead; only the second escalates.
449
+ // (at least sonnet) and only the second escalates. Only a component planned as opus consults the advisor.
391
450
  function retryModel(c, attempt, a) {
392
451
  if (!(a.advisor && attempt === 1)) return 'opus'
393
452
  return c.model === 'haiku' || !c.model ? 'sonnet' : c.model
@@ -412,8 +471,8 @@ async function runComponent(c, a) {
412
471
  return item
413
472
  }
414
473
 
415
- async function runStep(step, components, a) {
416
- const stepComps = components.filter(c => step.components.includes(c.name))
474
+ async function runStep(step, plan, a) {
475
+ const stepComps = plan.pendingComponents.filter(c => step.components.includes(c.name))
417
476
  let items
418
477
  if (step.mode === 'parallel') {
419
478
  // Fire every parallel component together, retries included — true concurrency, one wave.
@@ -440,10 +499,33 @@ async function rerunBlocked(items, a, afterStep) {
440
499
 
441
500
  const stripDot = f => f.replace(/^\.\//, '')
442
501
 
502
+ // Hands the fix and decide findings of one reviewer to a sonnet skeptic. A refuted finding becomes skip.
503
+ // A crashed skeptic or a missing verdict leaves the findings unchanged.
504
+ async function refuteFindings(a, key, findings) {
505
+ if (!findings) return findings
506
+ const open = findings.filter(f => f.action === 'fix' || f.action === 'decide')
507
+ if (!open.length) return findings
508
+ const out = await agent(skepticPrompt(a, open), { label: `skeptic:${key}`, phase: 'Review', ...modelOpts('sonnet'), schema: VERDICTS_SCHEMA })
509
+ .catch(() => null)
510
+ if (!out) {
511
+ log(`skeptic:${key} returned nothing, findings kept as they are`)
512
+ return findings
513
+ }
514
+ open.forEach((f, n) => {
515
+ const verdict = out.verdicts.find(v => v.number === n + 1)
516
+ if (verdict && !verdict.real) {
517
+ f.action = 'skip'
518
+ f.reason = `refuted: ${verdict.reason}`
519
+ f.refuted = true
520
+ }
521
+ })
522
+ return findings
523
+ }
524
+
443
525
  // Review the run's files, triage the findings, fix every clear one, then rerun build/test/lint.
444
526
  async function reviewAndFix(a, plan, allItems, verification, usedOpus) {
445
527
  const runFiles = [...new Set(allItems.flatMap(i => [
446
- i.component.file, i.component.sourceFile,
528
+ ...(i.component.files || []), i.component.sourceFile,
447
529
  ...(i.result ? [...(i.result.filesCreated || []), ...(i.result.filesModified || [])] : [])
448
530
  ]).filter(Boolean).map(stripDot))]
449
531
  const dirty = new Set((a.dirty || []).map(stripDot))
@@ -455,9 +537,14 @@ async function reviewAndFix(a, plan, allItems, verification, usedOpus) {
455
537
  ]
456
538
  if (plan.securitySensitive) reviewers.push({ key: 'security', prompt: securityPrompt, model: 'sonnet' })
457
539
  if (plan.lifecycleSensitive || plan.securitySensitive) reviewers.push({ key: 'flow', prompt: flowPrompt, model: 'opus' })
458
- const reports = await parallel(reviewers.map(r => () =>
459
- agent(r.prompt(a, runFiles), { label: `review:${r.key}`, phase: 'Review', ...modelOpts(r.model), schema: FINDINGS_SCHEMA })
460
- .then(out => out && out.findings.map(f => ({ ...f, reviewer: r.key })))))
540
+ // Each reviewer's skeptic starts as soon as that reviewer finishes.
541
+ const reports = await pipeline(
542
+ reviewers,
543
+ r => agent(r.prompt(a, runFiles), { label: `review:${r.key}`, phase: 'Review', ...modelOpts(r.model), schema: FINDINGS_SCHEMA })
544
+ .catch(() => null)
545
+ .then(out => ({ key: r.key, findings: out && out.findings.map(f => ({ ...f, reviewer: r.key })) })),
546
+ report => refuteFindings(a, report.key, report.findings)
547
+ )
461
548
  const missing = reviewers.filter((r, n) => !reports[n]).map(r => r.key)
462
549
  if (missing.length) log(`reviewer(s) returned nothing: ${missing.join(', ')}`)
463
550
 
@@ -465,7 +552,10 @@ async function reviewAndFix(a, plan, allItems, verification, usedOpus) {
465
552
  const findings = []
466
553
  const seen = new Set()
467
554
  let outside = 0
468
- for (const f of reports.filter(Boolean).flat()) {
555
+ // Refuted findings come last, so they never take the file:line slot of a live finding.
556
+ const reported = reports.filter(Boolean).flat()
557
+ const ordered = [...reported.filter(f => f.action !== 'skip'), ...reported.filter(f => f.action === 'skip')]
558
+ for (const f of ordered) {
469
559
  const file = stripDot(f.file)
470
560
  if (!runFiles.includes(file)) { outside++; continue }
471
561
  const key = `${file}:${f.line || 0}`
@@ -481,23 +571,21 @@ async function reviewAndFix(a, plan, allItems, verification, usedOpus) {
481
571
  if (outside) log(`review: dropped ${outside} finding(s) outside the run's files`)
482
572
 
483
573
  phase('Fix')
484
- const byFile = new Map()
485
- for (const f of findings.filter(f => f.action === 'fix')) {
486
- if (!byFile.has(f.file)) byFile.set(f.file, [])
487
- byFile.get(f.file).push(f)
488
- }
489
- const fixModel = plan.securitySensitive ? 'opus' : 'sonnet'
490
- await parallel([...byFile].map(([file, list]) => async () => {
491
- const out = await agent(fixerPrompt(a, file, list), { label: `fix:${file}`, phase: 'Fix', ...modelOpts(list.some(f => f.reviewer === 'flow') ? 'opus' : fixModel), schema: FIX_SCHEMA })
574
+ // One fixer applies every clear finding across files.
575
+ const toFix = findings.filter(f => f.action === 'fix')
576
+ if (toFix.length) {
577
+ const needsOpus = plan.securitySensitive || toFix.some(f => f.reviewer === 'flow')
578
+ const fixModel = needsOpus ? 'opus' : 'sonnet'
579
+ const out = await agent(fixerPrompt(a, toFix), { label: 'fix', phase: 'Fix', ...modelOpts(fixModel), schema: FIX_SCHEMA })
492
580
  .catch(() => null)
493
- for (const f of list) {
581
+ for (const f of toFix) {
494
582
  const item = out && out.items.find(i => i.id === f.id)
495
583
  f.status = item ? item.status : 'failed'
496
584
  if (item && item.note) f.note = item.note
497
585
  }
498
- }))
586
+ }
499
587
  const applied = findings.filter(f => f.status === 'applied').length
500
- log(`review: ${findings.length} finding(s), ${applied} fixed, ${findings.filter(f => f.action === 'decide').length} need a decision`)
588
+ log(`review: ${findings.length} finding(s), ${findings.filter(f => f.refuted).length} refuted, ${applied} fixed, ${findings.filter(f => f.action === 'decide').length} need a decision`)
501
589
 
502
590
  // The inline fast path ran no build/test yet, and applied fixes change what the verifier saw.
503
591
  let checks = null
@@ -512,27 +600,41 @@ async function reviewAndFix(a, plan, allItems, verification, usedOpus) {
512
600
  const a = args || {}
513
601
 
514
602
  phase('Orchestrate')
515
- const plan = await agent(orchestratorPrompt(a), { label: 'orchestrate', phase: 'Orchestrate', schema: STATE_SCHEMA })
603
+ const plan = await agent(orchestratorPrompt(a), { label: 'orchestrate', phase: 'Orchestrate', ...modelOpts('opus'), schema: STATE_SCHEMA })
516
604
  const steps = plan.steps
517
605
  const components = plan.pendingComponents
606
+ // Executors get the approach summary as context.
607
+ const ctx = { ...a, summary: plan.summary }
518
608
 
519
609
  phase('Execute')
520
610
  // A blocked component waits for the next step, then — if still blocked — for the end of the run.
611
+ // A step whose component still fails after its retries stops the run. Later steps would build on it.
521
612
  const results = []
522
613
  let waiting = []
523
614
  const late = []
524
615
  for (let n = 0; n < steps.length; n++) {
525
- const r = await runStep(steps[n], components, a)
616
+ const r = await runStep(steps[n], plan, ctx)
526
617
  results.push(r)
618
+ // A blocked component from the previous step that fails on its rerun stops the run too.
619
+ let rerunFailed = []
527
620
  if (waiting.length) {
528
- await rerunBlocked(waiting, a, n)
621
+ await rerunBlocked(waiting, ctx, n)
529
622
  late.push(...waiting.filter(isBlocked))
623
+ rerunFailed = waiting.filter(i => needsRetry(i.result))
530
624
  }
531
625
  waiting = r.items.filter(isBlocked)
532
626
  waiting.forEach(i => { i.lastTry = n })
627
+ const failed = [...r.items.filter(i => needsRetry(i.result)), ...rerunFailed]
628
+ if (failed.length) {
629
+ log(`stopping after step ${steps[n].number}: ${failed.map(i => i.component.name).join(', ')} failed`)
630
+ break
631
+ }
533
632
  }
534
- const finalRerun = [...late.filter(i => i.lastTry < steps.length - 1), ...waiting]
535
- if (finalRerun.length) await rerunBlocked(finalRerun, a, steps.length)
633
+ // `results` holds one entry per step that ran. The final rerun covers only those steps.
634
+ const lastRun = results.length - 1
635
+ const skippedSteps = steps.slice(results.length).map(s => ({ number: s.number, name: s.name }))
636
+ const finalRerun = [...late.filter(i => i.lastTry < lastRun), ...waiting]
637
+ if (finalRerun.length) await rerunBlocked(finalRerun, ctx, lastRun + 1)
536
638
 
537
639
  phase('Verify')
538
640
  const allItems = results.flatMap(s => s.items)
@@ -544,7 +646,7 @@ const mechanical = !usedOpus && !allItems.some(i => i.retried) && components.eve
544
646
  // Deterministic scope signal: files an executor touched beyond its planned target(s).
545
647
  // Tests and import sites are legitimate, so this is reported for the user, never a failure.
546
648
  const extraFiles = allItems.flatMap(i => {
547
- const planned = new Set([i.component.file, i.component.sourceFile].filter(Boolean).map(stripDot))
649
+ const planned = new Set([...(i.component.files || []), i.component.sourceFile].filter(Boolean).map(stripDot))
548
650
  const touched = i.result ? [...(i.result.filesCreated || []), ...(i.result.filesModified || [])].map(stripDot) : []
549
651
  return touched.filter(f => !planned.has(f)).map(f => ({ component: i.component.name, file: f }))
550
652
  })
@@ -555,7 +657,7 @@ if (allPassed && mechanical) {
555
657
  // No shell access here: the Checks agent in reviewAndFix runs build/test, /5:implement the scope check, when it sees inline: true.
556
658
  verification = { status: 'passed', completeness: 'passed', infrastructure: 'passed', acceptanceCriteria: 'n/a', commands: [], failures: [], inline: true }
557
659
  } else {
558
- verification = await agent(verifyPrompt(a, results), {
660
+ verification = await agent(verifyPrompt(a, results, skippedSteps), {
559
661
  label: 'verify', phase: 'Verify', ...modelOpts(usedOpus ? 'opus' : 'sonnet'), schema: VERIFICATION_SCHEMA
560
662
  })
561
663
  }
@@ -572,16 +674,18 @@ const checksPassed = !review || !review.checks || review.checks.status === 'pass
572
674
  // Returned to the /5:implement command for the findings file, the decisions, the scope check, per-step staging, and the report.
573
675
  return {
574
676
  feature: a.feature,
677
+ summary: plan.summary,
575
678
  steps,
576
679
  components,
577
680
  results: results.map(s => ({
578
681
  step: s.step,
579
682
  name: s.name,
580
683
  mode: s.mode,
581
- items: s.items.map(i => ({ component: i.component.name, file: i.component.file, sourceFile: i.component.sourceFile, retried: i.retried, escalated: i.escalated, result: i.result }))
684
+ items: s.items.map(i => ({ component: i.component.name, files: i.component.files, sourceFile: i.component.sourceFile, retried: i.retried, escalated: i.escalated, result: i.result }))
582
685
  })),
583
686
  verification,
687
+ skippedSteps,
584
688
  extraFiles,
585
689
  review,
586
- status: verification.status === 'passed' && checksPassed ? 'completed' : 'failed'
690
+ status: verification.status === 'passed' && checksPassed && !skippedSteps.length ? 'completed' : 'failed'
587
691
  }