vinta-ai-workflows 0.7.0-alpha25 → 0.7.0-alpha27

package/CHANGELOG.md

@@ -30,6 +30,207 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **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 +
+  Mermaid (or HTML) explainers, option cards that state each option's
+  consequences, the recommended default marked, and an in-page question panel
+  for asking the agent (questions, not decisions — the agent replies in the
+  next round). Round-based and file-based, so it works the same under Claude
+  Code, Codex, Cursor, and Copilot: the agent writes
+  `.vinta-ai-workflows/interviews/<slug>/rounds/round-NN.json`, blocks on
+  `interview-ui.mjs wait`, and resumes when the browser submits
+  `answers/round-NN.json`. Source:
+  [skills/vinta-derive-skills/resources/foundation-skills/interview-ui/](skills/vinta-derive-skills/resources/foundation-skills/interview-ui/)
+  — `SKILL.md`, the zero-dependency Node ≥ 18 localhost server + CLI
+  [scripts/interview-ui.mjs](skills/vinta-derive-skills/resources/foundation-skills/interview-ui/scripts/interview-ui.mjs)
+  (`start` / `wait` / `stop` / `status` / `serve`; binds `127.0.0.1` only,
+  serves files only from the interview's `docs/`), the shell
+  [resources/index.html](skills/vinta-derive-skills/resources/foundation-skills/interview-ui/resources/index.html),
+  and a sample round under `resources/examples/`. Copied verbatim as a whole
+  directory (bucket A), opt-in via the bootstrap's **Optional foundation
+  skills** question 7.
+- **Two new JSON Schemas**:
+  [`schemas/interview-round.v1.schema.json`](schemas/interview-round.v1.schema.json)
+  (agent → browser: groups, decisions, options with `consequences` /
+  `recommended` / `tags`, inline or file explainers, `replies[]`, `readback`
+  rounds) and
+  [`schemas/interview-answers.v1.schema.json`](schemas/interview-answers.v1.schema.json)
+  (browser → agent: per-decision `answered` / `waived` / `skipped` with
+  values, free text and notes, plus `questions[]` for the agent). Inventory
+  rows added to `schemas/README.md`.
+- **Config schema field `foundation_skills.interview-ui`** (`enabled` /
+  `disabled`). Additive — no schema major bump. Emitted by the bootstrap
+  Step 0.5 YAML; existing projects can add it by hand or on the next sync.
+- **Plan review: a page for a plan before it runs, and a chat with the agent
+  that wrote it.** Maestro's UI gains a **Plans** section. `vinta-ai-maestro
+  review open <workflow.json>` serves it and prints a link straight to the
+  plan. The page shows:
+  - **Graph.** The phase DAG, coloured by review state. Below it, the selected
+    phase's brief, its staffing and pipeline, the implementer and fixer
+    prompts, and its chores' prompts (the review loop's among them). These are
+    the real cold prompts a run would send, composed by the scheduler's own
+    function.
+  - **Plan.** The markdown, section by section, with an outline.
+  - **Gates.** A phase × gate matrix of the commands a run would execute.
+  - **Schedule.** A projected timeline with the critical path marked.
+  - **Issues.** What `validate` reports.
+
+  The reviewer can comment on the plan, a section, a phase, a prompt or a
+  gate, or select text and comment on the quote. Comments stay drafts until
+  sent to the agent as one batch. The sidebar chat shows whether the agent is
+  listening, working or away. The agent answers from its own session through
+  two new commands:
+  - `review wait` blocks, then prints what the person sent as JSON.
+  - `review reply` answers in the chat or on a thread, with `--resolve`.
+
+  Edits the agent makes to the plan show on the page within seconds.
+  **Approve plan** ends the loop. The review is committed beside the plan as
+  `ai-plans/<id>.review.json`. A new generated schema,
+  `schemas/plan-review.v1.schema.json`, validates it. Maestro's SPEC gains
+  §19 to describe it.
+- **`vinta-ai-maestro validate <workflow.json> [--json]`.** It checks a
+  workflow the way a run loads it, layered over `.vinta-ai-workflows.yaml`.
+  It also checks two things only a run used to find: the filename matches
+  the id, and every `plan_ref`, `prompt_ref` and `plan_context_refs` anchor
+  names a heading the plan has. Exit `0` means valid and `1` means not.
+  `--json` gives an agent one object with each issue's source, path and
+  message.
+- **`plan-feature` validates its workflow and runs the review.** When
+  `vinta-ai-maestro` is installed (on `PATH`, in `node_modules/.bin`, or
+  already cached for `npx --no-install`), the skill runs `validate --json` on
+  every workflow it writes. It fixes each issue and runs the check again, and
+  runs it again after every edit made during review. It never installs maestro
+  itself.
+
+  Once the files are written, the skill asks how to review: on the review
+  page, in chat, or later. On the page it serves the review, posts an
+  opening message, and loops on `review wait`. It edits the plan and then the
+  workflow for each comment, and answers every thread. The loop ends when the
+  plan is approved.
+
+- **Model fallbacks for models that run out of quota.** A frontier model sold
+  as a small credit allowance used to stall a whole run when its credits ran
+  out: the `quota` refusal parked the harness, and every model on it waited
+  for a reset that might never come. Now a model can name a fallback, and the
+  run switches to it instead of waiting.
+  - **`ai-models.yaml` entries take `fallback:`.** The shipped table sets
+    `claude-fable-5-1 → claude-opus-5-5` and `gpt-6-astra → gpt-5.6-sol`
+    (tier 4). `ai-models.v1.schema.json` gains the optional field, and the
+    nightly `check-ai-models` job checks fallback ids for staleness too.
+  - **Maestro: `defaults.model_fallbacks`** (model id → fallback id), in a
+    plan's workflow or in `.vinta-ai-workflows.yaml` under
+    `maestro.defaults`. A `quota` refusal on a listed model retries the
+    spawn on its fallback right away and leaves the harness unparked. Later
+    spawns of that model on the same harness go straight to the fallback,
+    until the reset time the vendor gave, or for the rest of the run if it
+    gave none. This also covers a turn cut off mid-way and the monitor and
+    conflict-fixer spawns. Chains are followed. If the fallback is refused
+    for quota too, the whole account is out: the harness parks as it did
+    before. Each substituted spawn is journaled as `node_model_fallback`.
+  - **`plan-feature` writes the map** into each plan's workflow from the
+    crew's `fallback:` entries. The plan-execution skills (`implement-phase`,
+    `review-phase`) follow the same rule when maestro isn't running them.
+- **`thermo-nuclear-review-loop` foundation skill.** A review-and-fix loop
+  over a change: the agent running it spawns one reviewer sub-agent, checks
+  each finding against the code, fixes the justified ones and answers the
+  rest, until the reviewer explicitly approves under a strict code-quality
+  standard. Questions only the human can settle (unreachable scenarios,
+  requirement ambiguity, destructive operations) go to them instead of being
+  assumed. Always shipped and copied verbatim (new
+  `foundation_skills.thermo-nuclear-review-loop`), because `review-phase`
+  runs it and every maestro workflow `plan-feature` writes names it in its
+  `review` chore. Also
+  invokable on its own. **Consumers**: re-sync to pick it up.
+- **Project defaults for maestro in `.vinta-ai-workflows.yaml`.** A new
+  `maestro:` section holds what every plan's `.workflow.json` used to repeat:
+  per-type gate defaults, resource pools, chores, run defaults and the
+  `project` block. Maestro layers each plan over it. The project's
+  `commands.*` come first, then `maestro.*`, then the plan, then the run's own
+  amendments. A plan now states only what is different, and editing the
+  project file reaches every plan that did not override it.
+  - **Gate types.** A gate with `"type": "test" | "lint" | "typecheck" |
+    "e2e"` takes its command from `maestro.gates.<type>`, else from
+    `commands.test_unit` / `lint` / `build` / `e2e`. A `maestro.gates.<type>.cmd`
+    gives maestro its own line, and `implement-plan` keeps running
+    `commands.*`. Every type the project has a command for is available under
+    the type's name, so a node can list `["typecheck", "test"]` with no gate
+    table.
+  - **`defaults.gates`**, the gates every phase runs unless it names its own.
+    `defaults.harness` and `defaults.pipeline` now default to `claude-code`
+    and `standard-phase`, and `base_branch` defaults to
+    `project.default_branch`.
+  - **The bootstrap asks for these** (interview item C.11) and writes the
+    section. `plan-feature` reads it and emits only plan-specific values.
+- **Scoped and full gates.** A gate can carry a `scoped_cmd` with
+  `{changed_files}` / `{touches}`. Phase gates run it, and the full `cmd` runs
+  once on each wave's merged tree. A failure there is a regression between
+  phases, and it fails the merge (`defaults.gate_scope: scoped`, the default;
+  `full` runs `cmd` everywhere). `commands.test_unit_scoped` and the new
+  `commands.lint_scoped` are inherited as scoped commands when they contain a
+  placeholder. `implement-plan`'s scoped suite fills the same placeholders.
+- **Every maestro run works on a plan branch, `plan/<workflow-id>/base`.**
+  It is cut from `base_branch` at start, and phases and waves build on it.
+  Pull requests still target `base_branch`. Commit a change to
+  `.vinta-ai-workflows.yaml` or the plan's `.workflow.json` on that branch,
+  and the running plan picks it up as a `config` amendment that names the
+  commit. A config change never undoes a change an operator or the monitor
+  made in the run, never rewrites a phase that has started, and ships with
+  the plan's PR. `run` warns when the checkout's config file differs from
+  what is committed on the plan branch.
+- **The gate guard.** On claude-code, every maestro agent gets a
+  `PreToolUse` hook, in every permission mode, through the per-lane settings
+  file only. It refuses two things: a gate's full command typed by hand
+  (answer: `vinta-ai-maestro gate <id>`), and a command matching a pool's new
+  `match` patterns when run without the lease (answer:
+  `vinta-ai-maestro with <pool> --`). Refusals are journalled as
+  `bare_gate_blocked`. The hook fails open and never auto-approves anything.
+  On codex and opencode a matching command is recorded after the fact as
+  `bare_gate_detected`. `doctor` reports which you get as
+  `gate-guard:<harness>`.
+
+- **Provision worktrees with your own script instead of the `prepare-worktree`
+  skill.** Set `commands.worktree_prepare` in `.vinta-ai-workflows.yaml` (and
+  optionally `commands.worktree_teardown`), and `implement-plan` runs that
+  command for the shared worktree, every lane and the integration worktree.
+  No LLM step and no `agent_models.worktree_prep` delegate are involved.
+  Worktrees, and therefore parallel phases, are now available when the skill
+  is enabled **or** the command is set. When both are set the command wins,
+  and the skill is offered as a fallback if the command fails.
+  - **The contract.** The command runs from the repo root with
+    `VINTA_WORKTREE_NAME`, `_PATH`, `_BRANCH`, `_BASE_REF`, `_KIND`
+    (`single` | `lane` | `integration`), `VINTA_MAIN_CHECKOUT`,
+    `VINTA_PLAN_PATH` and `VINTA_WORKTREE_SUMMARY` set. It must create a
+    runnable worktree at that path, on that new branch, and exit non-zero on
+    failure. The conductor then checks the result with git rather than
+    trusting the exit code: the right branch, the worktree registered, and
+    the main checkout's status unchanged. Writing the summary YAML is
+    optional. A summary carrying `reset_cmd`s lets a lane be reused across a
+    migration boundary. Without one the lane is re-provisioned (teardown,
+    then prepare again) instead. Lanes are provisioned one at a time, because
+    the command runs `git worktree add` itself.
+  - **Sandbox tier.** The conductor probes the tier itself. With the skill
+    disabled, its `sandbox-run.sh` is not installed, so the tier is `none` and
+    the review-phase stray-write check is the guard.
+  - **Bootstrap.** The `prepare-worktree` question gains a
+    `Yes — we provision with our own script/command` option.
+    `vinta-analyze-codebase` now records existing worktree scripts in
+    `commands.worktree_candidates`, and the interview offers them as the
+    command. Existing configs need no change.
+  - **The bootstrap can write the script for you.** A fourth answer,
+    `Yes — generate a provisioning script for this project`, adds an optional
+    step after `vinta-derive-skills`. It writes `prepare.sh`, `teardown.sh`
+    and a shared `lib.sh` (default `scripts/worktree/`) from bundled
+    templates, and points `commands.worktree_prepare` / `_teardown` at them.
+    The templates carry the contract: `--dry-run`, sanity checks, rollback of
+    a half-made worktree, generic compose isolation, the full summary YAML,
+    and a teardown that refuses a dirty worktree, drops only `*_wt_<name>`
+    databases and never runs `down -v`. They also refuse to fork or drop a
+    database on a non-local host. The bootstrap fills only the project's
+    dependency, env, database and service steps from the inventory, then
+    verifies with `bash -n`, a dry run, and an optional real smoke test. The
+    scripts are the project's to commit and edit; humans can run
+    `prepare.sh <name>` / `teardown.sh <name>` directly too.
 - **Agents stop for input with clickable questions instead of prose.** When a
   skill or a sub-agent needs a decision from you, it now asks through your
   harness's structured question tool, so you get the options as buttons plus
@@ -294,6 +495,61 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Changed
 
+- **`create-spec` offers a browser surface for its Step 0 interview.** When
+  `ai-tools/skills/interview-ui/` exists, the skill asks once whether to make
+  decisions in the browser or in chat. In browser mode the question bank,
+  clarity loop, read-back, and exit conditions are unchanged; each question
+  becomes a decision with `why`, quoted-back `context`, options with
+  consequences, and explainer docs, written one round at a time (A–C first,
+  later groups once the journeys are known). Projects without `interview-ui`
+  see no change.
+- **Bootstrap `Optional foundation skills` group grows to eight questions**
+  (`interview-ui` is question 7; `handoff-to-client` moves to 8).
+- **`review-phase` runs the thermo-nuclear review loop.** On the skills path
+  (`implement-plan`, `amend-plan`, `systematic-debugging`), each phase is now
+  reviewed by `thermo-nuclear-review-loop`, the loop maestro's `review` chore
+  runs. The conductor hosts it, because a sub-agent cannot spawn sub-agents of
+  its own. It spawns one reviewer sub-agent one tier above the tier the
+  phase's implementer ran at (a Tier 4 phase is reviewed at Tier 4), and hands
+  each round of findings to the phase's own implementer. The implementer
+  verifies each finding, fixes the justified ones, rejects the rest with
+  counter-evidence, and commits the round. Questions only a person can settle
+  come to you as structured questions. The phase passes only when the
+  reviewer explicitly approves. After 20 passes that still return blockers,
+  the conductor asks whether to continue for 20 more, stop the phase
+  unapproved, or amend the plan. **Consumers**: re-sync to re-render the
+  plan-execution skills.
+- **Maestro: a phase's review is now the `review` chore.** Once the phase's
+  gates are green, the implementer's own session runs
+  `thermo-nuclear-review-loop`: it spawns one reviewer sub-agent and fixes or
+  answers its findings until the reviewer approves. Then `deslop` runs, and
+  the gates run once more on the final tree. A red gate still goes to the
+  fixer. A review turn that ends unapproved asks the operator to continue or
+  stop. `plan-feature` now emits the `review`
+  chore and `defaults.chores: ["review", "deslop"]`, and transcribes the
+  Crew table's implementers into `crew`.
+- **Maestro: chore `when` is now `review`, `after_review` (the default) or
+  `after_pr`.** `review` chores must end with `VERDICT: pass` or
+  `VERDICT: fail`, and the phase continues only on pass. `after_review`
+  replaces `before_gate`.
+- **Maestro: `max_fix_rounds` has no default, and unset means no limit.** The
+  fixer works on a red gate until it is green, and the review loop runs until
+  the reviewer approves, without asking. Set `max_fix_rounds` on a node to get
+  the old behaviour back: after that many fix rounds or unsuccessful review
+  passes, the phase asks whether to continue or stop. **Migration:** a plan
+  that relied on the default of 4 now runs unbounded; add
+  `"max_fix_rounds": 4` to keep it.
+- **Maestro: every `workflow_amended` row carries `targets`.** Operator and
+  config amendments get them too, computed from the snapshot and the
+  proposal. Before, only monitor amendments had them.
+- **Maestro: a gate command can be amended after a phase that uses it is
+  done.** Changing a gate table no longer counts as rewriting a finished
+  phase. Before, such an amendment was refused as `body_changed_after_done`.
+- **Maestro: the editor saves only what you changed.** It shows the workflow
+  resolved over the project config, and on save it writes back only the
+  edited values. A first save no longer copies every default, or the
+  project's values, into the plan file.
+
 - **Maestro: the node view's right-hand column stays short.** Gate logs open
   in a dialog instead of an inline accordion. The dialog opens at the end of
   the log, keeps up with a running gate's output, numbers the lines, and has
@@ -391,8 +647,143 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   and never selects text. The host box follows the window's height instead of
   being fixed at 380px.
 
+### Deprecated
+
+- **`agent_models.reviewer` is ignored.** The review runs one tier above the
+  phase's implementer, so no configured tier is read. The key stays in the v1
+  config schema so existing configs still validate; drop it at your next
+  edit. Bootstrap no longer asks for it. `agent_models.fixer` now sets only
+  the merge-conflict fixer's tier, since the phase's implementer fixes review
+  findings at its own tier.
+
+### Removed
+
+- **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
+  (including the comment-hygiene check), the crew reviewer, or a separate
+  fixer per finding. The implementer's own install-time license check and
+  co-author rules are unchanged.
+- **Reviewers on the plan.** `plan-feature`'s Crew table loses its `Role`
+  column and its reviewer rows, and phases lose the optional
+  `**Review models**:` line. **Migration:** plans written with reviewer rows,
+  a `Role` column or `**Review models**:` lines still run; `implement-plan`
+  ignores them.
+- **Maestro: the reviewer role and its review loop.** Crew members are
+  implementers only, and the crew `role` field is gone. Also gone:
+  `defaults.reviewer_model` (in the workflow file and in the
+  `.vinta-ai-workflows.yaml` `maestro.defaults`), the consult step and the
+  review ledger. **Migration:** a `.workflow.json` with a crew `role`, a
+  reviewer crew member, a `before_gate` chore or `reviewer_model` no longer
+  parses. Re-emit it with `plan-feature`, or edit it by hand: drop the
+  reviewer members and every `role`, rename `before_gate` to `after_review`,
+  delete `reviewer_model`, and add the `review` chore.
+
 ### Fixed
 
+- **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
+  failed in its own setup on `git checkout exited 1` — four phases, up to
+  twenty-three attempts each, in one run. The integrator now keeps the
+  resolution as a commit under `refs/vinta-ai-maestro/resolutions/<node>`,
+  abandons the merge, and asks the phase whose merge it is: `commit`,
+  `commit --no-verify`, or `abort merge` (the unattended answer under
+  `--retry-after`). A retry reuses the kept resolution. Before any checkout,
+  the integrator refuses a worktree that is mid-merge, mid-rebase or
+  mid-cherry-pick *by name* (`integration worktree is mid-merge: a merge of
+  plan/x/phase-b into plan/x/integ-c …`). A conflict fixer that could not run
+  abandons the merge it was handed.
+- **Maestro: `GitCommandError` carries git's stderr.** The redacted, bounded
+  tail of what git said is in the error, in `node.attempt_failed`, in the
+  journal's `node_error` and so in the UI — `git commit exited 1: …No module
+  named 'settings.local'` instead of `git commit exited 1`. The integrator's
+  own errors (`UnresolvedConflictError` among them) keep their messages too
+  instead of being reported as their class name.
+- **Maestro: a setup failure that repeats is not retried unattended.** A phase
+  that fails before any agent ran, twice in a row on the same line, is parked
+  on its question without `--retry-after`'s self-answer, and the question
+  says why.
+- **Maestro: `project.env_files` reaches adopted lanes.** A resume gives each
+  lane the declared files it lacks and never overwrites one it has, so
+  amending the list reaches lanes that already exist. `doctor` fails a
+  declared file missing from the checkout and warns, by name, when a
+  gitignored file has a tracked example (`.env.example`,
+  `settings/local.py.example`) and nothing declares it.
+- **Maestro: a phase with no gates is no longer a silent pass.** `validate`
+  refuses a node that resolves to an empty `gates` list and `doctor` warns
+  naming the phases, unless the plan sets `defaults.allow_ungated_phases:
+  true` (new, additive). Twelve phases had finished without a check because
+  every node carried `gates: []` where its author meant "the project's".
+- **Maestro: a refused conflict-fixer spawn is backpressure.** A plan limit or
+  quota refusal while spawning the fixer parks the phase on the harness's
+  wait (`waiting_on_capacity`) instead of failing it and retrying on a timer.
+- **Maestro: `createdb` / `dropdb` reach the server `server_url` names.** The
+  template and lane commands pass `-h`, `-p` and `-U` from the URL; they used
+  the local socket, which is not a Docker-published server. The password stays
+  off the command line (`PGPASSWORD` or `~/.pgpass`).
+- **Maestro: `vinta-ai-maestro` resolves from inside every lane.** The daemon
+  writes a launcher for itself into `.vinta-ai-maestro/bin/` and puts it first
+  on the agents' `PATH`, so `with` and `gate` work when maestro is a project
+  devDependency reached through `node_modules/.bin` or `npx`.
+- **Maestro: agents are told a compose-delivered database is unreachable from
+  the host.** The implementer prompt names the connection variables that
+  resolve only inside the lane's compose network and says to run the suite
+  through the project's commands or the gate verb.
+- **Maestro: an editor save writes a patch even when the stored file does not
+  validate.** A cross-reference error in the committed file (a chore the
+  project no longer declares) made the save write the whole resolved document
+  — a hundred-line diff for a one-field edit. The shape is now enough to diff
+  against.
+- **Maestro: `purge <run-id>` forgets the run in `flow.db` too.** The UI went
+  on listing, and offering to resume, a run whose directory was gone.
+- **Maestro: the monitor thinks with the model the run declares now.** It was
+  built once at job start; an amendment to the crew's models reached it only
+  after a pause and resume.
+- **Maestro: `run` says where the run's state lives.** The store is the
+  checkout's, so a `ui` started in another checkout of the same repository
+  (the main one, while the run is in a worktree) lists other runs; the output
+  now names the store and the `--repo` to pass.
+- **plan-feature: `project.env_files` and the gate/chore inheritance rules.**
+  The skill told authors env-file copying did not belong in the `project`
+  block, which left every lane without `.env`; it now tells them to find the
+  gitignored files the project's hooks, gates and settings need (`*.example`
+  siblings, compose `env_file:` lines, the settings module) and to declare
+  them — once, in `.vinta-ai-workflows.yaml` under `maestro.project.env_files`,
+  or in the workflow. It also states plainly that `gates: []` and
+  `defaults.chores: []` mean *none* rather than "the project's", that an
+  override of a project gate must carry `type`, and that `vinta-ai-maestro
+  validate` must exit 0 before the plan is handed over. `vinta-bootstrap-ai-tools`
+  asks about `env_files` when it writes the `maestro:` section.
+- **Maestro: wave merges again use the membership the executor counted.**
+  `RecordingIntegrator.mergeWave` dropped it, so in production a merge fell
+  back to the integrator's own reading of the wave. That reading could differ
+  from the count if an amendment landed in between.
+- **Maestro: the gate run on a conflict resolution uses the amended gate
+  commands.** It used the workflow from the start of the run.
+- **Maestro: the API serves a run's definition as amended.** It cached the
+  snapshot forever, so a monitor retune made in the run's own process never
+  reached the UI.
+- **Maestro: an editor save from `ui` now reaches the run's job.** `ui`
+  is a separate process from the job hosting a run. A save to a running
+  plan's workflow used to replace the run's frozen snapshot from `ui` with no
+  runner: nothing adopted the change, and an amendment that needed a rebase
+  was refused. The job kept running the old definition until a resume. The
+  save is now sent to the job (`POST /api/runs/<id>/amend`), which applies it
+  under the usual amend rules, and `ui` writes the plan file only once the
+  job has accepted it. If the job does not answer, the save is refused
+  (`run_host_unreachable`) and nothing is written.
+- **Maestro: saving in the editor during a run no longer reports a failure.**
+  The amendment response failed the client's schema check even though the
+  save had gone through.
+
+- **`implement-plan`'s final report no longer suggests `docker compose down -v`
+  to tear down a lane.** `down -v` also deletes the compose volumes a worktree
+  deliberately shares with the main checkout (`shared_volumes`, such as a
+  dependency cache). The report now prints the same sequence the
+  `prepare-worktree` skill documents: `docker compose -p <project> down`, then
+  `docker volume rm` for each volume the worktree forked, then removal of the
+  generated compose override.
 - **`open-pr.sh` posts inline comments on macOS and reports why a comment
   failed.** Four bugs in the `open-pr-from-context` script, all seen while
   publishing a stacked plan from a Mac:

package/README.md

@@ -80,7 +80,7 @@ The bootstrap skills are **one-shot**. They scaffold the project once and are re
 - **Goals + Non-goals** — what's in / out of scope.
 - **Guiding Decisions** — feature flag (key, scope, default, flip-on criterion if any), storage shape, tenant scoping, API contract, schema rules. Load-bearing — every phase reaches back here.
 - **Data Model Changes** — migrations + rollout order.
-- **Phased Rollout** — opens with a **Crew** table (the agents this plan is staffed with, each with a role — `implementer` or `reviewer` — and a tier; every implementer keeps one worktree and one session for the whole run, while reviewers read the lane they are reviewing before it is committed), then each phase declares: `id`, `title`, `goal`, `Assigned to` (which crew member takes it — implement-plan resolves their tier to the cheapest available model), `reusable_skills` (other project skills the implementer should invoke), `Changes`, `Tests`, `Acceptance`, plus flags for `is_cross_repo` and `is_flag_removal` (both deferred).
+- **Phased Rollout** — opens with a **Crew** table (the implementers this plan is staffed with, each with a tier; every implementer keeps one worktree and one session for the whole run, and the `.workflow.json` transcribes the same roster). Reviews are not staffed: both `implement-plan` and `vinta-ai-maestro` review each phase with `thermo-nuclear-review-loop`, which spawns its own reviewer. Then each phase declares: `id`, `title`, `goal`, `Assigned to` (which crew member takes it — implement-plan resolves their tier to the cheapest available model), `reusable_skills` (other project skills the implementer should invoke), `Changes`, `Tests`, `Acceptance`, plus flags for `is_cross_repo` and `is_flag_removal` (both deferred).
 - **Risk & Rollout Notes**, **Open Questions**, **Touch List**.
 
 Phases are sized so the slowest path (e.g. cross-repo producer wiring, external integration approval) starts in Phase 1 and fast in-repo work fills in behind. Large mutation phases get split (`4a / 4b / 4c`) rather than monolithic.
@@ -99,11 +99,8 @@ Phases are sized so the slowest path (e.g. cross-repo producer wiring, external
 2. **Pick the model from the plan's per-phase suggestion.** Filter to what the runtime can actually run, choose the cheapest survivor. Capability gap on retry → escalate one tier; after Tier 4, stop and surface to the user.
 3. **Spawn the right agent type.** `implementer` by default; switch to a stack-specialist (`migration-author`, `deploy-author`, etc.) when that role's risk dominates the phase.
 4. **Implementer runs inner + outer loop.** Inner: lint → scoped tests → typecheck on touched files; iterate until green. Outer (only after inner is green): full build + full test suite + e2e where applicable. Never commits, pushes, or proceeds with a red gate.
-5. **Three-layer review** before merging the phase branch:
-   - **Layer 1 — mechanical**: read every diff, confirm outer gate ran green, scope-creep + secrets scan.
-   - **Layer 2 — plan compliance**: walk every "Changes" item, every "Tests" entry, the Acceptance line, AGENTS.md conventions, any reusable-skill compliance, feature-flag wiring, cross-phase consistency.
-   - **Layer 3 — independent reviewer**: spawn a fresh `reviewer` agent with no implementation context. Findings triaged BLOCKER / SHOULD-FIX / NIT.
-6. **Fix loop**: each finding → spawn a `fixer` agent (separate session) that re-runs inner + outer loops; orchestrator never edits directly. Repeat until all three layers are clean.
+5. **Review loop** before integrating the phase. `review-phase` runs the `thermo-nuclear-review-loop` skill with the orchestrator as the loop's host. One reviewer sub-agent, with no implementation context and one tier above the tier the implementer ran at, reviews the phase diff against the phase body and the plan's **Goals** and **Guiding Decisions**. Its findings go back to the phase's own implementer, which verifies each one, fixes the justified ones, rejects the rest with counter-evidence, re-runs the gates and commits the round. A question only a person can settle (an unreachable scenario, a scope call, a destructive step) comes to you as a structured question. The orchestrator never edits code.
+6. **Loop until the reviewer approves.** The reviewer re-reads the whole diff on every pass, and the phase passes only on its explicit approval. After 20 passes that still return blockers, the orchestrator pauses and asks whether to continue for 20 more, stop the phase unapproved, or amend the plan.
 
 **Branch model — one branch per phase, based on that phase's dependencies:**
 
@@ -139,7 +136,7 @@ Each phase's PR (or branch, depending on the project's PR policy captured at boo
 - **Cross-repo phases** (`is_cross_repo: true`) — work in another repository. Marked deferred in tracking; orchestrator continues to the next in-repo phase. Don't block on cross-repo work.
 - **Flag-removal phase** (always the last phase when a feature flag exists). Gated on real-world soak signal — handled by a dedicated flag-removal skill, not `implement-plan`. Marked deferred; orchestrator ends the run with a hand-off note.
 
-**Failure handling:** if a phase fails Layer 1 / 2 / 3 + fixer escalation, orchestrator stops, posts the agent's report, and asks how to proceed. It does not silently rerun, skip, or escalate models without the user.
+**Failure handling:** if a phase's gates stay red after escalation, or its review stops unapproved, orchestrator stops, posts the agent's report, and asks how to proceed. It does not silently rerun, skip, or escalate models without the user.
 
 #### PR creation: single flow via `prs-context` + `open-pr.sh`
 
@@ -200,7 +197,7 @@ The script bails early with `missing dependency: <name>` if any are absent. If a
 
 # Day 3+ — execution
 /implement-plan        # orchestrator runs phase 1 → phase 2 → ... → phase N-1
-                       # each phase: implementer + reviewer + fixer agents,
+                       # each phase: implementer + a review loop until approval,
                        # one stacked branch + PR per phase
 # merge phase branches sequentially as approvals land
 # soak phase 1 in prod → soak phase 2 → ...
@@ -223,12 +220,12 @@ Quick inventory of what `vinta-bootstrap-ai-tools` writes into your repo's `ai-t
 The 0.2.0 alpha line adds five foundation skills and restructures plan execution. Two ship in every bootstrapped project, three are opt-in:
 
 - **`handoff` (always)** — writes a session-continuation doc to `.vinta-ai-workflows/handoffs/` so a fresh session, a different agent, or a teammate can resume in-flight work without re-deriving context. Write mode gathers the goal, what's verified vs. still assumed, decisions and the alternatives rejected, landmines, and the single concrete next step **from the repo, never from memory**. Resume mode reads a handoff and re-checks its claims against the repo before trusting them.
-- **`deslop-comments` (always)** — rewrites the comments and doc blocks a task touched into Simple English, stripping AI-slop vocabulary and negative framing. Comment-only: no renames, no behavior change. It's wired into the review flow — `review-phase` Layer 2 gained a comment-hygiene check and dispatches a `fixer` to run this skill on any comment-slop finding — and is also invokable standalone ("deslop these comments").
+- **`deslop-comments` (always)** — rewrites the comments and doc blocks a task touched into Simple English, stripping AI-slop vocabulary and negative framing. Comment-only: no renames, no behavior change. `integrate-phase` / `amend-plan` run it over the PR-context prose they write, `vinta-ai-maestro` runs it as each phase's `deslop` chore, and it is also invokable standalone ("deslop these comments").
 - **`prepare-worktree` (opt-in)** — provisions a fully-runnable git worktree for parallel plan work so a long-running plan can build, test, migrate, and hit databases without disturbing the main checkout. It reads the plan plus `.gitignore` / manifests / env / docker config and gives every worktree its own copy of the dependency dirs (never a symlink) and decides per remaining ignored path whether to copy, fork, or share (dev DB, env files, compose project name). It also ships an OS-level write-guard — `sandbox-run.sh` (`sandbox-exec` / `bwrap`) for subprocess runtimes and a `PreToolUse` hook for Claude Code's in-process subagents — so a stray write back to the main checkout fails at the kernel layer instead of relying on a cooperative "stay in the worktree" instruction. `implement-plan` Step 0 question (c) opts a run into it, and parallel phase execution requires it — one lane per concurrent phase.
-- **`thermo-nuclear-code-quality-review` (opt-in)** — a deliberately harsh, on-demand structural-maintainability audit of a diff (abstraction quality, giant files, spaghetti-condition growth) that hunts for "code-judo" reframes collapsing whole branches / helpers / modes / layers rather than polishing them. Read-only — it reports findings and hands each fix to a `fixer`. `review-phase` Layer 3 now applies a condensed version of this lens on every phase and escalates to the full audit only when a phase touches core architecture, crosses ~1,000 lines, or surfaces a structural smell too big to fix inline.
+- **`thermo-nuclear-code-quality-review` (opt-in)** — a deliberately harsh, on-demand structural-maintainability audit of a diff (abstraction quality, giant files, spaghetti-condition growth) that hunts for "code-judo" reframes collapsing whole branches / helpers / modes / layers rather than polishing them. Read-only — it reports findings and hands each fix to a `fixer`. The per-phase review loop already applies a structural-simplification lens on every phase; this is the deliberate deep audit for when a change touches core architecture, crosses ~1,000 lines, or carries a structural smell worth a dedicated pass.
 - **`handoff-to-client` (opt-in, API-only repos)** — generates a self-contained markdown document for the client teams consuming the repo's API: every endpoint / operation added, changed, deprecated, or removed on the current branch vs. the default branch, with request/response shapes derived from the code, auth + error changes, breaking-change flags judged from the strictest plausible client, one realistic example per operation, and per-platform migration notes. Template-rendered from `skills.handoff-to-client.*` config (required `client_platforms`, plus `api_style` / `api_spec_path` / `output_dir`).
 
-Alongside the new skills, **`implement-plan` was decomposed into a modular plan-execution unit** — a thin conductor plus three co-shipped single-purpose sub-skills (`implement-phase`, `review-phase`, `integrate-phase`). `review-phase` is now the one review implementation shared by `implement-plan`, `amend-plan`, and `systematic-debugging`. The behavior is unchanged; the split is for reviewability and determinism. Two more knobs land in `.vinta-ai-workflows.yaml`: **`agent_models`** (set a tier per `reviewer` / `fixer` / `worktree_prep` / `integrate` so the review sub-agents and mechanical steps aren't stuck on the runtime default), and **E2E tests are now opt-in** in both `plan-feature` and `implement-plan` (they make runs materially slower; default off, re-enable per-run or per-project).
+Alongside the new skills, **`implement-plan` was decomposed into a modular plan-execution unit** — a thin conductor plus three co-shipped single-purpose sub-skills (`implement-phase`, `review-phase`, `integrate-phase`). `review-phase` is now the one review implementation shared by `implement-plan`, `amend-plan`, and `systematic-debugging`. The behavior is unchanged; the split is for reviewability and determinism. Two more knobs land in `.vinta-ai-workflows.yaml`: **`agent_models`** (set a tier per `fixer` / `worktree_prep` / `integrate` so the merge-conflict fixer and mechanical steps aren't stuck on the runtime default; `reviewer` is deprecated and ignored since 0.7.0, because the review runs one tier above the implementer), and **E2E tests are now opt-in** in both `plan-feature` and `implement-plan` (they make runs materially slower; default off, re-enable per-run or per-project).
 
 ### Foundation skills (project-agnostic)
 
@@ -242,18 +239,19 @@ Land at `ai-tools/skills/<name>/SKILL.md`. Always-on unless flagged optional.
 | [`open-pr-from-context`](skills/vinta-derive-skills/resources/foundation-skills/open-pr-from-context/SKILL.md) | always | Publish a `.vinta-ai-workflows/prs-context/<feature>/<phase>.md` file as a real PR + inline comments via `gh` / `glab`. Bundles [`open-pr.sh`](skills/vinta-derive-skills/resources/foundation-skills/open-pr-from-context/scripts/open-pr.sh). |
 | `implement-plan` | always (generated) | Phase-by-phase plan execution. Thin **conductor**: parses the plan, resolves one `WORKROOT`, and runs a fixed pipeline per phase (`implement-phase` → `review-phase` → `integrate-phase`), tracking + reporting. Generated from a template with project commands + branch / PR / co-author policy. |
 | `implement-phase` | always (unit) | Plan-execution sub-skill co-shipped with `implement-plan`: compose the implementer prompt, pick the model, spawn one implementer subagent for a single phase. |
-| `review-phase` | always (unit) | Plan-execution sub-skill: the three-layer review (mechanical / plan-compliance / independent reviewer) + fix loop. Shared by `implement-plan`, `amend-plan`, and `systematic-debugging`. |
+| `review-phase` | always (unit) | Plan-execution sub-skill: runs the `thermo-nuclear-review-loop` over one phase with the conductor as host — one reviewer sub-agent one tier above the implementer, the phase's own implementer fixing, questions to the human, until the reviewer explicitly approves. Shared by `implement-plan`, `amend-plan`, and `systematic-debugging`. |
 | `integrate-phase` | always (unit) | Plan-execution sub-skill: push the reviewed phase along the project's commit strategy + open the PR via context file. Under `commit_strategy = ask`, ships as `integrate-phase-stacked` + `integrate-phase-modular`. |
 | `amend-plan` | always (generated) | History-rewriting companion to `implement-plan` — revises in-flight plans, amends prior-phase commits, force-pushes, rebases stacked downstream branches. Reuses `review-phase` + `implement-phase`'s shared prompt loop. |
 | [`handoff`](skills/vinta-derive-skills/resources/foundation-skills/handoff/SKILL.md) | always | Session-continuation handoff doc → `.vinta-ai-workflows/handoffs/`. **Write** captures goal, verified-vs-unverified state, decisions + rejected alternatives, landmines, and the single next step — gathered from the repo, never memory. **Resume** verifies a handoff's claims against the repo before continuing from its next step. |
-| [`deslop-comments`](skills/vinta-derive-skills/resources/foundation-skills/deslop-comments/SKILL.md) | always | Rewrite comments + doc blocks touched during a task into Simple English, and delete the ones that shouldn't exist at all — where-used lists, another module's internals, restatements of the code, deferred-work notes, paths not taken (comment-only; no renames, no behavior change). `review-phase` Layer 2 depends on it, `integrate-phase` / `amend-plan` run it over the PR-context file, and it's invokable standalone. |
+| [`deslop-comments`](skills/vinta-derive-skills/resources/foundation-skills/deslop-comments/SKILL.md) | always | Rewrite comments + doc blocks touched during a task into Simple English, and delete the ones that shouldn't exist at all — where-used lists, another module's internals, restatements of the code, deferred-work notes, paths not taken (comment-only; no renames, no behavior change). `integrate-phase` / `amend-plan` run it over the PR-context file, `vinta-ai-maestro` runs it as each phase's `deslop` chore, and it's invokable standalone. |
+| [`thermo-nuclear-review-loop`](skills/vinta-derive-skills/resources/foundation-skills/thermo-nuclear-review-loop/SKILL.md) | always | Review-and-fix loop over a change: the running agent spawns one reviewer sub-agent, verifies its findings, fixes the justified ones and answers the rest, until the reviewer explicitly approves under a strict code-quality standard. Scope questions go to the human instead of being assumed. It is the per-phase review on both execution paths: `review-phase` runs it with the conductor as host, and `vinta-ai-maestro` runs it as each phase's `review` chore once the gates are green. Also invokable standalone. |
 | `write-unit-test` | default-on (generated) | Write durable unit tests for a unit of behavior, enforcing six framework-agnostic rules + this project's captured test conventions, with runner- and stack-specific best-practice packs. Ships automatically whenever a unit-test framework is detected (set `disabled` to opt out). Generated from a template; config under `skills.write-unit-test.*`. See below. |
 | `systematic-debugging` | **opt-in** | Root-cause-first debugging with project-specific repro commands + MCP evidence-gathering (error tracking, traces, logs, metrics, alerts). Renders from a catalogue of observability MCP servers the user declares. |
 | `add-e2e-test` | **opt-in** | Add an e2e test. Body covers e2e framework, page-object pattern, auth/storage-state, seed helpers, tenant scoping, screenshot conventions. |
 | `add-env-var` | **opt-in** | Propagate a new env var through every layer (`.env.example`, build tool envPrefix, build cache hash, app config, AGENTS.md, CI, deploy injection). |
 | [`add-one-off-script`](skills/vinta-derive-skills/resources/foundation-skills/add-one-off-script/SKILL.md) | **opt-in** | Author one-off operational scripts (backfills, cleanups, ad-hoc fixes). Ships a `BaseOneOffScript` class (Python + TS) enforcing dry-run default, idempotency, batched DB ops, segmented CSV backups, signal-safe interruption, multi-sink logging. |
 | [`prepare-worktree`](skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md) | **opt-in** | Provision a fully-runnable git worktree for parallel plan work — reads the plan + `.gitignore` + manifests + env / docker config and gives each worktree its **own dependency copy** (never a symlink) and decides per remaining ignored path whether to **copy / fork / share** (dev DB, env files, compose project name). Ships an OS-level write-guard (`sandbox-run.sh` + a Claude Code `PreToolUse` hook) so stray writes to the main checkout fail at the kernel layer. `implement-plan` Step 0 question (c) opts a run into it, and parallel phase execution requires it — one lane per concurrent phase. |
-| [`thermo-nuclear-code-quality-review`](skills/vinta-derive-skills/resources/foundation-skills/thermo-nuclear-code-quality-review/SKILL.md) | **opt-in** | Deliberately harsh structural-maintainability audit of a diff — abstraction quality, giant files, spaghetti-condition growth — hunting "code-judo" reframes that collapse whole branches / helpers / modes / layers. Read-only; hands each fix to `fixer`. `review-phase` Layer 3 runs a condensed lens every phase and escalates to this full audit on core-architecture / ~1000-line / structurally-smelly phases. |
+| [`thermo-nuclear-code-quality-review`](skills/vinta-derive-skills/resources/foundation-skills/thermo-nuclear-code-quality-review/SKILL.md) | **opt-in** | Deliberately harsh structural-maintainability audit of a diff — abstraction quality, giant files, spaghetti-condition growth — hunting "code-judo" reframes that collapse whole branches / helpers / modes / layers. Read-only; hands each fix to `fixer`. The per-phase review loop carries a condensed structural lens; this is the deliberate deep audit on top of it. |
 | `handoff-to-client` | **opt-in** | (API-only repos) Generate a self-contained API-change handoff doc for the client teams consuming the repo's API — every endpoint / operation added / changed / deprecated / removed vs the default branch, with request/response shapes, auth + error changes, breaking-change flags, one example per operation, and per-platform migration notes. Template-rendered from `skills.handoff-to-client.*` config (client platforms, API style, spec path). |
 
 #### `write-unit-test` in depth
@@ -287,8 +285,8 @@ Land at `ai-tools/agents/<name>.yaml` (canonical YAML; `setup-ai-tools.mjs` emit
 | Agent | Access | Role |
 |---|---|---|
 | `implementer` | read-write | Default coder for one plan phase. Reads AGENTS.md + plan + phase body, runs inner + outer test gates, reports back. Never branches, pushes, opens PRs, or adds AI co-author trailers. |
-| `reviewer` | read-only | Adversarial reviewer. Reads phase + diff + AGENTS.md, outputs `BLOCKER` / `SHOULD-FIX` / `NIT` findings with `file:line`. Does not edit. |
-| `fixer` | read-write | Applies one reviewer finding (or one named test failure). Smallest correct change, re-runs gates, reports. |
+| `reviewer` | read-only | Adversarial reviewer for reviews the team asks for. Reads phase + diff + AGENTS.md, outputs `BLOCKER` / `SHOULD-FIX` / `NIT` findings with `file:line`. Does not edit. `review-phase` does not use it: its loop spawns a general-purpose reviewer, so one standard applies. |
+| `fixer` | read-write | Resolves one merge conflict between phases, applies one review finding handed over cold, or fixes one named test failure. Smallest correct change, re-runs gates, reports. |
 
 Stack templates may add specialists like `migration-author` (Django) or `deploy-author` (Medplum) — see disclaimer above.
 
@@ -594,7 +592,7 @@ vinta-ai-workflows/
 
 `vinta-bootstrap-ai-tools` is the entry point — walks a fresh repo, runs the others in order. The rest can also be invoked individually to refresh a single artifact.
 
-The repository is also a pnpm workspace. `packages/` holds **private, unpublished** packages that are not part of what `install` puts in your project — the `files` whitelist excludes the directory. The one worth knowing about is [`packages/vinta-ai-maestro`](packages/vinta-ai-maestro/README.md): an opt-in daemon that executes the `ai-plans/<feature>.workflow.json` files `plan-feature` emits, scheduling independent phases across worktree lanes. Nothing requires it; the skills path runs the same plans with no daemon installed.
+The repository is also a pnpm workspace. `packages/` holds **private, unpublished** packages that are not part of what `install` puts in your project — the `files` whitelist excludes the directory. The one worth knowing about is [`packages/vinta-ai-maestro`](packages/vinta-ai-maestro/README.md): an opt-in daemon that executes the `ai-plans/<feature>.workflow.json` files `plan-feature` emits, scheduling independent phases across worktree lanes. Each phase there is implemented, gated, then reviewed by its own implementer through the `thermo-nuclear-review-loop` skill until the loop's reviewer approves, comment-cleaned by `deslop-comments`, and gated once more before it integrates. Nothing requires it; the skills path runs the same plans with no daemon installed.
 
 ### Why the `vinta-` prefix?
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vinta-ai-workflows",
-  "version": "0.7.0-alpha25",
+  "version": "0.7.0-alpha27",
   "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

@@ -6,17 +6,20 @@ JSON Schema (Draft 2020-12) contracts for every YAML or JSON payload the vinta-a
 
 | Artifact | YAML location in target project | Schema file | Authored by | Read by |
 |---|---|---|---|---|
-| Project config | `.vinta-ai-workflows.yaml` (repo root) | [`vinta-ai-workflows-config.v1.schema.json`](vinta-ai-workflows-config.v1.schema.json) | `vinta-bootstrap-ai-tools` (initial) → `vinta-sync-ai-tools` (updates) | every builder skill, every template render, every meta-skill |
+| Project config | `.vinta-ai-workflows.yaml` (repo root) | [`vinta-ai-workflows-config.v1.schema.json`](vinta-ai-workflows-config.v1.schema.json) | `vinta-bootstrap-ai-tools` (initial) → `vinta-sync-ai-tools` (updates) | every builder skill, every template render, every meta-skill ; `vinta-ai-maestro` reads `commands` + `maestro` and layers every workflow over them |
 | Sub-agent definition | `ai-tools/agents/<name>.yaml` | [`sub-agent.v1.schema.json`](sub-agent.v1.schema.json) | `vinta-derive-subagents` | `setup-ai-tools.mjs` (emits per-vendor copies) |
 | PR-context frontmatter | top-of-file YAML in `.vinta-ai-workflows/prs-context/{feature-kebab}/phase-{phase.id}.md` | [`prs-context-frontmatter.v1.schema.json`](prs-context-frontmatter.v1.schema.json) | `implement-plan` / `amend-plan` | `open-pr.sh` |
 | PR-context inline comments | YAML inside the ` ```yaml ... ``` ` fence under `# Comments` of the same file | [`prs-context-comments.v1.schema.json`](prs-context-comments.v1.schema.json) | `implement-plan` / `amend-plan` | `open-pr.sh` |
 | MCP preflight cache | `.vinta-ai-workflows/cache.yaml` (gitignored — per-developer-machine state) | [`mcp-preflight-cache.v1.schema.json`](mcp-preflight-cache.v1.schema.json) | rendered `systematic-debugging` SKILL.md (writes during Phase 0) | rendered `systematic-debugging` SKILL.md (reads at Phase 0 start) |
+| Interview round | `.vinta-ai-workflows/interviews/<slug>/rounds/round-NN.json` (gitignored working trail; JSON, not YAML) | [`interview-round.v1.schema.json`](interview-round.v1.schema.json) | the skill running the interview (`create-spec` Step 0 via `interview-ui`) | `interview-ui` server + shell (`ai-tools/skills/interview-ui/`) |
+| Interview answers | `.vinta-ai-workflows/interviews/<slug>/answers/round-NN.json` (gitignored; JSON) | [`interview-answers.v1.schema.json`](interview-answers.v1.schema.json) | `interview-ui` server, on browser submit | the skill running the interview (reads answers, writes the next round) |
 | AI model tier table | `ai-tools/skills/plan-feature/resources/ai-models.yaml` (shipped verbatim with the `plan-feature` foundation skill; source: `skills/vinta-derive-skills/resources/foundation-skills/plan-feature/resources/ai-models.yaml`) | [`ai-models.v1.schema.json`](ai-models.v1.schema.json) | nightly `check-ai-models` job ([`scripts/check-ai-models.mjs`](../scripts/check-ai-models.mjs)) → auto-PR | `plan-feature` (per-phase model suggestion) |
 | 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) |
 
-> **Three of these are generated, not hand-written**: `workflow.v1`, `postmortem.v1` and `intervention.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 intervention's is `src/intervention/intervention.ts`; regenerate either with `pnpm --filter vinta-ai-maestro <postmortem|intervention>:schema:gen`, verify with `:schema:check` — `tests/postmortem.test.ts` and `tests/intervention.test.ts` run those byte comparisons too. Edit the zod schemas, never the JSON.
+> **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.
 >
 > 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).
 

package/schemas/ai-models.v1.schema.json

@@ -75,6 +75,11 @@
                   "note": {
                     "type": "string",
                     "description": "Optional caveat (fallback, variant, when-to-step-up)."
+                  },
+                  "fallback": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Model id, same vendor, to run instead once this model is out of quota or credits. Transcribed into a plan's workflow as `defaults.model_fallbacks`; the plan-execution skills apply it when a spawn on this model is refused for quota. A budget decision, not a tier placement: it may point outside this tier."
                   }
                 }
               }