vinta-ai-workflows 0.7.0-alpha8 → 0.7.0

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": {
@@ -120,13 +135,13 @@
           "type": "string"
         },
         "dependency_licenses": {
-          "description": "Third-party dependency license policy. Captured at bootstrap; rendered into the repo-root `AGENTS.md` (`## Dependency licenses` section) and the `implement-plan` / `amend-plan` skill bodies so the implementer / reviewer agents check a new dep's SPDX license against `forbidden_spdx` before running any install command (`npm add`, `pnpm add`, `pip install`, `poetry add`, `uv add`, `cargo add`, `go get`, etc.). When `enforcement: block`, the agent must refuse the install and surface the violation to the user; `warn` records the violation in the phase report but proceeds; `off` skips the check entirely.",
+          "description": "Third-party dependency license policy. Captured at bootstrap; rendered into the repo-root `AGENTS.md` (`## Dependency licenses` section) and the `implement-plan` / `amend-plan` skill bodies so the implementer agent checks a new dep's SPDX license against `forbidden_spdx` before running any install command (`npm add`, `pnpm add`, `pip install`, `poetry add`, `uv add`, `cargo add`, `go get`, etc.). When `enforcement: block`, the agent must refuse the install and surface the violation to the user; `warn` records the violation in the phase report but proceeds; `off` skips the check entirely.",
           "type": "object",
           "required": ["enforcement", "forbidden_spdx"],
           "additionalProperties": false,
           "properties": {
             "enforcement": {
-              "description": "How the implementer / reviewer agents react when a new dep's license is in `forbidden_spdx`. `block` (default) — refuse install, ask user to confirm override before proceeding. `warn` — proceed but flag in the phase report. `off` — skip the check.",
+              "description": "How the implementer agent reacts when a new dep's license is in `forbidden_spdx`. `block` (default) — refuse install, ask user to confirm override before proceeding. `warn` — proceed but flag in the phase report. `off` — skip the check.",
               "type": "string",
               "enum": ["block", "warn", "off"],
               "default": "block"
@@ -139,7 +154,7 @@
               "default": ["GPL-2.0-only", "GPL-3.0-only", "AGPL-3.0-only", "SSPL-1.0"]
             },
             "allowed_overrides": {
-              "description": "Explicit per-package exceptions to `forbidden_spdx`. Each entry whitelists one package + license pair the team has accepted (legal review, dual-license clause, in-house carve-out). The implementer agent skips the block when the candidate package + license matches an entry; the reviewer agent treats the entry as load-bearing context (don't silently drop).",
+              "description": "Explicit per-package exceptions to `forbidden_spdx`. Each entry whitelists one package + license pair the team has accepted (legal review, dual-license clause, in-house carve-out). The implementer agent skips the block when the candidate package + license matches an entry, and treats the entry as load-bearing context (never silently drops it).",
               "type": "array",
               "items": {
                 "type": "object",
@@ -209,17 +224,27 @@
           "enum": ["enabled", "disabled"]
         },
         "prepare-worktree": {
-          "description": "Provision a fully-runnable git worktree for parallel feature work — symlinks 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"]
         },
         "thermo-nuclear-code-quality-review": {
-          "description": "Opt-in deep structural-maintainability audit of a diff — abstraction quality, giant files, spaghetti-condition growth — harsher than the standard per-phase review. Copy-verbatim foundation skill (bucket A). Read-only; hands each fix to the `fixer` agent. Invoked deliberately by the user, or escalated from the `review-phase` Layer 3 structural-simplification lens; never auto-run on every diff.",
+          "description": "Opt-in deep structural-maintainability audit of a diff — abstraction quality, giant files, spaghetti-condition growth — harsher than the standard per-phase review. Copy-verbatim foundation skill (bucket A). Read-only; hands each fix to the `fixer` agent. Invoked deliberately by the user; never auto-run on every diff. The per-phase review (`thermo-nuclear-review-loop`) already applies a structural-simplification lens; this skill is the deliberate deep audit.",
+          "type": "string",
+          "enum": ["enabled", "disabled"]
+        },
+        "thermo-nuclear-review-loop": {
+          "description": "Review-and-fix loop over a change: the running agent spawns one reviewer sub-agent, verifies its findings, fixes the justified ones and answers the rest, until the reviewer explicitly approves under a strict code-quality standard. Copy-verbatim foundation skill (bucket A), always shipped: it is the per-phase review on both execution paths. The `review-phase` skill runs it over each phase `implement-plan`, `amend-plan` and `systematic-debugging` produce, with the conductor as the loop's host; and every `vinta-ai-maestro` workflow `plan-feature` writes names it in its `review` chore, which runs on the implementer's session once a phase's gates are green. Set `disabled` only if a project deliberately opts out of phase review.",
+          "type": "string",
+          "enum": ["enabled", "disabled"]
+        },
+        "interview-ui": {
+          "description": "Run decision-heavy interviews (create-spec Step 0 today) as a full-screen browser form instead of a chat exchange: one decision per screen with context, Markdown/Mermaid explainers, and per-option consequences; the in-page chat is for questions to the agent, not decisions. Copy-verbatim foundation skill (bucket A), opt-in. The server and the page are `vinta-ai-maestro interview` (`start` / `wait` / `status` / `stop`; Node ≥ 22), rendered with maestro's design system. Rounds and answers are JSON (`interview-round.v1` / `interview-answers.v1`) under `.vinta-ai-workflows/interviews/<slug>/`. When `enabled`, `create-spec` offers the browser surface at the start of its interview.",
           "type": "string",
           "enum": ["enabled", "disabled"]
         },
         "deslop-comments": {
-          "description": "Rewrite comments and doc blocks touched during the current task into Simple English — strip AI-slop vocabulary and negative framing, comment-only (no renames, no behavior change). Copy-verbatim foundation skill (bucket A), always shipped: the `review-phase` Layer 2 comment-hygiene check and fix loop depend on it. Set `disabled` only if a project deliberately opts out of the review flow's comment-hygiene step.",
+          "description": "Rewrite comments and doc blocks touched during the current task into Simple English — strip AI-slop vocabulary and negative framing, comment-only (no renames, no behavior change). Copy-verbatim foundation skill (bucket A), always shipped: `vinta-ai-maestro`'s `deslop` chore runs it on every phase once the review approves, and `integrate-phase` / `amend-plan` run it over the PR-context prose they write. Set `disabled` only if a project deliberately opts out of both comment passes.",
           "type": "string",
           "enum": ["enabled", "disabled"]
         },
@@ -250,25 +275,38 @@
         "fixer": { "type": "string", "enum": ["enabled", "disabled"] }
       }
     },
+    "integrations": {
+      "description": "Per-integration opt-in for external tools that ship their own skills, as opposed to foundation skills this package bundles. An integration's skill is installed by that tool's own CLI into `ai-tools/skills/<name>/`, carries the tool's own ownership marker, and is never copied, rendered or refreshed by `vinta-derive-skills` / `vinta-update-project-skills`. Use `enabled` / `disabled`; `disabled` is a sticky opt-out, as for `foundation_skills`. Absent means the integration was never offered (projects bootstrapped before it existed).",
+      "type": "object",
+      "additionalProperties": { "type": "string", "enum": ["enabled", "disabled"] },
+      "properties": {
+        "pr-review-canvas": {
+          "description": "PR Review Canvas (`@vintasoftware/pr-review-canvas`, CLI `pr-review`): a topic-grouped review canvas for each PR, posted as a PR comment and read in a local review app. When `enabled`: `vinta-install-ai-tools-setup` runs `pr-review install-skill` into `ai-tools/skills/` (the CLI itself is a global install the user does, never auto-installed); the `integrate-phase` PR step runs the `pr-review-canvas` skill after `open-pr.sh` publishes a PR; and `plan-feature` adds an `after_pr` `review-canvas` chore to the maestro workflow it writes. Posting the canvas comment follows the tool's own `sharing.canvasComment` setting in `pr-review.config.yml`.",
+          "type": "string",
+          "enum": ["enabled", "disabled"]
+        }
+      }
+    },
     "agent_models": {
-      "description": "Per-role / per-task model selection for the plan-execution family, expressed as **tiers** (1–4) into the same table `plan-feature` uses — `ai-tools/skills/plan-feature/resources/ai-models.yaml`. Each consuming skill resolves a tier to a concrete model at runtime: take that tier's `models`, filter to the vendors the runtime exposes, pick the cheapest survivor. This keeps the config free of hard-coded model IDs (which go stale) — the nightly `check-ai-models` job keeps the tier table fresh. Every key is optional; an unset key (or the whole section absent) means the spawn uses the runtime's default model, i.e. today's behavior. These are the **project defaults**: the `reviewer` / `fixer` tiers here can be overridden per phase by a plan's optional `**Review models**:` line (a phase override wins over the value here for that phase only — see `plan-feature`). The per-phase implementer model is NOT here — that stays owned by each plan phase's `**Suggested AI model**:` line. The mechanical steps (`worktree_prep`, `integrate`) are never plan-named.",
+      "description": "Per-role / per-task model selection for the plan-execution family, expressed as **tiers** (1–4) into the same table `plan-feature` uses — `ai-tools/skills/plan-feature/resources/ai-models.yaml`. Each consuming skill resolves a tier to a concrete model at runtime: take that tier's `models`, filter to the vendors the runtime exposes, pick the cheapest survivor. This keeps the config free of hard-coded model IDs (which go stale) — the nightly `check-ai-models` job keeps the tier table fresh. Every key is optional; an unset key (or the whole section absent) means the spawn uses the runtime's default model, i.e. today's behavior. The per-phase implementer model is NOT here — the plan owns it, through its **Crew** table and each phase's `**Assigned to**:` line. Neither is the review model: `review-phase` runs its reviewer one tier above the tier the phase's implementer actually ran at, and the phase's own implementer fixes the findings at its own tier. The conflict fixer and the mechanical steps (`worktree_prep`, `integrate`) are never plan-named.",
       "type": "object",
       "additionalProperties": false,
       "properties": {
         "reviewer": {
-          "description": "Default tier for the independent reviewer subagent spawned by `review-phase` (Layer 3). Reviewing wants a capable model — Tier 3 is the usual default. A plan phase's `**Review models**:` line can override this for that phase. Unset (and no phase override) → runtime default.",
+          "description": "**Deprecated since 0.7.0, and ignored.** The plan-execution review runs one tier above the phase's implementer (`review-phase` derives it), so no configured tier is read. Kept so existing configs still validate; remove it at your next edit.",
+          "deprecated": true,
           "type": "integer",
           "minimum": 1,
           "maximum": 4
         },
         "fixer": {
-          "description": "Default tier for the fixer subagent spawned by `review-phase`'s fix loop to apply one reviewer finding. Narrow, well-specified edits — Tier 2 is the usual default. A plan phase's `**Review models**:` line can override this for that phase. Unset (and no phase override) → runtime default.",
+          "description": "Tier for the merge-conflict fixer subagent (the project's `fixer` agent type) that `implement-plan` spawns when a wave integration or a dependent phase's merge conflicts, and that `amend-plan` spawns when a rewrite conflicts with a child phase. Narrow, well-specified edits — Tier 2 is the usual default. Review findings are not this role's: the phase's own implementer fixes them, and a cold fallback fixer runs at the implementer's tier. Unset → runtime default.",
           "type": "integer",
           "minimum": 1,
           "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
@@ -295,6 +333,627 @@
       "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`, `codegen`, `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`), `verify_gates` (`full` | `scoped`), `base_gates` (`full` | `off`), `wave_gates` (`off` | `final` | `every`), `substitution` (`same_tier` | `up_one_tier` | `any`), `allow_ungated_phases`, `model_fallbacks`, `max_session_turns`, `max_spare_crew`, `pull_requests` (`phase` | `plan`).",
+          "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"
+              ]
+            },
+            "verify_gates": {
+              "type": "string",
+              "enum": [
+                "full",
+                "scoped"
+              ],
+              "description": "What a phase's `verify` runs once its review approves. `full` (the default): every gate's whole command on the phase branch, so a PR never carries a suite only a scoped run saw. `scoped`: the scoped form there too, for a suite too slow to run once per phase; the merged-tree gates are then the first full run. No effect under `gate_scope: full`."
+            },
+            "base_gates": {
+              "type": "string",
+              "enum": [
+                "full",
+                "off"
+              ],
+              "description": "Whether a multi-dependency phase's merged base is gated before the phase starts on it. `full` (the default): every command gate its dependencies declare, whole command, on the merged base; red fails the phase's setup. `off`: the phase starts on the merged base unchecked."
+            },
+            "substitution": {
+              "type": "string",
+              "enum": [
+                "same_tier",
+                "up_one_tier",
+                "any"
+              ],
+              "description": "How far above the member the plan named a phase may be moved. `up_one_tier` (the default): a busy member's phase may go to the next tier up the roster has, and a warm session never moves a phase up. `same_tier`: a peer at the same tier or wait. `any`: any tier above, warm sessions included."
+            },
+            "wave_gates": {
+              "type": "string",
+              "enum": [
+                "off",
+                "final",
+                "every"
+              ],
+              "description": "When the phases' gates run in full on a merged wave, in the integration worktree. `every` (the default): a wave's gates on every wave, so the next wave builds on a passing tree, and every gate of the plan on the last wave before the plan PR. `final`: the last wave's, and a wave's gates only on a wave whose merge needed a conflict resolution. `off`: none of these (the full form of a `scoped_cmd` gate still runs per wave under `gate_scope: scoped`)."
+            },
+            "allow_ungated_phases": {
+              "type": "boolean",
+              "description": "Whether a phase that resolves to no gates is acceptable. Off (the default): `vinta-ai-maestro validate` refuses the workflow and `doctor` warns, because an ungated phase passes its gate step without running anything."
+            },
+            "model_fallbacks": {
+              "description": "Model id → the model to run instead once the first is out of quota or credits. A `quota` refusal on a listed model retries on the fallback instead of parking the harness; later spawns of that model go straight to the fallback until the vendor's stated reset, or for the rest of the run. A plan's own map replaces this one whole.",
+              "type": "object",
+              "additionalProperties": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "max_session_turns": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "pull_requests": {
+              "type": "string",
+              "enum": [
+                "phase",
+                "plan"
+              ],
+              "description": "Which pull requests a run opens. `phase` (the default): one per phase, one per integration branch, and the plan PR that lands them. `plan`: the plan PR alone, from the last wave branch; phases' `after_pr` chores are then skipped."
+            },
+            "max_spare_crew": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Crew members a run may take on beyond the plan's roster (default 2). When the member a phase was planned for is busy, the phase gets a new member at that member's tier and model, with its own worktree, instead of borrowing a member another pending phase is planned for or waiting. `0` keeps the roster to the plan's."
+            }
+          },
+          "additionalProperties": false
+        },
+        "gates": {
+          "description": "Keyed by gate type (`test`, `lint`, `typecheck`, `e2e`) or by a custom id. 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). Any other key is a custom project-wide gate — e.g. `django-check: { cmd: uv run python manage.py check --fail-level WARNING }` — that every plan has under that id and that `maestro.defaults.gates` names like a type. A custom id is lowercase kebab-case; `codegen` is reserved (it names a plan's codegen steps).",
+          "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
+                },
+                "fresh_cmd": {
+                  "description": "The same check run from fresh state (the test database recreated, e.g. `pytest --create-db`). Run in place of `cmd` in the integration worktree whenever the state an earlier run left there may belong to another tree: the tree moved anywhere but forward, the gate has not run there yet in this process, its red output reads as a stale schema, or a conflict fixer reported `ENVIRONMENT_STALE`. Must check at least what `cmd` does.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "fresh_when": {
+                  "description": "Globs, relative to the repository root, of the files the state `fresh_cmd` recreates is built from — the migrations, typically (e.g. `apps/*/migrations/*.py`). When a file that matched at the gate's last run in the integration worktree is gone or different now, the gate runs `fresh_cmd` even though the tree moved forward: a reused database keeps a migration that was rewritten or renamed under it. Files added since do not count. Ignored without `fresh_cmd`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "cold_cmd": {
+                  "description": "What a phase gate runs in place of `scoped_cmd` when the lane lacks a `scope_cache` file (e.g. `make test`, the suite in parallel, instead of a `--testmon` run that without `.testmondata` runs every test serially). Defaults to `cmd`. Must check at least what `scoped_cmd` does.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "scope_cache": {
+                  "description": "Files `scoped_cmd` narrows by, relative to the lane (e.g. `apps/api/.testmondata`). When any is missing, a phase gate runs `cold_cmd` (or `cmd`) instead and journals why.",
+                  "type": "array",
+                  "items": { "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
+                },
+                "queue_timeout_s": {
+                  "description": "How long a phase gate may wait for its `requires` pools before the attempt fails, naming who held them. `timeout_s` counts only the command's own runtime. Absent, it waits as long as it takes.",
+                  "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
+                },
+                "fresh_cmd": {
+                  "description": "The same check run from fresh state (the test database recreated, e.g. `pytest --create-db`). Run in place of `cmd` in the integration worktree whenever the state an earlier run left there may belong to another tree: the tree moved anywhere but forward, the gate has not run there yet in this process, its red output reads as a stale schema, or a conflict fixer reported `ENVIRONMENT_STALE`. Must check at least what `cmd` does.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "fresh_when": {
+                  "description": "Globs, relative to the repository root, of the files the state `fresh_cmd` recreates is built from — the migrations, typically (e.g. `apps/*/migrations/*.py`). When a file that matched at the gate's last run in the integration worktree is gone or different now, the gate runs `fresh_cmd` even though the tree moved forward: a reused database keeps a migration that was rewritten or renamed under it. Files added since do not count. Ignored without `fresh_cmd`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "cold_cmd": {
+                  "description": "What a phase gate runs in place of `scoped_cmd` when the lane lacks a `scope_cache` file (e.g. `make test`, the suite in parallel, instead of a `--testmon` run that without `.testmondata` runs every test serially). Defaults to `cmd`. Must check at least what `scoped_cmd` does.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "scope_cache": {
+                  "description": "Files `scoped_cmd` narrows by, relative to the lane (e.g. `apps/api/.testmondata`). When any is missing, a phase gate runs `cold_cmd` (or `cmd`) instead and journals why.",
+                  "type": "array",
+                  "items": { "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
+                },
+                "queue_timeout_s": {
+                  "description": "How long a phase gate may wait for its `requires` pools before the attempt fails, naming who held them. `timeout_s` counts only the command's own runtime. Absent, it waits as long as it takes.",
+                  "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
+                },
+                "fresh_cmd": {
+                  "description": "The same check run from fresh state (the test database recreated, e.g. `pytest --create-db`). Run in place of `cmd` in the integration worktree whenever the state an earlier run left there may belong to another tree: the tree moved anywhere but forward, the gate has not run there yet in this process, its red output reads as a stale schema, or a conflict fixer reported `ENVIRONMENT_STALE`. Must check at least what `cmd` does.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "fresh_when": {
+                  "description": "Globs, relative to the repository root, of the files the state `fresh_cmd` recreates is built from — the migrations, typically (e.g. `apps/*/migrations/*.py`). When a file that matched at the gate's last run in the integration worktree is gone or different now, the gate runs `fresh_cmd` even though the tree moved forward: a reused database keeps a migration that was rewritten or renamed under it. Files added since do not count. Ignored without `fresh_cmd`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "cold_cmd": {
+                  "description": "What a phase gate runs in place of `scoped_cmd` when the lane lacks a `scope_cache` file (e.g. `make test`, the suite in parallel, instead of a `--testmon` run that without `.testmondata` runs every test serially). Defaults to `cmd`. Must check at least what `scoped_cmd` does.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "scope_cache": {
+                  "description": "Files `scoped_cmd` narrows by, relative to the lane (e.g. `apps/api/.testmondata`). When any is missing, a phase gate runs `cold_cmd` (or `cmd`) instead and journals why.",
+                  "type": "array",
+                  "items": { "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
+                },
+                "queue_timeout_s": {
+                  "description": "How long a phase gate may wait for its `requires` pools before the attempt fails, naming who held them. `timeout_s` counts only the command's own runtime. Absent, it waits as long as it takes.",
+                  "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
+                },
+                "fresh_cmd": {
+                  "description": "The same check run from fresh state (the test database recreated, e.g. `pytest --create-db`). Run in place of `cmd` in the integration worktree whenever the state an earlier run left there may belong to another tree: the tree moved anywhere but forward, the gate has not run there yet in this process, its red output reads as a stale schema, or a conflict fixer reported `ENVIRONMENT_STALE`. Must check at least what `cmd` does.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "fresh_when": {
+                  "description": "Globs, relative to the repository root, of the files the state `fresh_cmd` recreates is built from — the migrations, typically (e.g. `apps/*/migrations/*.py`). When a file that matched at the gate's last run in the integration worktree is gone or different now, the gate runs `fresh_cmd` even though the tree moved forward: a reused database keeps a migration that was rewritten or renamed under it. Files added since do not count. Ignored without `fresh_cmd`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "cold_cmd": {
+                  "description": "What a phase gate runs in place of `scoped_cmd` when the lane lacks a `scope_cache` file (e.g. `make test`, the suite in parallel, instead of a `--testmon` run that without `.testmondata` runs every test serially). Defaults to `cmd`. Must check at least what `scoped_cmd` does.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "scope_cache": {
+                  "description": "Files `scoped_cmd` narrows by, relative to the lane (e.g. `apps/api/.testmondata`). When any is missing, a phase gate runs `cold_cmd` (or `cmd`) instead and journals why.",
+                  "type": "array",
+                  "items": { "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
+                },
+                "queue_timeout_s": {
+                  "description": "How long a phase gate may wait for its `requires` pools before the attempt fails, naming who held them. `timeout_s` counts only the command's own runtime. Absent, it waits as long as it takes.",
+                  "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
+                }
+              }
+            }
+          },
+          "patternProperties": {
+            "^(?!(?:test|lint|typecheck|e2e|codegen)$)[a-z0-9][a-z0-9-]*$": {
+              "description": "A custom gate every plan has under this id, untyped: nothing supplies its command but `cmd` here. A plan's own gate of the same id replaces it whole. Same fields as a gate type's entry.",
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["cmd"],
+              "properties": {
+                "cmd": {
+                  "description": "The full check. Required: only the four gate types inherit a command from `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
+                },
+                "fresh_cmd": {
+                  "description": "The same check run from fresh state (the test database recreated, e.g. `pytest --create-db`). Run in place of `cmd` in the integration worktree whenever the state an earlier run left there may belong to another tree: the tree moved anywhere but forward, the gate has not run there yet in this process, its red output reads as a stale schema, or a conflict fixer reported `ENVIRONMENT_STALE`. Must check at least what `cmd` does.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "fresh_when": {
+                  "description": "Globs, relative to the repository root, of the files the state `fresh_cmd` recreates is built from — the migrations, typically (e.g. `apps/*/migrations/*.py`). When a file that matched at the gate's last run in the integration worktree is gone or different now, the gate runs `fresh_cmd` even though the tree moved forward: a reused database keeps a migration that was rewritten or renamed under it. Files added since do not count. Ignored without `fresh_cmd`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "cold_cmd": {
+                  "description": "What a phase gate runs in place of `scoped_cmd` when the lane lacks a `scope_cache` file (e.g. `make test`, the suite in parallel, instead of a `--testmon` run that without `.testmondata` runs every test serially). Defaults to `cmd`. Must check at least what `scoped_cmd` does.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "scope_cache": {
+                  "description": "Files `scoped_cmd` narrows by, relative to the lane (e.g. `apps/api/.testmondata`). When any is missing, a phase gate runs `cold_cmd` (or `cmd`) instead and journals why.",
+                  "type": "array",
+                  "items": { "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
+                },
+                "queue_timeout_s": {
+                  "description": "How long a phase gate may wait for its `requires` pools before the attempt fails, naming who held them. `timeout_s` counts only the command's own runtime. Absent, it waits as long as it takes.",
+                  "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"
+                ]
+              },
+              "scope": {
+                "description": "`run` (the default) counts this run's holders only; `host` also counts every other maestro run on the machine holding a pool of the same name, so two runs on one laptop take turns at the full suite.",
+                "type": "string",
+                "enum": [
+                  "run",
+                  "host"
+                ]
+              },
+              "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. `when` is `review` (runs once the phase's gates are green; the turn ends with `VERDICT: pass` or `VERDICT: fail` and the phase continues only on pass — e.g. a `thermo-nuclear-review-loop` chore), `after_review` (the default: runs after the review approved, before the final gate run — e.g. a `deslop-comments` chore) or `after_pr` (runs after the phase's PR is published).",
+          "type": "object",
+          "propertyNames": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          },
+          "additionalProperties": {
+            "type": "object"
+          }
+        },
+        "codegen": {
+          "description": "Codegen steps by id (`cmd`, `outputs`, `inputs`, `after`, `requires`, `timeout_s`, `format`) — the workflow schema's `codegen` entries. Deterministic commands that write declared files: an OpenAPI schema, the client generated from it, a route tree, or a formatter scoped to the files a phase changed (`format: true`, `{changed_files}` in `cmd`). Maestro runs them in every lane before its gates and commits what they write, and in the integration worktree around every merge, where a conflict confined to their outputs is settled by running them instead of by a fixer agent. A failing step is a red gate.",
+          "type": "object",
+          "propertyNames": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "required": [
+              "cmd",
+              "outputs"
+            ],
+            "properties": {
+              "cmd": {
+                "type": "string",
+                "minLength": 1
+              },
+              "outputs": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              }
+            }
+          }
+        },
+        "append_only": {
+          "description": "Files every phase only appends to — a DI container, a URL route list, a registry of notification kinds, a beat schedule — as gitattributes patterns. Maestro merges them in the integration worktree with git's `union` driver, so two phases each adding an entry do not conflict; the merged tree is then gated as any other. A plan's own `append_only` replaces this list.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "post_merge": {
+          "description": "A command run in maestro's integration worktree after git merges a branch by itself, with `{files}` replaced by the files both sides changed — e.g. `python -m py_compile {files} && ruff check --fix --select I,F811,F401 {files} && ruff format {files}`. What it changes is committed on top of the merge; a non-zero exit is journalled and the merged tree's gates judge it. A plan's own `post_merge` replaces this one.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["cmd"],
+          "properties": {
+            "cmd": { "type": "string", "minLength": 1 },
+            "timeout_s": { "type": "integer", "minimum": 1 }
+          }
+        },
+        "ci_only": {
+          "description": "CI checks deliberately left to CI, each with its reason (it needs credentials, a deploy, a hosted service). `vinta-ai-maestro doctor` warns about every CI command no gate runs; one listed here is a decision, not a gap. A plan's own `ci_only` replaces this list.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["command", "reason"],
+            "properties": {
+              "command": { "type": "string", "minLength": 1, "description": "The CI command as CI runs it; wrappers like `uv run` are ignored when matching." },
+              "reason": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        "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",
@@ -312,12 +971,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
             },
@@ -409,7 +1068,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 symlink-vs-copy-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": {
@@ -419,10 +1078,10 @@
               "minLength": 1
             },
             "deps_strategy": {
-              "description": "Default strategy for dep dirs (`node_modules/`, `vendor/`, `venv/`) when the active plan does NOT install new deps. `symlink` reuses main's install (fast, safe for read-only); `copy` clones it (safe for pnpm-style relative-symlink stores, fails for yarn PnP); `reinstall` runs the package manager fresh in the worktree. The skill flips to `reinstall` automatically when it detects dep churn in the plan body.",
+              "description": "Default strategy for dep dirs (`node_modules/`, `vendor/`, `venv/`). Every worktree owns its dep dirs; they are never symlinked back to the main checkout. `copy` makes a copy-on-write clone of main's install, close to free on disk on APFS / btrfs / XFS; it is safe for pnpm-style relative-link stores and falls back to a plain copy elsewhere. `reinstall` runs the package manager fresh in the worktree. The skill always reinstalls virtualenvs and yarn PnP, because their trees store absolute paths into the main checkout, and it adds an install on top of the copy when the plan adds deps. `symlink` is deprecated and read as `copy`; it stays in the enum only so existing configs keep validating.",
               "type": "string",
-              "enum": ["symlink", "copy", "reinstall"],
-              "default": "symlink"
+              "enum": ["copy", "reinstall", "symlink"],
+              "default": "copy"
             },
             "compose_network": {
               "description": "Default docker-compose networking strategy for the worktree. `per-worktree` spins a fresh isolated network (safest, doubles infra); `shared-external` joins an externally-declared network so the worktree can talk to main's compose services (queues, caches, search); `host` uses host networking when the project already does. Skill writes the chosen strategy into the worktree's `docker-compose.override.yml` (or equivalent) when `compose_change` is set.",