vinta-ai-workflows 0.7.0-alpha18 → 0.7.0-alpha19

package/CHANGELOG.md

@@ -7,6 +7,7 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [0.7.0] — YYYY-MM-DD
 
+<!-- pre-release: 0.7.0-alpha19 on 2026-09-19 -->
 <!-- pre-release: 0.7.0-alpha18 on 2026-09-17 -->
 <!-- pre-release: 0.7.0-alpha17 on 2026-09-17 -->
 <!-- pre-release: 0.7.0-alpha16 on 2026-09-16 -->
@@ -28,6 +29,74 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **Gate durations are now kept, not just displayed.** Every `gate_result` has
+  carried the runner's own `duration_ms` since gates were journalled, and
+  nothing read it back: the figure went to a live panel and was afterwards
+  reachable only by hand-parsing event payloads, so the one measurement that
+  answers "is the suite why this run took an hour" could not be asked of a
+  finished run. `analyzeRun` now rolls it up per gate — runs, cache hits,
+  summed runtime, the slowest single run, verdicts by kind — and each phase's
+  time split carries `gateRunMs` beside `gatePoolQueueMs`, so a run says how
+  much of its working time was the gate queue and how much was the gate. The
+  post-mortem carries the same as a `gate_costs` finding, which is what makes
+  it durable: `plan-feature` reads these artifacts when sizing the next plan,
+  and a gate pool's capacity and `max_parallel_lanes` are one decision made
+  with half the numbers. Cache hits are counted and their time kept in its own
+  `cache_saved_ms` column — a hit's duration is what the gate cost when it last
+  ran, and adding it to the runtime would report time the run specifically did
+  not spend. A verdict written before the runner measured itself is counted and
+  its milliseconds are not: both reports emit a `gate_durations_unrecorded` gap
+  naming the gates, because a gate reported as free is the number a planner
+  would act on hardest.
+
+- **Phases can run chores: declared agent turns that change the diff rather than
+  judge it.** A gate is a shell command that says pass or fail; a chore is an
+  agent asked to do something to the work — rewrite the comments this phase
+  wrote, add the changelog entry, extract the strings that need translating. It
+  runs on the implementer's own session, so the agent that wrote the diff is the
+  one asked to act on it. Declare them in `chores.<id>` (a `prompt` or a
+  `prompt_ref` into the plan, plus an optional `skill` the prompt names) and
+  pick them with `defaults.chores` for the run or `nodes[].chores` for one
+  phase — a node's list replaces the default rather than adding to it, so `[]`
+  opts a phase out. In `standard-phase` they run in a new `polish` state,
+  between a passing review and the gate: a chore edits the tree, so running it
+  later would merge a diff the gates never ran against, and running it earlier
+  would have the fixer rewrite what it just did. A chore that fails, or that the
+  harness had no capacity for, is journalled and the phase continues to its
+  gates — `on_failure: "fail"` is for one the phase is not correct without.
+
+- **The post-mortem now reports what the schedule cost.** Two findings, both
+  derived from events the journal already carried. `critical_path` is the
+  dependency chain that decided the wall clock — each phase's span, the total,
+  and its share of elapsed — because every phase *off* that chain could be made
+  instant without moving the run, and nothing said which phases those were.
+  `idle_capacity` reports the width the graph actually reached against the lanes
+  it asked for: a plan declaring three lanes that never runs more than two
+  phases at once pays for a third worktree, a third forked database and a third
+  desk, and gets none of them back. Run against a real fourteen-hour build, the
+  two say its critical path was **99% of elapsed time** — six phases, effectively
+  serial — with peak concurrency 2 against 3 lanes and **55% of lane time idle**.
+  `plan-feature` already reads these artifacts before drawing the next set of
+  dependency lines; until now neither depth nor width was in them. A
+  `blocking_cause_unrecorded` gap ships alongside, because the chain is what the
+  *graph* forced and a phase can also wait on a busy lane or an unanswered
+  question — which the journal cannot currently tell apart.
+
+- **`--retry-after <15m>`: an unanswered failure question eventually answers
+  itself.** An observed fourteen-hour run spent 4h07m — 29% of its wall clock —
+  parked on "This phase failed. Try it again?" with nobody at the keyboard; the
+  answer, when it came, was `retry`, and it worked. Unset by default, so a run
+  behaves exactly as it did. Accepts minutes bare or a unit (`15`, `15m`, `90s`,
+  `2h`) on both `run` and `serve`. It is deliberately unbounded and fires again
+  on each new question: a version capped by `--retries` would stall at the cap
+  and idle for the rest of the night, which is the failure it exists for. Every
+  firing is a full phase attempt, so the interval is the throttle. It reaches
+  the failure question and nothing else — a plan's own `await_human` gate asked
+  for a person, and both park through the same code, so answering those would be
+  the orchestrator overruling the plan. An unattended answer is journalled with
+  `unattended: true`, because "a human said try again" and "nobody was here" are
+  the same answer with very different meanings.
+
 - **The daemon now has a log of its own, and a Logs view to read it in.**
   Transcripts said what the agents did; nothing said what the *daemon* did, so
   "the run stopped and I don't know why" had no evidence behind it at all.
@@ -75,6 +144,82 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   is already a copy of the repository, and excluding it cost the one string that
   most often explains a failure. `--log-detail kind` narrows to the kind and the
   stack frames for a checkout under a stricter obligation than this store's own.
+- **A run that is dragging can now tune itself, within bounds somebody wrote
+  down.** A run can be mis-*configured* rather than broken — every phase doing
+  what it was asked, every gate reporting honestly, and the whole thing paying
+  for a test database it rebuilds on every gate run in every lane. Nobody needs
+  waking for that, and the post-mortem found it out an afternoon too late to
+  help. Now a watchdog wakes the run's monitor when a phase passes an hour or a
+  gate's uncached cost passes thirty minutes, the monitor reads the gate logs
+  and the durations, and it answers with a **proposal** that the daemon
+  validates and applies through the existing amend path. `--no-intervene` turns
+  it off.
+
+  It proposes; it never writes. Its authority is four verbs — a gate's command,
+  a gate's timeout, a phase's fix budget, a phase's model — and the line they
+  draw is that it may change **how** the run executes and never **what** it
+  builds. There is no way to express a change to a dependency, a phase brief, a
+  touch list, the base branch, or the set of phases: not refused at runtime,
+  unrepresentable.
+
+  The one field that can do real damage is a gate's command, because
+  `--reuse-db` and `-k not_slow` are the same edit to the same string, and a
+  gate narrowed wrongly goes green and looks like success in every log there
+  is. So a command may only be changed when the gate itself declares
+  `tuning.allowed_flags` — a list a person wrote in the committed plan, under
+  review, before the run started — and the proposed command must be the current
+  one's argv tokens, in order, plus additions from that list. A gate that
+  declares no `tuning` block is not tunable, which is the default.
+
+  A run gets three of these in its life, at most one per gate and per phase.
+  What it changed is journalled as identifiers; why it changed it is the
+  monitor's prose and goes in `runs/<run-id>/interventions.jsonl` beside the
+  run, including every attempt that was refused — an agent trying to do
+  something it may not do, with nobody in the room, is the record most worth
+  keeping. See `packages/vinta-ai-maestro/docs/monitor-intervention.md`.
+
+- **`plan-feature` is told what the newer post-mortem findings mean.** The
+  skill documents each finding and what to *do* about it, and three had been
+  added to the artifact without reaching it: `gate_costs`, `critical_path` and
+  `idle_capacity`. A finding a planning agent cannot interpret is a finding
+  that changes no plan, which is the whole return on emitting it — and the
+  three are among the most actionable there are. `gate_costs` sizes the gate
+  pool capacities a plan declares, and separates a slow suite from a fix loop
+  re-paying for the same one. `critical_path` is the chain to re-draw the graph
+  against: shortening a phase that is not on it changes nothing, so a plan that
+  parallelises harder without touching that chain buys nothing at all.
+  `idle_capacity` says the graph never got as wide as the lanes it asked for,
+  which is a fact about the plan rather than about the machine. Each now has a
+  row beside the findings that already had one.
+
+- **The post-mortem says what a run changed about itself, and whether it
+  helped.** `postmortem.v1` gains an `interventions[]` finding: one entry per
+  amendment the run made to itself, with the effect on the thing it changed. A
+  gate is scored against its own uncached durations either side of the
+  amendment — mean before, mean after, `cheaper` / `dearer` / `unchanged`
+  outside a ten-per-cent band. Cached hits are excluded, because a hit reports
+  the duration of the run that filled the cache and would drag the mean toward
+  whichever side of the boundary that run fell on.
+
+  It is a comparison and not a claim of cause, and the schema says so: a gate
+  that got cheaper did so while phases were finishing and caches warming. It is
+  worth carrying anyway, because without it an autonomous editor is one nobody
+  can tell is making runs worse — and because `plan-feature` now reads it, so a
+  project whose `unit` gate wants `--reuse-db` pays to find that out once
+  instead of every run.
+
+  A phase-level change (a fix budget, a model) is reported `unmeasured` rather
+  than estimated: a phase runs once, so there is no before to compare an after
+  against, and the only candidate baseline is a different phase doing different
+  work. An operator's amendment is not scored at all — a person deciding
+  something is not the run choosing it.
+
+- **`schemas/intervention.v1.schema.json`** — the document the monitor answers
+  with, generated from `src/intervention/intervention.ts` the way the workflow
+  and post-mortem schemas are generated from theirs. It is the odd one in
+  `schemas/`: it validates something a *model* writes rather than a skill or a
+  person, and it is the boundary deciding what an unattended run may change
+  about itself.
 
 - **A run no longer dies with the terminal that started it.** `vinta-ai-maestro
   serve` accepts `POST /api/runs`, so a run can be submitted to a daemon that
@@ -419,6 +564,28 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Changed
 
+- **The node view's gate panel is a list of verdicts you can open, not a stack
+  of scrolling boxes.** Every gate used to render its whole log at once, each
+  in its own fixed-height box with its own scrollbar — so three gates in a
+  third of a grid row was a column of letterbox slots, and a wheel gesture
+  over one of them was swallowed by that box instead of scrolling the page.
+  Gates are now an accordion: one row per gate, only one open at a time, and
+  the open log has no scroller of its own (it is tail-truncated at 64 KiB
+  already, and long lines wrap the way the diff panel's do). The panel opens
+  on the gate a human question points at, or on the first that is not passing.
+
+- **Each gate row says what happened and what it cost.** The verdict —
+  `running`, `passed`, `failed`, `timed out` — is on the wire now, so a phase
+  whose lint gate passed and whose unit gate failed reads as that instead of
+  as two identical rows; previously the UI could only name the single gate
+  §9.1's question happened to point at, because `NodeDetail` carried an id and
+  a log and nothing else. A running gate shows a clock counting from the
+  daemon's own start time, so a tab opened halfway through a slow suite shows
+  the true elapsed figure rather than starting from zero; a finished one shows
+  the runner's measurement of its latest attempt, with `cached` where the
+  cache served the verdict and a `×N` count where the gate has run more than
+  once.
+
 - **Crew members are named after their tier, not after a seniority.** A roster
   reads `tier1`, `tier2-1`, `tier2-2`, `tier4` and `reviewer` where it used to
   read `junior`, `mid-1`, `mid-2` and `senior`. Nothing about the data model
@@ -440,6 +607,27 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   which the schema requires to be lowercase kebab-case, so the date prefix is
   the only part the three can share. Existing dateless workflows are unaffected
   — this is the emitter's convention, not a schema rule.
+- **A gate's command can be retuned while the phase that runs it is still
+  running.** §9's amend refused any change reaching a node in flight, which is
+  exactly the node anyone is looking at when a run is dragging: a `unit` gate
+  missing `--reuse-db` could not be fixed until the run it was costing hours
+  had finished. The refusal now reads a narrower set. A node's harness, model,
+  pipeline, body and base are each read at a moment that has already passed, so
+  changing them is refused as before; a gate's *command* is resolved per gate
+  run by every reader of it, so a running phase simply runs the new command at
+  its next gate. Nothing downstream is blocked either, because a command moves
+  no branch's base. Changing **which** gates a node declares is still refused
+  mid-flight — a phase that gained a gate would finish without ever running it —
+  so that now counts as part of the phase body.
+
+- **A gate result is cached against the command that produced it.** The key was
+  `(gate id, tree hash)`, on the assumption that a gate id names a command.
+  Amending a live run makes that false, and an unchanged tree would have been
+  served the old command's verdict. The command is now part of the key, hashed
+  rather than stored — a command line is repository content. A cache database
+  written before this is dropped when it is opened: its rows cannot say which
+  command produced them, and one re-run per stale entry is the price a lost row
+  already costs.
 
 - **A session cannot inherit a machine's decision to stop compacting.** All
   three harnesses compact automatically when their context fills — there was
@@ -548,6 +736,75 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **`vinta-ai-maestro gate` gave up on the slowest gate after five minutes and
+  called it a daemon it could not reach.** The command awaited one `fetch`, on
+  the stated reasoning that a gate is slow for reasons the client cannot shorten
+  and so the client should simply wait — while its own comment claimed it
+  imposed no deadline of its own. It imposed 300 seconds, because that is where
+  Node's `fetch` abandons a response whose headers have not arrived, and a gate
+  that queues for a capacity-1 semaphore and then runs a test suite is routinely
+  slower. In a measured fourteen-hour run this fired **33 times, every one of
+  them on the `unit` gate and none on any other** — a perfect correlation with
+  duration, not a flaky daemon. The gates were running fine and cached green
+  results minutes later; only the answer was lost. Told a transport lie about
+  work in progress, agents wrote polling loops around a command documented as
+  needing none: in one phase, **24 of 108 shell turns were pure waiting, six of
+  them burning a full ten-minute ceiling — 60 minutes, 31% of that phase.** The
+  wait is a `202` hop loop now, which is what `with` already does, having found
+  the same bug the same way and fixed it first.
+
+- **A gate command cut short by the harness started the suite over.** An agent
+  harness caps how long one command may run, and a gate may exceed any such cap
+  — a plan declaring `timeout_s: 2400` is asking for forty minutes against a
+  ten-minute budget. So being killed partway is the *ordinary* ending, and what
+  an agent does next is run the command again. That used to start a second full
+  suite beside the first, queued behind the very semaphore its own predecessor
+  was still holding. The daemon now keys a running gate on `(phase, gate id)`
+  and the re-invocation attaches to it, which makes re-running the command the
+  correct move rather than a wasteful one — worth having, because it is the move
+  an agent makes anyway. There is no token to carry, deliberately: a client that
+  was killed has nothing in hand, and needing something would defeat the point.
+
+- **A pipeline that could not progress was journalled as the word "Error".** The
+  interpreter composes an id-safe reason for exactly this case — which state it
+  could not leave, and which trigger failed to match — and the scheduler threw
+  it as a bare `Error`. `failureReason` reports an unrecognised error by its
+  name, so the sentence was discarded at the one moment it was worth keeping.
+  It is a `PipelineStuckError` now, carrying the state, and the reason survives
+  into the journal. The same shape as the non-zero git exit, fixed the same way.
+
+- **A pull request said nothing but the plan anchor.** The daemon opened PRs
+  with `title: node.name` and `body: node.prompt_ref` — one line, a link to a
+  heading. It had no idea the `prs-context` mechanism existed: there was not a
+  single reference to it in the package, so the rich path the skills use
+  (`open-pr-from-context`, the project's own PR template, inline review
+  comments) was never reached from a run. `open_pr` now reads the phase's
+  `.vinta-ai-workflows/prs-context/<plan>/phase-<node>.md` when the agent wrote
+  one, and the implementer is asked to write it — the 5–15 line summary it
+  already produces, put where a human will read it instead of only the
+  transcript. With no context file the body is composed from the run's own
+  record: the brief, what the phase is based on and why that is not the default
+  branch, its declared surface, its gates, how many attempts it took, and any
+  merge conflicts an agent resolved on the way in — which nobody reviews.
+
+- **A phase with two dependencies could never open a pull request.** Its base is
+  an `integ-<id>` branch and `git_push` pushes only the node's own branch, so
+  `gh` was asked to open against a ref the forge had never seen. It refused, the
+  refusal was discarded, and the phase completed with no PR and nothing saying
+  so — in one observed run, the single node with two dependencies was the single
+  node with no PR. The integration base is pushed before the PR is opened, and
+  every outcome is journalled as `node_pr`, so a PR that did not open is now as
+  visible as one that did.
+
+- **A conflict resolution was never gated.** `IntegratorOptions.verify` has
+  existed as long as the conflict loop, documented as "a resolution that does
+  not build is not a resolution", and nothing ever supplied it. Six merges in
+  one run were resolved by an agent and went straight in — ungated — to become
+  the base the next phase built on, while the phases either side were gated to
+  the hilt. The union of the conflicting nodes' declared gates now runs in the
+  integration worktree, with that worktree's environment, and a red gate spends
+  a fix round instead of shipping.
+
 - **A conflict fixer that committed its own resolution failed the phase.** An
   agent told to resolve a merge conflict reaches for the sequence a person
   would — abort, merge again, resolve, commit — and the orchestrator then
@@ -629,6 +886,35 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   actually ran is someone else — so a phase declared for one tier and covered by
   a higher one offered that higher one as its escalation, and a third of the
   menu did nothing distinguishable from plain retry.
+- **An amended workflow now reaches the integrator too, and a wave merge is
+  pinned to the membership it was decided with.** Fixing the executor without
+  fixing the integrator is what made this reachable: `#lastOfWave` decides a
+  wave is complete by counting the executor's node set and `mergeWave` decided
+  what to merge by reading the integrator's, so while both were stale they
+  agreed with each other and nothing showed. One fresh and one stale is a wave
+  whose merge silently omits the branch of a phase that ran.
+
+  The case that gets there is a phase nobody depends on. An amendment is
+  refused while a node it *blocks* is in flight, and such a phase blocks
+  nothing, so it lands freely beside the wave-mates it will be merged with.
+
+  A wave's membership is now computed once, synchronously, by the code that
+  decides the wave is complete, and handed to the merge — a wave merge runs
+  behind the integration worktree's queue and an amendment can land in between,
+  so a merge that re-derived its own membership would merge a phase that never
+  ran. §9's rebase goes through that same queue now, since "the nodes this
+  amendment blocks are idle" says nothing about whether another wave's merge is
+  writing in that directory.
+
+- **An amended workflow now reaches the code that runs the gate.** `adopt`
+  replaced the scheduler's copy of the run's definition and nothing else, while
+  the effect executor and the agent-gate broker each held the snapshot they were
+  constructed with — and the command a gate actually runs is read from the
+  executor's. So an operator who edited a gate command mid-run moved the
+  snapshot, the journal and the pool reservations, watched the amendment be
+  accepted, and went on getting the old command. All three take the amendment
+  now, fanned out from one place, host side before the scheduler so that no
+  phase is dispatched against a definition half the system has not seen yet.
 
 - **Closing a terminal on a run now records the interruption.** `run` and
   `serve` handle SIGHUP as well as SIGINT and SIGTERM — SIGHUP is what a

package/package.json

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

package/schemas/README.md

@@ -14,8 +14,11 @@ JSON Schema (Draft 2020-12) contracts for every YAML or JSON payload the vinta-a
 | AI model tier table | `ai-tools/skills/plan-feature/resources/ai-models.yaml` (shipped verbatim with the `plan-feature` foundation skill; source: `skills/vinta-derive-skills/resources/foundation-skills/plan-feature/resources/ai-models.yaml`) | [`ai-models.v1.schema.json`](ai-models.v1.schema.json) | nightly `check-ai-models` job ([`scripts/check-ai-models.mjs`](../scripts/check-ai-models.mjs)) → auto-PR | `plan-feature` (per-phase model suggestion) |
 | Workflow (executable plan) | `ai-plans/YYYY-MM-DD-<feature-kebab>.workflow.json` — **JSON, not YAML** | [`workflow.v1.schema.json`](workflow.v1.schema.json) | `plan-feature` (emitted alongside the human-readable plan) | `vinta-ai-maestro` (the orchestrator daemon) |
 | Plan post-mortem | `.vinta-ai-maestro/runs/<run-id>/postmortem.json` — **JSON, not YAML**; per-run state beside the frozen workflow, copied to `ai-plans/<feature-kebab>.postmortem.json` when a team wants it committed | [`postmortem.v1.schema.json`](postmortem.v1.schema.json) | `vinta-ai-maestro` (once a run has ended) | `plan-feature` (when planning the next feature in the same repo) |
+| Monitor intervention | not a file the user writes — the document the run's monitor answers with when a watchdog wakes it, recorded per attempt at `.vinta-ai-maestro/runs/<run-id>/interventions.jsonl` | [`intervention.v1.schema.json`](intervention.v1.schema.json) | the run monitor (`vinta-ai-maestro`, when a phase or a gate crosses a threshold) | `vinta-ai-maestro` (validates it, then applies it through §9's amend path) |
 
-> `workflow.v1.schema.json` and `postmortem.v1.schema.json` are the two schemas here that are **generated, not hand-written**. The workflow's source of truth is `packages/vinta-ai-maestro/src/types.ts`; regenerate with `pnpm --filter vinta-ai-maestro schema:gen` and verify with `schema:check`. The post-mortem's is `packages/vinta-ai-maestro/src/postmortem/postmortem.ts`; regenerate with `node --experimental-strip-types src/postmortem/generate.ts` from `packages/vinta-ai-maestro`, verify with the same command plus `--check` — `tests/postmortem.test.ts` runs that byte comparison too. Edit the zod schemas, never the JSON.
+> **Three of these are generated, not hand-written**: `workflow.v1`, `postmortem.v1` and `intervention.v1`. The workflow's source of truth is `packages/vinta-ai-maestro/src/types.ts`; regenerate with `pnpm --filter vinta-ai-maestro schema:gen` and verify with `schema:check`. The post-mortem's is `src/postmortem/postmortem.ts` and the intervention's is `src/intervention/intervention.ts`; regenerate either with `pnpm --filter vinta-ai-maestro <postmortem|intervention>:schema:gen`, verify with `:schema:check` — `tests/postmortem.test.ts` and `tests/intervention.test.ts` run those byte comparisons too. Edit the zod schemas, never the JSON.
+>
+> The intervention schema is the odd one: it validates a document a *model* writes rather than one a skill or a person does, and it is the boundary that decides what an unattended run may change about itself. Its verbs are deliberately few and deliberately cannot express a change to what a phase builds — see [`docs/monitor-intervention.md`](../packages/vinta-ai-maestro/docs/monitor-intervention.md).
 
 ## Versioning rules
 

package/schemas/intervention.v1.schema.json

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

package/schemas/postmortem.v1.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/vintasoftware/vinta-ai-workflows/schemas/postmortem.v1.schema.json",
   "title": "vinta-ai-maestro plan post-mortem",
-  "description": "What one finished `vinta-ai-maestro` run learned about the plan that produced it: dependencies that were never used, dependencies discovered missing, same-wave phases that conflicted, and phases whose duration diverged from their wave. Ids, waves, paths, durations and counts only. Lives at `.vinta-ai-maestro/runs/<run-id>/postmortem.json` in a target project, emitted by `vinta-ai-maestro` after a run ends and read by `plan-feature` when planning the next feature in the same repo. GENERATED from packages/vinta-ai-maestro/src/postmortem/postmortem.ts — edit there, not here. See schemas/README.md for versioning rules.",
+  "description": "What one finished `vinta-ai-maestro` run learned about the plan that produced it: dependencies that were never used, dependencies discovered missing, same-wave phases that conflicted, phases whose duration diverged from their wave, what each gate cost, and changes the run made to its own plan while it ran. Ids, waves, paths, durations and counts only. Lives at `.vinta-ai-maestro/runs/<run-id>/postmortem.json` in a target project, emitted by `vinta-ai-maestro` after a run ends and read by `plan-feature` when planning the next feature in the same repo. GENERATED from packages/vinta-ai-maestro/src/postmortem/postmortem.ts — edit there, not here. See schemas/README.md for versioning rules.",
   "type": "object",
   "properties": {
     "$schema": {
@@ -203,6 +203,73 @@
             "description": "Two same-wave phases that actually fought over the same code at integration."
           }
         },
+        "gate_costs": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "gate": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^[a-z0-9][a-z0-9-]*$"
+              },
+              "runs": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 9007199254740991,
+                "description": "Verdicts recorded for this gate, over every phase and every fix round."
+              },
+              "cached_runs": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Of those, the ones the result cache served. They cost this run nothing."
+              },
+              "ran_ms": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Summed runtime of the verdicts the run actually paid for — the runner’s own measurement, not the distance between two journal rows. Cache hits are excluded."
+              },
+              "slowest_ms": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "The slowest single paid run. What a `timeout_s` is set against."
+              },
+              "cache_saved_ms": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Summed runtime of the cache hits: what those gates cost the last time they really ran. An estimate of time saved, never additive with `ran_ms`."
+              },
+              "failed_runs": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Verdicts that came back red."
+              },
+              "timed_out_runs": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Verdicts killed at `timeout_s`. The most expensive kind of run there is."
+              }
+            },
+            "required": [
+              "gate",
+              "runs",
+              "cached_runs",
+              "ran_ms",
+              "slowest_ms",
+              "cache_saved_ms",
+              "failed_runs",
+              "timed_out_runs"
+            ],
+            "additionalProperties": false,
+            "description": "What one gate cost the run. A plan is sized against this: the gate that dominates `ran_ms` is the one whose pool capacity decides the wall clock, and a gate whose `runs` far exceeds its phases is a fix loop re-paying for the same suite."
+          }
+        },
         "duration_divergences": {
           "type": "array",
           "items": {
@@ -254,13 +321,199 @@
             "additionalProperties": false,
             "description": "A phase whose real duration was wildly out of line with its wave placement — which is exactly what makes the next plan’s parallelism estimate wrong."
           }
+        },
+        "critical_path": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "nodes": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "node": {
+                        "type": "string",
+                        "minLength": 1,
+                        "pattern": "^[a-z0-9][a-z0-9-]*$"
+                      },
+                      "wave": {
+                        "type": "integer",
+                        "minimum": -9007199254740991,
+                        "maximum": 9007199254740991
+                      },
+                      "span_ms": {
+                        "type": "integer",
+                        "minimum": 0,
+                        "maximum": 9007199254740991
+                      }
+                    },
+                    "required": [
+                      "node",
+                      "wave",
+                      "span_ms"
+                    ],
+                    "additionalProperties": false
+                  },
+                  "description": "The chain in the order it ran, each with the time it was running."
+                },
+                "span_ms": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 9007199254740991,
+                  "description": "The chain’s total. The floor this graph could reach."
+                },
+                "share_of_elapsed": {
+                  "type": "number",
+                  "minimum": 0,
+                  "maximum": 1,
+                  "description": "How much of the run’s wall clock this one chain accounts for."
+                }
+              },
+              "required": [
+                "nodes",
+                "span_ms",
+                "share_of_elapsed"
+              ],
+              "additionalProperties": false,
+              "description": "The dependency chain that decided how long the run took. A plan is re-drawn against this: shortening any other phase changes nothing, and the only way to a faster run is a shallower graph or a cheaper phase on this list."
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "idle_capacity": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "lane_capacity": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 9007199254740991,
+                  "description": "Lanes the plan asked to be provisioned."
+                },
+                "peak_concurrency": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 9007199254740991,
+                  "description": "The most phases that were ever running at once. The width the graph reached."
+                },
+                "lane_ms_provisioned": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 9007199254740991
+                },
+                "lane_ms_used": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 9007199254740991,
+                  "description": "Summed phase spans — one lane each, while running."
+                },
+                "idle_share": {
+                  "type": "number",
+                  "minimum": 0,
+                  "maximum": 1,
+                  "description": "Provisioned lane time no phase occupied."
+                }
+              },
+              "required": [
+                "lane_capacity",
+                "peak_concurrency",
+                "lane_ms_provisioned",
+                "lane_ms_used",
+                "idle_share"
+              ],
+              "additionalProperties": false,
+              "description": "What the run paid for and did not use. A lane is a worktree, a forked database and a desk for a crew member, and a plan that is never as wide as its lane count bought all three for nothing — which is a fact about the graph, not about the machine."
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "interventions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "amendment": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 9007199254740991,
+                "description": "The amendment ordinal, matching the run’s `workflow_amended` history."
+              },
+              "at_ms": {
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991,
+                "description": "When the run amended itself."
+              },
+              "target": {
+                "type": "string",
+                "minLength": 1,
+                "description": "What it changed, as the ledger keys it — `gate:<id>` or `node:<id>`."
+              },
+              "effect": {
+                "type": "string",
+                "enum": [
+                  "cheaper",
+                  "dearer",
+                  "unchanged",
+                  "unmeasured"
+                ],
+                "description": "`cheaper` / `dearer` / `unchanged` compare the gate’s mean uncached duration before and after. `unmeasured` means the journal cannot answer — a phase-level change, or a gate with no runs on one side of the amendment."
+              },
+              "before_ms": {
+                "description": "Mean uncached duration of this gate before the amendment. Absent when unmeasured.",
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991
+              },
+              "after_ms": {
+                "description": "The same, after. Absent when unmeasured.",
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991
+              },
+              "runs_before": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "runs_after": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "record_ref": {
+                "type": "string",
+                "description": "Where the monitor’s own account of this change lives, relative to the run directory. The reasoning, the evidence and the command are prose about a repository and stay there; this artifact carries what can be counted."
+              }
+            },
+            "required": [
+              "amendment",
+              "at_ms",
+              "target",
+              "effect",
+              "record_ref"
+            ],
+            "additionalProperties": false,
+            "description": "One amendment a run made to itself, and what happened to the thing it changed. The effect is a comparison of measured durations, not a claim of cause: a gate that got cheaper across an amendment did so while other things were also changing."
+          },
+          "description": "Amendments the run made to itself (§9.2), oldest first. Empty means it made none, which is a fact rather than a gap: `workflow_amended` rows say who wrote them."
         }
       },
       "required": [
         "unused_dependencies",
         "missing_dependencies",
         "wave_conflicts",
-        "duration_divergences"
+        "gate_costs",
+        "duration_divergences",
+        "critical_path",
+        "idle_capacity",
+        "interventions"
       ],
       "additionalProperties": false
     },
@@ -272,9 +525,12 @@
           "kind": {
             "type": "string",
             "enum": [
+              "blocking_cause_unrecorded",
               "dependency_use_unrecorded",
               "gate_result_unrecorded",
-              "integration_record_unavailable"
+              "gate_durations_unrecorded",
+              "integration_record_unavailable",
+              "intervention_effect_unmeasured"
             ]
           },
           "needs": {
@@ -316,6 +572,15 @@
               "minLength": 1,
               "pattern": "^[a-z0-9][a-z0-9-]*$"
             }
+          },
+          "gates": {
+            "description": "The gates the gap applies to.",
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^[a-z0-9][a-z0-9-]*$"
+            }
           }
         },
         "required": [

package/schemas/workflow.v1.schema.json

@@ -368,6 +368,16 @@
           "minLength": 1,
           "pattern": "^[a-z0-9][a-z0-9-]*$"
         },
+        "chores": {
+          "default": [],
+          "description": "The chores every phase runs unless it names its own. Most chores are run-wide — a comment pass, a changelog entry — and repeating them on every node is how one phase ends up quietly missing one.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          }
+        },
         "max_session_turns": {
           "default": 12,
           "description": "Turns one reused session slot may take before the next spawn starts fresh (§15.5). A shared session only ever grows; without a ceiling a long node eventually dies on a context-window error that reads as a broken harness.",
@@ -504,6 +514,25 @@
             "minimum": 1,
             "maximum": 9007199254740991
           },
+          "tuning": {
+            "type": "object",
+            "properties": {
+              "allowed_flags": {
+                "minItems": 1,
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "description": "Flags the monitor may ADD to this gate’s command, verbatim and whole. Matched as exact argv tokens, so `--reuse-db` permits `--reuse-db` and nothing else — not `--reuse-db-and-more`, and not a flag that merely starts the same way. A flag taking a separate value (`-n auto`) is written as the two tokens it is. Removing or rewriting an existing token is never permitted, whatever is listed here: the proposed command must be this one’s tokens, in order, plus additions."
+              }
+            },
+            "required": [
+              "allowed_flags"
+            ],
+            "additionalProperties": false,
+            "description": "What an autonomous retune of this gate may do. Absent — the default — means the command is not the monitor’s to touch."
+          },
           "description": {
             "type": "string"
           }
@@ -514,6 +543,60 @@
         "additionalProperties": false
       }
     },
+    "chores": {
+      "default": {},
+      "description": "Agent turns a phase runs beside its gates, by id. A gate judges and a chore changes the tree, so they are separate registries — see ChoreSchema.",
+      "type": "object",
+      "propertyNames": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "^[a-z0-9][a-z0-9-]*$"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "prompt": {
+            "description": "The instruction, inline. Exactly one of `prompt` and `prompt_ref` is required.",
+            "type": "string",
+            "minLength": 1
+          },
+          "prompt_ref": {
+            "description": "Where the instruction lives, in `prompt_ref` form (`ai-plans/PLAN.md#deslop`), resolved by the same resolver as a phase brief. Prefer it over `prompt` for anything longer than a sentence: it keeps the text reviewable in the plan rather than in a JSON string.",
+            "type": "string",
+            "minLength": 1
+          },
+          "skill": {
+            "description": "A skill the agent should use, named in the prompt rather than passed as a harness flag — codex and opencode have no skills, and a chore that only works on one harness is a chore that silently does nothing on the other two.",
+            "type": "string",
+            "minLength": 1
+          },
+          "session": {
+            "default": "main",
+            "description": "The session slot this turn continues (§15). `main` — the default — is the implementer’s: the agent that wrote the phase already holds the brief, the diff and its own reasons, and that is most of what makes a chore cheap. A slot no other effect names starts a fresh session every time and pays for a cold context.",
+            "type": "string",
+            "minLength": 1
+          },
+          "model": {
+            "description": "Overrides the model the phase’s implementer would otherwise run at. A mechanical pass does not need the tier the phase was staffed at.",
+            "type": "string",
+            "minLength": 1
+          },
+          "on_failure": {
+            "default": "continue",
+            "description": "`continue` — the default — journals a failed chore and moves on to the gates. A chore is polish, and losing an implemented phase to one that timed out is the worse trade. `fail` is for a chore whose output the phase is not correct without.",
+            "type": "string",
+            "enum": [
+              "continue",
+              "fail"
+            ]
+          },
+          "description": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
     "nodes": {
       "minItems": 1,
       "type": "array",
@@ -583,6 +666,15 @@
               "pattern": "^[a-z0-9][a-z0-9-]*$"
             }
           },
+          "chores": {
+            "description": "The chores this phase runs, in order. Optional rather than defaulted, and that is the whole of its override rule: absent takes `defaults.chores`, and a list — `[]` included — replaces it. Merging instead would leave no way to skip a run-wide chore on the one phase it makes no sense for.",
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^[a-z0-9][a-z0-9-]*$"
+            }
+          },
           "harness": {
             "description": "Overrides defaults.harness.",
             "type": "string",
@@ -680,6 +772,7 @@
                         "enum": [
                           "spawn_agent",
                           "run_gate",
+                          "run_chore",
                           "git_branch",
                           "git_merge",
                           "git_push",
@@ -744,6 +837,7 @@
                         "enum": [
                           "spawn_agent",
                           "run_gate",
+                          "run_chore",
                           "git_branch",
                           "git_merge",
                           "git_push",
@@ -864,6 +958,7 @@
                         "enum": [
                           "spawn_agent",
                           "run_gate",
+                          "run_chore",
                           "git_branch",
                           "git_merge",
                           "git_push",

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

@@ -274,6 +274,10 @@ Each file carries `findings` and `gaps`. Use them like this:
 - **`wave_conflicts`** — two same-wave phases that actually fought, with the contested `paths`. Cross-check those paths against this plan's **Touch List**: two phases of yours touching one of them in the same wave is the same defect repeating. Add the edge, or split so only one phase owns the file.
 - **`duration_divergences`** — `direction: "longer"` means that phase set its wave's wall clock alone, so every peer you parallelised it with bought nothing; keep comparable-size work together and let the long pole start in wave 1. `"shorter"` means a small phase sat behind a long one and could have been folded in or moved earlier. Sizing, never time estimates in the plan body.
 - **`unused_dependencies`** — edges the run proved nobody needed. Drop the equivalent edge here. **Empty is not evidence of a tight graph**: check `gaps` first, because a `dependency_use_unrecorded` entry means dependency use was never measured on that run, not that every edge earned its place.
+- **`gate_costs`** — what each gate actually cost, per gate rather than per phase: `runs`, `cached_runs`, `ran_ms`, `slowest_ms`, `cache_saved_ms`, and the failed and timed-out counts. This is what sizes the **gate pool capacities** you declare. The gate that dominates `ran_ms` is the one whose pool decides the run's wall clock — give that one the capacity and stop widening the others. A gate whose `runs` far exceeds the number of phases that declare it is a fix loop re-paying for the same suite: that is a signal about `max_fix_rounds` or about phases too large to get right in two rounds, not about the gate.
+- **`critical_path`** — the dependency chain that decided how long the run took, each phase with the time it was running, plus `span_ms` and `share_of_elapsed`. **Re-draw the graph against this one.** Shortening any phase *not* on this list changes nothing at all, so a plan that parallelises harder without touching this chain buys nothing. A high `share_of_elapsed` means the graph is deep rather than wide: look for an edge on that chain that is convention rather than a real artifact dependency, and cut it. This is the finding most likely to change a plan's shape.
+- **`idle_capacity`** — what the run paid for and did not use: `lane_capacity` against `peak_concurrency`, and `idle_share` of the provisioned lane time. A lane is a worktree, a forked database and a crew member's desk, so a plan that never got as wide as its lane count bought all three for nothing. `peak_concurrency` well under `lane_capacity` means **this graph cannot use that many lanes** — either declare fewer next time, or find the edges that are serialising work that did not need to be serial. It is a fact about the graph, not about the machine.
+- **`interventions`** — changes the run made to *itself* while it ran, because a watchdog found it paying for something the plan could have stopped it paying for. A `gate:<id>` entry with `effect: "cheaper"` is the useful one: that gate's command or timeout was wrong in the workflow this project keeps emitting, and the run had to discover it at its own expense. **Carry the change forward** — the gate block you emit for this feature should already have it, so the next run does not pay again. The reasoning and the actual command are not in this file (it carries counts, not prose); they are in `interventions.jsonl` beside it in the run directory, which is where to look before copying anything. An `effect: "dearer"` entry is the opposite signal and is worth saying out loud to the human: the run tuned itself in the wrong direction, and whatever it changed should probably not be in the next plan. `unmeasured` means exactly that — the change may have been right or wrong and the run could not tell, so treat it as no evidence rather than as weak evidence.
 
 Rules for using them:
 
@@ -603,6 +607,9 @@ First key in the file is `"$schema"`, pointing at `https://github.com/vintasoftw
 | `resources.lane` | `{"capacity": N, "kind": "worktree"}`. **Required** — a lane pool is where phases are dispatched, and a workflow without one has nowhere to run. `N` = the number of **implementers** on the roster, because each keeps one worktree for the whole run. Reviewers add nothing: they read the lane under review. How many run *at once* is still capped by the graph and by the project's parallel-lane budget (3 when unstated); an implementer idle in wave 1 still has a desk. |
 | `resources.<pool>` | One `{"kind": "semaphore"}` pool per expensive shared thing a gate contends for — the test database, the e2e browser grid, a staging deploy slot. `capacity: 1` when only one can run at a time. |
 | `gates.<id>` | The checks a phase must pass, as **shell commands run in the phase's lane** — the project's real typecheck / test / lint invocations, not an agent and not prose. Give the slow ones `requires` naming the pool they contend for, and a `timeout_s` that is generous rather than tight. |
+| `chores.<id>` | Agent turns a phase runs beside its gates, for work that changes the diff rather than judging it. **Always emit the `deslop` chore below** — it is the comment-hygiene pass, and without it a maestro run has none. Add another only when the plan genuinely needs one (a changelog entry, a translation extraction); a chore is a model turn per phase, so each one has to earn it. |
+| `defaults.chores` | `["deslop"]`. The chores every phase runs unless it names its own. |
+| `nodes[].chores` | **Omit** on almost every phase — absent means the run-wide default. Name a list only to give one phase a different set, and `[]` to opt one out. A list *replaces* the default rather than adding to it. |
 | `nodes[]` | One per phase, in plan order. |
 | `nodes[].id` | `p` + the phase number, lowercased: `Phase 1` → `p1`, `Phase 4a` → `p4a`, `Phase 1b` → `p1b`. |
 | `nodes[].name` | The phase title without its `Phase N —` prefix. |
@@ -622,6 +629,7 @@ Rules the mapping depends on:
 - **`touches` is what the same-wave overlap check reads.** Executors *warn* on two same-wave nodes declaring the same path rather than refusing, so an incomplete Touch List doesn't fail loudly — it fails at merge. Transcribe every file the phase creates or edits, including tests.
 - **Never invent a model id.** Pick the tier from the rubric under "Staff the plan", then read the id out of [resources/ai-models.yaml](resources/ai-models.yaml). Ids drift; tiers don't.
 - **The roster is the same decision as the Crew table.** `crew` transcribes it: one entry per row, `tier` from the Tier column, `model` from that tier in `ai-models.yaml`. A member the table does not list, or a table row with no `crew` entry, means the two were edited separately.
+- **A gate is a command; a chore is an agent.** Both run per phase and that is where the resemblance stops. A gate is a shell line that says pass or fail and decides whether the phase merges. A chore is a turn that *changes* the diff — the comment pass, a changelog entry — and it is never what stands between a phase and its merge: one that fails is recorded and the phase carries on to its gates. Anything you can express as a command belongs in `gates`, where it is cached and queued and costs no model time.
 - **Gate commands must be commands the repo actually runs today.** Read them out of the project's task runner (`package.json` scripts, `Makefile`, `pyproject.toml`, CI config) rather than guessing a conventional one. A gate that doesn't exist fails every phase identically, and looks like a code problem.
 - **The graph must agree with the Execution graph table.** Same nodes, same edges, same waves — they are two renderings of one set of `**Depends on**:` lines, so derive both from the lines rather than transcribing one from the other. A disagreement means one was hand-edited, and the executor flags it.
 - **`plan_context_refs` is anchors, never prose.** It names sections of the plan; it never restates them. A summary written into the JSON is a second copy that drifts the first time someone edits the plan, and the whole point of the field is that the implementer reads what the plan actually says.
@@ -815,7 +823,10 @@ and this `ai-plans/2026-03-04-bookmark-folders.workflow.json`:
   "defaults": {
     "harness": "claude-code",
     "model": "claude-sonnet-5",
-    "pipeline": "standard-phase"
+    "pipeline": "standard-phase",
+    "chores": [
+      "deslop"
+    ]
   },
   "resources": {
     "lane": {
@@ -842,6 +853,13 @@ and this `ai-plans/2026-03-04-bookmark-folders.workflow.json`:
       "timeout_s": 1800
     }
   },
+  "chores": {
+    "deslop": {
+      "skill": "deslop-comments",
+      "prompt": "Rewrite the comments and doc blocks this phase wrote into Simple English, and delete the ones that should not be there. Comment-only: no renames, no logic changes.",
+      "description": "The comment-hygiene pass, on the diff that is about to merge."
+    }
+  },
   "nodes": [
     {
       "id": "p1",
@@ -1041,4 +1059,5 @@ When in doubt, model the plan after a recent example in `ai-plans/` — look for
 - [ ] **`project` decided, not defaulted** — asked via `AskUserQuestion`, then either written (roles `dev` / `test`, each naming its own database, engine fields filled from the project, `migrate_cmd` read out of its task runner) or deliberately omitted because lanes share the main checkout's database. No `reset_cmd`, no compose project name, no seed command, no env-file strategy — those are the worktree's, not the plan's.
 - [ ] No credential anywhere in the workflow file: `connection_url_var` is a variable name, and `server_url` is a host and port.
 - [ ] Model ids come from [resources/ai-models.yaml](resources/ai-models.yaml) and appear **only** in the `crew` block — no node carries a `model`, and `crew` transcribes the Crew table row for row.
+- [ ] `chores` declares `deslop` and `defaults.chores` names it, so every phase's diff gets the comment pass before it is gated. No node carries its own `chores` unless that phase genuinely needs a different set.
 - [ ] `pipelines` is omitted — `defaults.pipeline: standard-phase` is enough, and the executor supplies it.