vinta-ai-workflows 0.7.0-alpha33 → 0.7.0-alpha35

package/CHANGELOG.md

@@ -7,6 +7,8 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [0.7.0] — YYYY-MM-DD
 
+<!-- pre-release: 0.7.0-alpha35 on 2026-10-16 -->
+<!-- pre-release: 0.7.0-alpha34 on 2026-10-16 -->
 <!-- pre-release: 0.7.0-alpha33 on 2026-10-16 -->
 <!-- pre-release: 0.7.0-alpha31 on 2026-10-09 -->
 <!-- pre-release: 0.7.0-alpha30 on 2026-10-09 -->
@@ -33,6 +35,54 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **`vinta-ai-maestro`: integration is visible while it happens.** A phase in
+  `integrate` — a merge, a suite on the merged tree, a push, none with an
+  agent — showed `running` over a silent transcript, and one queued behind it
+  looked the same. Now:
+  - The phase view has an **Integration** timeline: each merge, conflict fix
+    round, `verify`, wave gate, push and PR of this attempt, a live clock on
+    the one in progress, and the log of every step that has one.
+  - The run view has an **Integration worktree** panel: who holds it, the step
+    it is on and for how long, and who is queued behind it. The roster and
+    the phase header show each running phase's pipeline step.
+  - `status` prints the step beside each running phase and an `integration`
+    line (`a · wave 1 gate unit · 6m 13s · 1 queued (b)`); `status --json`
+    carries `nodes[].step` and `integration`.
+  - A conflict fixer's turn is also written to the transcript of the phase
+    being based or building the wave, not only to the incoming phase's.
+
+  Two additive journal events back it: `node_step` (the pipeline state an
+  attempt entered) and `integration_step` (a step started or finished in the
+  worktree, identifiers and a log path only). Older runs have neither and
+  show no timeline.
+- **`vinta-ai-maestro`: `accept` on an unapproved review.** The review-budget
+  question offered `continue` or `stop`, and operators answered `stop` meaning
+  "take it as it is" — which fails the attempt and, under `--on-failure
+  retry`, starts the phase over. It now offers `continue`, `accept` and `stop`
+  and says what each does. `accept` ends the review loop and keeps the work:
+  the polish chores, the gates and integration still run, and the answer is
+  journalled. The unattended answer is unchanged (`continue` once, then
+  `stop`); the coordinator cannot answer `accept`.
+- **`vinta-ai-maestro validate` warns about parallel phases adding migrations
+  to one app**, and `plan-feature` treats them as real overlap. Two phases
+  that neither depends on the other, each adding a migration under the same
+  directory (Django `<app>/migrations/`, Alembic `…/versions/`, Rails
+  `db/migrate/`, Prisma `prisma/migrations/`), start from the same latest
+  migration; merged, the graph has two leaves and every gate on the merged
+  tree fails. Their Touch Lists name different files, so nothing flagged it.
+  `validate --json` gains a `warnings` list, printed as `warning:` lines in
+  text mode, and the review page shows them in their own panel; neither
+  changes the exit code or `valid`. `plan-feature` now says to add the edge,
+  or to name the phase whose integration writes the merge migration.
+- **`vinta-ai-maestro node resume <run> <phase>`**, the undo of `node pause`:
+  it withdraws a pause not yet taken, releases a phase parked on the pause, or
+  gives a held phase its `--retry-after` timer back. It used to take
+  answering an undocumented "The operator paused this node. Resume it?"
+  question, or answering a held phase's question by hand.
+- **`vinta-ai-maestro status` shows the question each phase is asking**, with
+  its choices, and `status --json` carries it per node as `question`
+  (`effectId`, `question`, `kind`, `choices`, `askedAt`). `asking: true` alone
+  sent operators into `flow.db` to read it.
 - **`vinta-ai-maestro`: ways past a stale gate verdict.** `gate <id>
   --no-cache` runs a gate past its cached result and keeps the new one in its
   place; a cached red now says so. `gate-cache invalidate <run-id> <gate-id>
@@ -609,6 +659,30 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Changed
 
+- **`vinta-ai-maestro`: the full suite runs before a PR, and on every merged
+  tree.** Under `gate_scope: scoped`, a phase's gates ran their scoped form
+  everywhere, so a PR could carry a suite only a scoped run had seen, and most
+  phases were `done` before any full suite touched their code.
+  - A phase's gates run scoped until its review approves; `verify`, after the
+    review, runs every gate's full `cmd` on the phase branch. A red full run
+    goes back to a fixer and through the review again — more review rounds,
+    no failing suite in a PR. The fixer is told the gate failed in full, and
+    `vinta-ai-maestro gate <id> --full` runs the whole command for an agent.
+  - `defaults.wave_gates` now defaults to `every`: each wave's gates run in
+    full on the merged tree, so the next wave builds on a passing one. Set
+    `final` for the previous behaviour.
+  - A multi-dependency phase's `integ-<id>` base runs its dependencies' gates
+    in full before the phase starts, cached on the merged tree; red fails the
+    phase's setup with `BaseGateError`. A clean base merge used to run nothing.
+  - Wave and base gate failures now reach the journal with their gate and log,
+    not just their error name.
+  - Each full run can be skipped in a plan's `defaults` or the project's
+    `maestro.defaults` (`.vinta-ai-workflows.yaml`): `verify_gates: scoped`
+    keeps `verify` on the scoped form, `base_gates: off` leaves merged bases
+    unchecked, and `wave_gates: final` / `off` as before. Both new fields are
+    in `vinta-ai-workflows-config.v1.schema.json`, and the bootstrap asks when
+    the full suite should run. The run coordinator may tighten them, never
+    loosen them.
 - **`vinta-ai-maestro`: a recycled lane no longer keeps the last phase's
   ignored files.** A lane handed to the next phase kept everything gitignored,
   and one kept `apps/api/.mypy_cache` and a deleted package's `__pycache__`,
@@ -957,6 +1031,51 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **`vinta-ai-maestro`: a claude-code turn the CLI calls "blocked" no longer
+  fails unless a tool was refused in it.** The CLI's own turn summary marks a
+  turn `blocked` whenever its last message names a next step for a person —
+  a review ending "Nothing was pushed." over `VERDICT: pass`, an implementer
+  listing an open point — and each such turn was recorded as failed
+  ("claude-code: the turn ended blocked"), an approving review included. One
+  observed phase had 43 of them. The summary now fails a turn only alongside a
+  `permission_denied` in the same turn, the case it was added for; whether
+  the rest did their job is for verdicts, gates and the agent's questions. A
+  turn's errors no longer outlive it in a session held open for background
+  work.
+- **`vinta-ai-maestro`: a merge git stopped with nothing unmerged no longer
+  starts a fixer.** `rerere.autoupdate` replaying a recorded resolution, or a
+  `pre-merge-commit` / `commit-msg` hook refusing the merged code, leaves
+  `git merge` non-zero with no unmerged path, and the integrator handed the
+  conflict fixer an empty file list — nineteen rounds in one observed phase,
+  each told to resolve nothing. With no conflict markers left, the merge now
+  goes to `verify` and is committed, recorded as resolved in 0 rounds; a hook
+  that refuses that commit gets the refused-commit question (commit, commit
+  past the hooks, or abort), worded for a clean merge. Only a red gate sends it
+  to the fixer. A merge git refused before merging anything (an untracked file
+  in the way) fails with git's own error.
+- **`vinta-ai-maestro`: a merge finished by hand survives the next attempt.**
+  A conflict the fixer could not settle fails the phase with "finish the merge
+  by hand … and commit it", and the next attempt's `mergeWave` cut
+  `wave-<N>` again from `wave-<N-1>` and re-merged every member, throwing the
+  resolution away and hitting the same conflict on every attempt. A wave or
+  `integ-<id>` branch that still contains its starting point, and whose merges
+  all brought in work still in the members' current tips, is now kept, and only
+  the members it lacks are merged. A member redone after it was merged still
+  forces a rebuild. The error now says the branch is kept.
+- **`vinta-ai-maestro`: a merged tree that fails its gates is no longer
+  reported as an unresolved conflict with no paths.** Two sibling phases that
+  each added a Django migration on the same parent merged cleanly and failed
+  `verify` together, and the phase failed "unresolved conflict: p4a both
+  changed , …". Each fix round is now told which gate the merged tree failed
+  and where its log is, and the rounds end in `IntegrationVerifyError`, naming
+  the gate and its log path (`nodes/_integration/gates/<gate>.log`).
+- **`vinta-ai-maestro`: `exec` accepts a lane's short name or its phase, and
+  `with` / `gate` work inside it.** `exec <run> crew-3-tier2-2` and
+  `exec <run> p1` were refused `unknown_target`; only the full
+  `<run-id>-crew-3-tier2-2` worked. Both now resolve, and a refusal lists the
+  run's targets. Inside `exec`, `with test-suite -- make test` said "no live
+  run is available" while the run was live: the command now holds leases as the
+  phase running in the lane, or as itself on an idle one, until it exits.
 - **`vinta-ai-maestro`: a fix loop that changes nothing now stops and asks.**
   A typecheck red because of ignored files left in a lane kept coming back
   from the gate cache after they were gone, and twenty fixers in a row found

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vinta-ai-workflows",
-  "version": "0.7.0-alpha33",
+  "version": "0.7.0-alpha35",
   "description": "Bootstrap AI tooling (AGENTS.md, skills, sub-agents) across Claude Code, Codex, Cursor, and VS Code + GitHub Copilot.",
   "type": "module",
   "bin": {

package/schemas/vinta-ai-workflows-config.v1.schema.json

@@ -339,7 +339,7 @@
       "additionalProperties": false,
       "properties": {
         "defaults": {
-          "description": "Run defaults a plan's `defaults` overrides field by field: `harness`, `model`, `pipeline`, `chores`, `gates` (the gate ids every phase runs unless it names its own), `gate_scope` (`scoped` | `full`), `wave_gates` (`off` | `final` | `every`), `substitution` (`same_tier` | `up_one_tier` | `any`), `allow_ungated_phases`, `model_fallbacks`, `max_session_turns`, `max_spare_crew`, `pull_requests` (`phase` | `plan`).",
+          "description": "Run defaults a plan's `defaults` overrides field by field: `harness`, `model`, `pipeline`, `chores`, `gates` (the gate ids every phase runs unless it names its own), `gate_scope` (`scoped` | `full`), `verify_gates` (`full` | `scoped`), `base_gates` (`full` | `off`), `wave_gates` (`off` | `final` | `every`), `substitution` (`same_tier` | `up_one_tier` | `any`), `allow_ungated_phases`, `model_fallbacks`, `max_session_turns`, `max_spare_crew`, `pull_requests` (`phase` | `plan`).",
           "type": "object",
           "properties": {
             "harness": {
@@ -379,6 +379,22 @@
                 "full"
               ]
             },
+            "verify_gates": {
+              "type": "string",
+              "enum": [
+                "full",
+                "scoped"
+              ],
+              "description": "What a phase's `verify` runs once its review approves. `full` (the default): every gate's whole command on the phase branch, so a PR never carries a suite only a scoped run saw. `scoped`: the scoped form there too, for a suite too slow to run once per phase; the merged-tree gates are then the first full run. No effect under `gate_scope: full`."
+            },
+            "base_gates": {
+              "type": "string",
+              "enum": [
+                "full",
+                "off"
+              ],
+              "description": "Whether a multi-dependency phase's merged base is gated before the phase starts on it. `full` (the default): every command gate its dependencies declare, whole command, on the merged base; red fails the phase's setup. `off`: the phase starts on the merged base unchecked."
+            },
             "substitution": {
               "type": "string",
               "enum": [
@@ -395,7 +411,7 @@
                 "final",
                 "every"
               ],
-              "description": "When the phases' gates run in full on a merged wave, in the integration worktree. `final` (the default): every gate of the plan on the last wave before the plan PR, and a wave's gates on any wave whose merge needed a conflict resolution. `every`: on every wave as well. `off`: none of these (the full form of a `scoped_cmd` gate still runs per wave under `gate_scope: scoped`)."
+              "description": "When the phases' gates run in full on a merged wave, in the integration worktree. `every` (the default): a wave's gates on every wave, so the next wave builds on a passing tree, and every gate of the plan on the last wave before the plan PR. `final`: the last wave's, and a wave's gates only on a wave whose merge needed a conflict resolution. `off`: none of these (the full form of a `scoped_cmd` gate still runs per wave under `gate_scope: scoped`)."
             },
             "allow_ungated_phases": {
               "type": "boolean",

package/schemas/workflow.v1.schema.json

@@ -420,7 +420,7 @@
         },
         "gate_scope": {
           "default": "scoped",
-          "description": "`scoped` — the default — runs a gate’s `scoped_cmd` on phase gates and its full `cmd` on the gate that re-runs after a wave merge. `full` runs `cmd` everywhere.",
+          "description": "`scoped` — the default — runs a gate’s `scoped_cmd` on a phase’s gates up to and during its review, and its full `cmd` once the review approves (`verify`) and on every merged tree in the integration worktree. `full` runs `cmd` everywhere.",
           "type": "string",
           "enum": [
             "scoped",
@@ -453,9 +453,27 @@
           "minimum": 0,
           "maximum": 9007199254740991
         },
+        "verify_gates": {
+          "default": "full",
+          "description": "What `standard-phase`’s `verify` runs once the review approves. `full` — the default — runs every gate’s whole `cmd` on the phase branch, so a PR never carries a suite only a scoped run saw; a red full run goes back to a fixer and the review. `scoped` keeps the scoped form there too, for a suite too slow to run once per phase — the merged-tree gates are then the first full run. No effect under `gate_scope: full`.",
+          "type": "string",
+          "enum": [
+            "full",
+            "scoped"
+          ]
+        },
+        "base_gates": {
+          "default": "full",
+          "description": "Whether a multi-dependency phase’s base (`integ-<id>`, its dependencies merged) is gated before the phase starts on it. `full` — the default — runs every command gate its dependencies declare, whole `cmd`, on the merged base, cached on its tree; red fails the phase’s setup. `off` starts the phase on the merged base unchecked.",
+          "type": "string",
+          "enum": [
+            "full",
+            "off"
+          ]
+        },
         "wave_gates": {
-          "default": "final",
-          "description": "When the phases’ gates run in full on a merged wave, in the integration worktree. Each phase passes its gates on its own branch, and two parallel phases can each be green and disagree with each other — a sender and a receiver of one signal, say — which only a merged tree shows. `final` — the default — runs every gate of the plan once on the last wave before the plan PR opens, and the wave’s phases’ gates on any wave whose merge needed a conflict resolution. `every` runs the wave’s phases’ gates on every wave as well, which costs one full suite per wave and catches a disagreement at the wave that introduced it. `off` runs none of these. Under `gate_scope: scoped` the full form of a narrowed gate still runs on each wave whatever this says: that is where the suite the phases skipped is paid back.",
+          "default": "every",
+          "description": "When the phases’ gates run in full on a merged wave, in the integration worktree. Each phase passes its gates on its own branch, and two parallel phases can each be green and disagree with each other — a sender and a receiver of one signal, say — which only a merged tree shows. `every` — the default — runs the wave’s phases’ gates on every wave, so the next wave builds on a passing tree and a disagreement is caught at the wave that introduced it, and every gate of the plan once on the last wave before the plan PR opens. It costs one full suite per wave. `final` runs the last wave’s and any wave whose merge needed a conflict resolution only. `off` runs none of these. Under `gate_scope: scoped` the full form of a narrowed gate still runs on each wave whatever this says: that is where the suite the phases skipped is paid back.",
           "type": "string",
           "enum": [
             "off",

package/skills/vinta-bootstrap-ai-tools/SKILL.md

@@ -101,7 +101,8 @@ These bleed across sub-skills, so capture once now:
    On `Set project defaults`, capture:
    - **Gates every phase runs.** Multi-select `AskUserQuestion` over the types the commands above give a command for: `typecheck` (from `commands.build`), `lint`, `test` (from `commands.test_unit`), and `e2e` only when `add-e2e-test` is enabled. → `maestro.defaults.gates`.
    - **A different command for maestro.** `AskUserQuestion` per selected type: `Same as commands.* (Recommended)`, `Different for maestro (I'll give it)`. Teams pick a different one when lanes need a flag the inner loop does not, e.g. `pytest --reuse-db -n auto`. → `maestro.gates.<type>.cmd`. `implement-plan` keeps running `commands.*`.
-   - **Scoped gates.** Only when `test` (or `lint`) is selected: should a phase's gate run narrowed to the files the phase changed, with the full command run once per merged wave? `AskUserQuestion`: `Yes — scoped per phase, full per wave (Recommended)`, `No — full command every phase`. On `Yes`, propose a template with `{changed_files}` for the detected runner (`vitest related {changed_files} --run`, `jest --findRelatedTests {changed_files}`, `pytest --testmon {changed_files}`, `ruff check {changed_files}`) and confirm it. It lands in `commands.test_unit_scoped` / `commands.lint_scoped`, where `implement-plan` reads it too. `No` sets `maestro.defaults.gate_scope: full`.
+   - **Scoped gates.** Only when `test` (or `lint`) is selected: should a phase's gate run narrowed to the files the phase changed until its review approves, with the full command run after the review and on every merged tree? `AskUserQuestion`: `Yes — scoped until review, full after (Recommended)`, `No — full command every time`. On `Yes`, propose a template with `{changed_files}` for the detected runner (`vitest related {changed_files} --run`, `jest --findRelatedTests {changed_files}`, `pytest --testmon {changed_files}`, `ruff check {changed_files}`) and confirm it. It lands in `commands.test_unit_scoped` / `commands.lint_scoped`, where `implement-plan` reads it too. `No` sets `maestro.defaults.gate_scope: full`.
+   - **When the full suite runs.** Only on `Yes` above. `AskUserQuestion`: `After each review and on every merged tree (Recommended)`, `Only on merged trees`, `Only on merged waves`. The first is the default and emits nothing. `Only on merged trees` skips the per-phase full run after review (`maestro.defaults.verify_gates: scoped`), for a suite too slow to run once per phase. `Only on merged waves` also leaves multi-dependency bases unchecked (`verify_gates: scoped` and `base_gates: off`).
    - **A test-suite pool.** `AskUserQuestion`: `One suite at a time (Recommended for DB-backed suites)`, `Two at a time`, `No limit`. A limit emits `maestro.resources.test-suite` (`kind: semaphore`, `capacity` 1 or 2) and `maestro.gates.test.requires: [test-suite]`. Then offer the runner's command patterns as the pool's `match` (`pytest*`, `uv run pytest*`, `pnpm test*`), which makes agents take the lease before running tests by hand.
    - **Files git does not carry.** A maestro lane is a worktree and has only what git tracks. Read `.gitignore` for entries with a tracked `*.example` / `*.sample` / `*.template` sibling, the compose file's `env_file:` lines, and the gitignored settings module the framework imports (`DJANGO_SETTINGS_MODULE`'s local module, typically). Propose the list in a multi-select `AskUserQuestion` (header `Env files`), each path pre-selected; the user confirms or drops entries. → `maestro.project.env_files`. Every hook, gate and `manage.py` call in a lane depends on these, and a plan that omits them fails in ways that look like code problems. Nothing found → omit the key and say so.
 
@@ -366,7 +367,9 @@ run_options:
 maestro:
   defaults:
     gates: <C.11 → gates every phase runs, e.g. [typecheck, lint, test]>
-    gate_scope: <C.11 → omit for "scoped" (the default); `full` on "No — full command every phase">
+    gate_scope: <C.11 → omit for "scoped" (the default); `full` on "No — full command every time">
+    verify_gates: <C.11 → omit (the default, `full`); `scoped` on "Only on merged trees" or "Only on merged waves">
+    base_gates: <C.11 → omit (the default, `full`); `off` on "Only on merged waves">
   gates:
     test:
       cmd: <C.11 → maestro-only test command; omit to use commands.test_unit>

package/skills/vinta-derive-skills/resources/foundation-skills/plan-feature/SKILL.md

@@ -254,6 +254,7 @@ Before publishing the plan, cross-check the **Touch List**: for every pair of ph
 
 - **Trivial overlap** (a shared `__init__.py`, a settings registry, a route table) — fine. Note it under the graph table so the reviewer isn't surprised.
 - **Real overlap** (the same use case, the same serializer, the same view) — **add the dependency edge** and let one phase build on the other. A serialized pair that merges cleanly beats a parallel pair that needs a human to untangle.
+- **Migrations in one app count as real overlap, even in different files.** Two phases that run in parallel and each add a migration to the same app both start from the same latest migration. Each is green alone; merged, the migration graph has two leaves (Django) or two heads (Alembic), and every gate on the merged tree fails. Their Touch Lists name two different new files, so path overlap never shows it. Prefer the edge — usually by folding both schema changes into the foundation phase — or, when the two must stay parallel, say in the later phase's body that the integration step writes the merge migration. `vinta-ai-maestro validate` warns about such a pair; put the migrations directory in each phase's Touch List so it can.
 
 ### Design *for* parallelism when it's cheap
 
@@ -607,7 +608,8 @@ First key in the file is `"$schema"`, pointing at `https://github.com/vintasoftw
 | `chores.review-canvas` | **Emit only when `.vinta-ai-workflows.yaml` has `integrations.pr-review-canvas: enabled`.** An `after_pr` chore: maestro runs it once each phase's PR is open, and it posts a review canvas on that PR. Emit it exactly as shown under "The review-canvas chore" below. Never emit it when the integration is `disabled` or absent. The skill it names is installed only when the integration is enabled. |
 | `defaults.chores` | `["review", "deslop"]`, plus `"review-canvas"` when that chore is emitted — or **omit the key** when `maestro.defaults.chores` already names the same list. The chores every phase runs unless it names its own. **Never write `"chores": []` to mean "the project's"**: an empty list *replaces* the project's list with nothing, and the run then runs no chore at all. |
 | `defaults.substitution` | **Omit** — it defaults to `up_one_tier`: a busy member's phase may go to the next tier up the roster has, and a warm session never moves a phase up. Set `same_tier` when the top tier is a limited credit allowance that must not absorb other tiers' work. |
-| `defaults.wave_gates` | **Omit** — it defaults to `final`: every gate of the plan runs once on the merged tree before the plan PR opens, plus a wave's gates on any wave whose merge needed a conflict resolution. Set `every` for a plan with many parallel phases on shared interfaces, where finding a cross-phase break at the wave that introduced it is worth one full suite per wave. Never `off` unless the project's suite cannot run in the integration worktree. |
+| `defaults.wave_gates` | **Omit** — it defaults to `every`: each wave's gates run in full on the merged tree, so the next wave builds on a passing one, and every gate of the plan once more before the plan PR opens. Set `final` only for a plan whose suite is too slow to run once per wave. Never `off` unless the project's suite cannot run in the integration worktree. |
+| `defaults.verify_gates` / `defaults.base_gates` | **Omit** — both default to `full`: a phase runs its gates' full commands once its review approves, and a multi-dependency phase's merged base is gated before it starts. Set `verify_gates: scoped` or `base_gates: off` only when the human says the suite is too slow for it, and say so in the plan. |
 | `defaults.gates` | The gate ids every phase runs. **Omit the key** when `maestro.defaults.gates` is already the list this plan wants; set it when most phases share a list the project does not name. A node with no `gates` key takes it. **Never `[]`**: that is a run with no gates. |
 | `nodes[].chores` | **Omit the key** on almost every phase — absent means the run-wide default. Name a list only to give one phase a different set, and `[]` only to deliberately opt one phase out. A list *replaces* the default rather than adding to it; `[]` is "no chores", never "the default". |
 | `nodes[]` | One per phase, in plan order. |
@@ -640,7 +642,7 @@ Rules the mapping depends on:
 Read `.vinta-ai-workflows.yaml` before writing the document. Its `commands` and its `maestro:` section are laid **under** this file when maestro loads it: every value the project already supplies reaches this plan without being written here, and a value written here overrides it for this plan alone. So the document says what is particular to this plan and nothing else. A copy of a project value is not harmless — it freezes the value into the plan, and a later change to the project's file never reaches it.
 
 - **Gates by type.** A gate typed `test`, `lint`, `typecheck` or `e2e` takes its command from the project — `maestro.gates.<type>`, else `commands.test_unit` / `lint` / `build` / `e2e`. Each type the project has a command for is available under the type's own name, so a node can list `"gates": ["typecheck", "test"]` with no `gates` table at all. Write an entry only to change something for this plan: `{ "type": "test", "timeout_s": 3600 }` keeps the project's command and extends its timeout; `{ "cmd": "…" }` (no type) replaces it outright.
-- **`scoped_cmd`** is the same check narrowed to what a phase changed, with `{changed_files}` / `{touches}` in it. The project normally supplies it (`commands.test_unit_scoped`, `maestro.gates.<type>.scoped_cmd`). Phase gates run it, and the full command runs once on each merged wave. Set one here only for a plan whose phases need a different narrowing.
+- **`scoped_cmd`** is the same check narrowed to what a phase changed, with `{changed_files}` / `{touches}` in it. The project normally supplies it (`commands.test_unit_scoped`, `maestro.gates.<type>.scoped_cmd`). A phase's gates run it until its review approves; the full command runs after that, on the phase branch, and on every merged tree — each wave and each multi-dependency base. Set one here only for a plan whose phases need a different narrowing.
 - **Pools, chores and the `project` block** merge per id: an entry here replaces the project's entry of the same id whole. Declare `resources.lane` (it is this plan's — one desk per implementer), and a pool, chore or database only when the project has none or this plan needs a different one.
 - **`defaults`** merge field by field: omit what `maestro.defaults` already says.
 - **Omitting a key inherits; writing `[]` replaces with nothing.** `nodes[].gates`, `defaults.gates`, `defaults.chores` and `nodes[].chores` are lists, and lists replace rather than merge. The only way to take the project's list is to leave the key out. `"gates": []` on a node is a phase with no gates, `"chores": []` in `defaults` is a run with no review and no comment pass — both silent at run time, and both exactly what the observed run did. When in doubt, omit the key and read what `validate --json` resolved.
@@ -1071,6 +1073,8 @@ Fix each issue by its `source`:
 - **`workflow`**: the document's shape or graph, such as an unknown node, a cycle, an undeclared pool, a crew member that cannot take its phase, a gate entry with neither `cmd` nor `type`, a phase with no gates, or an id that does not match the filename. Re-derive the field from the plan. A gate `"has no cmd"` is an override that forgot its `"type"`. A phase that `"has no gates"` is a node carrying `"gates": []` — remove the key so it takes `defaults.gates`, name its gates, or, for a plan whose phases genuinely have nothing to run, set `defaults.allow_ungated_phases: true`. If the plan itself is wrong (a cycle in its `**Depends on**:` lines), fix the plan first.
 - **`config`**: `.vinta-ai-workflows.yaml` does not parse. That file is the project's, not the plan's. Do not edit it to make the plan pass. Tell the human what is wrong and where.
 
+**`warnings` do not change the exit code, and each still gets an answer.** Today the one warning is two phases that run in parallel and both add migrations to the same app (see "Same-wave phases must not fight over the same files"). Add the dependency edge, or keep the pair parallel and say in the later phase's body that the merge migration is written at integration. Either way, name the choice when you hand the plan over. An older maestro prints no `warnings` key.
+
 ## Review the plan with the human
 
 A plan is cheapest to change before anything runs. Once both files are written and the workflow validates, hand the plan over for review. Ask with `AskUserQuestion`: header `Review`, question "The plan and its workflow are written — `<plan path>` and `<workflow path>`. How do you want to review it?"