vinta-ai-workflows 0.7.0-alpha2 → 0.7.0-alpha21

package/README.md

@@ -292,6 +292,22 @@ Land at `ai-tools/agents/<name>.yaml` (canonical YAML; `setup-ai-tools.mjs` emit
 
 Stack templates may add specialists like `migration-author` (Django) or `deploy-author` (Medplum) — see disclaimer above.
 
+### Integrations (external tools)
+
+Integrations are external tools that ship their own skill. The bootstrap asks about each one. When one is enabled, the tool's own CLI installs and updates its skill. This package never copies, renders or edits that skill. Enabling one is recorded under `integrations` in `.vinta-ai-workflows.yaml`.
+
+| Integration | What it adds |
+|---|---|
+| [`pr-review-canvas`](https://github.com/vintasoftware/pr-review-canvas) | A review canvas for every PR an agent opens: the diff grouped by topic, with attention points for the reviewer, shared as a PR comment and read in a local app (`pr-review serve`). `integrate-phase` runs `/pr-review-canvas <n>` after `open-pr.sh` publishes the PR. `plan-feature` adds an `after_pr` `review-canvas` chore so that [vinta-ai-maestro](packages/vinta-ai-maestro/README.md#chores-about-the-pr--when-after_pr) does the same on each phase PR. Offered only for GitHub / GitLab projects where agents open PRs. |
+
+The tool itself is a machine-level install, like `gh`, and the bootstrap never installs it:
+
+```bash
+npm install -g @vintasoftware/pr-review-canvas
+```
+
+When the CLI is present, the bootstrap runs `pr-review install-skill --claude-dir ai-tools/skills --codex-dir ai-tools/skills`, so one copy in `ai-tools/skills/pr-review-canvas/` serves every vendor. Refresh it with `pr-review upgrade`, and check it with `pr-review doctor`. Do not edit the copy: the tool stamps a hash into it and reports an edited copy as stale. Sharing and other settings live in the tool's own `pr-review.config.yml`.
+
 ## Staying in sync with upstream
 
 Bootstrap is a snapshot. `vinta-ai-workflows` keeps shipping — new foundation skills, refined templates, sharper agent prompts, schema additions, stack support, best-practice updates lifted from real projects. Pulling those into a previously-bootstrapped repo is a first-class flow, not an afterthought. **This is one of the most important capabilities of the package.**

package/package.json

@@ -1,17 +1,14 @@
 {
   "name": "vinta-ai-workflows",
-  "version": "0.7.0-alpha2",
+  "version": "0.7.0-alpha21",
   "description": "Bootstrap AI tooling (AGENTS.md, skills, sub-agents) across Claude Code, Codex, Cursor, and VS Code + GitHub Copilot.",
   "type": "module",
-  "packageManager": "pnpm@10.33.0",
   "bin": {
     "vinta-ai-workflows": "./vinta-ai-workflows.mjs"
   },
-  "scripts": {
-    "check-ai-models": "node scripts/check-ai-models.mjs",
-    "test": "node --test tests/*.test.mjs"
-  },
   "devDependencies": {
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "yaml": "^2.4.0"
   },
   "files": [
@@ -26,10 +23,15 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git"
+    "url": "git+https://github.com/vintasoftware/vinta-ai-workflows.git"
   },
   "publishConfig": {
     "access": "public"
   },
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "check-ai-models": "node scripts/check-ai-models.mjs",
+    "validate-schemas": "node scripts/validate-schemas.mjs",
+    "test": "node --test tests/*.test.mjs"
+  }
+}

package/schemas/README.md

@@ -12,10 +12,13 @@ JSON Schema (Draft 2020-12) contracts for every YAML or JSON payload the vinta-a
 | 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` |
 | MCP preflight cache | `.vinta-ai-workflows/cache.yaml` (gitignored — per-developer-machine state) | [`mcp-preflight-cache.v1.schema.json`](mcp-preflight-cache.v1.schema.json) | rendered `systematic-debugging` SKILL.md (writes during Phase 0) | rendered `systematic-debugging` SKILL.md (reads at Phase 0 start) |
 | AI model tier table | `ai-tools/skills/plan-feature/resources/ai-models.yaml` (shipped verbatim with the `plan-feature` foundation skill; source: `skills/vinta-derive-skills/resources/foundation-skills/plan-feature/resources/ai-models.yaml`) | [`ai-models.v1.schema.json`](ai-models.v1.schema.json) | nightly `check-ai-models` job ([`scripts/check-ai-models.mjs`](../scripts/check-ai-models.mjs)) → auto-PR | `plan-feature` (per-phase model suggestion) |
-| Workflow (executable plan) | `ai-plans/<feature-kebab>.workflow.json` — **JSON, not YAML** | [`workflow.v1.schema.json`](workflow.v1.schema.json) | `plan-feature` (emitted alongside the human-readable plan) | `vinta-ai-maestro` (the orchestrator daemon) |
+| Workflow (executable plan) | `ai-plans/YYYY-MM-DD-<feature-kebab>.workflow.json` — **JSON, not YAML** | [`workflow.v1.schema.json`](workflow.v1.schema.json) | `plan-feature` (emitted alongside the human-readable plan) | `vinta-ai-maestro` (the orchestrator daemon) |
 | Plan post-mortem | `.vinta-ai-maestro/runs/<run-id>/postmortem.json` — **JSON, not YAML**; per-run state beside the frozen workflow, copied to `ai-plans/<feature-kebab>.postmortem.json` when a team wants it committed | [`postmortem.v1.schema.json`](postmortem.v1.schema.json) | `vinta-ai-maestro` (once a run has ended) | `plan-feature` (when planning the next feature in the same repo) |
+| Monitor intervention | not a file the user writes — the document the run's monitor answers with when a watchdog wakes it, recorded per attempt at `.vinta-ai-maestro/runs/<run-id>/interventions.jsonl` | [`intervention.v1.schema.json`](intervention.v1.schema.json) | the run monitor (`vinta-ai-maestro`, when a phase or a gate crosses a threshold) | `vinta-ai-maestro` (validates it, then applies it through §9's amend path) |
 
-> `workflow.v1.schema.json` and `postmortem.v1.schema.json` are the two schemas here that are **generated, not hand-written**. The workflow's source of truth is `packages/vinta-ai-maestro/src/types.ts`; regenerate with `pnpm --filter vinta-ai-maestro schema:gen` and verify with `schema:check`. The post-mortem's is `packages/vinta-ai-maestro/src/postmortem/postmortem.ts`; regenerate with `node --experimental-strip-types src/postmortem/generate.ts` from `packages/vinta-ai-maestro`, verify with the same command plus `--check` — `tests/postmortem.test.ts` runs that byte comparison too. Edit the zod schemas, never the JSON.
+> **Three of these are generated, not hand-written**: `workflow.v1`, `postmortem.v1` and `intervention.v1`. The workflow's source of truth is `packages/vinta-ai-maestro/src/types.ts`; regenerate with `pnpm --filter vinta-ai-maestro schema:gen` and verify with `schema:check`. The post-mortem's is `src/postmortem/postmortem.ts` and the intervention's is `src/intervention/intervention.ts`; regenerate either with `pnpm --filter vinta-ai-maestro <postmortem|intervention>:schema:gen`, verify with `:schema:check` — `tests/postmortem.test.ts` and `tests/intervention.test.ts` run those byte comparisons too. Edit the zod schemas, never the JSON.
+>
+> The intervention schema is the odd one: it validates a document a *model* writes rather than one a skill or a person does, and it is the boundary that decides what an unattended run may change about itself. Its verbs are deliberately few and deliberately cannot express a change to what a phase builds — see [`docs/monitor-intervention.md`](../packages/vinta-ai-maestro/docs/monitor-intervention.md).
 
 ## Versioning rules
 
@@ -87,3 +90,7 @@ done
 ```
 
 For PR-context frontmatter, extract the YAML block first (`yq` does this cleanly), then validate.
+
+## Checking the schemas themselves (this repo only)
+
+`npm run validate-schemas` (also part of `npm test`) compiles every schema here under Ajv's strict Draft 2020-12 mode and checks the fixtures in `tests/schema-fixtures/<schema-file-stem>/`: everything under `valid/` must pass, everything under `invalid/` must fail. A fixture is `.json`, `.yaml` / `.yml`, or a `.md` file whose YAML frontmatter is the payload. **A conditional rule (`if` / `then`) needs an `invalid/` fixture for each branch it enforces** — a lenient validator ignores a broken one silently. Pass file paths instead to validate payloads against the schema their `$schema` key or `yaml-language-server` comment names.

package/schemas/intervention.v1.schema.json

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

package/schemas/postmortem.v1.schema.json

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

package/schemas/prs-context-frontmatter.v1.schema.json

@@ -8,8 +8,6 @@
     "schema_version",
     "plan_id",
     "feature_name",
-    "phase_id",
-    "phase_title",
     "branch",
     "base",
     "created_at",
@@ -34,24 +32,30 @@
       "pattern": "^[A-Z][A-Z0-9_]*$",
       "minLength": 1
     },
+    "kind": {
+      "description": "Which PR this file opens. `phase` (the default when absent): one phase's branch into its dependency-derived base. `integration`: a multi-dependency phase's `plan/<plan-id>/integ-<phase-id>` branch into the default branch, so the phase PR stacked on it can land. `plan`: the final wave branch (or, under modular commits, the plan branch) into the default branch — the PR that lands the whole plan.",
+      "type": "string",
+      "enum": ["phase", "integration", "plan"],
+      "default": "phase"
+    },
     "phase_id": {
-      "description": "Phase id verbatim from the plan's `Phased Rollout` section (e.g. `1`, `4a`, `2.5`).",
+      "description": "Phase id verbatim from the plan's `Phased Rollout` section (e.g. `1`, `4a`, `2.5`). Required unless `kind` is `plan`; for `kind: integration` it is the phase whose `integ-` branch this is.",
       "type": "string",
       "pattern": "^[0-9]+(\\.[0-9]+)?[a-z]?$",
       "minLength": 1
     },
     "phase_title": {
-      "description": "Phase title verbatim from the plan's `Phased Rollout` section.",
+      "description": "Phase title verbatim from the plan's `Phased Rollout` section. Required unless `kind` is `plan`.",
       "type": "string",
       "minLength": 1
     },
     "branch": {
-      "description": "Source branch the PR opens from. Default convention `plan/<plan-id-kebab>/phase-<phase.id>`.",
+      "description": "Source branch the PR opens from. `plan/<plan-id-kebab>/phase-<phase.id>` for a phase, `plan/<plan-id-kebab>/integ-<phase.id>` for an integration PR, the final `plan/<plan-id-kebab>/wave-<N>` (or `plan/<plan-id-kebab>` under modular commits) for the plan PR.",
       "type": "string",
       "minLength": 1
     },
     "base": {
-      "description": "Target branch. Either the project's default branch (`main`) or the previous phase's stacked branch.",
+      "description": "Target branch. A phase PR targets its dependency-derived base (the default branch, a dependency's phase branch, or its `integ-` branch); integration and plan PRs target the default branch.",
       "type": "string",
       "minLength": 1
     },
@@ -73,5 +77,12 @@
         { "const": "" }
       ]
     }
-  }
+  },
+  "allOf": [
+    {
+      "description": "Every PR but the plan PR belongs to one phase.",
+      "if": { "not": { "properties": { "kind": { "const": "plan" } }, "required": ["kind"] } },
+      "then": { "required": ["phase_id", "phase_title"] }
+    }
+  ]
 }

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

@@ -250,6 +250,18 @@
         "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.",
       "type": "object",