vinta-ai-workflows 0.7.0-alpha32 → 0.7.0-alpha34

package/CHANGELOG.md

@@ -7,6 +7,8 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [0.7.0] — YYYY-MM-DD
 
+<!-- pre-release: 0.7.0-alpha34 on 2026-10-16 -->
+<!-- pre-release: 0.7.0-alpha33 on 2026-10-16 -->
 <!-- pre-release: 0.7.0-alpha31 on 2026-10-09 -->
 <!-- pre-release: 0.7.0-alpha30 on 2026-10-09 -->
 <!-- pre-release: 0.7.0-alpha20 on 2026-09-24 -->
@@ -32,6 +34,90 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **`vinta-ai-maestro`: `accept` on an unapproved review.** The review-budget
+  question offered `continue` or `stop`, and operators answered `stop` meaning
+  "take it as it is" — which fails the attempt and, under `--on-failure
+  retry`, starts the phase over. It now offers `continue`, `accept` and `stop`
+  and says what each does. `accept` ends the review loop and keeps the work:
+  the polish chores, the gates and integration still run, and the answer is
+  journalled. The unattended answer is unchanged (`continue` once, then
+  `stop`); the coordinator cannot answer `accept`.
+- **`vinta-ai-maestro validate` warns about parallel phases adding migrations
+  to one app**, and `plan-feature` treats them as real overlap. Two phases
+  that neither depends on the other, each adding a migration under the same
+  directory (Django `<app>/migrations/`, Alembic `…/versions/`, Rails
+  `db/migrate/`, Prisma `prisma/migrations/`), start from the same latest
+  migration; merged, the graph has two leaves and every gate on the merged
+  tree fails. Their Touch Lists name different files, so nothing flagged it.
+  `validate --json` gains a `warnings` list, printed as `warning:` lines in
+  text mode, and the review page shows them in their own panel; neither
+  changes the exit code or `valid`. `plan-feature` now says to add the edge,
+  or to name the phase whose integration writes the merge migration.
+- **`vinta-ai-maestro node resume <run> <phase>`**, the undo of `node pause`:
+  it withdraws a pause not yet taken, releases a phase parked on the pause, or
+  gives a held phase its `--retry-after` timer back. It used to take
+  answering an undocumented "The operator paused this node. Resume it?"
+  question, or answering a held phase's question by hand.
+- **`vinta-ai-maestro status` shows the question each phase is asking**, with
+  its choices, and `status --json` carries it per node as `question`
+  (`effectId`, `question`, `kind`, `choices`, `askedAt`). `asking: true` alone
+  sent operators into `flow.db` to read it.
+- **`vinta-ai-maestro`: ways past a stale gate verdict.** `gate <id>
+  --no-cache` runs a gate past its cached result and keeps the new one in its
+  place; a cached red now says so. `gate-cache invalidate <run-id> <gate-id>
+  [--tree <hash>]` forgets a gate's results for the operator and the run
+  coordinator (`POST /api/runs/:id/gates/:gate/invalidate`, journalled as
+  `gate_cache_invalidated`; an agent's token cannot reach it). Both are for a
+  verdict whose cause git does not track — an ignored file, a tool's cache, an
+  installed dependency — which the tree-keyed cache would otherwise replay.
+
+- **`vinta-ai-maestro`: a phase's decisions outlive the session they were
+  made in.** Each node now keeps a list of what was settled for it: agents'
+  questions with their answers (marked as the operator's, the coordinator's,
+  or unattended), the operator's `node context` and `redirect` text, and the
+  findings the review rejected with their counter-evidence. Every later
+  prompt carries the list — implementer, fixer, chores, and the review, which
+  hands it to its reviewer — so a fresh reviewer, a replaced session or a
+  retry no longer re-asks or re-raises what was already decided. Before
+  this, an unattended run answered one question four times and a phase ran
+  some thirty rounds without converging, and operator context sent with
+  `node context` had to be re-sent after a session change. The review now
+  rejects a finding that re-opens a decision, citing it, and asks the
+  operator about it at most once, and only with new evidence. It ends its
+  report with a `REJECTED:` line per rejected finding, which the run keeps.
+  The list is bounded (the newest 12 answers and notes and the newest 8
+  rejected findings), kept across retries, written to
+  `runs/<id>/nodes/<node>/decisions.jsonl` and read back when a run resumes.
+
+- **`vinta-ai-maestro judge calibrate`: measure a permission-judge question
+  before a run relies on it.** It replays a past run's `Bash` calls
+  (`--run <run-id>`), or a file of commands each optionally labelled `safe` or
+  `unsafe` (`--commands <file>`), against a candidate question
+  (`--question` / `--question-file`) and threshold (`--threshold`) through the
+  classifier in `--system-one`. Nothing is executed. It reports how many would
+  be allowed and refused, the score distribution, every labelled command
+  judged the wrong way, and the highest-scoring must-deny command, and exits 1
+  on a misjudged one so a case file can guard a project's question in CI.
+  Commands are printed as recorded, never their output.
+
+- **`vinta-ai-maestro`: `project.reset_cmd` and `project.recycle_keep`.**
+  `reset_cmd` is a project hook run inside a lane when it is recycled for the
+  next phase, and only then, after maestro's own resets and before
+  `setup_cmd`. `recycle_keep` lists gitignore patterns a recycled lane keeps
+  (`.venv`, say) now that the recycle cleans ignored files. Both optional, in
+  `workflow.v1`.
+
+- **`vinta-ai-maestro`: `node fresh <run> <phase>` drops a phase's agent
+  session without failing the attempt.** The phase's next turn starts cold with
+  the whole brief, journalled `node_session` `reason: operator_fresh`; the turn
+  in flight is not stopped (pair it with `redirect` for that). It is the way out
+  of a session gone wrong — an agent replaying killed work or carrying on with
+  the previous phase — that used to cost an `abort`. Also `POST
+  /api/runs/:run/nodes/:node/fresh`, and the run coordinator can use it. The
+  post-mortem's `operations.node_operations[].op` gains `fresh` (additive, in
+  `postmortem.v1.schema.json`).
+
+
 - **`vinta-ai-maestro`: a busy crew member is replaced, not borrowed
   (`defaults.max_spare_crew`, default 2).** When the member a phase is planned
   for — or the one an operator picked with `retry with <member>` — is busy, or
@@ -552,6 +638,15 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Changed
 
+- **`vinta-ai-maestro`: a recycled lane no longer keeps the last phase's
+  ignored files.** A lane handed to the next phase kept everything gitignored,
+  and one kept `apps/api/.mypy_cache` and a deleted package's `__pycache__`,
+  so mypy reported 18 errors on clean code. The recycle now cleans ignored
+  files too, keeping only the copied `node_modules`, the `env_files` and the
+  new `project.recycle_keep` patterns. **Migration:** anything expensive your
+  lanes build and should keep across phases, such as a `.venv`, goes in
+  `recycle_keep`; otherwise `setup_cmd`, which already runs on every
+  recycle, rebuilds it.
 - **`vinta-ai-maestro`: agents wait for background work the way a normal
   Claude Code session does.** A headless session no longer ends at the first
   turn that leaves background work running. It stays open, the agent is woken
@@ -891,6 +986,171 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **`vinta-ai-maestro`: a claude-code turn the CLI calls "blocked" no longer
+  fails unless a tool was refused in it.** The CLI's own turn summary marks a
+  turn `blocked` whenever its last message names a next step for a person —
+  a review ending "Nothing was pushed." over `VERDICT: pass`, an implementer
+  listing an open point — and each such turn was recorded as failed
+  ("claude-code: the turn ended blocked"), an approving review included. One
+  observed phase had 43 of them. The summary now fails a turn only alongside a
+  `permission_denied` in the same turn, the case it was added for; whether
+  the rest did their job is for verdicts, gates and the agent's questions. A
+  turn's errors no longer outlive it in a session held open for background
+  work.
+- **`vinta-ai-maestro`: a merge git stopped with nothing unmerged no longer
+  starts a fixer.** `rerere.autoupdate` replaying a recorded resolution, or a
+  `pre-merge-commit` / `commit-msg` hook refusing the merged code, leaves
+  `git merge` non-zero with no unmerged path, and the integrator handed the
+  conflict fixer an empty file list — nineteen rounds in one observed phase,
+  each told to resolve nothing. With no conflict markers left, the merge now
+  goes to `verify` and is committed, recorded as resolved in 0 rounds; a hook
+  that refuses that commit gets the refused-commit question (commit, commit
+  past the hooks, or abort), worded for a clean merge. Only a red gate sends it
+  to the fixer. A merge git refused before merging anything (an untracked file
+  in the way) fails with git's own error.
+- **`vinta-ai-maestro`: a merge finished by hand survives the next attempt.**
+  A conflict the fixer could not settle fails the phase with "finish the merge
+  by hand … and commit it", and the next attempt's `mergeWave` cut
+  `wave-<N>` again from `wave-<N-1>` and re-merged every member, throwing the
+  resolution away and hitting the same conflict on every attempt. A wave or
+  `integ-<id>` branch that still contains its starting point, and whose merges
+  all brought in work still in the members' current tips, is now kept, and only
+  the members it lacks are merged. A member redone after it was merged still
+  forces a rebuild. The error now says the branch is kept.
+- **`vinta-ai-maestro`: a merged tree that fails its gates is no longer
+  reported as an unresolved conflict with no paths.** Two sibling phases that
+  each added a Django migration on the same parent merged cleanly and failed
+  `verify` together, and the phase failed "unresolved conflict: p4a both
+  changed , …". Each fix round is now told which gate the merged tree failed
+  and where its log is, and the rounds end in `IntegrationVerifyError`, naming
+  the gate and its log path (`nodes/_integration/gates/<gate>.log`).
+- **`vinta-ai-maestro`: `exec` accepts a lane's short name or its phase, and
+  `with` / `gate` work inside it.** `exec <run> crew-3-tier2-2` and
+  `exec <run> p1` were refused `unknown_target`; only the full
+  `<run-id>-crew-3-tier2-2` worked. Both now resolve, and a refusal lists the
+  run's targets. Inside `exec`, `with test-suite -- make test` said "no live
+  run is available" while the run was live: the command now holds leases as the
+  phase running in the lane, or as itself on an idle one, until it exits.
+- **`vinta-ai-maestro`: a fix loop that changes nothing now stops and asks.**
+  A typecheck red because of ignored files left in a lane kept coming back
+  from the gate cache after they were gone, and twenty fixers in a row found
+  nothing to fix. When a gate is red again on the very tree a fixer turn left
+  unchanged, the scheduler reruns that gate once without the cache; if it is
+  still red the same way, `standard-phase` goes to `exhausted` instead of
+  spawning another fixer — with or without `max_fix_rounds` — and the run
+  coordinator is woken. New guard fact `gate.stalled`, new `run_gate` param
+  `no_cache`, new journal event `gate_stalled`. A fixer that moved the tree at
+  all is never a stall. A custom pipeline keeps its own guards and can opt in
+  on `gate.stalled`.
+
+- **`vinta-ai-maestro`: a claude-code review no longer loses a reviewer answer
+  that comes back early.** When a reviewer resumed with `SendMessage` answered
+  while the agent was still writing its last message, the session ended at the
+  turn's `result` and killed the turn the CLI starts to hand over the answer.
+  The review then stated no verdict and went to the operator as `unapproved`.
+  The session now waits for that turn, for at most a minute of silence.
+
+- **`vinta-ai-maestro purge` no longer ends a run you did not name.** A bulk
+  `purge --lanes` removed the lanes of paused, failed and interrupted runs —
+  the integration worktree included — so `run --resume` had nothing to adopt,
+  and a bulk `purge` deleted those runs' frozen snapshots. A run that could
+  still be resumed is now kept whole, directory and lanes, and named with the
+  reason; purge it by name, or pass the new `--force`. A run whose job is
+  still running is kept even then.
+- **`vinta-ai-maestro purge --lanes` tears a lane down, not just its
+  worktree.** It used to leave every forked database, compose stack and lane
+  summary behind, including summaries whose worktree was already gone. Each
+  reaped lane's summary is now its teardown manifest: `docker compose -p
+  <project> down`, `docker volume rm` for its forked volumes, the `reset_cmd`
+  of its own service namespaces, and `dropdb` (or the project's `dropdb_cmd`)
+  for its forked databases — every command listed before anything runs, and
+  under `--dry-run` nothing runs. Only what is provably that lane's is
+  touched: never a compose-delivered database, an index-numbered service slot,
+  or a summary `prepare-worktree` wrote for a worktree you made. A step that
+  fails is reported, and its lane's summary is kept so a rerun retries it.
+- **`vinta-ai-maestro run --help` says which runs resume.** It claimed a run
+  that "finished" could not be resumed, while a `failed` run resumes — its
+  failed phases and the ones they blocked are attempted again, and `status`
+  prints the command for it. The help now names paused, interrupted and
+  failed as resumable, and only `done` and `cancelled` as refused.
+- **`vinta-ai-maestro`: the shipped permission-judge question no longer
+  refuses routine commands.** Under `--permission judged` it allowed 44 of 69
+  commands from a real run, refusing `ls .env*`, `cat .env.example`,
+  `docker ps` and the project's own `make` targets. The question now says a
+  secret is a *value* — listing env files and reading templates is allowed,
+  reading a real `.env` is not — allows read-only inspection and the project's
+  own commands in its worktree, and still refuses pushes, `sudo`, writes
+  outside the worktree and another project's containers or volumes. A
+  project that set its own `judges.permission.question` is unaffected; the
+  default `allow_above` stays 0.9.
+
+- **`vinta-ai-maestro`: the disk preflight sizes the pool the run will
+  really create.** `run --resume` with every worktree still on disk was
+  refused (`3 lanes + 1 integration worktree needs 37.9 GiB, only 18.0 GiB
+  free`) by a doctor that charged for them all again; it now charges only the
+  worktrees still to be made, and passes a resume that makes none. A staffed run
+  is counted as the pool provisions it — a worktree per crew member, not per
+  unit of `resources.lane.capacity` — plus `defaults.max_spare_crew`
+  headroom, and the doctor, the pool and the refusal line now name the same
+  count. The per-lane estimate is the tracked tree at the base branch, the
+  copied `node_modules` and the `env_files`, instead of a walk of the whole
+  main checkout that counted `.git`, the `.vinta-ai-maestro/` store (lanes
+  included) and ignored caches — one run's estimate had grown from 4.0 to
+  9.5 GiB a lane against real lanes of about 1.1 GiB.
+
+- **`vinta-ai-maestro`: an integration merge a pause, stop or kill caught
+  half-way no longer wedges the run.** Every later attempt used to fail on
+  `integration worktree is mid-merge` until someone ran `git merge --abort` by
+  hand. The integrator now recognises a merge it started — one of the plan's
+  phase branches (or a kept resolution, or the plan branch) into one of its
+  `integ-`/`wave-` branches — keeps what it had under
+  `refs/vinta-ai-maestro/abandoned/<branch>`, aborts it and redoes it, so the
+  result is gated again; each one journals `integration_reclaimed`. The same
+  sweep runs on `run --resume` and when a stop outlives its deadline. A conflict
+  left for a person that nobody finished is redone on the retry the same way.
+  A merge the run did not start is still refused by name. A failed `git_merge`
+  of a named branch now aborts its merge.
+
+- **`vinta-ai-maestro`: aborting the only runnable phase no longer ends the
+  run.** A run whose remaining phases all depended on an aborted one ended
+  `failed` at once, and the `node retry` that followed was refused as `run has
+  ended`. Aborted phases now hold the run open for their retry (no timer retries
+  them); `pause` or `stop` ends it. Under `--on-failure stop` an abort still ends
+  the run. A retry sent while the aborted attempt is still winding down is
+  applied once it has.
+
+- **`vinta-ai-maestro`: a gate run inside `with` no longer deadlocks every
+  lane.** `vinta-ai-maestro with test-suite -- vinta-ai-maestro gate test`
+  held the only `test-suite` slot while the gate queued for it, and every
+  lane's tests and gates queued behind the pair (55 minutes in one run). The
+  gate guard now refuses `gate` inside `with` and tells the agent to run the
+  gate on its own. The daemon refuses a gate whose resources the asking phase
+  already holds through `with` (`holds_required:<resource>`), naming the
+  process holding them. The agent prompts state the same rule.
+- **`vinta-ai-maestro`: `with` and `gate` say who they are waiting on.** A
+  queued answer names each holder of the resource: the phase, its lane, and
+  how it holds it (`with` with its process id, a gate an agent ran, or the
+  phase's own gate step). When the holder is the asking phase itself, the
+  message says so. It used to say "held by another lane" in exactly that case.
+  `gate` now says "queued" until the gate has its resources and "running"
+  after; it used to say "running" throughout.
+- **`vinta-ai-maestro`: commands left behind by an ended agent session stop
+  holding capacity.** Each agent session gets a turn id
+  (`VINTA_AI_MAESTRO_TURN_ID`), which `with` and `gate` send with every
+  request. When the session ends, the leases its commands hold are released,
+  their queued waits and queued gates are cancelled, and their next request is
+  refused (`turn_ended`). A request for a phase that is not running is refused
+  too (`holder_not_running`). A command backgrounded with `&` used to keep its
+  place in the queue for as long as it lived: one run had nine such waiters,
+  up to 55 minutes old.
+- **`vinta-ai-maestro`: `pause` finishes while an agent waits on a lease or a
+  gate.** A pause (or stop) now answers every queued `with` and `gate` with
+  `run_pausing` (`run_stopping`) and refuses new ones. The CLIs tell the agent
+  to end its turn, which is the step boundary the pause waits for. Commands
+  and gates already running finish as before. The halt log names each node
+  the drain is still waiting on and what it is doing, and
+  `vinta-ai-maestro pause` prints the same list.
+
 - **`vinta-ai-maestro`: a turn the agent never took part in is no longer read
   as work.** A session that ended with no text and no tool call — observed when
   a resumed claude-code session closed a replay of killed background tasks

package/package.json

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

package/schemas/postmortem.v1.schema.json

@@ -680,7 +680,8 @@
                       "add_context",
                       "redirect",
                       "pause",
-                      "abort"
+                      "abort",
+                      "fresh"
                     ]
                   },
                   "by": {
@@ -704,7 +705,7 @@
                 ],
                 "additionalProperties": false
               },
-              "description": "Steering, pauses and aborts, per phase."
+              "description": "Steering, pauses, aborts and dropped sessions, per phase."
             },
             "questions": {
               "type": "object",

package/schemas/workflow.v1.schema.json

@@ -360,6 +360,20 @@
           "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
+        },
+        "reset_cmd": {
+          "description": "Run inside a lane when it is recycled for another phase, and only then — never on a freshly provisioned lane. Runs with the lane’s environment applied, after maestro has reset the worktree, the env files, the databases and the services, and before `setup_cmd`. For what a phase leaves behind that the clean does not reach: a cache outside the worktree, a `recycle_keep` directory that needs pruning rather than deleting.",
+          "type": "string",
+          "minLength": 1
+        },
+        "recycle_keep": {
+          "default": [],
+          "description": "Ignored paths a recycled lane keeps. A recycle removes every untracked and ignored file the previous phase left — caches such as `.mypy_cache` and `__pycache__` included, which once kept a deleted package importable and failed a type check on clean code — except the copied dependency tree, the `env_files` and what is listed here. Each entry is a gitignore pattern handed to `git clean -e`: `.venv` keeps one at any depth, `/apps/api/.venv` only that one. For what is expensive to rebuild; anything not listed is rebuilt by `setup_cmd`, which runs on every recycle.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
         }
       },
       "required": [

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

@@ -254,6 +254,7 @@ Before publishing the plan, cross-check the **Touch List**: for every pair of ph
 
 - **Trivial overlap** (a shared `__init__.py`, a settings registry, a route table) — fine. Note it under the graph table so the reviewer isn't surprised.
 - **Real overlap** (the same use case, the same serializer, the same view) — **add the dependency edge** and let one phase build on the other. A serialized pair that merges cleanly beats a parallel pair that needs a human to untangle.
+- **Migrations in one app count as real overlap, even in different files.** Two phases that run in parallel and each add a migration to the same app both start from the same latest migration. Each is green alone; merged, the migration graph has two leaves (Django) or two heads (Alembic), and every gate on the merged tree fails. Their Touch Lists name two different new files, so path overlap never shows it. Prefer the edge — usually by folding both schema changes into the foundation phase — or, when the two must stay parallel, say in the later phase's body that the integration step writes the merge migration. `vinta-ai-maestro validate` warns about such a pair; put the migrations directory in each phase's Touch List so it can.
 
 ### Design *for* parallelism when it's cheap
 
@@ -1071,6 +1072,8 @@ Fix each issue by its `source`:
 - **`workflow`**: the document's shape or graph, such as an unknown node, a cycle, an undeclared pool, a crew member that cannot take its phase, a gate entry with neither `cmd` nor `type`, a phase with no gates, or an id that does not match the filename. Re-derive the field from the plan. A gate `"has no cmd"` is an override that forgot its `"type"`. A phase that `"has no gates"` is a node carrying `"gates": []` — remove the key so it takes `defaults.gates`, name its gates, or, for a plan whose phases genuinely have nothing to run, set `defaults.allow_ungated_phases: true`. If the plan itself is wrong (a cycle in its `**Depends on**:` lines), fix the plan first.
 - **`config`**: `.vinta-ai-workflows.yaml` does not parse. That file is the project's, not the plan's. Do not edit it to make the plan pass. Tell the human what is wrong and where.
 
+**`warnings` do not change the exit code, and each still gets an answer.** Today the one warning is two phases that run in parallel and both add migrations to the same app (see "Same-wave phases must not fight over the same files"). Add the dependency edge, or keep the pair parallel and say in the later phase's body that the merge migration is written at integration. Either way, name the choice when you hand the plan over. An older maestro prints no `warnings` key.
+
 ## Review the plan with the human
 
 A plan is cheapest to change before anything runs. Once both files are written and the workflow validates, hand the plan over for review. Ask with `AskUserQuestion`: header `Review`, question "The plan and its workflow are written — `<plan path>` and `<workflow path>`. How do you want to review it?"