vinta-ai-workflows 0.7.0-alpha27 → 0.7.0-alpha29

package/CHANGELOG.md

@@ -30,6 +30,32 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **`vinta-ai-maestro`: `run` now shows what a slow start is doing.** Until
+  now `run` printed "starting in the background…" and nothing else until the
+  run was up, which can take minutes (`prepare_cmd`, preflight, database
+  templates, lane provisioning). The job now prints a timestamped line per
+  step — plan branch, `prepare_cmd`, environment checks, each database
+  template, each lane ready (`3/5`) — and the launching `run` streams the
+  job's log to the terminal as it is written, with a "still starting…" line
+  after 15 s of quiet. Lines carry names and counts only, never command
+  output. A refused start is no longer printed twice.
+
+- **`vinta-ai-maestro`: `createdb_cmd` / `dropdb_cmd` on a Postgres
+  `external` database** (`workflow.v1.schema.json`, optional, defaults
+  `createdb` / `dropdb`). They replace only the binary name — in the template
+  setup, the per-lane clone and the reset — so a project whose Postgres is a
+  container with a password the host cannot supply can set
+  `docker compose exec -T db createdb`. `-h/-p/-U` from `server_url` still
+  follow. Existing workflows are unchanged.
+
+- **`vinta-ai-maestro`: a database password prompt no longer hangs `run`.**
+  Template, clone and reset commands now run with stdin closed, no controlling
+  terminal and a two-minute timeout that ends the whole process tree; a prompt
+  becomes a failed run carrying the command's stderr instead of a job stuck at
+  `starting`. `doctor` now runs the effective `dropdb_cmd --if-exists` against
+  a name that cannot exist and `FAIL`s, naming the missing password, when it
+  cannot authenticate — a server that merely answers used to pass.
+
 - **New optional foundation skill: `interview-ui`** — run decision-heavy
   interviews as a full-screen browser form instead of a chat exchange. One
   decision per screen with the context the agent already knows, Markdown +
@@ -658,6 +684,13 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Removed
 
+- **Maestro: the monitor's intervention documents.** The watchdog no longer
+  asks the monitor for a JSON proposal of four verbs; the coordinator acts
+  through the run's API under the same "how, never what" rule, enforced on
+  every amendment it makes. `schemas/intervention.v1.schema.json`, the
+  `intervention:schema:*` scripts and `runs/<id>/interventions.jsonl` are
+  gone; the post-mortem's `interventions` now point at the coordinator's
+  conversation.
 - **The three-layer phase review.** `review-phase` no longer runs the
   mechanical checks (including the review-time secret scan, dependency-license
   check and co-author trailer check), the plan-compliance walkthrough
@@ -679,8 +712,117 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   reviewer members and every `role`, rename `before_gate` to `after_review`,
   delete `reviewer_model`, and add the `review` chore.
 
+### Added
+
+- **Maestro: `land` and `propagate`.** `land <run-id>` says how a finished
+  run lands — the plan PR, with a merge commit, and nothing else — lists every
+  phase and integration PR with its state, and marks the ones whose work is
+  already in the base (every commit they add is a merge of commits the base
+  has, such as a GitHub "Update branch"); `--close` closes those with a
+  comment. `propagate <run-id> <phase>` carries a fix made on a phase branch
+  after the run into every `integ-*` and `wave-*` branch that contains it,
+  keeping the wave chain, and stops at a conflict with the branch untouched.
+- **Maestro: `defaults.substitution`** (`same_tier` | `up_one_tier` | `any`,
+  additive, default `up_one_tier`). A busy member's phase may go at most to
+  the next tier the roster has, and a warm session no longer moves a phase up
+  a tier unless `any`. **Behavior change:** runs that relied on warm-session
+  promotion to a higher tier now stay at the planned tier; set `any` to keep
+  it. Substitutions above plan are shown in `status`, the run view and the
+  post-mortem.
+- **Maestro: post-mortem findings** `failure_causes`, `crew_substitutions`,
+  `operations` and `cross_phase_failures`, and `wave_conflicts[].where`
+  (additive). `plan-feature` reads them.
+- **Maestro: the run coordinator.** The run's monitor becomes its
+  coordinator: one agent per run that is woken when a phase fails, an attempt
+  errors, maestro logs an error about itself, a phase waits 20 minutes for
+  the integration worktree, or a phase or gate crosses its cost threshold, and
+  that can act: steer, redirect, pause, abort or retry a phase, answer a
+  question a `--retry-after` timer could answer, amend the live run, and run
+  commands in a lane or the integration worktree. It reaches the run with a
+  token of its own, everything it does is journalled as its own, and the run
+  refuses what it may not do: change what the plan builds, weaken a check
+  (drop a gate or chore, rewrite a gate command beyond its
+  `tuning.allowed_flags`, edit a judge gate, change `hooks`, lower
+  `wave_gates`), answer a question the operator holds, or halt the run. Woken
+  at most 24 times per run; `--no-coordinator` turns the wakes off
+  (`--no-intervene` still works).
+- **Maestro: `node`, `workflow`, `amend` and `exec` commands.** Steer one
+  phase (`context`, `redirect`, `pause`, `abort`, `retry`, `answer`), print or
+  amend a live run's workflow, and run a command in a lane or the integration
+  worktree with that worktree's environment — its database, compose project
+  and ports — from a terminal. `exec … integration` holds the integration
+  worktree while the command runs, so no merge or unattended retry checks a
+  branch out underneath a manual repair.
+- **Maestro: `defaults.wave_gates`** (`off` | `final` | `every`, additive,
+  default `final`). The phases' gates now run in full on the merged tree:
+  every gate of the plan on the last wave before the plan PR opens, and a
+  wave's gates on any wave whose merge needed a conflict resolution; `every`
+  checks every wave. Merged waves were never tested under `gate_scope: full`,
+  and two parallel phases that each passed their gates disagreed on a signal's
+  keyword arguments, failing 22 tests that only showed up after the plan PR.
+  `plan-feature` now puts a contract test for any interface two parallel
+  phases share into the foundation phase.
+- **Maestro: pausing a phase parked on a question holds it.** Under
+  `--retry-after` the unattended timer no longer answers a question the
+  operator paused; a person's answer releases it, and `status` and the node
+  view say "paused by operator". The pause used to be recorded as `ignored`
+  while the timer fired anyway. Node operations now answer with the delivery
+  they recorded, so `POST …/pause` on a node with nothing to pause reports
+  `"delivery": "ignored"` instead of a bare `ok`.
+- **Maestro: `nodes[].deferred`** (additive). A phase carrying it — the
+  soak-gated flag removal `plan-feature` now emits it on — is not dispatched
+  when its dependencies merge; it parks on a question naming the reason, and
+  the operator answers `start` or `stop`. The scheduler used to run such a
+  phase immediately.
+- **Maestro: `node_wait` and the "waiting for the integration worktree"
+  state.** A phase queued behind the integration worktree journals who holds
+  it; `status` and the node view show it. It used to read `running` with no
+  agent process, which looked like a frozen run.
+- **Maestro: `interrupted` run status.** A signal to the job now kills every
+  live agent turn and gate, the fix round in progress and any merge standing
+  in the integration worktree, and ends the run `interrupted` (resumable)
+  instead of `failed` with orphaned agents still editing the worktree. The
+  daemon's close is bounded so an open browser socket cannot hang shutdown.
+- **Maestro: `doctor` warns about `docker compose run`/`exec` without `-T`**
+  in gates and the `project` block, and `plan-feature` says so.
+
 ### Fixed
 
+- **Maestro: PRs say how the plan lands.** Every phase and integration PR is
+  marked as a review unit that lands through the plan PR, and the plan PR says
+  to merge it alone; it used to offer two landing paths, and a 36-PR landing
+  resolved the same conflicts several times by hand. A phase PR also names the
+  sibling phases its base leaves out, so a CI failure in their area is not
+  read as its own.
+- **Maestro: the post-mortem reports what happened.** Conflicts are read from
+  the journal, base merges included, so a run that restarted no longer
+  reports none; amendments and operator operations, failure causes, crew
+  substitutions and cross-phase failures on merged waves are recorded.
+- **Maestro: a finished run stops its compose stacks** (volumes kept) and
+  prints how to remove its lanes and volumes; `status` and `doctor` list what
+  runs that are over left running or on disk. One run left twenty containers,
+  five worktrees and a job process up a day and a half after it was done.
+- **Maestro: wave branches are built across a restart.** Wave completion was
+  counted in memory, so a run that restarted with some phases of a wave merged
+  before and the rest after never built that wave, and the next wave failed on
+  `git checkout` (exit 128) on every retry. A phase the journal calls `done`
+  now counts as arrived; a wave the run never built is built before the wave
+  on top of it, and a wave that completes before the one under it waits for
+  it (`wave_deferred`) instead of failing. A missing wave is named
+  ("wave 5 was never built") rather than left to git. New `wave_built` event.
+- **Maestro: a phase that moved lanes can check out its branch.** The branch
+  is released from the sibling worktree that still had it (detached at its
+  commit, tree untouched) before the new lane takes it. Git's "already used
+  by worktree" refusal failed one phase 39 attempts in a row.
+- **Maestro: a conflict-fixer round has a time limit** (20 minutes by
+  default) and is told to verify only the files it touched; one round spent
+  hours re-running a suite that could not reach its database while three
+  phases queued behind it.
+- **Maestro: recreated lanes read the amended `env_files`.** The pool takes
+  the amended `project` block, so a single-use lane re-provisioned mid-run no
+  longer loses files declared after the run started. A compose-delivered
+  database whose service is in `compose.publish` also gets
+  `<connection_url_var>_HOST`, the same URL on the published host port.
 - **Maestro: a merge commit git refuses no longer leaves the integration
   worktree mid-merge.** A pre-commit hook failing in the integration worktree
   left `MERGE_HEAD` behind, and every phase whose base was built there then
@@ -2574,6 +2716,19 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   nothing produces a merge commit full of markers that passes into the wave
   branch unnoticed.
 
+### Security
+
+- **Maestro: lane agents hold a token of their own.** A run's agents used to
+  reach its API with the operator's token (`VINTA_AI_MAESTRO_TOKEN`), so an
+  agent could steer, abort, amend, `exec` in, pause or stop its own run, or
+  save a workflow from the editor, as the operator. They now get an agent
+  token that reaches only their own leases (`with`), `gate`, and the
+  permission-judge and gate-guard hooks; every other route answers
+  `403 agent_forbidden`. It does not open the WebSocket (and so no PTY
+  takeover), `ui` never forwards it to a run's job, and it is redacted from
+  the logs like the other tokens. Nothing to migrate: lanes are handed the new
+  token when a run starts or resumes.
+
 > The repository also gained `packages/vinta-ai-maestro/`, the workspace package
 > that executes these workflows. It is published as its own npm package,
 > `vinta-ai-maestro`, carrying the same version as `vinta-ai-workflows`, and is

package/package.json

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

package/schemas/README.md

@@ -17,11 +17,9 @@ JSON Schema (Draft 2020-12) contracts for every YAML or JSON payload the vinta-a
 | Workflow (executable plan) | `ai-plans/YYYY-MM-DD-<feature-kebab>.workflow.json` — **JSON, not YAML** | [`workflow.v1.schema.json`](workflow.v1.schema.json) | `plan-feature` (emitted alongside the human-readable plan) | `vinta-ai-maestro` (the orchestrator daemon) |
 | Plan post-mortem | `.vinta-ai-maestro/runs/<run-id>/postmortem.json` — **JSON, not YAML**; per-run state beside the frozen workflow, copied to `ai-plans/<feature-kebab>.postmortem.json` when a team wants it committed | [`postmortem.v1.schema.json`](postmortem.v1.schema.json) | `vinta-ai-maestro` (once a run has ended) | `plan-feature` (when planning the next feature in the same repo) |
 | Plan review | `ai-plans/YYYY-MM-DD-<feature-kebab>.review.json` — **JSON, not YAML**; beside the plan and its workflow, committed with them | [`plan-review.v1.schema.json`](plan-review.v1.schema.json) | the `vinta-ai-maestro` review page (a person's comments, messages, approval) and `vinta-ai-maestro review reply` (the agent's answers) | `plan-feature`, through `vinta-ai-maestro review wait` |
-| Monitor intervention | not a file the user writes — the document the run's monitor answers with when a watchdog wakes it, recorded per attempt at `.vinta-ai-maestro/runs/<run-id>/interventions.jsonl` | [`intervention.v1.schema.json`](intervention.v1.schema.json) | the run monitor (`vinta-ai-maestro`, when a phase or a gate crosses a threshold) | `vinta-ai-maestro` (validates it, then applies it through §9's amend path) |
 
-> **Four of these are generated, not hand-written**: `workflow.v1`, `postmortem.v1`, `intervention.v1` and `plan-review.v1`. The workflow's source of truth is `packages/vinta-ai-maestro/src/types.ts`; regenerate with `pnpm --filter vinta-ai-maestro schema:gen` and verify with `schema:check`. The post-mortem's is `src/postmortem/postmortem.ts`, the intervention's is `src/intervention/intervention.ts` and the plan review's is `src/review/document.ts`; regenerate any of them with `pnpm --filter vinta-ai-maestro <postmortem|intervention|review>:schema:gen`, verify with `:schema:check` — `tests/postmortem.test.ts`, `tests/intervention.test.ts` and `tests/review.test.ts` run those byte comparisons too. Edit the zod schemas, never the JSON.
+> **Three of these are generated, not hand-written**: `workflow.v1`, `postmortem.v1` and `plan-review.v1`. The workflow's source of truth is `packages/vinta-ai-maestro/src/types.ts`; regenerate with `pnpm --filter vinta-ai-maestro schema:gen` and verify with `schema:check`. The post-mortem's is `src/postmortem/postmortem.ts` and the plan review's is `src/review/document.ts`; regenerate either with `pnpm --filter vinta-ai-maestro <postmortem|review>:schema:gen`, verify with `:schema:check` — `tests/postmortem.test.ts` and `tests/review.test.ts` run those byte comparisons too. Edit the zod schemas, never the JSON.
 >
-> The intervention schema is the odd one: it validates a document a *model* writes rather than one a skill or a person does, and it is the boundary that decides what an unattended run may change about itself. Its verbs are deliberately few and deliberately cannot express a change to what a phase builds — see [`docs/monitor-intervention.md`](../packages/vinta-ai-maestro/docs/monitor-intervention.md).
 
 ## Versioning rules
 

package/schemas/postmortem.v1.schema.json

@@ -169,6 +169,14 @@
                 "maximum": 9007199254740991,
                 "description": "The wave whose merge produced the conflict."
               },
+              "where": {
+                "description": "`wave`: the wave merge. `base`: building a phase’s `integ-` base out of its dependencies, a wave earlier. Absent on post-mortems written before base conflicts were counted.",
+                "type": "string",
+                "enum": [
+                  "base",
+                  "wave"
+                ]
+              },
               "nodes": {
                 "minItems": 2,
                 "type": "array",
@@ -489,7 +497,7 @@
               },
               "record_ref": {
                 "type": "string",
-                "description": "Where the monitor’s own account of this change lives, relative to the run directory. The reasoning, the evidence and the command are prose about a repository and stay there; this artifact carries what can be counted."
+                "description": "Where the run coordinator’s own account of this change lives, relative to the run directory: its conversation. The reasoning, the evidence and the commands are prose about a repository and stay there; this artifact carries what can be counted."
               }
             },
             "required": [
@@ -502,7 +510,334 @@
             "additionalProperties": false,
             "description": "One amendment a run made to itself, and what happened to the thing it changed. The effect is a comparison of measured durations, not a claim of cause: a gate that got cheaper across an amendment did so while other things were also changing."
           },
-          "description": "Amendments the run made to itself (§9.2), oldest first. Empty means it made none, which is a fact rather than a gap: `workflow_amended` rows say who wrote them."
+          "description": "Amendments the run made to itself (§9.2), oldest first. Empty means it made none, which is a fact rather than a gap: `workflow_amended` rows say who wrote them. Changes a person made are in `operations`."
+        },
+        "failure_causes": {
+          "description": "Failed attempts grouped by cause, most expensive first.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "reason": {
+                "type": "string",
+                "maxLength": 300,
+                "description": "The scheduler’s recorded reason, verbatim up to 300 characters."
+              },
+              "setup": {
+                "type": "boolean",
+                "description": "Whether these attempts failed before any agent ran — provisioning, a base merge, a checkout. The machinery’s failure rather than the work’s, and the kind a plan cannot fix but a project configuration can."
+              },
+              "attempts": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 9007199254740991,
+                "description": "Attempts that failed with this reason, across every phase."
+              },
+              "nodes": {
+                "minItems": 1,
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "^[a-z0-9][a-z0-9-]*$"
+                },
+                "description": "The phases it hit."
+              }
+            },
+            "required": [
+              "reason",
+              "setup",
+              "attempts",
+              "nodes"
+            ],
+            "additionalProperties": false,
+            "description": "One cause of failed attempts, and what it cost: the run’s retries, grouped."
+          }
+        },
+        "crew_substitutions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "node": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^[a-z0-9][a-z0-9-]*$"
+              },
+              "planned": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The member the plan named."
+              },
+              "planned_tier": {
+                "description": "Their tier. Absent on rows written before it was recorded.",
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991
+              },
+              "member": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Who ran it instead."
+              },
+              "tier": {
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991
+              },
+              "model": {
+                "description": "The model that member ran on, from the roster.",
+                "type": "string"
+              },
+              "reason": {
+                "type": "string",
+                "enum": [
+                  "peer_busy",
+                  "warm_session"
+                ],
+                "description": "`peer_busy`: the planned member was working. `warm_session`: promoted to reuse an open session."
+              },
+              "attempts": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 9007199254740991,
+                "description": "Attempts this member took the phase for."
+              },
+              "above_plan": {
+                "type": "boolean",
+                "description": "Whether this ran at a higher tier than the plan named — dearer than budgeted."
+              },
+              "node_cost_usd": {
+                "description": "What the whole phase cost, every attempt and member included, when its harness reported cost.",
+                "type": "number",
+                "minimum": 0
+              }
+            },
+            "required": [
+              "node",
+              "planned",
+              "member",
+              "tier",
+              "reason",
+              "attempts",
+              "above_plan"
+            ],
+            "additionalProperties": false,
+            "description": "A phase run by somebody other than the member its plan named."
+          }
+        },
+        "operations": {
+          "type": "object",
+          "properties": {
+            "amendments": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "amendment": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 9007199254740991
+                  },
+                  "at_ms": {
+                    "type": "integer",
+                    "minimum": -9007199254740991,
+                    "maximum": 9007199254740991
+                  },
+                  "author": {
+                    "type": "string",
+                    "enum": [
+                      "operator",
+                      "monitor",
+                      "coordinator",
+                      "config"
+                    ]
+                  }
+                },
+                "required": [
+                  "amendment",
+                  "at_ms",
+                  "author"
+                ],
+                "additionalProperties": false
+              },
+              "description": "Every change to the run’s definition while it ran, whoever made it."
+            },
+            "node_operations": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "node": {
+                    "type": "string",
+                    "minLength": 1,
+                    "pattern": "^[a-z0-9][a-z0-9-]*$"
+                  },
+                  "op": {
+                    "type": "string",
+                    "enum": [
+                      "add_context",
+                      "redirect",
+                      "pause",
+                      "abort"
+                    ]
+                  },
+                  "by": {
+                    "type": "string",
+                    "enum": [
+                      "operator",
+                      "coordinator"
+                    ]
+                  },
+                  "count": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 9007199254740991
+                  }
+                },
+                "required": [
+                  "node",
+                  "op",
+                  "by",
+                  "count"
+                ],
+                "additionalProperties": false
+              },
+              "description": "Steering, pauses and aborts, per phase."
+            },
+            "questions": {
+              "type": "object",
+              "properties": {
+                "asked": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 9007199254740991
+                },
+                "by_operator": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 9007199254740991
+                },
+                "unattended": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 9007199254740991,
+                  "description": "Answered by a `--retry-after` timer."
+                },
+                "by_coordinator": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 9007199254740991
+                },
+                "unanswered": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 9007199254740991
+                }
+              },
+              "required": [
+                "asked",
+                "by_operator",
+                "unattended",
+                "by_coordinator",
+                "unanswered"
+              ],
+              "additionalProperties": false,
+              "description": "Every question a phase was parked on, and who answered it."
+            },
+            "exec_runs": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "target": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "by": {
+                    "type": "string",
+                    "enum": [
+                      "operator",
+                      "coordinator"
+                    ]
+                  },
+                  "count": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 9007199254740991
+                  },
+                  "failed": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                  }
+                },
+                "required": [
+                  "target",
+                  "by",
+                  "count",
+                  "failed"
+                ],
+                "additionalProperties": false
+              },
+              "description": "Commands run by hand in a lane or the integration worktree (`vinta-ai-maestro exec`)."
+            }
+          },
+          "required": [
+            "amendments",
+            "node_operations",
+            "questions",
+            "exec_runs"
+          ],
+          "additionalProperties": false,
+          "description": "What was done to the run while it ran, by a person or its coordinator. Repairs made outside maestro — a wave branch rebuilt in another checkout — leave no record and are not counted."
+        },
+        "cross_phase_failures": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "wave": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 9007199254740991
+              },
+              "gate": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^[a-z0-9][a-z0-9-]*$"
+              },
+              "members": {
+                "minItems": 1,
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "^[a-z0-9][a-z0-9-]*$"
+                },
+                "description": "The phases merged in that wave."
+              },
+              "at_ms": {
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991
+              },
+              "exit_code": {
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991
+              }
+            },
+            "required": [
+              "wave",
+              "gate",
+              "members",
+              "at_ms",
+              "exit_code"
+            ],
+            "additionalProperties": false,
+            "description": "A gate that every phase passed on its own branch and that failed on the merged wave: two of `members` (or one of them and an earlier wave) disagree. The evidence of a missing dependency or a missing contract test that `missing_dependencies`’ ordering cannot see."
+          }
         }
       },
       "required": [

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`), `allow_ungated_phases`, `model_fallbacks`, `max_session_turns`.",
+          "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`.",
           "type": "object",
           "properties": {
             "harness": {
@@ -379,6 +379,24 @@
                 "full"
               ]
             },
+            "substitution": {
+              "type": "string",
+              "enum": [
+                "same_tier",
+                "up_one_tier",
+                "any"
+              ],
+              "description": "How far above the member the plan named a phase may be moved. `up_one_tier` (the default): a busy member's phase may go to the next tier up the roster has, and a warm session never moves a phase up. `same_tier`: a peer at the same tier or wait. `any`: any tier above, warm sessions included."
+            },
+            "wave_gates": {
+              "type": "string",
+              "enum": [
+                "off",
+                "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`)."
+            },
             "allow_ungated_phases": {
               "type": "boolean",
               "description": "Whether a phase that resolves to no gates is acceptable. Off (the default): `vinta-ai-maestro validate` refuses the workflow and `doctor` warns, because an ungated phase passes its gate step without running anything."

package/schemas/workflow.v1.schema.json

@@ -106,6 +106,16 @@
                     "connection_url_var": {
                       "type": "string",
                       "minLength": 1
+                    },
+                    "createdb_cmd": {
+                      "description": "Replaces the `createdb` binary name (default `createdb`) in every command that creates a lane database. A trusted command prefix, unquoted, like `migrate_cmd`; the `-h`/`-p`/`-U` flags derived from `server_url` still follow it. Only meaningful for `external`. For a Postgres in a container whose password the host cannot supply: `docker compose exec -T db createdb` — the official image trusts connections made from inside the container, so no password is needed there.",
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "dropdb_cmd": {
+                      "description": "Replaces the `dropdb` binary name (default `dropdb`), exactly as `createdb_cmd` does for `createdb`. Set both together: `docker compose exec -T db dropdb`.",
+                      "type": "string",
+                      "minLength": 1
                     }
                   },
                   "required": [
@@ -175,6 +185,16 @@
                     "connection_url_var": {
                       "type": "string",
                       "minLength": 1
+                    },
+                    "createdb_cmd": {
+                      "description": "Replaces the `createdb` binary name (default `createdb`) in every command that creates a lane database. A trusted command prefix, unquoted, like `migrate_cmd`; the `-h`/`-p`/`-U` flags derived from `server_url` still follow it. Only meaningful for `external`. For a Postgres in a container whose password the host cannot supply: `docker compose exec -T db createdb` — the official image trusts connections made from inside the container, so no password is needed there.",
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "dropdb_cmd": {
+                      "description": "Replaces the `dropdb` binary name (default `dropdb`), exactly as `createdb_cmd` does for `createdb`. Set both together: `docker compose exec -T db dropdb`.",
+                      "type": "string",
+                      "minLength": 1
                     }
                   },
                   "required": [
@@ -393,6 +413,26 @@
             "full"
           ]
         },
+        "substitution": {
+          "default": "up_one_tier",
+          "description": "How far above the member the plan named a phase may be moved when that member is busy or another holds a warm session. `same_tier` — only a peer at the same tier; a phase waits rather than run dearer. `up_one_tier` — the default — also the next tier up the roster has, when nobody at the planned tier is free; a warm session never moves a phase up. `any` — any tier above, and a warm session above the plan may take it to avoid a cold start. One observed run moved 23 phases from Tier 3 to a Tier 4 member whose credits then ran out, and nothing showed it.",
+          "type": "string",
+          "enum": [
+            "same_tier",
+            "up_one_tier",
+            "any"
+          ]
+        },
+        "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.",
+          "type": "string",
+          "enum": [
+            "off",
+            "final",
+            "every"
+          ]
+        },
         "chores": {
           "default": [],
           "description": "The chores every phase runs unless it names its own. Most chores are run-wide — a comment pass, a changelog entry — and repeating them on every node is how one phase ends up quietly missing one.",
@@ -850,6 +890,11 @@
             "minLength": 1,
             "pattern": "^[a-z0-9][a-z0-9-]*$"
           },
+          "deferred": {
+            "description": "Why this phase must not start on its own — \"deferred until the flag has soaked two weeks at 100% in production\". A deferred phase is not dispatched when its dependencies are done: it parks on a question naming this reason, and the operator answers `start` (now) or `stop` (fail it, blocking what depends on it). Without it the scheduler would run a soak-gated flag removal the moment its dependencies merged.",
+            "type": "string",
+            "minLength": 1
+          },
           "max_fix_rounds": {
             "description": "Fix rounds a phase may spend on red gates, and unsuccessful iterations each review turn may run, before the operator is asked whether to keep going (§16). Absent — the default — sets no limit: the fixer works until the gates are green and the review loop until the reviewer approves. A fix round is a fixer turn; a review iteration is one pass of the review loop that returned blockers. When a set budget runs out the shipped pipeline asks rather than fails: `continue` grants the same budget again, `stop` fails the phase and hands it to `--on-failure`.",
             "type": "integer",

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

@@ -260,6 +260,7 @@ Before publishing the plan, cross-check the **Touch List**: for every pair of ph
 Two habits pay for themselves:
 
 - **Front-load shared scaffolding into a wave-1 foundation phase.** Types, the migration, the empty module, the fixture. Every use-case phase then depends only on that one phase, and they all run at once, instead of forming a chain.
+- **Pin every interface two parallel phases share with a contract test in that foundation phase.** A signal payload one phase sends and another receives, a protocol or ABC one implements and another calls, a DI provider one registers and another injects, an event schema, a serializer shape. Write the test that states the contract (the keyword arguments a receiver requires, the methods an implementation must have) into the foundation phase, so each parallel phase's own gates run it on its own branch. Without it, two phases can each be green alone and disagree with each other: one observed run had a sender omit an `organization_id` its sibling's receiver required, and the merged wave failed 22 tests that no phase's gate could have seen. The executor also runs the plan's gates once on the merged tree before the plan PR (`defaults.wave_gates`), but that catches the disagreement at the end, when it costs a rework of both phases.
 - **Split by seam, not by layer, when the seams are independent.** Four use-cases on the same entity are four independent phases if they only share the model. Four layers of one use-case (repository → service → serializer → view) are a chain no matter how you number them.
 
 Don't contort the plan for concurrency, though. A genuinely sequential feature is a chain of waves of one, and that is a correct plan.
@@ -275,13 +276,18 @@ ls -t .vinta-ai-maestro/runs/*/postmortem.json ai-plans/*.postmortem.json 2>/dev
 Each file carries `findings` and `gaps`. Use them like this:
 
 - **`missing_dependencies`** — a phase failed, a phase it did *not* declare landed, and only then did it pass. The previous plan was missing that edge. If this feature couples the same two layers, **declare the edge here**, naming the artifact. Entry is ordering evidence, not proof (the file's own `gate_result_unrecorded` gap says so) — confirm the coupling exists in the code before you draw it.
-- **`wave_conflicts`** — two same-wave phases that actually fought, with the contested `paths`. Cross-check those paths against this plan's **Touch List**: two phases of yours touching one of them in the same wave is the same defect repeating. Add the edge, or split so only one phase owns the file.
+- **`wave_conflicts`** — two phases that actually fought, with the contested `paths`: at a wave merge (`where: "wave"`), or while a phase's `integ-` base was built out of its dependencies (`where: "base"`), which is the same signal a wave earlier. Cross-check those paths against this plan's **Touch List**: two phases of yours touching one of them in the same wave is the same defect repeating. Add the edge, or split so only one phase owns the file.
 - **`duration_divergences`** — `direction: "longer"` means that phase set its wave's wall clock alone, so every peer you parallelised it with bought nothing; keep comparable-size work together and let the long pole start in wave 1. `"shorter"` means a small phase sat behind a long one and could have been folded in or moved earlier. Sizing, never time estimates in the plan body.
 - **`unused_dependencies`** — edges the run proved nobody needed. Drop the equivalent edge here. **Empty is not evidence of a tight graph**: check `gaps` first, because a `dependency_use_unrecorded` entry means dependency use was never measured on that run, not that every edge earned its place.
 - **`gate_costs`** — what each gate actually cost, per gate rather than per phase: `runs`, `cached_runs`, `ran_ms`, `slowest_ms`, `cache_saved_ms`, and the failed and timed-out counts. This is what sizes the **gate pool capacities** you declare. The gate that dominates `ran_ms` is the one whose pool decides the run's wall clock — give that one the capacity and stop widening the others. A gate whose `runs` far exceeds the number of phases that declare it is a fix loop re-paying for the same suite: that is a signal about `max_fix_rounds` or about phases too large to get right in two rounds, not about the gate.
 - **`critical_path`** — the dependency chain that decided how long the run took, each phase with the time it was running, plus `span_ms` and `share_of_elapsed`. **Re-draw the graph against this one.** Shortening any phase *not* on this list changes nothing at all, so a plan that parallelises harder without touching this chain buys nothing. A high `share_of_elapsed` means the graph is deep rather than wide: look for an edge on that chain that is convention rather than a real artifact dependency, and cut it. This is the finding most likely to change a plan's shape.
 - **`idle_capacity`** — what the run paid for and did not use: `lane_capacity` against `peak_concurrency`, and `idle_share` of the provisioned lane time. A lane is a worktree, a forked database and a crew member's desk, so a plan that never got as wide as its lane count bought all three for nothing. `peak_concurrency` well under `lane_capacity` means **this graph cannot use that many lanes** — either declare fewer next time, or find the edges that are serialising work that did not need to be serial. It is a fact about the graph, not about the machine.
-- **`interventions`** — changes the run made to *itself* while it ran, because a watchdog found it paying for something the plan could have stopped it paying for. A `gate:<id>` entry with `effect: "cheaper"` is the useful one: that gate's command or timeout was wrong in the workflow this project keeps emitting, and the run had to discover it at its own expense. **Carry the change forward** — the gate block you emit for this feature should already have it, so the next run does not pay again. The reasoning and the actual command are not in this file (it carries counts, not prose); they are in `interventions.jsonl` beside it in the run directory, which is where to look before copying anything. An `effect: "dearer"` entry is the opposite signal and is worth saying out loud to the human: the run tuned itself in the wrong direction, and whatever it changed should probably not be in the next plan. `unmeasured` means exactly that — the change may have been right or wrong and the run could not tell, so treat it as no evidence rather than as weak evidence.
+- **`interventions`** — changes the run's coordinator made to the run while it ran, because it found the run paying for something the plan could have stopped it paying for. A `gate:<id>` entry with `effect: "cheaper"` is the useful one: that gate's command or timeout was wrong in the workflow this project keeps emitting, and the run had to discover it at its own expense. **Carry the change forward** — the gate block you emit for this feature should already have it, so the next run does not pay again. The reasoning and the actual command are not in this file (it carries counts, not prose); they are in the coordinator's conversation its `record_ref` names, which is where to look before copying anything. An `effect: "dearer"` entry is the opposite signal and is worth saying out loud to the human: the run tuned itself in the wrong direction, and whatever it changed should probably not be in the next plan. `unmeasured` means exactly that — the change may have been right or wrong and the run could not tell, so treat it as no evidence rather than as weak evidence.
+
+- **`cross_phase_failures`** — a gate every phase passed on its own branch that failed on a merged wave: two of that wave's `members` disagree about something they share (a signal's arguments, a protocol, a provider). This is a missing dependency or a missing contract test that `missing_dependencies` cannot see, because nothing *landed* in between — it only showed up merged. If this feature has phases on the same interface, put a contract test for it in the foundation phase (see "Design *for* parallelism").
+- **`failure_causes`** — failed attempts grouped by reason, with `attempts` and the phases each one hit. An entry with `setup: true` failed before any agent ran — provisioning, a base merge, a checkout — and repeating it is the project configuration's fault, not the plan's: name it to the human (a missing `env_files` entry, a compose service that will not start) rather than reshaping the graph around it. A `setup: false` cause that hit many phases is a gate or a contract the plan should have settled first.
+- **`crew_substitutions`** — phases run by somebody other than the member the plan named. Entries with `above_plan: true` ran dearer than budgeted; many of them on one member means the roster was too thin at that tier for the plan's width. Size the **Crew** table so each wave's phases are covered at their own tier, rather than relying on cover from above.
+- **`operations`** — what people (and the coordinator) did to the run: amendments, steering, pauses, aborts, who answered the questions, commands run by hand. A plan whose runs needed many of these is telling you where it was underspecified: a phase steered or redirected repeatedly needed a sharper brief; the same question answered the same way every time belonged in the plan.
 
 Rules for using them:
 
@@ -426,7 +432,7 @@ Watch for the accidental version of this: making an in-repo phase `**Depends on*
 
 ### Flag-removal phase depends on everything
 
-The mandatory final flag-removal phase depends on **every** gated phase — it deletes the branches they added. Say so in its `**Depends on**:` line. It sits alone in the deepest wave and is deferred by the executor anyway (soak-gated), so this edge costs nothing and documents the real constraint.
+The mandatory final flag-removal phase depends on **every** gated phase — it deletes the branches they added. Say so in its `**Depends on**:` line. It sits alone in the deepest wave, so this edge costs nothing and documents the real constraint. **The executor does not know it is soak-gated unless the workflow says so**: give that node `deferred` (see the mapping table) carrying the soak condition, or the scheduler starts it the moment its dependencies merge.
 
 ### Never give time estimates
 
@@ -600,6 +606,8 @@ First key in the file is `"$schema"`, pointing at `https://github.com/vintasoftw
 | `chores.<id>` | Agent turns a phase runs once its gates are green. **Always emit the `review` and `deslop` chores below unless `maestro.chores.review` / `maestro.chores.deslop` already declare them** — `review` is the phase's code review (see "The review chore") and `deslop` the comment-hygiene pass, and without them a maestro run has neither. Add another only when the plan genuinely needs one (a changelog entry, a translation extraction); a chore is a model turn per phase, so each one has to earn it. |
 | `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.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. |
@@ -611,6 +619,7 @@ First key in the file is `"$schema"`, pointing at `https://github.com/vintasoftw
 | `nodes[].gates` | The gate ids this phase must pass, in the order they should run. **Omit the key** when they are the run's `defaults.gates` (the plan's or the project's `maestro.defaults.gates`). **`[]` is an ungated phase** — its gate step passes without running anything — and is for a phase that genuinely has nothing to check, declared with `defaults.allow_ungated_phases: true`; `vinta-ai-maestro validate` refuses a phase that resolves to no gates otherwise. One observed run finished twelve phases without a single check because every node carried `"gates": []` where the author meant "the project's". |
 | `nodes[].crew` | The id from this phase's `**Assigned to**:` line. **Required on every node of a staffed workflow** — a half-staffed document is refused, because the executor would be running two staffing rules at once. |
 | `nodes[].model` / `nodes[].harness` | **Omit `model` entirely on a staffed workflow** — the member carries it, and a node setting both is refused. `harness` only when this one phase runs on a different CLI than `defaults`. |
+| `nodes[].deferred` | The phase's soak or wait condition, as prose, on every phase the Execution graph marks **deferred** — the flag-removal phase above all. A deferred phase is not started when its dependencies merge: the executor parks it on a question naming this text, and a person answers `start` when the condition holds (or `stop`). Omit on every other phase. Without it the scheduler runs a soak-gated flag removal the moment the phases it depends on land. |
 | `nodes[].max_fix_rounds` | Omit. Absent means no limit: the fixer works until the gates are green and the review loop until the reviewer approves. Set it to cap the fix rounds a phase may spend on red gates, and the review iterations each review turn may run, before the operator is asked. When a phase spends a set budget, the executor asks the operator whether to continue rather than failing the phase. Set one only on a phase you want a person to look at if it drags on — an expensive suite, a phase with a known risk of going in circles. |
 | `nodes[].pipeline` | Omit. A per-phase pipeline is for a phase that genuinely runs a different lifecycle, which is rare enough that needing it is a signal to re-read the plan. |
 | `pipelines` | **Omit.** The executor ships `standard-phase` — see "The pipeline block". |
@@ -622,7 +631,7 @@ Rules the mapping depends on:
 - **Never invent a model id.** Pick the tier from the rubric under "Staff the plan", then read the id out of [resources/ai-models.yaml](resources/ai-models.yaml). Ids drift; tiers don't.
 - **The roster is the same decision as the Crew table.** `crew` transcribes it: one entry per row, `tier` from the Tier column, `model` from that tier in `ai-models.yaml`. A member the table does not list, or a row with no `crew` entry, means the two were edited separately.
 - **A gate is a command; a chore is an agent.** Both run per phase and that is where the resemblance stops. A gate is a shell line that says pass or fail and decides whether the phase merges. A chore is a turn that *changes* the diff — the review loop's fixes, the comment pass, a changelog entry — and it runs only once the phase's gates are green. Only the `review` chore stands between a phase and its merge; any other chore that fails is recorded and the phase carries on to its final gate run. Anything you can express as a command belongs in `gates`, where it is cached and queued and costs no model time.
-- **Gate commands must be commands the repo actually runs today.** Read them out of the project's task runner (`package.json` scripts, `Makefile`, `pyproject.toml`, CI config) rather than guessing a conventional one. A gate that doesn't exist fails every phase identically, and looks like a code problem.
+- **Gate commands must be commands the repo actually runs today.** Read them out of the project's task runner (`package.json` scripts, `Makefile`, `pyproject.toml`, CI config) rather than guessing a conventional one. A gate that doesn't exist fails every phase identically, and looks like a code problem. A command that goes through `docker compose run` or `exec` needs `-T`: a gate runs with no terminal, and without it compose fails with "the input device is not a TTY" before the command starts (`doctor` warns about it).
 - **The graph must agree with the Execution graph table.** Same nodes, same edges, same waves — they are two renderings of one set of `**Depends on**:` lines, so derive both from the lines rather than transcribing one from the other. A disagreement means one was hand-edited, and the executor flags it.
 - **`plan_context_refs` is anchors, never prose.** It names sections of the plan; it never restates them. A summary written into the JSON is a second copy that drifts the first time someone edits the plan, and the whole point of the field is that the implementer reads what the plan actually says.
 
@@ -985,6 +994,7 @@ and this `ai-plans/2026-03-04-bookmark-folders.workflow.json`:
     {
       "id": "p5",
       "name": "Remove the bookmark-folders feature flag",
+      "deferred": "until the bookmark-folders flag has soaked two weeks at 100% in production with no rollback or incident attributed.",
       "depends_on": [
         {
           "node": "p2",
@@ -1017,7 +1027,7 @@ and this `ai-plans/2026-03-04-bookmark-folders.workflow.json`:
 }
 ```
 
-Read the three renderings against each other: `p2` and `p3` both name only `p1`, so they sit in wave 2 and run at once; `p4` names both, so it is wave 3; `p5` names every gated phase, so it is wave 4 and alone there. `p2` and `p4` both touch `apps/bookmarks/api/views.py` — allowed, because the edge between them puts them in different waves; had they been same-wave, that overlap is what "Same-wave phases must not fight over the same files" is about.
+Read the three renderings against each other: `p2` and `p3` both name only `p1`, so they sit in wave 2 and run at once; `p4` names both, so it is wave 3; `p5` names every gated phase, so it is wave 4 and alone there — and carries `deferred`, so once `p4` merges the executor asks rather than starts it. `p2` and `p4` both touch `apps/bookmarks/api/views.py` — allowed, because the edge between them puts them in different waves; had they been same-wave, that overlap is what "Same-wave phases must not fight over the same files" is about.
 
 No node carries a `model`. `p1` and `p5` are the Tier 1 phases and run on `tier1`'s model because that is who took them — the roster says it once instead of two nodes repeating an id that goes stale on the next model bump.
 
@@ -1179,6 +1189,7 @@ When in doubt, model the plan after a recent example in `ai-plans/` — look for
 - [ ] Same-wave phases checked against the **Touch List** for file overlap; real overlaps either serialized with an edge or called out explicitly under the graph table.
 - [ ] Post-mortems from previous runs (`.vinta-ai-maestro/runs/*/postmortem.json`, plus any committed beside a plan) read **before** the graph was drawn; every finding either changed an edge, a wave or a split, or was consciously dismissed as not applying to this feature.
 - [ ] Slow-moving / cross-repo work sits in wave 1, and no in-repo phase depends on a cross-repo phase when it only needs the contract.
+- [ ] Every interface two same-wave phases share (a signal payload, a protocol, a DI provider, an event schema) has a contract test in the foundation phase they both depend on.
 - [ ] **Crew** table is the first thing under **Phased Rollout**: one row per implementer and no reviewer rows, every member taking at least one phase, every `Takes` cell agreeing with that phase's `**Assigned to**:` line.
 - [ ] **Every member earns their place** — by concurrency (a wave genuinely needs that many hands *at or above* those phases' tiers) or by cheapness (they take work a dearer member would otherwise do). Check it wave by wave: sort the wave's phase tiers against the roster's and confirm the roster covers them one for one.
 - [ ] Every phase is assigned to a member whose tier is **at or above** the rubric tier its work implies — no phase handed down a tier to save money.
@@ -1188,7 +1199,7 @@ When in doubt, model the plan after a recent example in `ai-plans/` — look for
 <!-- e2e:end -->
 - [ ] Feature flag declared in **Guiding Decisions** (key, scope, default, flip-on criterion) **unless** **Guiding Decisions** explicitly justifies "no flag — purely additive surface".
 - [ ] ≥1 test per gated phase asserts flag-off behavior unchanged.
-- [ ] If flag declared, **final entry under Phased Rollout is dedicated flag-removal phase** with prerequisite (soak window), full deletion touch list, `grep` acceptance check.
+- [ ] If flag declared, **final entry under Phased Rollout is dedicated flag-removal phase** with prerequisite (soak window), full deletion touch list, `grep` acceptance check — and its workflow node carries `deferred` with that prerequisite.
 - [ ] No time estimates anywhere.
 - [ ] Cross-repo phases labeled `Phase Nb`, deploy ordering called out.
 - [ ] Risk & Rollout Notes covers locks, partitions, backfills, rollback.

package/schemas/intervention.v1.schema.json

@@ -1,170 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/vintasoftware/vinta-ai-workflows/schemas/intervention.v1.schema.json",
-  "title": "vinta-ai-maestro monitor intervention",
-  "description": "The monitor’s proposal for a run it was woken up about: a closed set of execution-tuning verbs, applied by the host through §9’s amend path. It cannot express a change to what a phase builds — only to how the run executes it. Written by the run monitor when a watchdog wakes it about a phase that has outrun its threshold, and applied by `vinta-ai-maestro` through §9’s amend path. GENERATED from packages/vinta-ai-maestro/src/intervention/intervention.ts — edit there, not here. See schemas/README.md for versioning rules.",
-  "type": "object",
-  "properties": {
-    "$schema": {
-      "description": "Optional URL of this schema, for editor validation. Ignored at runtime.",
-      "type": "string"
-    },
-    "schema_version": {
-      "type": "number",
-      "const": 1,
-      "description": "Schema major version. Bumped only on breaking changes."
-    },
-    "changes": {
-      "maxItems": 4,
-      "type": "array",
-      "items": {
-        "oneOf": [
-          {
-            "type": "object",
-            "properties": {
-              "verb": {
-                "type": "string",
-                "const": "retune_gate"
-              },
-              "gate": {
-                "type": "string",
-                "minLength": 1,
-                "pattern": "^[a-z0-9][a-z0-9-]*$",
-                "description": "The gate id, as the workflow declares it."
-              },
-              "cmd": {
-                "type": "string",
-                "minLength": 1,
-                "description": "The proposed command. Must be the current command’s argv tokens, in order, plus tokens drawn from this gate’s `tuning.allowed_flags`. Nothing may be removed or rewritten."
-              },
-              "evidence": {
-                "type": "string",
-                "minLength": 1,
-                "maxLength": 600,
-                "description": "What was observed and where — the gate log line, the durations, the transcript. Unverifiable by construction and required regardless: it is what an intervention is audited and scored against, and a change made with nobody watching that cannot say why it was made is not auditable at all."
-              }
-            },
-            "required": [
-              "verb",
-              "gate",
-              "cmd",
-              "evidence"
-            ],
-            "additionalProperties": false
-          },
-          {
-            "type": "object",
-            "properties": {
-              "verb": {
-                "type": "string",
-                "const": "retime_gate"
-              },
-              "gate": {
-                "type": "string",
-                "minLength": 1,
-                "pattern": "^[a-z0-9][a-z0-9-]*$"
-              },
-              "timeout_s": {
-                "type": "integer",
-                "minimum": 1,
-                "maximum": 9007199254740991,
-                "description": "The proposed timeout, in seconds."
-              },
-              "evidence": {
-                "type": "string",
-                "minLength": 1,
-                "maxLength": 600,
-                "description": "What was observed and where — the gate log line, the durations, the transcript. Unverifiable by construction and required regardless: it is what an intervention is audited and scored against, and a change made with nobody watching that cannot say why it was made is not auditable at all."
-              }
-            },
-            "required": [
-              "verb",
-              "gate",
-              "timeout_s",
-              "evidence"
-            ],
-            "additionalProperties": false
-          },
-          {
-            "type": "object",
-            "properties": {
-              "verb": {
-                "type": "string",
-                "const": "rebudget_fixes"
-              },
-              "node": {
-                "type": "string",
-                "minLength": 1,
-                "pattern": "^[a-z0-9][a-z0-9-]*$",
-                "description": "The phase id."
-              },
-              "max_fix_rounds": {
-                "type": "integer",
-                "minimum": 0,
-                "maximum": 10
-              },
-              "evidence": {
-                "type": "string",
-                "minLength": 1,
-                "maxLength": 600,
-                "description": "What was observed and where — the gate log line, the durations, the transcript. Unverifiable by construction and required regardless: it is what an intervention is audited and scored against, and a change made with nobody watching that cannot say why it was made is not auditable at all."
-              }
-            },
-            "required": [
-              "verb",
-              "node",
-              "max_fix_rounds",
-              "evidence"
-            ],
-            "additionalProperties": false
-          },
-          {
-            "type": "object",
-            "properties": {
-              "verb": {
-                "type": "string",
-                "const": "retier_phase"
-              },
-              "node": {
-                "type": "string",
-                "minLength": 1,
-                "pattern": "^[a-z0-9][a-z0-9-]*$"
-              },
-              "model": {
-                "type": "string",
-                "minLength": 1,
-                "description": "The model to hand this phase. Must already be on the run’s roster — a monitor that could name any string could spend money on a model the plan never staffed, and could name one that does not exist."
-              },
-              "evidence": {
-                "type": "string",
-                "minLength": 1,
-                "maxLength": 600,
-                "description": "What was observed and where — the gate log line, the durations, the transcript. Unverifiable by construction and required regardless: it is what an intervention is audited and scored against, and a change made with nobody watching that cannot say why it was made is not auditable at all."
-              }
-            },
-            "required": [
-              "verb",
-              "node",
-              "model",
-              "evidence"
-            ],
-            "additionalProperties": false
-          }
-        ]
-      },
-      "description": "What to change, or nothing. Empty is a real and expected answer: a phase that is slow because its work is hard needs no amendment, and a monitor that cannot say so will invent one."
-    },
-    "summary": {
-      "type": "string",
-      "minLength": 1,
-      "maxLength": 1000,
-      "description": "One paragraph on what was found, whether or not anything is being changed."
-    }
-  },
-  "required": [
-    "schema_version",
-    "changes",
-    "summary"
-  ],
-  "additionalProperties": false
-}