vinta-ai-workflows 0.7.0-alpha1 → 0.7.0-alpha11

package/CHANGELOG.md

@@ -7,10 +7,115 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [0.7.0] — YYYY-MM-DD
 
+<!-- pre-release: 0.7.0-alpha11 on 2026-09-15 -->
+<!-- pre-release: 0.7.0-alpha10 on 2026-09-15 -->
+<!-- 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 -->
 
 ### 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
@@ -216,6 +321,423 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **`vinta-ai-maestro with` waits for the lock instead of giving up on it.** Its
+  usage said it blocked until the resource was granted, and it did — for about
+  five minutes, which is where Node's own `fetch` stops waiting for a response.
+  A test suite behind a capacity-1 semaphore beats that regularly. What the
+  agent saw was "could not reach the lease daemon", and what agents did with
+  that, repeatedly, was run the command without a lease: exactly the stampede
+  the pool exists to prevent, arrived at by an agent behaving reasonably.
+
+  The wait is the client's now. The daemon answers `202 still queued` within
+  seconds and **leaves its own queue behind it**, so nothing is granted to a
+  request that has gone away; the client loops until it is granted, saying so
+  once and then occasionally, so a transcript shows a wait rather than a
+  silence. Only answers that waiting cannot change — a resource this run does
+  not declare, a run that is no longer live — end it.
+
+  And when it does end that way, the refusal says what not to do about it.
+  "The resource lease was not granted" is an error with no alternative in it;
+  the rule against working around it now travels with the message rather than
+  sitting only in a prompt the agent read twenty minutes earlier. The prompt
+  says it too, including that waiting is the expected outcome and not a failure.
+
+- **A retry gets a fresh fix budget.** `fix_rounds` was set to 0 when a node was
+  created and never again, so a phase that spent its whole budget on attempt 1
+  began attempt 2 already exhausted — one review, one fix, and the exhaustion
+  transition fired straight back. Seen with `max_fix_rounds: 4`: the retry got a
+  single round before the operator was asked again, forty seconds of work
+  standing in for four rounds of it. A retry that inherits the reason the last
+  attempt ran out is not a retry. It resets wherever a node is re-driven from
+  its pipeline's initial state — a capacity refusal, an automatic retry, the
+  operator's answer, the `retry` verb — which is one place rather than four.
+
+- **The last fix is reviewed rather than failed unread.** `standard-phase`
+  checked the budget on the way *out* of `fix`, so the final fixer's work went
+  straight to `failed` with nothing looking at it. Two phases in one run ended
+  on a fixer reporting "all gates green, committed, tree clean" and were failed
+  anyway. The check now sits in front of the fixer, on both doors into it: every
+  fixer that runs is reviewed, and the review after the last one can still pass
+  the phase. Guarding only the review side left a red gate under a passing
+  reviewer looping forever, which is the other half of the same change.
+
+  `max_fix_rounds` still means the number of fixers a phase may spend. `0` now
+  means none, where before it let one run and failed the phase regardless.
+
+- **Agents are told not to background their work.** An implementer started five
+  commands with `run_in_background: true` and closed its turn with "I'll wait for
+  the test result notification before continuing to the outer gate". There is no
+  notification: a headless session ends when the turn ends and whatever it
+  backgrounded is killed with it. Three sessions ended with no report and no
+  commit, and the reviewer failed each for uncommitted work — true, and not the
+  cause. Nothing had said so, and believing a tool that offers backgrounding will
+  still be there afterwards is not unreasonable.
+
+- **The reviewer runs the gates instead of taking their word for it.** The prompt
+  asked it to confirm the outer gate was green, which an agent can do by reading
+  the implementer's report — one reused reviewer session reached a verdict in
+  under four minutes without running the project's tests at all. It is now asked
+  to run them, to say what they returned, and to treat being unable to run them
+  as a finding. Re-review rounds are asked again, because a session that
+  remembers running them last round is remembering a different tree.
+
+- **A retried phase keeps the commits the attempt before it made.** A failed
+  phase re-enters its pipeline at the initial state, which runs `git_branch`
+  again — and `checkout -B` moves an existing branch unconditionally, so attempt
+  2 began by resetting attempt 1's work to base. The files left the worktree,
+  the next reviewer correctly reported "phase not implemented at all", and the
+  fix budget burned re-implementing from nothing until the operator was asked. A
+  phase that produced real commits was guaranteed to lose them.
+
+  "Cold" was always meant to describe the agent's *session*, not its branch —
+  and the default policy targets environmental failures, which is exactly when
+  the previous attempt's code is worth keeping. A resumed branch is checked out,
+  never rebased onto a base that moved: a conflict there would fail the retry
+  during its setup, before the agent that might resolve it has run. A branch
+  that committed nothing is still moved up. Whether this is a second attempt is
+  read from the journal rather than from the ref, because a phase branch's name
+  carries the plan id and not the run id — an identically named branch left by
+  an earlier run must still be cut fresh. `node_assigned` now records
+  `previous_head`, so a reset that does happen is visible in the run rather than
+  only in a reflog.
+
+- **A phase is judged on commits, and the prompts finally say so.** An
+  implementer ran four sessions, reported `SUCCESS` with a green inner loop, and
+  never ran `git commit`: its deliverables were untracked files. The reviewer
+  reads the committed diff, so it saw an empty one and reported "not implemented
+  at all"; the fixer re-implemented, also without committing; the rounds ran out
+  and the lane was recycled over the files. Every instruction that agent had was
+  *about* committing — "never commit while a gate is red" — and none of them
+  said it had to.
+
+  Implementers and fixers, cold and continued, are now told that the phase is
+  reviewed and merged from commits on its branch, that an uncommitted file does
+  not exist as far as the run is concerned, and that the turn is not over until
+  `git status --porcelain` is empty of their work — staged by explicit path,
+  never `git add -A`, because a lane holds local files that are not theirs to
+  commit. The reviewer reads the working tree as well as the diff: a full tree
+  with an empty diff is a real failure and is *not* "not implemented", and the
+  difference decides whether the fixer writes the code again or simply commits
+  it.
+
+- **A recycled lane no longer deletes work nobody committed.** Both recycle
+  paths throw the working tree away. The tree is now committed first — with
+  plumbing, and **off the branch**, under `refs/vinta-ai-maestro/wip/`. On the
+  branch was the first implementation, and it was wrong: a lane's dirty tree
+  holds gate artifacts as often as deliverables, and a phase branch is the base
+  of its dependents, so one gate's scratch file reached the next phase and
+  failed a gate for a reason nothing in that phase caused. Nothing merges,
+  nothing reaches a dependent, and one `git restore --source <ref>` gets a file
+  back. Where the rescue itself fails, the recycle refuses and names the paths.
+
+  The retry question says how much is at stake: commits are kept, and *N*
+  uncommitted files in the lane will be set aside.
+
+- **`project.hooks: skip`.** Committing is not optional any more, and a
+  `language: system` pre-commit chain reads a never-committed-in worktree as a
+  fresh machine — one project's hooks built a 510 MB virtualenv before allowing
+  a first commit, per lane, after four attempts and a two-minute timeout. Set
+  per worktree, so the operator's own checkout keeps its hooks, and opt-in,
+  because hooks are usually there for a reason.
+
+- **`doctor` knows when a project needs docker compose.** It assembled its
+  options without a `project`, so `needsCompose` was handed `undefined` on every
+  invocation and reported "not required by this project" for a
+  compose-delivered database — and `run`'s own preflight did the same. A check
+  nothing can reach is worse than an absent one: it reads as a pass.
+
+- **A failing `setup_cmd` says why.** It carried a lane name and nothing else,
+  so the operator saw "could not provision the lane pool under …" and had to
+  replay the command by hand with the lane environment rebuilt to find a missing
+  settings module. It carries the exit code and a bounded stderr tail now — the
+  same class of thing as a harness refusal's own explanation, which this package
+  already decided to carry after an afternoon lost to the same silence.
+
+- **A lane the executor was not given is refused, not guessed.** It fell back to
+  the right directory with an *empty environment* — a gate running against the
+  wrong compose project and no forked connection string, with nothing anywhere
+  saying a lane was missing.
+
+- **The monitor reads, and does not run.** Its shell has no lane environment, so
+  the project's own commands run from it contend with the lanes instead of
+  observing them. One reported "the final gate fails on a port conflict" when no
+  gate had run at all, and the operator believed it. Gate results come from the
+  journal and the gate logs.
+
+- **`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
@@ -238,22 +760,25 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   nothing produces a merge commit full of markers that passes into the wave
   branch unnoticed.
 
-> The repository also gained `packages/vinta-ai-maestro/`, a **private workspace
-> package** that executes these workflows. It is not published and is not part of
-> the `vinta-ai-workflows` package — the root `files` whitelist excludes
-> `packages/`, so nothing in it is installed by `npx vinta-ai-workflows install`.
-> What ships from that work is the two generated schemas above and the skill
-> changes that produce and consume them.
+> 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 private workspace package: oklch tokens in three layers mirroring
+> 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. Equally unpublished: nothing in it reaches `npx
-> vinta-ai-workflows install`.
+> 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`.
 
 ## [0.6.1] — 2026-08-17
 

package/package.json

@@ -1,16 +1,11 @@
 {
   "name": "vinta-ai-workflows",
-  "version": "0.7.0-alpha1",
+  "version": "0.7.0-alpha11",
   "description": "Bootstrap AI tooling (AGENTS.md, skills, sub-agents) across Claude Code, Codex, Cursor, and VS Code + GitHub Copilot.",
   "type": "module",
-  "packageManager": "pnpm@10.33.0",
   "bin": {
     "vinta-ai-workflows": "./vinta-ai-workflows.mjs"
   },
-  "scripts": {
-    "check-ai-models": "node scripts/check-ai-models.mjs",
-    "test": "node --test tests/*.test.mjs"
-  },
   "devDependencies": {
     "yaml": "^2.4.0"
   },
@@ -26,10 +21,14 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git"
+    "url": "git+https://github.com/vintasoftware/vinta-ai-workflows.git"
   },
   "publishConfig": {
     "access": "public"
   },
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "check-ai-models": "node scripts/check-ai-models.mjs",
+    "test": "node --test tests/*.test.mjs"
+  }
+}

package/schemas/workflow.v1.schema.json

@@ -191,6 +191,150 @@
             }
           },
           "additionalProperties": false
+        },
+        "env_files": {
+          "default": [],
+          "description": "Repo-relative ignored files every lane needs its own COPY of — `.env`, `.env.docker`, `.envrc`. Copied, never symlinked: lane provisioning appends to them (a connection string, a compose override path), and a symlink would write those lane-specific lines back into the main checkout. A declared file that is missing fails provisioning rather than producing a lane whose stack cannot boot.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "commands": {
+          "default": {},
+          "type": "object",
+          "properties": {
+            "lint": {
+              "type": "string",
+              "minLength": 1
+            },
+            "typecheck": {
+              "type": "string",
+              "minLength": 1
+            },
+            "test": {
+              "description": "The whole suite.",
+              "type": "string",
+              "minLength": 1
+            },
+            "test_one": {
+              "description": "A single test or a subtree. The agent appends the target, so end it accordingly.",
+              "type": "string",
+              "minLength": 1
+            },
+            "migrate": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "additionalProperties": false,
+          "description": "The project’s own command lines, handed to every agent verbatim. A fixed vocabulary rather than free-form, because the prompt has to be able to say which one step 3 of the working instructions means. Declaring these is how an agent stops guessing: a project whose suite only runs inside a container, or only against a lane-specific database, has no way of telling one otherwise, and `pytest` is a plausible guess that is wrong in exactly that project."
+        },
+        "hooks": {
+          "default": "run",
+          "description": "Whether the repository’s git hooks run on commits made inside a lane. `run` is the default and is what a developer’s own checkout does. `skip` points the lane at an empty `core.hooksPath`, for the case this exists for: a `language: system` pre-commit chain that, in a worktree that has never been committed in, builds a virtualenv per lane before it will let a commit through — observed as four failed commit attempts, one of them a two-minute timeout, and a 510 MB `.venv` per lane. The gates still run; this only stops each lane paying a whole-environment install to make a commit.",
+          "type": "string",
+          "enum": [
+            "run",
+            "skip"
+          ]
+        },
+        "services": {
+          "default": {},
+          "description": "Shared servers each lane gets its own namespace inside, by id. One postgres, one redis, one rabbit on the machine, with a database / db index / vhost per lane — which is the difference between six lanes being viable on a laptop and not. The alternative a project falls into without this is booting a server per lane, or sharing one with no isolation at all.",
+          "type": "object",
+          "propertyNames": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "namespace": {
+                "type": "string",
+                "enum": [
+                  "index",
+                  "name"
+                ],
+                "description": "How this lane’s namespace inside the shared server is derived. `index` is a small integer, for a server with a fixed number of slots — redis’s sixteen databases are the case it exists for. `name` is a token derived from the lane, for a server that names things freely: a vhost, a bucket prefix, a schema."
+              },
+              "url": {
+                "description": "The shared server, without the per-lane segment — `redis://localhost:6379`. Omit it where the namespace *is* the value: an object-storage prefix has no URL to hang off, and the variable then carries the bare token.",
+                "type": "string",
+                "minLength": 1
+              },
+              "url_var": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Env var the lane reads this service’s address from."
+              },
+              "capacity": {
+                "default": 16,
+                "description": "How many distinct namespaces the server has. Only meaningful for `index`, where a pool larger than this is refused before anything is created — two lanes on one redis database is the bug this exists to prevent, and reaching it by arithmetic is no better than reaching it by neglect.",
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 9007199254740991
+              },
+              "create_cmd": {
+                "description": "Run once per lane, in the lane. `{namespace}`, `{url}` and `{lane}` are substituted. Declaring a vhost is a `rabbitmqadmin` invocation this package has no business knowing; a project that needs none declares none.",
+                "type": "string",
+                "minLength": 1
+              },
+              "reset_cmd": {
+                "description": "Empties this lane’s namespace when the lane is handed to the next phase. Same substitutions. A service without one keeps whatever the last phase left in it, which for a cache is usually right and for a queue usually is not — declaring this is how a project says which of those it has.",
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "required": [
+              "namespace",
+              "url_var"
+            ],
+            "additionalProperties": false,
+            "description": "A shared server each lane gets its own namespace inside."
+          }
+        },
+        "compose": {
+          "default": {
+            "enabled": true,
+            "publish": [],
+            "shared_volumes": []
+          },
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "default": true,
+              "description": "Whether lane provisioning generates a compose override. On by default, and it does nothing at all in a project with no compose file. Where there is one and docker cannot answer, provisioning fails rather than quietly producing lanes that share a data volume — set this to false to say that is genuinely what you want.",
+              "type": "boolean"
+            },
+            "publish": {
+              "default": [],
+              "description": "Services that must keep a reachable host port, republished on one this lane was granted instead of the one the project pinned. Empty is the default and is usually right outright: where the project’s own test command runs inside compose, services reach each other by container DNS on the lane’s own network and a published port buys nothing but a collision. The granted port reaches the lane as `LANE_PORT_<SERVICE>_<CONTAINER_PORT>`.",
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "shared_volumes": {
+              "default": [],
+              "description": "Volume keys that leak past the project name and are to be left leaking. The escape hatch for the one decision this cannot make for you: re-pinning a shared dependency volume is correct, and it costs every lane the install that sharing it was avoiding. A read-only cache with no dependency churn in the plan is safe here. A data volume never is — that is two servers on one data directory, which is the bug this exists to prevent.",
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "additionalProperties": false,
+          "description": "How a lane’s compose stack is isolated past `COMPOSE_PROJECT_NAME`."
+        },
+        "setup_cmd": {
+          "description": "The project’s own lane-setup command, run inside each freshly provisioned lane with that lane’s environment applied. The escape hatch for whatever a project needs that no field here describes. It MUST be idempotent: it runs again every time the lane is recycled for another phase.",
+          "type": "string",
+          "minLength": 1
         }
       },
       "required": [
@@ -455,6 +599,7 @@
           },
           "max_fix_rounds": {
             "default": 2,
+            "description": "Rounds the fixer gets to clear a review’s findings before the phase fails. Two is a budget, not a target, and it is measured in *rounds* rather than findings — a first review raising four legitimate blockers can exhaust it while every round is making progress. Raise it on a phase you expect to be argued over; it is the knob that decides how much a phase gets to be wrong before it is handed to `--on-failure`.",
             "type": "integer",
             "minimum": 0,
             "maximum": 9007199254740991

package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md

@@ -355,7 +355,7 @@ state:
     files: [.env, .envrc, ...]
   dev_db:
     engine: postgres | mysql | sqlite | mongo | redis
-    strategy: fork | share | stub
+    strategy: fork | share | stub     # closed set — see "The summary is read by machine"
     forked_name: <forked db name>   # null when share / stub
     connection_url_var: DATABASE_URL
     reset_cmd: <shell command that returns this DB to the state of a fresh checkout>
@@ -365,7 +365,7 @@ state:
     # instead of reusing this worktree across a migration boundary.
   test_db:
     engine: ...
-    strategy: fork | share
+    strategy: fork | share            # closed set, as above
     forked_name: ...
     connection_url_var: TEST_DATABASE_URL
     reset_cmd: <same idea, for the test DB>   # null when not resettable
@@ -467,6 +467,14 @@ Every step gated on user confirmation when the worktree has un-pushed branches.
 
 - **Symlink for reads, copy for writes, fork for state.** This is the only mental model that scales. Default to fork when unsure — disk is cheap, corrupted main-checkout DBs are not.
 - **Never share a writable DB across worktrees by default.** The race conditions are subtle and the failure mode is silent data corruption.
+### The summary is read by machine
+
+This file is not a note to the next human. [vinta-ai-maestro](https://github.com/vintasoftware/vinta-ai-workflows/tree/main/packages/vinta-ai-maestro) parses it to decide whether a lane can be handed to another phase, so **every `|` above is a closed set and every key is required** — `null` is how you say "none", and omitting the key is not the same thing.
+
+A value outside the set makes the lane unusable by the daemon. It does not fail loudly at write time; it fails later, as `doctor` reporting the lane and the field it could not accept, long after the worktree and its forked databases exist. Seen in the wild: a `strategy: create-empty-and-migrate` invented to describe a database that had been created empty and migrated by hand, with `reset_cmd` left off entirely. Neither is in the spec, and the pair cost eleven lanes their readability.
+
+If none of the listed strategies describes what you did, **the honest record is the closest one plus a `note:`** — the schema keeps `note` free-form for exactly this. A database created empty and migrated is a `fork` whose `reset_cmd` re-runs that same creation; a database you could not provision at all is a `stub`. What it must never be is a fourth word.
+
 - **`COMPOSE_PROJECT_NAME` does not isolate `external:`/fixed-`name:` volumes or fixed host ports — always run the [4a](#4a--neutralize-compose-isolation-leaks) generator.** For a compose-delivered DB the data volumes are forked *unconditionally* (independent of `schema_change` and `test_db_strategy`): the worktree runs its own server, and two servers on one volume is corruption. "Share the DB" only ever means share a connection to a single already-running server, never a second server on shared storage. The fix is a generated, out-of-tree override + a `COMPOSE_FILE` line in the copied `.env` — never an edit to any tracked compose file. Verify the volume-differs invariant before declaring the worktree runnable.
 - **Every fork decision lands in `.vinta-ai-workflows/worktrees/<name>.yaml`.** Teardown reads it; humans grep it; agents resuming a stalled plan read it. No decision lives only in conversation memory.
 - **Worktree root governed by runtime conventions.** claude-code uses `.claude/worktrees/`; other harnesses use sibling dirs. Don't fight the harness — match it.