vinta-ai-workflows 0.7.0-alpha25 → 0.7.0-alpha26

package/CHANGELOG.md

@@ -30,6 +30,95 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **Project defaults for maestro in `.vinta-ai-workflows.yaml`.** A new
+  `maestro:` section holds what every plan's `.workflow.json` used to repeat:
+  per-type gate defaults, resource pools, chores, run defaults and the
+  `project` block. Maestro layers each plan over it. The project's
+  `commands.*` come first, then `maestro.*`, then the plan, then the run's own
+  amendments. A plan now states only what is different, and editing the
+  project file reaches every plan that did not override it.
+  - **Gate types.** A gate with `"type": "test" | "lint" | "typecheck" |
+    "e2e"` takes its command from `maestro.gates.<type>`, else from
+    `commands.test_unit` / `lint` / `build` / `e2e`. A `maestro.gates.<type>.cmd`
+    gives maestro its own line, and `implement-plan` keeps running
+    `commands.*`. Every type the project has a command for is available under
+    the type's name, so a node can list `["typecheck", "test"]` with no gate
+    table.
+  - **`defaults.gates`**, the gates every phase runs unless it names its own.
+    `defaults.harness` and `defaults.pipeline` now default to `claude-code`
+    and `standard-phase`, and `base_branch` defaults to
+    `project.default_branch`.
+  - **The bootstrap asks for these** (interview item C.11) and writes the
+    section. `plan-feature` reads it and emits only plan-specific values.
+- **Scoped and full gates.** A gate can carry a `scoped_cmd` with
+  `{changed_files}` / `{touches}`. Phase gates run it, and the full `cmd` runs
+  once on each wave's merged tree. A failure there is a regression between
+  phases, and it fails the merge (`defaults.gate_scope: scoped`, the default;
+  `full` runs `cmd` everywhere). `commands.test_unit_scoped` and the new
+  `commands.lint_scoped` are inherited as scoped commands when they contain a
+  placeholder. `implement-plan`'s scoped suite fills the same placeholders.
+- **Every maestro run works on a plan branch, `plan/<workflow-id>/base`.**
+  It is cut from `base_branch` at start, and phases and waves build on it.
+  Pull requests still target `base_branch`. Commit a change to
+  `.vinta-ai-workflows.yaml` or the plan's `.workflow.json` on that branch,
+  and the running plan picks it up as a `config` amendment that names the
+  commit. A config change never undoes a change an operator or the monitor
+  made in the run, never rewrites a phase that has started, and ships with
+  the plan's PR. `run` warns when the checkout's config file differs from
+  what is committed on the plan branch.
+- **The gate guard.** On claude-code, every maestro agent gets a
+  `PreToolUse` hook, in every permission mode, through the per-lane settings
+  file only. It refuses two things: a gate's full command typed by hand
+  (answer: `vinta-ai-maestro gate <id>`), and a command matching a pool's new
+  `match` patterns when run without the lease (answer:
+  `vinta-ai-maestro with <pool> --`). Refusals are journalled as
+  `bare_gate_blocked`. The hook fails open and never auto-approves anything.
+  On codex and opencode a matching command is recorded after the fact as
+  `bare_gate_detected`. `doctor` reports which you get as
+  `gate-guard:<harness>`.
+
+- **Provision worktrees with your own script instead of the `prepare-worktree`
+  skill.** Set `commands.worktree_prepare` in `.vinta-ai-workflows.yaml` (and
+  optionally `commands.worktree_teardown`), and `implement-plan` runs that
+  command for the shared worktree, every lane and the integration worktree.
+  No LLM step and no `agent_models.worktree_prep` delegate are involved.
+  Worktrees, and therefore parallel phases, are now available when the skill
+  is enabled **or** the command is set. When both are set the command wins,
+  and the skill is offered as a fallback if the command fails.
+  - **The contract.** The command runs from the repo root with
+    `VINTA_WORKTREE_NAME`, `_PATH`, `_BRANCH`, `_BASE_REF`, `_KIND`
+    (`single` | `lane` | `integration`), `VINTA_MAIN_CHECKOUT`,
+    `VINTA_PLAN_PATH` and `VINTA_WORKTREE_SUMMARY` set. It must create a
+    runnable worktree at that path, on that new branch, and exit non-zero on
+    failure. The conductor then checks the result with git rather than
+    trusting the exit code: the right branch, the worktree registered, and
+    the main checkout's status unchanged. Writing the summary YAML is
+    optional. A summary carrying `reset_cmd`s lets a lane be reused across a
+    migration boundary. Without one the lane is re-provisioned (teardown,
+    then prepare again) instead. Lanes are provisioned one at a time, because
+    the command runs `git worktree add` itself.
+  - **Sandbox tier.** The conductor probes the tier itself. With the skill
+    disabled, its `sandbox-run.sh` is not installed, so the tier is `none` and
+    the review-phase stray-write check is the guard.
+  - **Bootstrap.** The `prepare-worktree` question gains a
+    `Yes — we provision with our own script/command` option.
+    `vinta-analyze-codebase` now records existing worktree scripts in
+    `commands.worktree_candidates`, and the interview offers them as the
+    command. Existing configs need no change.
+  - **The bootstrap can write the script for you.** A fourth answer,
+    `Yes — generate a provisioning script for this project`, adds an optional
+    step after `vinta-derive-skills`. It writes `prepare.sh`, `teardown.sh`
+    and a shared `lib.sh` (default `scripts/worktree/`) from bundled
+    templates, and points `commands.worktree_prepare` / `_teardown` at them.
+    The templates carry the contract: `--dry-run`, sanity checks, rollback of
+    a half-made worktree, generic compose isolation, the full summary YAML,
+    and a teardown that refuses a dirty worktree, drops only `*_wt_<name>`
+    databases and never runs `down -v`. They also refuse to fork or drop a
+    database on a non-local host. The bootstrap fills only the project's
+    dependency, env, database and service steps from the inventory, then
+    verifies with `bash -n`, a dry run, and an optional real smoke test. The
+    scripts are the project's to commit and edit; humans can run
+    `prepare.sh <name>` / `teardown.sh <name>` directly too.
 - **Agents stop for input with clickable questions instead of prose.** When a
   skill or a sub-agent needs a decision from you, it now asks through your
   harness's structured question tool, so you get the options as buttons plus
@@ -294,6 +383,17 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Changed
 
+- **Maestro: every `workflow_amended` row carries `targets`.** Operator and
+  config amendments get them too, computed from the snapshot and the
+  proposal. Before, only monitor amendments had them.
+- **Maestro: a gate command can be amended after a phase that uses it is
+  done.** Changing a gate table no longer counts as rewriting a finished
+  phase. Before, such an amendment was refused as `body_changed_after_done`.
+- **Maestro: the editor saves only what you changed.** It shows the workflow
+  resolved over the project config, and on save it writes back only the
+  edited values. A first save no longer copies every default, or the
+  project's values, into the plan file.
+
 - **Maestro: the node view's right-hand column stays short.** Gate logs open
   in a dialog instead of an inline accordion. The dialog opens at the end of
   the log, keeps up with a running gate's output, numbers the lines, and has
@@ -393,6 +493,35 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **Maestro: wave merges again use the membership the executor counted.**
+  `RecordingIntegrator.mergeWave` dropped it, so in production a merge fell
+  back to the integrator's own reading of the wave. That reading could differ
+  from the count if an amendment landed in between.
+- **Maestro: the gate run on a conflict resolution uses the amended gate
+  commands.** It used the workflow from the start of the run.
+- **Maestro: the API serves a run's definition as amended.** It cached the
+  snapshot forever, so a monitor retune made in the run's own process never
+  reached the UI.
+- **Maestro: an editor save from `ui` now reaches the run's job.** `ui`
+  is a separate process from the job hosting a run. A save to a running
+  plan's workflow used to replace the run's frozen snapshot from `ui` with no
+  runner: nothing adopted the change, and an amendment that needed a rebase
+  was refused. The job kept running the old definition until a resume. The
+  save is now sent to the job (`POST /api/runs/<id>/amend`), which applies it
+  under the usual amend rules, and `ui` writes the plan file only once the
+  job has accepted it. If the job does not answer, the save is refused
+  (`run_host_unreachable`) and nothing is written.
+- **Maestro: saving in the editor during a run no longer reports a failure.**
+  The amendment response failed the client's schema check even though the
+  save had gone through.
+
+- **`implement-plan`'s final report no longer suggests `docker compose down -v`
+  to tear down a lane.** `down -v` also deletes the compose volumes a worktree
+  deliberately shares with the main checkout (`shared_volumes`, such as a
+  dependency cache). The report now prints the same sequence the
+  `prepare-worktree` skill documents: `docker compose -p <project> down`, then
+  `docker volume rm` for each volume the worktree forked, then removal of the
+  generated compose override.
 - **`open-pr.sh` posts inline comments on macOS and reports why a comment
   failed.** Four bugs in the `open-pr-from-context` script, all seen while
   publishing a stacked plan from a Mac:

package/package.json

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

package/schemas/README.md

@@ -6,7 +6,7 @@ JSON Schema (Draft 2020-12) contracts for every YAML or JSON payload the vinta-a
 
 | Artifact | YAML location in target project | Schema file | Authored by | Read by |
 |---|---|---|---|---|
-| Project config | `.vinta-ai-workflows.yaml` (repo root) | [`vinta-ai-workflows-config.v1.schema.json`](vinta-ai-workflows-config.v1.schema.json) | `vinta-bootstrap-ai-tools` (initial) → `vinta-sync-ai-tools` (updates) | every builder skill, every template render, every meta-skill |
+| Project config | `.vinta-ai-workflows.yaml` (repo root) | [`vinta-ai-workflows-config.v1.schema.json`](vinta-ai-workflows-config.v1.schema.json) | `vinta-bootstrap-ai-tools` (initial) → `vinta-sync-ai-tools` (updates) | every builder skill, every template render, every meta-skill ; `vinta-ai-maestro` reads `commands` + `maestro` and layers every workflow over them |
 | Sub-agent definition | `ai-tools/agents/<name>.yaml` | [`sub-agent.v1.schema.json`](sub-agent.v1.schema.json) | `vinta-derive-subagents` | `setup-ai-tools.mjs` (emits per-vendor copies) |
 | PR-context frontmatter | top-of-file YAML in `.vinta-ai-workflows/prs-context/{feature-kebab}/phase-{phase.id}.md` | [`prs-context-frontmatter.v1.schema.json`](prs-context-frontmatter.v1.schema.json) | `implement-plan` / `amend-plan` | `open-pr.sh` |
 | PR-context inline comments | YAML inside the ` ```yaml ... ``` ` fence under `# Comments` of the same file | [`prs-context-comments.v1.schema.json`](prs-context-comments.v1.schema.json) | `implement-plan` / `amend-plan` | `open-pr.sh` |

package/schemas/vinta-ai-workflows-config.v1.schema.json

@@ -69,20 +69,35 @@
       "properties": {
         "lint": { "type": "string" },
         "format": { "type": "string" },
+        "lint_scoped": {
+          "description": "Lint narrowed to what a phase changed, as a template with `{changed_files}` or `{touches}` (e.g. `pnpm eslint {changed_files}`). `vinta-ai-maestro` inherits it as the `scoped_cmd` of `lint`-typed gates; see `test_unit_scoped` for how the placeholders are filled.",
+          "type": "string",
+          "minLength": 1
+        },
         "build": {
           "description": "Type-check / build gate. Often the same as the test command on Python projects.",
           "type": "string"
         },
         "test_unit": { "type": "string" },
         "test_unit_scoped": {
-          "description": "Per-package or per-app scoped suite (e.g. `pnpm test:patient`).",
+          "description": "Per-package or per-app scoped suite (e.g. `pnpm test:patient`). `implement-plan` reads it as guidance for the outer gate's scoped run. When it contains `{changed_files}` (the files the phase changed against its base) or `{touches}` (the phase's Touch List), it is also a template: `implement-plan` substitutes them, and `vinta-ai-maestro` inherits it as the `scoped_cmd` of `test`-typed gates — e.g. `pnpm vitest related {changed_files} --run`. A line without a placeholder is not inherited by maestro, which has no agent to decide what to scope it to.",
           "type": "string"
         },
         "test_unit_new_pattern": {
           "description": "Pattern for running a single new test file in isolation. Use placeholders like `<pkg>` / `<new-test-path>`.",
           "type": "string"
         },
-        "e2e": { "type": "string" }
+        "e2e": { "type": "string" },
+        "worktree_prepare": {
+          "description": "The project's own command for provisioning a runnable git worktree, used by `implement-plan` / `amend-plan` **instead of** the `prepare-worktree` skill. Set it when the team already has a script (`bin/new-worktree`, a Makefile target, `git gtr new`, …) or wants deterministic, LLM-free provisioning. Worktrees are available to the plan-execution family when this is set **or** `foundation_skills.prepare-worktree` is `enabled`; when both are set the command wins and the skill is offered as a fallback if the command fails. Runs from the main checkout root with `VINTA_WORKTREE_NAME`, `VINTA_WORKTREE_PATH`, `VINTA_WORKTREE_BRANCH`, `VINTA_WORKTREE_BASE_REF`, `VINTA_WORKTREE_KIND` (`single` | `lane` | `integration`), `VINTA_MAIN_CHECKOUT`, `VINTA_PLAN_PATH` and `VINTA_WORKTREE_SUMMARY` in its environment. It MUST create a worktree at `VINTA_WORKTREE_PATH` on a new branch `VINTA_WORKTREE_BRANCH` based on `VINTA_WORKTREE_BASE_REF`, and exit 0 only when that worktree is runnable. It MAY write the summary YAML at `VINTA_WORKTREE_SUMMARY` (the shape `prepare-worktree` writes); a summary carrying `reset_cmd`s lets a lane be reused across a migration boundary, and without one the conductor re-provisions the lane instead. The full contract is in the rendered `implement-plan` skill (Step 0.5). The bootstrap can generate a conforming `prepare.sh` / `teardown.sh` pair for the project (its `prepare-worktree` question, option `generate a provisioning script`).",
+          "type": "string",
+          "minLength": 1
+        },
+        "worktree_teardown": {
+          "description": "Optional counterpart to `worktree_prepare`: removes a worktree the prepare command created, plus any state it made outside git (forked DBs, compose volumes, caches). Receives the same `VINTA_WORKTREE_*` environment. Used when a lane is re-provisioned mid-run, when the user cancels at the worktree confirmation gate, and in the teardown commands the final report prints (never auto-run at the end of a run). Unset → teardown is `git worktree remove <path>`, which leaks anything the prepare command created outside the worktree; set it whenever the prepare command forks databases or volumes. Ignored when `worktree_prepare` is unset.",
+          "type": "string",
+          "minLength": 1
+        }
       }
     },
     "policies": {
@@ -209,7 +224,7 @@
           "enum": ["enabled", "disabled"]
         },
         "prepare-worktree": {
-          "description": "Provision a fully-runnable git worktree for parallel feature work — gives each worktree its own copy of the dep dirs, copies env files, forks dev / test DBs, namespaces docker-compose project + network, drops a summary YAML for mechanical teardown. Copy-verbatim foundation skill (bucket A). When `enabled`, project-level defaults (worktree root, deps strategy, compose network strategy) live under `skills.prepare-worktree`. Consumed by `implement-plan` when its Step 0 question (c) opts in — the orchestrator runs `prepare-worktree` once at the start of a plan run and threads the worktree path through every subagent's prompt so phases all stack inside the same isolated checkout.",
+          "description": "Provision a fully-runnable git worktree for parallel feature work — gives each worktree its own copy of the dep dirs, copies env files, forks dev / test DBs, namespaces docker-compose project + network, drops a summary YAML for mechanical teardown. Copy-verbatim foundation skill (bucket A). When `enabled`, project-level defaults (worktree root, deps strategy, compose network strategy) live under `skills.prepare-worktree`. Consumed by `implement-plan` when its Step 0 question (c) opts in — the orchestrator runs `prepare-worktree` once at the start of a plan run and threads the worktree path through every subagent's prompt so phases all stack inside the same isolated checkout. Set `disabled` when the project provisions worktrees with its own command instead (`commands.worktree_prepare`) — worktrees stay available to `implement-plan` either way.",
           "type": "string",
           "enum": ["enabled", "disabled"]
         },
@@ -280,7 +295,7 @@
           "maximum": 4
         },
         "worktree_prep": {
-          "description": "Tier for the mechanical worktree-provisioning step (`prepare-worktree`), which `implement-plan` / `amend-plan` run once at the start of a worktree-enabled run. When set, the conductor delegates the step to a subagent at this tier instead of running it inline in its own (usually pricier) session. Mechanical, precedent-driven work — Tier 1 is the usual default. Unset → conductor runs it inline. Irrelevant when `foundation_skills.prepare-worktree` is `disabled`.",
+          "description": "Tier for the mechanical worktree-provisioning step (`prepare-worktree`), which `implement-plan` / `amend-plan` run once at the start of a worktree-enabled run. When set, the conductor delegates the step to a subagent at this tier instead of running it inline in its own (usually pricier) session. Mechanical, precedent-driven work — Tier 1 is the usual default. Unset → conductor runs it inline. Irrelevant when `foundation_skills.prepare-worktree` is `disabled`, and when `commands.worktree_prepare` is set — a shell command needs no model, so the conductor runs it directly.",
           "type": "integer",
           "minimum": 1,
           "maximum": 4
@@ -307,6 +322,314 @@
       "uniqueItems": true,
       "default": []
     },
+    "maestro": {
+      "description": "Project-wide defaults for `vinta-ai-maestro` runs, layered UNDER every plan's `ai-plans/*.workflow.json`: a plan's own value wins, and a run's mid-run amendments win over both. Maps keyed by id (`resources`, `chores`, `project.databases`, `project.services`) merge per id with the plan's entry replacing the project's whole; a typed gate merges field by field; lists replace. Shapes are the workflow schema's (`workflow.v1.schema.json`) — maestro validates them strictly at load. A run follows its plan branch (`plan/<workflow-id>/base`): committing a change to this file on that branch applies it to the live run. Absent: every plan carries everything itself.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "defaults": {
+          "description": "Run defaults a plan's `defaults` overrides field by field: `harness`, `model`, `pipeline`, `chores`, `gates` (the gate ids every phase runs unless it names its own), `gate_scope` (`scoped` | `full`), `reviewer_model`, `max_session_turns`.",
+          "type": "object",
+          "properties": {
+            "harness": {
+              "type": "string",
+              "enum": [
+                "claude-code",
+                "codex",
+                "opencode"
+              ]
+            },
+            "model": {
+              "type": "string",
+              "minLength": 1
+            },
+            "pipeline": {
+              "type": "string",
+              "pattern": "^[a-z0-9][a-z0-9-]*$"
+            },
+            "chores": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[a-z0-9][a-z0-9-]*$"
+              }
+            },
+            "gates": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[a-z0-9][a-z0-9-]*$"
+              }
+            },
+            "gate_scope": {
+              "type": "string",
+              "enum": [
+                "scoped",
+                "full"
+              ]
+            },
+            "reviewer_model": {
+              "type": "string",
+              "minLength": 1
+            },
+            "max_session_turns": {
+              "type": "integer",
+              "minimum": 1
+            }
+          },
+          "additionalProperties": false
+        },
+        "gates": {
+          "description": "Per gate type. Each type with a command is also available to every plan under the type's own name (`gates: [typecheck, test]` on a node, with no gate table).",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "test": {
+              "description": "Defaults a gate of this type inherits, over the matching `commands.*` line. Any field a plan's own gate sets wins over these.",
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "cmd": {
+                  "description": "The full check maestro runs for this type. Overrides the `commands.*` line for maestro only — `implement-plan` keeps running `commands.*`.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "scoped_cmd": {
+                  "description": "The check narrowed to what a phase changed, with `{changed_files}` and/or `{touches}`. Run by phase gates under `gate_scope: scoped`; the full `cmd` runs once on each wave's merged tree.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "requires": {
+                  "description": "Resource pools the gate holds while it runs, e.g. `[test-suite]`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "pattern": "^[a-z0-9][a-z0-9-]*$"
+                  }
+                },
+                "timeout_s": {
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "tuning": {
+                  "description": "Flags the monitor may add to `cmd` when it retunes the gate mid-run. Same shape as a workflow gate's `tuning`.",
+                  "type": "object",
+                  "properties": {
+                    "allowed_flags": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "minItems": 1
+                    }
+                  },
+                  "required": [
+                    "allowed_flags"
+                  ],
+                  "additionalProperties": false
+                }
+              }
+            },
+            "lint": {
+              "description": "Defaults a gate of this type inherits, over the matching `commands.*` line. Any field a plan's own gate sets wins over these.",
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "cmd": {
+                  "description": "The full check maestro runs for this type. Overrides the `commands.*` line for maestro only — `implement-plan` keeps running `commands.*`.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "scoped_cmd": {
+                  "description": "The check narrowed to what a phase changed, with `{changed_files}` and/or `{touches}`. Run by phase gates under `gate_scope: scoped`; the full `cmd` runs once on each wave's merged tree.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "requires": {
+                  "description": "Resource pools the gate holds while it runs, e.g. `[test-suite]`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "pattern": "^[a-z0-9][a-z0-9-]*$"
+                  }
+                },
+                "timeout_s": {
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "tuning": {
+                  "description": "Flags the monitor may add to `cmd` when it retunes the gate mid-run. Same shape as a workflow gate's `tuning`.",
+                  "type": "object",
+                  "properties": {
+                    "allowed_flags": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "minItems": 1
+                    }
+                  },
+                  "required": [
+                    "allowed_flags"
+                  ],
+                  "additionalProperties": false
+                }
+              }
+            },
+            "typecheck": {
+              "description": "Defaults a gate of this type inherits, over the matching `commands.*` line. Any field a plan's own gate sets wins over these.",
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "cmd": {
+                  "description": "The full check maestro runs for this type. Overrides the `commands.*` line for maestro only — `implement-plan` keeps running `commands.*`.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "scoped_cmd": {
+                  "description": "The check narrowed to what a phase changed, with `{changed_files}` and/or `{touches}`. Run by phase gates under `gate_scope: scoped`; the full `cmd` runs once on each wave's merged tree.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "requires": {
+                  "description": "Resource pools the gate holds while it runs, e.g. `[test-suite]`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "pattern": "^[a-z0-9][a-z0-9-]*$"
+                  }
+                },
+                "timeout_s": {
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "tuning": {
+                  "description": "Flags the monitor may add to `cmd` when it retunes the gate mid-run. Same shape as a workflow gate's `tuning`.",
+                  "type": "object",
+                  "properties": {
+                    "allowed_flags": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "minItems": 1
+                    }
+                  },
+                  "required": [
+                    "allowed_flags"
+                  ],
+                  "additionalProperties": false
+                }
+              }
+            },
+            "e2e": {
+              "description": "Defaults a gate of this type inherits, over the matching `commands.*` line. Any field a plan's own gate sets wins over these.",
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "cmd": {
+                  "description": "The full check maestro runs for this type. Overrides the `commands.*` line for maestro only — `implement-plan` keeps running `commands.*`.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "scoped_cmd": {
+                  "description": "The check narrowed to what a phase changed, with `{changed_files}` and/or `{touches}`. Run by phase gates under `gate_scope: scoped`; the full `cmd` runs once on each wave's merged tree.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "requires": {
+                  "description": "Resource pools the gate holds while it runs, e.g. `[test-suite]`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "pattern": "^[a-z0-9][a-z0-9-]*$"
+                  }
+                },
+                "timeout_s": {
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "tuning": {
+                  "description": "Flags the monitor may add to `cmd` when it retunes the gate mid-run. Same shape as a workflow gate's `tuning`.",
+                  "type": "object",
+                  "properties": {
+                    "allowed_flags": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "minItems": 1
+                    }
+                  },
+                  "required": [
+                    "allowed_flags"
+                  ],
+                  "additionalProperties": false
+                }
+              }
+            }
+          }
+        },
+        "resources": {
+          "description": "Capacity pools by id, e.g. a `test-suite` semaphore. `match` lists command patterns (`pytest*`) an agent must run under `vinta-ai-maestro with <pool> --`.",
+          "type": "object",
+          "propertyNames": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "required": [
+              "capacity",
+              "kind"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "capacity": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "kind": {
+                "type": "string",
+                "enum": [
+                  "worktree",
+                  "semaphore"
+                ]
+              },
+              "match": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "description": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "chores": {
+          "description": "Chore definitions by id (`prompt` or `prompt_ref`, `skill`, `session`, `model`, `when`, `on_failure`) — the workflow schema's `chores` entries.",
+          "type": "object",
+          "propertyNames": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          },
+          "additionalProperties": {
+            "type": "object"
+          }
+        },
+        "project": {
+          "description": "The workflow schema's `project` block (`migrate_cmd`, `databases`, `env_files`, `commands`, `hooks`, `services`, `compose`, `prepare_cmd`, `setup_cmd`), merged under a plan's own field by field. `project.commands` additionally inherits `lint`, `typecheck` (from `commands.build`) and `test` (from `commands.test_unit`).",
+          "type": "object"
+        }
+      }
+    },
     "run_options": {
       "description": "Per-skill run-option defaults. Skills override via per-invocation prompts; values here are the defaults shown.",
       "type": "object",
@@ -324,12 +647,12 @@
               "default": false
             },
             "use_worktree": {
-              "description": "Default answer to Step 0 question (c) — whether `implement-plan` should provision isolated git worktrees (via `prepare-worktree`) and run phase subagents inside them. False = run in the current checkout. True = provision at the start of the plan run: one shared worktree for a sequential run, or one lane per concurrent phase plus an integration worktree when `parallel_phases` is on. Per-run prompt still asks; this is the suggested default shown.",
+              "description": "Default answer to Step 0 question (c) — whether `implement-plan` should provision isolated git worktrees (via `commands.worktree_prepare` when set, else the `prepare-worktree` skill) and run phase subagents inside them. False = run in the current checkout. True = provision at the start of the plan run: one shared worktree for a sequential run, or one lane per concurrent phase plus an integration worktree when `parallel_phases` is on. Per-run prompt still asks; this is the suggested default shown.",
               "type": "boolean",
               "default": false
             },
             "parallel_phases": {
-              "description": "Default answer to Step 0 question (e) — whether `implement-plan` implements independent phases concurrently, one git worktree lane per in-flight phase. The plan's per-phase `**Depends on**:` lines define the graph; a phase starts as soon as every phase it depends on is green. True (default) = run in parallel whenever the graph has a wave wider than one phase. False = one phase at a time. Requires `foundation_skills.prepare-worktree` enabled and `use_worktree` resolving true — several agents cannot share one working tree — and `implement-plan` refuses rather than silently degrading when that is not the case. Per-run prompt still asks; this is the suggested default shown.",
+              "description": "Default answer to Step 0 question (e) — whether `implement-plan` implements independent phases concurrently, one git worktree lane per in-flight phase. The plan's per-phase `**Depends on**:` lines define the graph; a phase starts as soon as every phase it depends on is green. True (default) = run in parallel whenever the graph has a wave wider than one phase. False = one phase at a time. Requires worktrees to be available (`foundation_skills.prepare-worktree` enabled or `commands.worktree_prepare` set) and `use_worktree` resolving true — several agents cannot share one working tree — and `implement-plan` refuses rather than silently degrading when that is not the case. Per-run prompt still asks; this is the suggested default shown.",
               "type": "boolean",
               "default": true
             },
@@ -421,7 +744,7 @@
           }
         },
         "prepare-worktree": {
-          "description": "Configuration for the `prepare-worktree` foundation skill. Optional when `foundation_skills.prepare-worktree` is `enabled` — every field has a sensible default. Consumed by the skill at runtime to bias the per-worktree copy-vs-reinstall-vs-fork decisions.",
+          "description": "Configuration for the `prepare-worktree` foundation skill. Optional when `foundation_skills.prepare-worktree` is `enabled` — every field has a sensible default. Consumed by the skill at runtime to bias the per-worktree copy-vs-reinstall-vs-fork decisions. When the project provisions with `commands.worktree_prepare` instead, the plan-execution conductor still reads `worktree_root` and `summary_dir` from here to compute `VINTA_WORKTREE_PATH` / `VINTA_WORKTREE_SUMMARY`; the other fields are skill-only and ignored.",
           "type": "object",
           "additionalProperties": false,
           "properties": {