vinta-ai-workflows 0.7.0-alpha9 → 0.7.0

package/CHANGELOG.md

@@ -5,635 +5,489 @@ All notable changes to `vinta-ai-workflows` are documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.7.0] — YYYY-MM-DD
-
-<!-- pre-release: 0.7.0-alpha9 on 2026-09-14 -->
-<!-- pre-release: 0.7.0-alpha8 on 2026-09-14 -->
-<!-- pre-release: 0.7.0-alpha7 on 2026-09-14 -->
-<!-- pre-release: 0.7.0-alpha6 on 2026-09-13 -->
-<!-- pre-release: 0.7.0-alpha5 on 2026-09-13 -->
-<!-- pre-release: 0.7.0-alpha4 on 2026-09-13 -->
-<!-- pre-release: 0.7.0-alpha3 on 2026-09-12 -->
-<!-- pre-release: 0.7.0-alpha2 on 2026-09-12 -->
-<!-- pre-release: 0.7.0-alpha1 on 2026-09-11 -->
+## [0.7.0] — 2026-11-03
+
+<!-- Graduates the 0.7.0-alpha1 … 0.7.0-alpha39 series (2026-09-11 to
+     2026-10-24). This section is the net change since 0.6.1. The
+     alpha-by-alpha record is in the GitHub pre-releases and in this file's
+     git history before the release commit. -->
 
 ### Added
 
-- **A project declares what makes a lane runnable.** `project.env_files` copies
-  ignored configuration into each worktree, `project.setup_cmd` runs an
-  idempotent setup hook on provisioning and recycle, and the fixed
-  `project.commands` vocabulary tells implementers, reviewers and fixers the
-  project's real lint, typecheck, test and migration entry points.
-
-- **Compose-backed lanes are isolated past `COMPOSE_PROJECT_NAME`.** The daemon
-  now generates an out-of-tree Compose override per lane, strips fixed host
-  ports, re-pins fixed and external volumes, and carries the complete lane
-  environment into agent and takeover processes as well as gates. Explicitly
-  published services receive probed per-lane ports recorded in the teardown
-  summary.
-
-- **Shared services get one namespace per lane.** `project.services` models a
-  fixed index or lane-derived name inside one Redis, RabbitMQ, object-storage,
-  or similar server, with project-owned create/reset commands and capacity
-  validation before provisioning creates templates or worktrees.
-
-- **Agents can take the semaphore a workflow declares.**
-  `vinta-ai-maestro with <resource> -- <cmd>` waits on the run's existing
-  `ResourcePools`, runs the heavy inner-loop command, and releases on exit.
-  Renewable leases expire when their client disappears, are visible in the
-  live journal, and are surfaced in implementer, reviewer and fixer prompts.
-
-- **A failed phase retries itself, and then asks.** `--on-failure` defaults to
-  `retry`: one cold re-attempt (`--retries <n>`, 0–5), and then the node parks
-  on a question — retry, retry with another member of the crew, or stop. The
-  failures this system produces are overwhelmingly environmental and are gone by
-  the second attempt; the ones that survive it are the ones worth a person.
-  `ask` skips the automatic attempt. `stop` is the old behaviour and remains the
-  right choice for CI, because everything else eventually **waits**.
-
-  A failure that survives its retries says so: the reason carries
-  `(after N attempts)`, which no event otherwise records.
-
-- **A failed phase can be retried by hand.** A **Retry phase** button, and
-  `POST /api/runs/:runId/nodes/:nodeId/retry`. It returns the node to the ready
-  set and unblocks the subtree its failure blocked — a phase that died of
-  something environmental holds up work that was never broken. It needs the run
-  to still be in flight, which with the new default it usually is; a run that
-  has genuinely ended is re-run, not retried, and says so rather than doing
-  nothing.
-
-- **The monitor can go and look.** It was given a digest and nothing else, and
-  read exactly as thin as that sounds — it could say a phase had failed and
-  never say what the phase had written. It is briefed as a technical project
-  manager now, with the map: the plan document, each phase's brief, each lane's
-  worktree path, each branch and its base, and where the journal and transcripts
-  live. It has a shell and its working directory is the repository, so it can
-  read the diff before drawing a conclusion. The digest stays as the index —
-  bounded, cheap, enough to know which phase is worth a closer look.
-
-- **The monitor conversation is kept.** It lived in component state, so a reload
-  threw away every question and every answer — a worse record than the run it
-  describes. It is written to the transcript store under a reserved node id and
-  read back on load, so it outlives the tab, the daemon and the run.
-
-- **Panels expand.** Anything holding content that is only nominally
-  summarisable — an agent's transcript, a gate log, the monitor conversation,
-  the steering box — takes the full container width and about a screen of
-  height on demand. The height travels as a CSS variable, because the element
-  that has to grow is a scroller several components below the panel.
-
-- **A run has a spokesperson you can ask.** `serve` grows a **Monitor** panel on
-  the run view: one agent that reads the journal and answers in prose — what is
-  blocked, why a phase failed, what it would take to move on. It runs on the
-  dearest tier on the crew, because it is read by a person deciding what to do
-  about a failing run, and it is asked a handful of times rather than hundreds.
-
-  Three things it deliberately is not.
-
-  **It is not in the permission path.** The obvious thought, once an agent has
-  been refused something, is to put a smarter agent in front of the refusals —
-  but a phase makes hundreds of tool calls (one node in one real run made 179)
-  and a model turn before each is latency and cost spent on questions like "may
-  I run ruff", which should never have been questions. Permissions are settled
-  structurally, once per spawn, for free.
-
-  **It does not read the transcripts.** Piping every agent's output into a
-  second agent would make the monitor the most expensive thing in the run and
-  tie its cost to the work rather than to the questions. It reads a bounded
-  digest — statuses, failure reasons, pending questions, the last few refusals
-  with their sentences, one trimmed last word per phase — so a one-hour run and
-  a one-day run cost about the same to ask about.
-
-  **It has no authority.** It can explain a §9.1 pause; it cannot answer one.
-  An agent that could quietly approve its colleagues' work would turn a
-  checkpoint into a formality, and the checkpoint is the point.
-
-  It answers about **finished runs too**, which is when "why did this fail" is
-  usually asked, and it needs no lane: it writes nothing.
-
-- **`serve` reads `--permission`.** The flag has been accepted and ignored since
-  it existed. It decides how the monitor is spawned, so it is read now.
-
-- **A plan staffs a team, instead of picking a model per phase.** Choosing a tier
-  phase by phase answers "what runs this one" ten times and never adds it up, so the
-  two questions that decide what a feature costs go unasked: how many agents does
-  this need at once, and is any of them too junior for what it was handed.
-  - `plan-feature` opens **Phased Rollout** with a **Crew** table — one row per
-    agent, carrying its tier and the phases it takes — and every phase carries an
-    **`**Assigned to**:`** line naming one of them. It replaces
-    `**Suggested AI model**:`; a plan that still has the old line keeps working, and
-    the executor reads the tier straight off it.
-  - The **Execution graph** table gains an **Agent** column and an **Idle** note.
-    Reading across a row says who is working that wave; reading down a column says
-    who is not. A wave that will serialize because the roster cannot staff it is now
-    stated in the plan rather than discovered as a slow run.
-  - **Every member has to earn 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). The roster is therefore **not** capped
-    at the widest wave — a junior who runs the migration and the flag deletion is
-    worth having in a graph that never runs two phases at once — but the lane pool
-    still is, because lanes are bought with concurrency and crew are not.
-  - **Reviewers are a role on the crew, and implementers and reviewers are
-    disjoint.** A member has `role: implementer` or `role: reviewer`; a phase cannot
-    be assigned to a reviewer and a reviewer never writes code, so an agent reading
-    its own diff is not something a plan can express. A phase is read by the
-    cheapest reviewer at or above its tier. A roster with no reviewer still runs and
-    falls back to `agent_models.reviewer`, cold, one session per phase.
-    - **A reviewer reads the lane it is reviewing**, with the phase's changes still
-      uncommitted in it, and has no worktree of its own. That is what puts review
-      before the commit: a finding is fixed in the working tree rather than
-      recorded as a mistake on the branch plus a correction after it. The cost is
-      that a reviewer's directory follows the work, so its session carries only
-      between reviews that land in the same lane.
-  - **A crew member is an agent that lives for the whole run.** Each one keeps its
-    own worktree and its own session across every phase it takes, so the agent that
-    takes Phase 4 still knows what it learned about the codebase in Phase 1 —
-    which is most of what a cold agent's first turn of a phase is spent
-    rediscovering.
-    - This works because the *directory* stops moving. Lanes used to be anonymous
-      slots handed out by a free list, so a member landed somewhere different each
-      phase and its context described paths it was not standing in. Pinning each
-      member to one worktree leaves a far smaller question — which files changed —
-      and `git diff --name-only` answers it exactly.
-    - A cross-phase continuation therefore gets the new phase's **full brief** (it
-      is new work, not a delta) behind a re-orientation: same agent, same directory,
-      everything you learned still holds; the tree is on a different branch; these
-      files differ; and — the sentence that matters most — whether the previous
-      phase's own work is in this tree at all.
-    - A delta that cannot be computed is reported as **unknown**, never as empty.
-      "Nothing changed" is the one wording that would stop an agent re-reading.
-    - Two things still start cold: a member whose previous phase **failed**, because
-      its session is the context that failed with it, and the final fix round.
-    - The cost, stated plainly: **one worktree and one set of forked databases per
-      implementer**, so `resources.lane.capacity` is now the implementer count
-      rather than the widest wave, and adding a cheaper implementer is a trade of
-      disk against money rather than free.
-  - The workflow document gained a top-level **`crew`** block and **`nodes[].crew`**.
-    A staffed node carries no `model` — the member has one — and a document that is
-    half-staffed, names a member nobody declared, assigns a phase to a reviewer,
-    declares an implementer nobody is assigned to, or staffs a reviewer below every
-    phase on the plan is refused before the run starts.
-  - `vinta-ai-maestro` claims an agent **before** the lane, prefers the member the plan
-    named, covers with the **cheapest** qualified free peer when they are busy, and
-    **waits rather than handing a phase below its tier** — even with a lane free. A
-    lane is disk; a phase run by too junior an agent does not fail cleanly, it fails
-    review two rounds later with nothing pointing back at the staffing. A reviewer is
-    claimed per review turn rather than per phase — it has one session ledger and
-    two concurrent reviews would collide over it — so one reviewer on a three-lane
-    plan is a queue at the review step and not a serialised run.
-  - The run view reports who actually worked against who the plan said would.
-    `substituted` is the figure to read beside a cost that overran: every
-    substitution ran at or above the budgeted tier, so a run can be entirely green
-    and still have been staffed dearer than planned.
-
-- **`implement-plan` runs independent phases in parallel.** The plan now carries a
-  dependency graph and the conductor schedules against it: a phase starts as soon as
-  every phase it depends on is green and a worktree lane is free, instead of waiting
-  for its turn in plan order. A chain-shaped plan behaves exactly as before —
-  sequential execution is the one-lane case of the same scheduler.
-  - `plan-feature` gives every phase a **`**Depends on**:`** line naming the artifact
-    it needs from each upstream phase, and opens **Phased Rollout** with an
-    **Execution graph** table derived from those lines. It also checks same-wave
-    phases against the **Touch List** for file overlap and tells you to add an edge
-    when two phases would fight over the same file.
-  - New shared partial `plan-execution/partials/parallel-lanes.md` carries the graph
-    parse, the worktree lane pool, the dependency-derived branch topology, the
-    dispatch loop, the tracking-directory schema, and the sibling-lane write guard.
-  - `prepare-worktree` documents provisioning a **pool** of lanes for one plan and
-    records a `reset_cmd` per forked DB so a lane can be reused across phases without
-    carrying the previous phase's migrations into the next one's test run.
-  - Two new config fields: `run_options.implement-plan.parallel_phases` (default
-    `true`) and `run_options.implement-plan.max_parallel_lanes` (default `3`), asked
-    at bootstrap alongside the existing `prepare-worktree` follow-ups.
-
-- **`plan-feature` emits an executable `ai-plans/<feature-kebab>.workflow.json`
-  beside every plan.** The markdown stays the document humans review; the JSON is
-  the same phase graph in the form an orchestrator runs — one node per phase, one
-  `depends_on` entry per `**Depends on**:` clause carrying both the upstream phase
-  and the artifact it provides, plus the phase's Touch List, gates, capacity pools
-  and model tier. Validated by
-  [`schemas/workflow.v1.schema.json`](schemas/workflow.v1.schema.json), which the
-  emitted file references from its `$schema` key so editors validate it as it is
-  written. **Unconditional** — no config field, no bootstrap question, no opt-in:
-  a project with no orchestrator carries a file nothing reads, and a project that
-  adopts one later finds its plans already executable.
-
-- **Review findings go back to the phase's own implementer, not to a fresh fixer.**
-  The agent that wrote the code still holds the phase brief, the plan's bounds, the
-  dependency context and its own reasoning; a fresh fixer held a quoted finding and
-  had to rediscover the rest — slower, dearer, and likelier to "fix" a symptom by
-  undoing something the phase chose deliberately. The fix message is now a delta —
-  the findings, nothing else — because re-sending the brief invites a
-  re-implementation rather than a fix.
-
-  Three rules keep that from costing what it buys. **The reviewer is never the
-  implementer**: continuing the reviewer across rounds is fine, but the review must
-  come from an agent that did not write the code. **The last round before giving up
-  goes to a fresh fixer, always** — reuse means the agent that wrote the bug is
-  fixing it, which is usually the point and occasionally exactly wrong, because that
-  assumption *was* the bug. And where a runtime cannot continue a finished
-  sub-agent, the old cold hand-off still happens and is recorded as one, so a slow
-  phase can be read later without guessing.
-
-  One consequence worth knowing: a continued implementer fixes at its own crew
-  member's tier, so `agent_models.fixer` now governs only the cold cases. A project
+- **`vinta-ai-maestro`: a `plan-feature` plan runs itself, phases in parallel,
+  with you steering from a terminal or a browser.** A new workspace package,
+  `packages/vinta-ai-maestro/`, published as its own npm package under the same
+  version number as `vinta-ai-workflows` and run with `npx vinta-ai-maestro`
+  (Node ≥ 22). It is not part of the `vinta-ai-workflows` tarball: what reaches
+  the skills package is the generated schemas below and the skill changes that
+  produce and consume them. [SPEC.md](packages/vinta-ai-maestro/SPEC.md) is the
+  authority and the package README is the operator's manual.
+  - **A run.** `run <workflow.json>` starts the plan's `.workflow.json` as a
+    background job and returns; closing the terminal changes nothing
+    (`--foreground` keeps it in the process, for CI). The run works on a plan
+    branch, `plan/<workflow-id>/base`, cut from `base_branch`. Each phase gets a
+    crew member, a lane — a git worktree with its own copy of the dependency
+    dirs, forked `dev` / `test` databases, an isolated compose project, a
+    namespace in each shared service, the declared `env_files` and a
+    `setup_cmd` — and the `standard-phase` pipeline: implement, gates, review,
+    polish chores, verify, integrate (merge, gates on the merged tree, push,
+    PR), `after_pr` chores. A phase with one dependency branches from it, one
+    with several from an `integ-<id>` merge; each wave merges into
+    `plan/<id>/wave-<N>`, and the last wave opens the plan PR, the one PR that
+    lands the plan. `run --resume <run-id>` picks a paused, interrupted or
+    failed run back up with the policy it was started with. Policy flags:
+    `--on-failure retry|ask|stop` (default `retry`: one cold attempt, then a
+    question), `--retries`, `--retry-after <15m>` (an unanswered failure
+    question answers itself, backing off when attempts fail fast),
+    `--agent-answer-after` (how long an agent's own question waits before the
+    recommended options are taken), `--permission ask|auto|full|judged`
+    (default `auto`), `--harness-profile <name>` (a named binary and
+    environment — a second account, say — from
+    `~/.config/vinta-ai-maestro/profiles.yaml`), `--system-one <config.json>`,
+    `--no-coordinator` and `--coordinator-authority full`.
+  - **Harnesses.** claude-code, codex (`codex app-server`, codex-cli ≥ 0.147.0)
+    and opencode, behind one adapter contract: spawn, resume, inject a message
+    into a running turn, wait for background work, compact. A quota, rate-limit
+    or concurrency refusal parks the harness, not the phase, until the reset
+    time the vendor stated; `defaults.model_fallbacks` and
+    `defaults.harness_fallbacks` move the refused spawn to a fallback instead;
+    a provider outage re-runs the phase when the harness answers, charging
+    nothing to its attempts; a logged-out CLI asks you to log in. Sessions
+    start one at a time per harness, and the ceiling a run discovers is kept
+    for the next one.
+  - **The crew.** A plan staffs a team, the Crew table `plan-feature` writes:
+    one member per agent with a tier, a model and a harness, and every phase
+    assigned to one of them. A member keeps its worktree and its session across
+    the phases it takes, so what it learned in phase 1 is still there in
+    phase 4. A busy member is covered by the cheapest qualified free peer or by
+    a spare in its image (`defaults.max_spare_crew`, default 2); a phase is
+    never handed below its tier (`defaults.substitution`, default
+    `up_one_tier`); a phase its review keeps rejecting moves up a tier
+    (`defaults.escalate_after_rejections`, default 3); a merge conflict goes to
+    the most senior member who wrote one of its sides.
+  - **Gates.** A gate is a shell command, by type (`test`, `lint`, `typecheck`,
+    `e2e`, taking the project's `commands.*`) or by a project-wide id
+    (`maestro.gates.<id>`), or a judge question put to a System One classifier.
+    Phase gates run a `scoped_cmd` (`{changed_files}` / `{touches}`) until the
+    review approves; `verify` then runs the full `cmd` on the phase branch, and
+    the full suite runs on every merged base and wave (`verify_gates`,
+    `base_gates`, `wave_gates`, all full by default). Results are cached per
+    gate, command and tree. `fresh_cmd` and `fresh_when` run a gate from a
+    fresh test database when the tree moved under it; `cold_cmd` and
+    `scope_cache` cover a lane with no test cache; `timeout_s`,
+    `queue_timeout_s` and `tuning.allowed_flags` bound and retune a gate.
+    Resource pools (`resources`, `scope: run | host`) serialise the heavy ones
+    across lanes, and across every maestro run on the machine. Agents run a
+    gate with `vinta-ai-maestro gate <id>` and take a pool with
+    `vinta-ai-maestro with <resource> -- <cmd>`; on claude-code a `PreToolUse`
+    gate guard refuses the bare command, and `--permission judged` asks a
+    classifier about each shell call. `codegen` steps regenerate generated
+    files rather than merging them, `append_only` files merge as a union,
+    `post_merge` runs a formatter over what git merged, and `ci_only` records
+    the CI checks deliberately left to CI.
+  - **Review and chores.** Once a phase's gates are green, the implementer's
+    own session runs the `review` chore, `thermo-nuclear-review-loop`: one
+    reviewer sub-agent, each finding verified and fixed or rejected with
+    counter-evidence, until the reviewer explicitly approves. A phase's
+    decisions — answered questions, operator context, rejected findings — are
+    kept and carried into every later prompt, so nothing is asked twice.
+    `deslop` and the project's other `after_review` chores run before verify;
+    `after_pr` chores (a review canvas, say) run once the PR is open. A chore
+    reporting `Status: FAILURE` is recorded as failed. `max_fix_rounds` is
+    unset by default, which means no limit; set it to be asked.
+  - **Integration.** A conflict goes to a conflict fixer in the integration
+    worktree, with a time limit per round and its resolution gated by the union
+    of both phases' gates; what a round left is kept under
+    `refs/vinta-ai-maestro/` across attempts. A resolution that undoes a
+    phase's deletion is flagged. A merge git or a hook refuses goes to you.
+    Every phase and integration PR carries a **Landing** section pointing at
+    the plan PR; `land <run>` says how a finished run lands and closes the PRs
+    whose work is already in the base; `propagate <run> <phase>` carries a late
+    fix into every `integ-` and `wave-` branch; `sync-base <run>` brings a moved
+    `base_branch` into a live plan.
+  - **Steering.** `status`, `logs [-f]`, `logs --failures <gate-log>`, `pause`,
+    `stop`, `node context|redirect|pause|resume|abort|retry|fresh|answer`,
+    `node interrupt|reassign|step` (take a phase over at its step without
+    failing it), `switch-harness`, `fixer interrupt|reassign`, `workflow`,
+    `amend` (a live run takes an edited workflow, rebasing the done phases the
+    change reaches), `exec <run> <lane|integration> -- <cmd>` (a command with
+    the lane's environment, holding the integration worktree while it runs),
+    `gate-cache invalidate`, `purge [--lanes --branches]` (never the only copy
+    of work), `doctor` (every check a run depends on, from disk and servers to
+    env files, compose `-T`, gate scope and the CI jobs no gate covers),
+    `validate`, `simulate` and `judge calibrate`. Every acting request takes a
+    reason, journalled with what it explains.
+  - **The run coordinator.** One agent per run, woken when a phase fails, an
+    attempt errors, a phase waits on the integration worktree or a gate crosses
+    its cost threshold, at most 24 times a run. It reads the journal and the
+    repository and acts through the same API as you: steer, pause, retry,
+    answer the questions a timer could answer, amend the live run, run a
+    command. It may change how the run executes, never what it builds, and
+    never weakens a check. Everything decided without you — by it or by a
+    timer — is listed in `status`, the run view, the plan PR and the
+    post-mortem.
+  - **The browser UI.** `ui` serves every run in the project and hosts none,
+    so closing it interrupts nothing. A run view with the plan graph, the
+    roster, the integration worktree's record, resource pools, sessions and
+    cost, what was decided without you, a notifications inbox and the
+    coordinator as a sidebar; a phase view with the transcript rendered the way
+    the harnesses render it, the phase's running processes and gates, its
+    changes as a diff, its integration timeline, its PR, and steering as a chat
+    input; an analytics page while the run goes and the post-mortem as a report
+    after; a Logs view over the daemon's own log; a workflow editor that saves
+    only what you changed; Pause, Stop, Retry and Resume. Every page fits a
+    phone, in light and dark.
+  - **The record.** Everything lands under `.vinta-ai-maestro/` (gitignored):
+    the run's journal, each phase's transcript with the role that wrote each
+    line, gate logs, the daemon's own log (`logs/daemon.ndjson`, identifiers
+    only, enforced), and once the run ends a post-mortem (`postmortem.v1`):
+    dependencies declared but unused or discovered at gate time, conflicts,
+    the critical path, idle capacity, gate costs, failure causes, crew
+    substitutions, failed chores and unattended decisions. `plan-feature` reads
+    it before planning the next feature in the same repository.
+  - **Security.** The daemon binds loopback and every API request carries a
+    token. Agents hold a token of their own that reaches only their leases,
+    gates and hooks; the coordinator has one of its own; a run's job keeps its
+    token in a `0600` file that `ui` never prints. Nothing in the journal or
+    the log holds repository contents, and every token is redacted from both.
+    The only API key the package ever uses is the one a `--system-one`
+    classifier config names; the harnesses run on your logged-in CLIs.
+  - **Platforms.** macOS, Linux and Windows, each in CI.
+
+- **`vinta-design-system` and `vinta-dag-editor`**, two more workspace
+  packages maestro's UI is built on: oklch tokens in three layers, six
+  run-status tones (waiting is amber and failure is red, never the same hue),
+  shadcn/ui components on Tailwind CSS v4 and a light/dark/system theme; and
+  the framework-agnostic Web Component that draws and edits plan DAGs —
+  arrowed edges, dependencies drawn by dragging, phase ids on the cards, a
+  details strip, keyboard zoom, full screen. They publish on their own cadence
+  as dependencies of `vinta-ai-maestro`; nothing in either reaches
+  `npx vinta-ai-workflows install`.
+
+- **Plan review: a page for a plan before it runs, and a chat with the agent
+  that wrote it.** `vinta-ai-maestro review open <workflow.json>` serves the
+  plan's graph with every phase's real prompts, the plan's markdown, a phase ×
+  gate matrix, the projected schedule and what `validate` reports. You comment
+  on the plan, a phase, a prompt or a gate and send the batch; the agent answers
+  through `review wait` and `review reply`, edits the plan, and **Approve plan**
+  ends the loop. The review is committed beside the plan as
+  `ai-plans/<id>.review.json` (`plan-review.v1`, see
+  [packages/vinta-ai-maestro/SPEC.md § 19](packages/vinta-ai-maestro/SPEC.md)).
+  When maestro is installed, `plan-feature` runs `validate --json` on every
+  workflow it writes and asks whether to review on the page, in chat, or later.
+
+- **The browser interview.** A decision-heavy interview — `create-spec`'s
+  Step 0 first — can run 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 with the recommended default marked, and a question panel for
+  asking the agent. Round-based and file-based, so it works the same under
+  every harness: the agent writes
+  `.vinta-ai-workflows/interviews/<slug>/rounds/round-NN.json`
+  (`interview-round.v1`), blocks on `vinta-ai-maestro interview wait`, and
+  resumes when the page submits `answers/round-NN.json`
+  (`interview-answers.v1`). The page is maestro's
+  (`interview start|wait|status|stop --dir <dir>`,
+  [SPEC.md § 20](packages/vinta-ai-maestro/SPEC.md)), rendered with the design
+  system; the server binds loopback, carries a token in the printed URL,
+  serves documents only from the interview's `docs/` and accepts a round's
+  answers once. Opt in with the new `interview-ui` foundation skill (bootstrap
+  **Optional foundation skills** question 7, `foundation_skills.interview-ui`
+  in the config schema); it ships `SKILL.md` and an example round, and needs
+  `vinta-ai-maestro` runnable from the project (`npx --no-install
+  vinta-ai-maestro` when it is a devDependency, `npx vinta-ai-maestro`
+  otherwise). `create-spec` asks once per interview whether to decide in the
+  browser or in chat; projects without the skill see no change.
+
+- **`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 a person can settle — unreachable scenarios, requirement
+  ambiguity, destructive operations — go to them instead of being assumed.
+  Always shipped (`foundation_skills.thermo-nuclear-review-loop`), because
+  `review-phase` runs it and every maestro workflow names it in its `review`
+  chore; also invokable on its own.
+
+- **`plan-feature` emits an executable workflow and staffs a crew.**
+  `ai-plans/YYYY-MM-DD-<feature-kebab>.workflow.json` lands beside every plan,
+  unconditionally — a project with no orchestrator carries a file nothing
+  reads, and one that adopts maestro later finds its plans already executable.
+  It is the same phase graph in the form a run loads: one node per phase,
+  `depends_on` from each phase's `**Depends on**:` line, its Touch List, gates,
+  pools and crew member, validated by `workflow.v1`. The plan opens **Phased
+  Rollout** with a **Crew** table and an **Execution graph** table, and every
+  phase carries `**Assigned to**:` and `**Depends on**:` lines; they replace
+  `**Suggested AI model**:`, which old plans may keep. The skill asks what a
+  phase lane needs its own copy of and writes the workflow's `project` block,
+  emits the codegen steps and append-only files it detects in the project,
+  writes the crew's model fallbacks, puts a contract test for any interface two
+  parallel phases share into the foundation phase, and reads the post-mortems
+  of earlier runs before drawing the next graph.
+
+- **`implement-plan` runs independent phases in parallel** on the skills path
+  too, with no maestro. The plan carries a dependency graph and the conductor
+  schedules against it: a phase starts as soon as every phase it depends on is
+  green and a worktree lane is free. A chain-shaped plan behaves exactly as
+  before. Lanes are a pool of worktrees, branches base on their dependencies
+  (`integ-<id>` for several, `plan/<id>/wave-<N>` per wave), tracking is a
+  directory with one file per phase so wave merges never conflict on it, a
+  sibling-lane write guard covers the pool, and `modular-commits` keeps its
+  atomic units on lane branches. Two new config fields:
+  `run_options.implement-plan.parallel_phases` (default `true`) and
+  `max_parallel_lanes` (default `3`). The skill refuses rather than degrading
+  when parallel execution is asked for and worktrees are unavailable.
+
+- **Provision worktrees with your own script instead of the `prepare-worktree`
+  skill.** Set `commands.worktree_prepare` (and optionally
+  `commands.worktree_teardown`) in `.vinta-ai-workflows.yaml`; `implement-plan`
+  and maestro run that command for every lane and the integration worktree,
+  with `VINTA_WORKTREE_NAME`, `_PATH`, `_BRANCH`, `_BASE_REF`, `_KIND`,
+  `VINTA_MAIN_CHECKOUT`, `VINTA_PLAN_PATH` and `VINTA_WORKTREE_SUMMARY` set,
+  and check the result with git rather than trusting the exit code. The
+  bootstrap offers existing worktree scripts `vinta-analyze-codebase` found,
+  and can write the scripts for you — `prepare.sh`, `teardown.sh` and `lib.sh`
+  under `scripts/worktree/`, from templates that carry the contract, dry runs,
+  rollback, compose isolation and a teardown that refuses a dirty worktree.
+
+- **Agents stop for input with clickable questions instead of prose.** Every
+  skill and sub-agent asks through the harness's structured question tool
+  (Claude Code's `AskUserQuestion`, OpenCode's `question`, Codex's
+  `request_user_input`, Cursor's `AskQuestion`, Copilot's `askQuestions`,
+  Gemini CLI's `ask_user`): 2–4 options with descriptions, the recommended one
+  first. `AGENTS.md` gains an **Asking the human** section, copied verbatim
+  from
+  [`vinta-write-agents-md/resources/asking-the-human.md`](skills/vinta-write-agents-md/resources/asking-the-human.md).
+  Sub-agents, which cannot ask, return `status: NEEDS_INPUT` with the question
+  in the tool's shape, and the new `plan-execution/partials/relay-questions.md`
+  turns it into a question, records the answer and continues the same agent.
+  Every prose stop point across the plan-execution unit, the foundation skills
+  and the bootstrap skills became such a question. `vinta-sync-ai-tools` adds
+  a one-time migration for existing projects.
+
+- **PR Review Canvas integration (`integrations.pr-review-canvas`).** The
+  bootstrap offers [PR Review Canvas](https://github.com/vintasoftware/pr-review-canvas)
+  as its first *integration*: an external tool that installs its own skill,
+  nothing of which is bundled here. A new optional top-level `integrations`
+  object in the config schema records the opt-in (interview group D.2, asked
+  when `code_host` is GitHub or GitLab and `pr_creation` is `agents-create`).
+  When enabled, `vinta-install-ai-tools-setup` runs `pr-review install-skill`
+  (the CLI is never auto-installed; the install command is printed), the
+  `integrate-phase` PR step runs `/pr-review-canvas <n>` after `open-pr.sh`
+  publishes, and `plan-feature` adds an `after_pr` `review-canvas` chore to the
+  workflow it writes. The analysis, derive and update skills treat an
+  integration-owned skill as the tool's and never edit it.
+
+- **Model fallbacks for models that run out of quota.** `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`),
+  `ai-models.v1.schema.json` gains the optional field, the nightly
+  `check-ai-models` job checks fallback ids for staleness, `plan-feature`
+  writes the map into each workflow's `defaults.model_fallbacks`, and the
+  plan-execution skills follow the same rule when maestro is not running them.
+
+- **Five generated JSON Schemas, and the schemas are checked.**
+  [`workflow.v1`](schemas/workflow.v1.schema.json) (the executable plan),
+  [`postmortem.v1`](schemas/postmortem.v1.schema.json),
+  [`plan-review.v1`](schemas/plan-review.v1.schema.json),
+  [`interview-round.v1`](schemas/interview-round.v1.schema.json) and
+  [`interview-answers.v1`](schemas/interview-answers.v1.schema.json) are
+  generated from zod sources in `vinta-ai-maestro` and byte-compared in its
+  tests; see [`schemas/README.md`](schemas/README.md). `npm run
+  validate-schemas` (part of `npm test`) compiles every schema under `schemas/`
+  with Ajv in strict Draft 2020-12 mode and checks the fixtures in
+  `tests/schema-fixtures/`: `valid/` must pass, `invalid/` must fail.
+
+- **Config schema (`vinta-ai-workflows-config.v1`), all additive.** A `maestro`
+  section holding what every plan used to repeat — gates by type and by id,
+  resources (with `scope`), chores, `defaults` (gates, harness, pipeline,
+  `gate_scope`, `verify_gates`, `base_gates`, `wave_gates`,
+  `pull_requests: phase | plan`, `max_spare_crew`, `substitution`,
+  `escalate_after_rejections`, `model_fallbacks`, `harness_fallbacks`), the
+  `project` block (databases, services, `env_files`, `setup_cmd`,
+  `prepare_cmd`, `reset_cmd`, `recycle_keep`, `hooks`, `lane_seed`), `codegen`,
+  `append_only`, `ci_only` and `post_merge` — which maestro layers each plan
+  over (`commands.*`, then `maestro.*`, then the plan, then the run's own
+  amendments). Also `integrations`, `foundation_skills.interview-ui`,
+  `foundation_skills.thermo-nuclear-review-loop`, `commands.worktree_prepare`
+  / `worktree_teardown`, `commands.worktree_candidates`, `commands.lint_scoped`
+  and `run_options.implement-plan.parallel_phases` / `max_parallel_lanes`. The
+  bootstrap interview asks for each (maestro defaults are group C.11, with
+  follow-ups on `env_files`, the test gate in lanes, a fresh-database form,
+  when the full suite runs, CI checks with no gate, and test-tool caches
+  missing from `.gitignore`), and `vinta-sync-ai-tools` offers them to
+  existing projects. `prs-context-frontmatter.v1` gains an optional `kind`
+  (`phase | integration | plan`).
+
+### Changed
+
+- **`plan-feature`: plans have fewer, longer phases.** The phase size ceiling
+  rises from 1500 to 4000 LoC, tests included, and the sub-phase trigger moves
+  to that same ceiling; the Step 0 **Phase granularity** default flips to
+  bundling closely-related use-cases into one phase, with one use-case per
+  phase as the opt-in answer. A phase of a few hundred lines has to justify
+  standing alone. A plan drawn before the change is still valid as written.
+  The skill also tells the author to read the CI config and give every locally
+  runnable CI job a gate (and to record the rest under `ci_only`), treats two
+  parallel phases adding migrations to the same app as file overlap, treats a
+  rename of a shared symbol as an interface change, names the enum for
+  same-named choice fields two phases expose, lists the usual append-only
+  registries, tells authors to declare the gitignored files a lane needs under
+  `project.env_files`, and states that `gates: []` means *none*. Its AI model
+  tiers cite the latest OpenAI, Anthropic and Google releases
+  (`claude-sonnet-5-5`, `gpt-6.1-sol`, `gemini-3.1-pro-preview`); tier
+  placement is unchanged. Re-derive the skill to pick these up.
+
+- **`implement-plan` and its sub-skills follow what maestro learned from real
+  runs.** Implementers commit when a gate stays red and report `FAILURE`
+  naming the gate; an uncommitted file does not exist as far as the run is
+  concerned. They run every command in the foreground, never hand-edit a
+  generated file, and list every gate they ran and its result; the conductor
+  reviews only a `SUCCESS` report whose gates are all green. Every spawn of a
+  phase carries the decisions already made in it, and a resumed implementer
+  checks the branch for committed work first. Every merged tree runs the full
+  gate, whatever the `full_test_suite` answer is, and the Quick test scope
+  means scoped tests until the review approves and the full suite once before
+  integration. The merge fixer keeps what a side deleted, stages by name,
+  verifies narrowly, and confirms a resolution by scanning the files for
+  markers, never by asking git; a merge refused by a hook or by git goes to
+  the human. A member moved to its next phase is told first that its objective
+  changed; a continuation that fails is retried cold with the full brief; an
+  outage or an expired login asks `Wait and retry` / `Switch model` / `Stop
+  the run` rather than escalating the tier. Lanes are recycled fully between
+  phases, leftovers saved to a `refs/wip/` ref first. A dispatched phase agent
+  does the work itself: every composed implementer prompt and a guard at the
+  top of each conductor refuse to hand a phase to a sub-agent. The plan PR is
+  the one PR that lands the plan, and every phase and integration PR says so.
+  Re-derive the skills to pick this up; plans and tracking directories written
+  before the change still work.
+
+- **`review-phase` runs the thermo-nuclear review loop.** Each phase is
+  reviewed by `thermo-nuclear-review-loop`, hosted by the conductor because a
+  sub-agent cannot spawn sub-agents of its own: one reviewer one tier above the
+  phase's implementer (a Tier 4 phase is reviewed at Tier 4), each round of
+  findings handed to the phase's own implementer, which verifies, fixes or
+  rejects with counter-evidence and commits the round. A reviewer pass with no
+  verdict is continued once and never counts as approval; a finding re-raised
+  without new evidence is rejected on the spot; after 3 rejecting passes a
+  fresh implementer one tier up takes over; after 20 passes that still return
+  blockers the conductor asks whether to continue, stop the phase unapproved,
+  **Accept as is** (integrated with its open blockers recorded) or amend the
+  plan. After approval the implementer runs `deslop-comments` over the
+  comments the phase added.
+
+- **`amend-plan` cascades along the dependency graph, and amends a live
+  maestro run.** A rewrite touches the amended phase's dependent closure
+  instead of "every phase with a higher number", rebases in topological order,
+  rebuilds `integ-` bases first, refuses to run while a phase is in flight, and
+  gains a `dependency-change` amendment kind. When a maestro run of the plan is
+  running, paused, interrupted or failed, the skill asks whether to amend it,
+  edits the plan and the run's own workflow copy, commits both on the plan
+  branch and applies them with `vinta-ai-maestro amend`; it also carries the
+  operator recipes for a live run (`switch-harness`, `node reassign`, `node
+  interrupt`, `--harness-profile`, `propagate`, `sync-base`).
+
+- **`prepare-worktree`: worktrees get their own copy of the dependency dirs,
+  never a symlink.** A symlinked `node_modules` / `vendor/` / `venv/` sent
+  writes back into the main checkout and made parallel worktrees race on one
+  tree. The skill copies every dependency dir with a copy-on-write clone
+  (`cp -ac` on macOS, `cp -a --reflink=auto` on Linux) and reinstalls
+  virtualenvs and yarn PnP; `skills.prepare-worktree.deps_strategy` now
+  defaults to `copy`. The skill also documents provisioning a pool of lanes for
+  one plan with a `reset_cmd` per forked database, and its summary's `|`
+  alternatives are closed sets read by machine. **Consumers:** re-sync to pick
+  up the new body; worktrees that already exist keep their links until they
+  are re-provisioned.
+
+- **`create-spec` offers a browser surface for its Step 0 interview** when
+  `ai-tools/skills/interview-ui/` exists (see **The browser interview** above).
+  The question bank, clarity loop, read-back and exit conditions are
+  unchanged.
+
+- **`write-unit-test`: time-independent tests and deterministic generated
+  output.** Rule 8 requires a frozen clock and an explicit timezone on any test
+  touching dates, and host-independent schema or client generation. The Django
+  pack and stack notes spell out `freezegun` / `time-machine` with
+  `override_settings(TIME_ZONE=...)` and `tzdata`-sourced timezone choices.
+
+- **Django stack notes** cover database reuse and testmon in lanes, keeping
+  the virtual environment out of a bind-mounted worktree, registries every
+  phase appends to, drf-spectacular `ENUM_NAME_OVERRIDES` for new choice
+  fields, and the CI-mirroring checks a plan's gates should carry
+  (`manage.py check --deploy --fail-level WARNING`, `makemigrations --check`,
+  a regenerate-and-diff gate for a schema or client).
+
+- **The bootstrap and sync skills.** `vinta-bootstrap-ai-tools` asks the new
+  questions listed under **Config schema** above, no longer offers `symlink`
+  for dependency dirs, and no longer asks for a reviewer tier; the **Optional
+  foundation skills** group grows to eight questions (`interview-ui` is 7,
+  `handoff-to-client` moves to 8). `vinta-analyze-codebase` records existing
+  worktree scripts and integration-owned skills. `vinta-sync-ai-tools` carries
+  the asking-the-human migration, offers the PR Review Canvas integration to
+  existing projects as an `opt-in-offer`, and re-renders the plan-execution
+  skills together. Every generated skill now carries
+  `disable-model-invocation: true`.
+
+- **`agent_models.fixer` now sets only the merge-conflict fixer's tier.** The
+  phase's own implementer fixes review findings at its own tier, so a project
   that set `fixer` cheap to save money is saving it on fewer rounds.
 
-- **The workflow schema gained `defaults.max_session_turns`.** Optional, default
-  12. An orchestrator that reuses one agent session across a phase's implement
-  and fix turns needs a ceiling on how long that session may grow before the next
-  turn starts cold; without one a long phase eventually dies on a context-window
-  error that reads as a broken harness. `plan-feature` omits the field — it is a
-  safety limit, not something a plan tunes — and its field table says so.
-
-- **`plan-feature` asks about the project's databases and emits the workflow's
-  `project` block.** The block records what a phase lane must **fork** to be a
-  working checkout — the `dev` and `test` databases, and the project's own
-  migrate command, which runs once per template database rather than once per
-  lane. Without it every lane got a git worktree and nothing else, so two phases
-  running concurrently pointed their test gate at the same rows. Asked at
-  emission time with one `AskUserQuestion` call ("what does a phase lane need its
-  own copy of", "how is that database delivered"); the rest — the migrate
-  command, the database names, the env var names — is read out of the project's
-  settings and task runner rather than asked.
-
-  Two rules the skill is explicit about, because both are easy to get wrong:
-  **sharing is the absence of a declaration** (there is no `share` value, and a
-  lane that reads the main checkout's database has nothing to describe), and
-  **each role names its own database** (a lane's fork is named from `name` and
-  the lane, not the role, so `dev` and `test` sharing one `name` collapse to one
-  forked database). Everything `prepare-worktree` discovers per worktree —
-  `reset_cmd`, compose project names, volume forks, seed commands, env-file
-  strategy — stays out of the block by design.
-
-- **New schema
-  [`postmortem.v1.schema.json`](schemas/postmortem.v1.schema.json)** — the
-  structured plan post-mortem an orchestrator writes at
-  `.vinta-ai-maestro/runs/<run-id>/postmortem.json` once a run has ended: dependencies
-  that were declared but never used, dependencies discovered at gate time,
-  same-wave phases that actually conflicted, and phases whose real duration
-  diverged from their wave placement. `plan-feature` reads it before drawing the
-  next feature's Execution graph, which is what stops a plan from repeating a
-  defect the last run already paid for. Like
-  [`workflow.v1.schema.json`](schemas/workflow.v1.schema.json) it is
-  **generated** from a zod source rather than hand-written — see
-  [`schemas/README.md`](schemas/README.md).
+### Deprecated
 
-### Changed
+- **`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.
 
-- **Phase branches base on their dependencies, not on the previous phase.** A phase
-  with no dependencies cuts from the default branch; one with a single dependency
-  cuts from that phase's branch; one with several cuts from a
-  `plan/{plan-id}/integ-{phase-id}` branch that merges them. Each wave is then merged
-  into a `plan/{plan-id}/wave-{N}` integration branch, which is what a resume anchors
-  on and what the final report points at. The PR `base` follows the same value —
-  a stacked plan produces exactly the stack it did before.
-- **Tracking is a directory, not a file.** `{{PLAN_DIR}}/TRACKING_{plan-id}/` holds
-  `run.md` (conductor-owned), one `phase-{id}.md` per phase (written only by the lane
-  that ran it, committed on that phase's own branch), and `waves/wave-{N}.md`. No two
-  branches write the same path, so wave merges no longer conflict on tracking. A run
-  started under the old single-file layout is migrated on resume.
-- **An implementer is told about its dependencies only.** Prior-phase context passed
-  into a phase prompt is now that phase's transitive dependency closure rather than
-  "everything finished so far" — a sibling lane's work is not in the phase's base
-  branch, and describing it as done made the implementer code against files it could
-  not see.
-- **The stray-write guard covers sibling lanes.** The sandbox denies the whole
-  worktree pool root and allows back only the running lane; the review-phase backstop
-  checks the main checkout and every sibling workroot after each implementer and
-  fixer. A write into a lane that is mid-implementation is worse than a stray
-  main-checkout write.
-- **`amend-plan` cascades along the dependency graph.** A rewrite touches the
-  amended phase's dependent closure instead of "every phase with a higher number",
-  rebases in topological order, rebuilds `integ-` bases before rebasing a
-  multi-dependency phase onto them, and refuses to run while any phase is still in
-  flight. It gained a `dependency-change` amendment kind for edits to a
-  `**Depends on**:` line.
-- **`implement-plan` refuses rather than degrading** when parallel execution is asked
-  for but worktrees are unavailable — several agents cannot share one working tree,
-  and silently falling back to sequential would discard the schedule the user
-  approved.
-- **`modular-commits` supports parallel runs**: lanes commit their atomic units on
-  `plan/{plan-id}/lane-{phase-id}` branches, merged `--no-ff` into the single plan
-  branch at each wave boundary, so the unit commits survive.
+- **`skills.prepare-worktree.deps_strategy: symlink`** stays in the schema
+  enum so existing configs validate, but is deprecated and read as `copy`.
+  Change it to `copy` (or `reinstall`) in `.vinta-ai-workflows.yaml` to stop
+  the interview default from being re-emitted.
+
+### 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 thermo-nuclear review loop replaces them. The
+  implementer's own install-time license check and co-author rules are
+  unchanged.
+
+- **Reviewers on the plan.** `plan-feature`'s Crew table has no `Role` column
+  and no reviewer rows, and phases have no `**Review models**:` line.
+  **Migration:** plans written with them still run; `implement-plan` ignores
+  them.
 
 ### Fixed
 
-- **`serve --host 0.0.0.0` prints a URL another machine can open.** Binding
-  every interface made the server report the wildcard back, so the line printed
-  for the operator to open — and share — was `http://0.0.0.0:<port>`, which
-  resolves for nobody. The bind is unchanged; the printed host is now this
-  machine's LAN address. The daemon still warns, because the token in that URL
-  is the only thing between the run and anyone who can reach the port.
-
-- **An agent can run a shell command.** `auto` mapped to the vendor's
-  `acceptEdits`, which accepts file *edits* and nothing else — a shell command
-  still goes to a permission prompt, and in `-p` there is nobody to answer one.
-  A run of eight phases died of it: the agents wrote their code and were then
-  refused `ruff`, `pytest`, `git add` and `docker compose`, **69 denials across
-  two lanes**, every gate failing on work that was never allowed to be checked.
-  `auto` now allows `Bash` in the policy file it already writes.
-
-  What that costs is worth stating plainly: **`Bash` was never confined to the
-  lane.** The deny list covers the file-editing tools and a shell redirection
-  walks through it, so allowing the shell allows commands on the machine.
-  `auto` has always promised exactly this in words — "the agent works unattended
-  inside its lane" — and this is the first version where the words are true.
-  `ask` still does not allow it: that mode exists for a human at the browser,
-  and the prompt is its purpose.
-
-- **A refusal says why, in the words the harness used.** `permission_denied`
-  carried a decision token and deliberately dropped the sentence beside it, on
-  §11 grounds. Then a run failed with forty-five denials reading
-  `reason: "other"`, and finding out what that meant cost an afternoon and a
-  rebuilt reproduction — the sentence said "this Bash command contains multiple
-  operations; the following parts require approval". §11 keeps repository
-  *contents* out of the record; a refusal's own explanation is not contents, and
-  the `tool_use` row above it already carries the path and the command verbatim.
-  Withholding it protected nothing and hid the one fact worth having.
-
-- **`serve` opens a run that has already finished.** The API resolved a run from
-  the in-memory registry *and* the journal and required both, so a daemon
-  started with nothing running listed the operator's history — the list reads
-  the journal — and then answered 404 for every run in it, under a message
-  saying the daemon was not running. Reads now need only the journal, which is
-  where a run's whole record lives and which outlives the daemon by design
-  (§5.3). Steering a finished run is still refused, with `409` rather than
-  `404`: the run exists, and saying it does not sends the operator hunting for a
-  typo instead of reading the status in front of them.
-
-- **Four places the UI asked the operator to work around it.** The transcript
-  opened at the *oldest* row it held, so a live agent's newest line — the one
-  the panel was opened to read — sat below the fold and every arriving entry
-  pushed it further down; it now opens at the newest and stays there, but only
-  while the operator is already at the bottom, because scrolling up is reading.
-  The `git diff` command overflowed its panel, uncopyable without selecting
-  blind, and now wraps. The shell's bounded column went from 1280px to 1600px:
-  1280 is a reading measure, and the Nodes table's columns are ids, lane names
-  and branch names, none of which can be abbreviated without losing what
-  identifies them. And the notification interval said "Remind every 5 min"
-  without ever saying what it would remind anyone about — it repeats the
-  notification for a phase that stopped to ask the operator something, until
-  they answer, which is what the options say now.
-
-- **A killed terminal releases its directory on Windows.** Two PTY tests failed
-  teardown with `EBUSY: rmdir`: killing a process there is not synchronous with
-  releasing what it held, so the conpty and its background child are gone as far
-  as the test is concerned while the OS still has the working directory open.
-
-- **A failed phase can be retried instead of ending the run.** `run` takes
-  `--on-failure <stop|ask>`. `stop` is the default and is what every run has
-  always done — the phase fails, its dependents block, the run finishes. `ask`
-  parks the node on a question instead: retry, retry with another member of the
-  crew, or stop.
-
-  It exists because the failures worth retrying are overwhelmingly
-  environmental — a permission wall, a grant nobody made, a gate whose service
-  was not up — and the only recovery was to start the whole plan again, running
-  every phase that had already succeeded a second time. Only pass `ask` when
-  somebody is watching: the run waits, which is exactly why it is not the
-  default.
-
-  The alternatives offered are **members of the crew, not models**. A staffed
-  run has no free-floating models in it — a phase is taken by a member, and the
-  tier floor that decides who may take it is the assigned member's own — so a
-  model is something the plan cannot express and nobody could be found to hold.
-  A member below the phase's tier is never offered: an operator answering a
-  question is not a reason to hand a phase to somebody the plan judged too
-  junior for it.
-
-  The retry starts **cold**, and everything the node held goes back before it
-  waits (§6.1) — an operator at lunch must not be holding a lane another phase
-  could use.
-
-- **A refusal nobody was asked about is now said out loud.** The adapter knew
-  about `permission_request`, a question waiting for an answer, and nothing
-  else. The refusal an operator actually hits is not a question: a read outside
-  the working directory is decided by the CLI and announced as
-  `permission_denied`, with no request to reply to. That frame was dropped at
-  the first `switch` — no event, no journal row, no transcript line. The new
-  `permission_denied` event carries the decision token (`workingDir`, `mode`)
-  and never the vendor's prose, which names the file being read (§11).
-
-- **A turn that ended blocked is no longer a turn that succeeded.** The CLI
-  says `status_category: "blocked"` one frame before reporting
-  `is_error: false`, and both are true from its side: it was asked for
-  something it could not do and said so. Taking the second at its word is how a
-  phase passed having written no code and then failed two steps later under
-  another name. A session that reported an error no longer ends `ok` — which
-  also makes a reviewer fail closed, since its verdict is read back out of a
-  transcript whose session did not end cleanly.
-
-- **An agent still could not write in its own lane.** The entry below passed
-  claude-code `--permission-mode auto`, which matched our own vocabulary for
-  "works unattended" and is not what the vendor means by the word: `auto` still
-  routes a write to a permission prompt, and in `-p` there is nobody to answer
-  one. Run against the CLI, a `Write` to the agent's *own working directory*
-  comes back denied with no reason attached — the same dead end, wearing the
-  word that made it look closed. `acceptEdits` is the mode under which that
-  write succeeds, and is what `auto` now maps to. The test covering this
-  asserted the word rather than the behaviour, so it pinned the bug in place.
-
-- **A phase can read the operator's checkout.** A lane is a worktree cut from a
-  branch, so anything uncommitted — a plan written this morning, a spec that
-  never leaves the operator's machine — is present where they are and absent
-  from every lane. Reaching for it was refused before the model saw a byte, with
-  a message that reads like a prompt awaiting an answer ("Claude requested
-  permissions to read from …, but you haven't granted it yet") when in fact
-  nothing is asking: the CLI denies it outright, emits no permission request,
-  and the session then ends *successfully*, having written nothing.
-
-  The repository root is now granted to every claude-code agent for **reading**.
-  Granting a directory also grants writing in it, and the lane sits inside the
-  directory being granted, so the grant is paired with a deny list that keeps
-  the lane the only writable place under it — the operator's source and every
-  sibling lane stay refused. That list names the *siblings* at each level down
-  to the lane rather than the root itself, because the vendor resolves deny
-  before allow with no carve-out: `deny: <repo>/**` plus `allow: <lane>/**`
-  refuses the lane too. Each of those facts was established by running the CLI.
-
-  **This covers the file-editing tools and not `Bash`.** A shell redirection was
-  never confined to the working directory and is not confined now; that boundary
-  is the OS's, and the vendor's sandbox that enforces it also switches off the
-  network a phase needs to install anything.
-
-  codex needed nothing: under `--approve-for-me` it already reads anywhere on
-  disk, which was confirmed the same way.
-
-- **An agent can write in its own lane.** Every adapter declared
-  `permissionControl: true` and passed no policy at all: claude-code was spawned
-  as `-p --output-format stream-json …` with no `--permission-mode`, and codex as
-  `exec --json` with no sandbox and no approval flag, under a comment saying it
-  took both on the command line. So a headless run asked before its first write,
-  emitted a `permission_request`, rendered it in the transcript — and nothing
-  anywhere answered. The phase failed reporting a permission system it could not
-  see, having written nothing.
-
-  `run` and `serve` now take `--permission <ask|auto|full>`, defaulting to
-  `auto`. **The operator sets it, never the workflow document**: the document is
-  committed and shared, and a file in a repository should not be able to tell
-  someone else's machine to run agents without approvals.
-
-  Both CLIs refuse combinations that looked reasonable, and both were found by
-  running them rather than reading them: codex rejects `--sandbox` alongside
-  `--approve-for-me`, and `codex exec resume` accepts neither — passing the
-  fresh-spawn policy there turned a `stale_session` refusal, which the scheduler
-  retries cold, into a `fatal` one that fails the node.
-
-  This reverses a documented decision. The README said the daemon passed no
-  permission flags and that a committed `.claude/settings.json` was what made a
-  run able to write; that is now the narrowing layer on top of a mode, not the
-  only thing standing between an agent and a blocked lane.
-- **`purge --lanes --branches` clears what a failed run leaves behind.** A run's
-  lane worktrees are not under `runs/`, so no purge ever reached them: three
-  failed attempts at one plan left twelve worktrees, twelve summaries, and a set
-  of `plan/<id>/phase-*` branches still checked out — which is what makes the
-  *next* run of that plan impossible, since git refuses to check out a branch a
-  second worktree holds.
-
-  One rule decides both: **never delete the only copy of work.** A phase can
-  leave work committed on its branch or uncommitted in its worktree, and both
-  count — so a branch carrying commits no other branch has is kept, a lane with
-  a dirty tree is kept, and each is listed with the command to remove it by
-  hand. Untracked files count as work: a phase that wrote three new modules and
-  never committed them is exactly the case worth protecting.
-
-  Emptiness is measured as "carries no commit another branch does not already
-  have", not as "merged into HEAD". The latter is relative to wherever the
-  operator is standing, so on a feature branch — the checkout this is most often
-  run from — every empty phase branch looked unmerged and nothing was ever
-  cleaned up.
-
-  `--dry-run` and `--yes` work as they already did, and a worktree that will not
-  go is named rather than counted.
-
-- **`doctor` now catches, before a lane exists, the failures that used to take a
-  run each.** Four consecutive runs of one plan failed four different ways, and
-  every one of them was knowable at minute zero from the workflow and the repo.
-  - **Every `prompt_ref` and `plan_context_ref` is resolved against
-    `base_branch`**, with `git cat-file -e`, which reads the branch's tree and
-    so cannot be satisfied by a working-tree copy — the working tree being
-    exactly what a lane will not have. It distinguishes the three cases, because
-    they have three different fixes: never committed, **staged but never
-    committed** (`git add` alone does not put a file in a branch), and committed
-    on a different branch. The last offers both routes out — merge it, or point
-    `base_branch` at the branch that has it — since only the operator knows
-    which they want.
-  - **Phase branches held by another worktree** are reported with the directory
-    to remove. Lane directories are named per run and phase branches per
-    workflow, so a failed run leaves worktrees holding the branch names the next
-    run will try to cut, and git refuses to check out a branch twice. Nothing
-    cleans those up: `purge` deletes run state under `.vinta-ai-maestro/runs/`,
-    and lane worktrees are not there. `doctor` does not delete them either — a
-    failed lane's worktree is the only place its state survives — but it now
-    names each one and the exact command.
-
-- **A failed node records why.** `node_status` carried `{"status":"failed"}` and
-  nothing else, so two runs failing for two unrelated reasons produced identical
-  journal rows and the cause survived only in the operator's terminal. The
-  reason is now persisted — **sanitized**, not raw: errors the package builds
-  itself are identifiers by construction and are kept verbatim, and anything
-  else is reduced to its kind, the rule `recycleStage` already followed. The
-  journal is durable and API-served, and an exception message from a dependency
-  is exactly how repository content gets into one. Blocked dependents record
-  which node blocked them.
-
-- **Two diagnostics that named the symptom and hid the cause.** Both came out of
-  one real run, and neither was a wrong answer — just an unusable one.
-  - **A phase whose plan is not committed** failed with `prompt_ref "…" names no
-    readable file`, against a path that was spelled correctly. A lane is a fresh
-    worktree of the base branch, so a plan sitting untracked in the operator's
-    checkout is in the one place the run cannot look. The message now names the
-    directory it resolved against and says why a plan is often not in it.
-  - **A lane summary the daemon could not accept** reported `summary unreadable`
-    and advised deleting the lane — which takes its forked databases with it,
-    over what turned out to be two wrong fields. `doctor` now names the fields
-    and what was expected, and offers repair before deletion. A file that does
-    not parse at all still reports as unreadable, because there is no field to
-    name. Neither message carries the offending *value*: a summary holds
-    database names and connection variables, and the value that failed
-    validation is the likeliest thing in it to be one.
-
-  `prepare-worktree` gained the rule that would have prevented the summary in
-  the first place — its `|` alternatives are closed sets read by machine, `null`
-  is how you say "none", and a strategy outside the set should be the closest
-  one plus a `note:` rather than a fourth word.
-
-- **`npx vinta-ai-maestro` now runs.** The published package pointed its `bin` at
-  `src/cli/bin.ts` and relied on Node stripping the types at startup — which Node
-  refuses to do anywhere under `node_modules`, unconditionally and with no flag to
-  override. So the CLI worked from a checkout and died on first run once installed,
-  with `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`.
-
-  `packages/vinta-ai-maestro` now builds: `tsc` emits `dist/` with
-  `rewriteRelativeImportExtensions` (the source imports `.ts` specifiers, which
-  emitted JS cannot keep), vite writes the daemon's UI into `dist/ui`, and the
-  shebang is rewritten from the source's `--experimental-transform-types` form to
-  a plain `#!/usr/bin/env node` — a compiled entry point has no types left to
-  transform, and should not ask Node for a flag it is free to retire. `prepack`
-  runs the build, so a tarball can never be cut from a stale `dist/`.
-
-  Three packaging faults surfaced with it, each of which broke an install on its
-  own:
-  - **The UI was never in the tarball.** `serve` resolves its static root as
-    `dist/ui` and refuses to read outside it, so it would have booted and answered
-    every page with "build the UI first". The build now asserts `dist/ui/index.html`
-    exists rather than trusting a vite config that writes outside its own root.
-  - **`tailwindcss` and `tw-animate-css` were imported but never declared.** They
-    resolved only through pnpm's `.bin` shim setting `NODE_PATH`; building by any
-    other path failed to resolve them. Both are now devDependencies.
-  - **Everything the UI imports was a runtime dependency.** React, xterm,
-    lucide-react and the three workspace packages are bundled into `dist/ui` by
-    vite and cannot be loaded at runtime — yet a consumer installed all of them,
-    and two carried `workspace:*` specifiers that no registry understands. Moved to
-    devDependencies; the published package now declares six runtime dependencies
-    instead of fourteen.
-
-  CI packs the tarball, installs it into a throwaway project and runs the binary
-  from `node_modules`. Every previous check ran from a checkout, which is the one
-  place this class of bug cannot appear.
-
-- **Lane provisioning serializes `git worktree add`, not only the database
-  template.** `prepare-worktree` previously named one serialization point; there
-  are two. Git rewrites `.git/worktrees/` metadata on every add, and concurrent
-  adds against one repository clobber each other's entries — a reproducible
-  corruption, not a theoretical race. Worktrees are added one at a time; the
-  expensive per-lane work (dependency linking, database cloning, summary
-  writing) still overlaps around it.
-
-- **The conflict-fixer round budget is an integration-level setting, not a
-  phase's `max_fix_rounds`.** `parallel-lanes.md` now says so, and defaults it to
-  two. A merge conflict belongs to a *pair* of phases, so deriving the budget
-  from one of them made the answer depend on which phase happened to merge
-  second.
-
-- **A resolved merge conflict is confirmed by scanning the files, never by asking
-  git.** `git add` clears a path's unmerged flag whether or not `<<<<<<<` is
-  still sitting in it, so git's index cannot answer "did the fixer actually fix
-  it". `parallel-lanes.md` now requires scanning the conflicted paths for
-  conflict markers before the merge is committed. Without it, a fixer that did
-  nothing produces a merge commit full of markers that passes into the wave
-  branch unnoticed.
-
-> 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
-> run with `npx vinta-ai-maestro`. It is not part of the `vinta-ai-workflows`
-> tarball — the root `files` whitelist excludes `packages/`, so nothing in it is
-> installed by `npx vinta-ai-workflows install`. What ships from that work into
-> the skills package is the two generated schemas above and the skill changes
-> that produce and consume them.
->
-> Its browser UI is now built on `packages/design-system/` (`vinta-design-system`),
-> a second workspace package: oklch tokens in three layers mirroring
-> `vinta-schedule-design-system`, six run-status **tones** (`idle`, `active`,
-> `wait`, `attention`, `ok`, `error` — waiting is amber and failure is red, never
-> the same hue), shadcn/ui components on Tailwind CSS v4, a small layout kit, and
-> a light/dark/system theme. The run graph and the pipeline editor are re-skinned
-> through their own custom properties, so the canvas and the badges beside it
-> share one palette. It and `vinta-dag-editor` publish on their own cadence
-> (`0.1.0`) as dependencies of `vinta-ai-maestro`; nothing in either reaches
-> `npx vinta-ai-workflows install`.
+- **`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: a GNU-only `sed` idiom that BSD `sed`
+  rejected, so trailing blank lines were never trimmed; a lowercase
+  `side: right` that GitHub answered with "422 Validation Failed", now
+  upper-cased; `gh api` and `glab api` stderr thrown away, so a failed comment
+  gave no reason; and a multi-line `awk -v` that BSD `awk` rejected when
+  adding to a `## Publish log` section. Projects that patched their own copy
+  can re-sync with `vinta-sync-ai-tools`.
+
+- **`check-ai-models` no longer mistakes sibling models for snapshots of a
+  cited id.** The matcher used substrings, so `claude-sonnet-5` matched
+  `claude-sonnet-5-5` and hid the newer release, and `gemini-3-pro` matched
+  `gemini-3-pro-image` so a retired model still looked available. It accepts
+  only exact ids, dated or `-vN` snapshot suffixes, and provider prefixes.
+
+- **`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. The report prints the sequence
+  `prepare-worktree` documents: `docker compose -p <project> down`, then
+  `docker volume rm` for each forked volume, then removal of the generated
+  compose override.
+
+- **`prepare-worktree` serialises `git worktree add`, not only the database
+  template.** Git rewrites `.git/worktrees/` metadata on every add, and
+  concurrent adds against one repository clobber each other's entries.
+  Worktrees are added one at a time; the per-lane work around them still
+  overlaps.
 
 ## [0.6.1] — 2026-08-17
 
@@ -996,7 +850,6 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   **Consumers**: re-sync to pick up the opt-in questions. E2E-disabled projects
   are unaffected (the e2e regions strip out as before).
 
-
 <!-- pre-release: 0.2.0-alpha6 on 2026-07-13 -->
 
 ### Changed
@@ -1033,7 +886,6 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
-
 - **`handoff` foundation skill — session-continuation handoff docs between
   agents.** Write mode captures the current task (goal, verified-vs-unverified
   state, decisions + rejected alternatives, landmines, single concrete next