vinta-ai-workflows 0.6.1 → 0.7.0-alpha10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/CHANGELOG.md +714 -0
  2. package/README.md +21 -13
  3. package/package.json +8 -8
  4. package/schemas/README.md +5 -1
  5. package/schemas/postmortem.v1.schema.json +339 -0
  6. package/schemas/vinta-ai-workflows-config.v1.schema.json +13 -1
  7. package/schemas/workflow.v1.schema.json +978 -0
  8. package/skills/vinta-bootstrap-ai-tools/SKILL.md +9 -1
  9. package/skills/vinta-derive-skills/SKILL.md +6 -2
  10. package/skills/vinta-derive-skills/resources/foundation-skills/open-pr-from-context/scripts/open-pr.sh +0 -0
  11. package/skills/vinta-derive-skills/resources/foundation-skills/plan-feature/SKILL.md +622 -32
  12. package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md +34 -4
  13. package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/scripts/claude-worktree-write-guard.py +0 -0
  14. package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/scripts/gen-claude-sandbox-settings.sh +0 -0
  15. package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/scripts/gen-compose-worktree-override.sh +0 -0
  16. package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/scripts/sandbox-run.sh +0 -0
  17. package/skills/vinta-derive-skills/resources/plan-execution/README.md +21 -4
  18. package/skills/vinta-derive-skills/resources/plan-execution/partials/agent-models.md +30 -3
  19. package/skills/vinta-derive-skills/resources/plan-execution/partials/commit-strategy/modular.md +27 -14
  20. package/skills/vinta-derive-skills/resources/plan-execution/partials/commit-strategy/stacked.md +12 -18
  21. package/skills/vinta-derive-skills/resources/plan-execution/partials/implementer-prompt.md +19 -9
  22. package/skills/vinta-derive-skills/resources/plan-execution/partials/model-pick.md +25 -9
  23. package/skills/vinta-derive-skills/resources/plan-execution/partials/parallel-lanes.md +240 -0
  24. package/skills/vinta-derive-skills/resources/plan-execution/partials/review-layers.md +56 -5
  25. package/skills/vinta-derive-skills/resources/plan-execution/partials/worktree-seam.md +13 -6
  26. package/skills/vinta-derive-skills/resources/plan-execution/shell/amend-plan-template.md +17 -12
  27. package/skills/vinta-derive-skills/resources/plan-execution/shell/implement-phase-template.md +5 -3
  28. package/skills/vinta-derive-skills/resources/plan-execution/shell/implement-plan-template.md +94 -57
  29. package/skills/vinta-derive-skills/resources/plan-execution/shell/integrate-phase-template.md +2 -1
  30. package/skills/vinta-derive-skills/resources/plan-execution/shell/review-phase-template.md +16 -5
  31. package/skills/vinta-install-ai-tools-setup/resources/setup-ai-tools.mjs +0 -0
package/README.md CHANGED
@@ -48,9 +48,9 @@ After bootstrap, the project ships with **three foundation skills** that take a
48
48
  └─────────────────┘ Phased Rollout, Touch List, Risks)
49
49
  │
50
50
  ▼
51
- ┌─────────────────┐ one stacked branch per phase + tracking file
52
- │ implement-plan │───► plan/<feature>/phase-1, phase-2, ...
53
- └─────────────────┘ pushed to GitHub / GitLab / etc.
51
+ ┌─────────────────┐ one branch per phase (independent phases run in
52
+ │ implement-plan │───► parallel lanes) + a tracking dir
53
+ └─────────────────┘ plan/<feature>/phase-1, phase-2, wave-1, ...
54
54
  ```
55
55
 
56
56
  You also get: an `AGENTS.md` tuned to the codebase — a regular file at the repo root, with per-vendor aliases (`CLAUDE.md`, `.github/copilot-instructions.md`) symlinked to it — project-specific sub-agents and skills derived from the actual stack, and per-vendor wiring so Claude Code / Codex / Cursor / Copilot all see the same artifacts.
@@ -80,7 +80,7 @@ The bootstrap skills are **one-shot**. They scaffold the project once and are re
80
80
  - **Goals + Non-goals** — what's in / out of scope.
81
81
  - **Guiding Decisions** — feature flag (key, scope, default, flip-on criterion if any), storage shape, tenant scoping, API contract, schema rules. Load-bearing — every phase reaches back here.
82
82
  - **Data Model Changes** — migrations + rollout order.
83
- - **Phased Rollout** — each phase declares: `id`, `title`, `goal`, `Suggested AI model` (per vendor — implement-plan picks the cheapest available), `reusable_skills` (other project skills the implementer should invoke), `Changes`, `Tests`, `Acceptance`, plus flags for `is_cross_repo` and `is_flag_removal` (both deferred).
83
+ - **Phased Rollout** — opens with a **Crew** table (the agents this plan is staffed with, each with a role — `implementer` or `reviewer` — and a tier; every implementer keeps one worktree and one session for the whole run, while reviewers read the lane they are reviewing before it is committed), then each phase declares: `id`, `title`, `goal`, `Assigned to` (which crew member takes it — implement-plan resolves their tier to the cheapest available model), `reusable_skills` (other project skills the implementer should invoke), `Changes`, `Tests`, `Acceptance`, plus flags for `is_cross_repo` and `is_flag_removal` (both deferred).
84
84
  - **Risk & Rollout Notes**, **Open Questions**, **Touch List**.
85
85
 
86
86
  Phases are sized so the slowest path (e.g. cross-repo producer wiring, external integration approval) starts in Phase 1 and fast in-repo work fills in behind. Large mutation phases get split (`4a / 4b / 4c`) rather than monolithic.
@@ -105,28 +105,34 @@ Phases are sized so the slowest path (e.g. cross-repo producer wiring, external
105
105
  - **Layer 3 — independent reviewer**: spawn a fresh `reviewer` agent with no implementation context. Findings triaged BLOCKER / SHOULD-FIX / NIT.
106
106
  6. **Fix loop**: each finding → spawn a `fixer` agent (separate session) that re-runs inner + outer loops; orchestrator never edits directly. Repeat until all three layers are clean.
107
107
 
108
- **Branch model — one branch per phase, stacked:**
108
+ **Branch model — one branch per phase, based on that phase's dependencies:**
109
+
110
+ Every phase in the plan declares what it needs (`**Depends on**: Phase 1 (the `BookmarkFolder` model), …`). That line — not the phase's number — decides both when it runs and what it branches from.
109
111
 
110
112
  ```bash
111
- # First executed phase — branches from the default branch.
113
+ # A phase with no dependencies — branches from the default branch.
112
114
  git checkout main && git pull --ff-only
113
115
  git checkout -b plan/<feature-kebab>/phase-1
114
- # implementer's commits land here
115
116
  git push -u origin plan/<feature-kebab>/phase-1
116
117
 
117
- # Phase 2 stacks on phase 1 — never branches back to main.
118
+ # A phase depending on exactly one phase — branches from it.
118
119
  git checkout plan/<feature-kebab>/phase-1
119
120
  git checkout -b plan/<feature-kebab>/phase-2
120
121
  git push -u origin plan/<feature-kebab>/phase-2
121
122
 
122
- # Phase 3 stacks on phase 2, etc.
123
+ # A phase depending on several — branches from a merge of them.
124
+ git checkout -B plan/<feature-kebab>/integ-4 plan/<feature-kebab>/phase-2
125
+ git merge --no-ff plan/<feature-kebab>/phase-3
126
+ git checkout -b plan/<feature-kebab>/phase-4
123
127
  ```
124
128
 
125
- Each phase's PR (or branch, depending on the project's PR policy captured at bootstrap) targets the previous phase's branch, not `main`. This keeps the diff per PR scoped to a single phase, makes review manageable, and lets the team merge phases sequentially as approvals land — earlier phases ship to production while later ones are still in review.
129
+ Each phase's PR (or branch, depending on the project's PR policy captured at bootstrap) targets its own base, not `main`. This keeps the diff per PR scoped to a single phase, makes review manageable, and lets the team merge as approvals land. A plan whose phases form a chain produces exactly the classic stack; a plan with independent phases produces several short stacks, reunited by per-wave integration branches (`plan/<feature-kebab>/wave-<N>`).
130
+
131
+ **Parallel phases.** Because the plan carries a dependency graph, `implement-plan` implements independent phases **at the same time** — one worktree lane per phase in flight, each with its own dev + test database and compose stack, so concurrent test runs don't collide. A phase starts the moment every phase it depends on is green and a lane frees up; a failed phase blocks only its dependents while the rest of the plan keeps going. On by default (`run_options.implement-plan.parallel_phases`, capped by `max_parallel_lanes`, default 3), it requires `prepare-worktree` and refuses to run rather than silently falling back to sequential when worktrees aren't available. A chain-shaped plan runs one phase at a time — same scheduler, one lane.
126
132
 
127
133
  **Alternative: modular commits.** Teams that prefer one branch + one PR per plan can set `policies.commit_strategy: modular-commits` in `.vinta-ai-workflows.yaml`. Under that mode, every phase pushes its **atomic unit commits** (one per service, use-case wire-up, init export, serializer field, refactor, or bug fix — tests in the same commit as code) to a single `plan/<feature-kebab>` branch; the PR opens once after Phase 1 review and gets updated as later phases push. The third option, `commit_strategy: ask`, prompts `implement-plan` at Step 0 (alongside the existing `pause_between_phases` / `generate_inline_comments` opt-ins) and caches the answer in the tracking file. Default is `stacked-branches` — the model documented above. See [`schemas/vinta-ai-workflows-config.v1.schema.json`](schemas/vinta-ai-workflows-config.v1.schema.json) for the field definition.
128
134
 
129
- **Tracking file** — `ai-plans/TRACKING_<feature-kebab>.md`. The orchestrator writes it from `git diff` + the agent's report (not the agent's narration). Records: completed phases (status, model used, branch, base, e2e+screenshots when applicable, 5–15 line summary), current phase, remaining phases, deferred phases. Acts as the durable context handoff between phase prompts. Deleted on plan completion.
135
+ **Tracking directory** — `ai-plans/TRACKING_<feature-kebab>/`. The orchestrator writes it from `git diff` + the agent's report (not the agent's narration): `run.md` for run options, the resolved dependency graph, and the lane pool; one `phase-<id>.md` per phase (status, model used, branch, base, wave, e2e+screenshots when applicable, 5–15 line summary); `waves/wave-<N>.md` for each integration merge. It is a directory rather than one file so concurrent lanes never write the same path — each phase's entry is committed on that phase's own branch, which keeps wave merges clean. Acts as the durable context handoff between phase prompts, scoped per phase to its own dependencies. Deleted on plan completion.
130
136
 
131
137
  **Phases the orchestrator never auto-executes:**
132
138
 
@@ -218,7 +224,7 @@ The 0.2.0 alpha line adds five foundation skills and restructures plan execution
218
224
 
219
225
  - **`handoff` (always)** — writes a session-continuation doc to `.vinta-ai-workflows/handoffs/` so a fresh session, a different agent, or a teammate can resume in-flight work without re-deriving context. Write mode gathers the goal, what's verified vs. still assumed, decisions and the alternatives rejected, landmines, and the single concrete next step **from the repo, never from memory**. Resume mode reads a handoff and re-checks its claims against the repo before trusting them.
220
226
  - **`deslop-comments` (always)** — rewrites the comments and doc blocks a task touched into Simple English, stripping AI-slop vocabulary and negative framing. Comment-only: no renames, no behavior change. It's wired into the review flow — `review-phase` Layer 2 gained a comment-hygiene check and dispatches a `fixer` to run this skill on any comment-slop finding — and is also invokable standalone ("deslop these comments").
221
- - **`prepare-worktree` (opt-in)** — provisions a fully-runnable git worktree for parallel plan work so a long-running plan can build, test, migrate, and hit databases without disturbing the main checkout. It reads the plan plus `.gitignore` / manifests / env / docker config and decides per ignored path whether to symlink, copy, or fork (dev DB, env files, compose project name). It also ships an OS-level write-guard — `sandbox-run.sh` (`sandbox-exec` / `bwrap`) for subprocess runtimes and a `PreToolUse` hook for Claude Code's in-process subagents — so a stray write back to the main checkout fails at the kernel layer instead of relying on a cooperative "stay in the worktree" instruction. `implement-plan` Step 0 question (c) opts a run into it.
227
+ - **`prepare-worktree` (opt-in)** — provisions a fully-runnable git worktree for parallel plan work so a long-running plan can build, test, migrate, and hit databases without disturbing the main checkout. It reads the plan plus `.gitignore` / manifests / env / docker config and decides per ignored path whether to symlink, copy, or fork (dev DB, env files, compose project name). It also ships an OS-level write-guard — `sandbox-run.sh` (`sandbox-exec` / `bwrap`) for subprocess runtimes and a `PreToolUse` hook for Claude Code's in-process subagents — so a stray write back to the main checkout fails at the kernel layer instead of relying on a cooperative "stay in the worktree" instruction. `implement-plan` Step 0 question (c) opts a run into it, and parallel phase execution requires it — one lane per concurrent phase.
222
228
  - **`thermo-nuclear-code-quality-review` (opt-in)** — a deliberately harsh, on-demand structural-maintainability audit of a diff (abstraction quality, giant files, spaghetti-condition growth) that hunts for "code-judo" reframes collapsing whole branches / helpers / modes / layers rather than polishing them. Read-only — it reports findings and hands each fix to a `fixer`. `review-phase` Layer 3 now applies a condensed version of this lens on every phase and escalates to the full audit only when a phase touches core architecture, crosses ~1,000 lines, or surfaces a structural smell too big to fix inline.
223
229
  - **`handoff-to-client` (opt-in, API-only repos)** — generates a self-contained markdown document for the client teams consuming the repo's API: every endpoint / operation added, changed, deprecated, or removed on the current branch vs. the default branch, with request/response shapes derived from the code, auth + error changes, breaking-change flags judged from the strictest plausible client, one realistic example per operation, and per-platform migration notes. Template-rendered from `skills.handoff-to-client.*` config (required `client_platforms`, plus `api_style` / `api_spec_path` / `output_dir`).
224
230
 
@@ -246,7 +252,7 @@ Land at `ai-tools/skills/<name>/SKILL.md`. Always-on unless flagged optional.
246
252
  | `add-e2e-test` | **opt-in** | Add an e2e test. Body covers e2e framework, page-object pattern, auth/storage-state, seed helpers, tenant scoping, screenshot conventions. |
247
253
  | `add-env-var` | **opt-in** | Propagate a new env var through every layer (`.env.example`, build tool envPrefix, build cache hash, app config, AGENTS.md, CI, deploy injection). |
248
254
  | [`add-one-off-script`](skills/vinta-derive-skills/resources/foundation-skills/add-one-off-script/SKILL.md) | **opt-in** | Author one-off operational scripts (backfills, cleanups, ad-hoc fixes). Ships a `BaseOneOffScript` class (Python + TS) enforcing dry-run default, idempotency, batched DB ops, segmented CSV backups, signal-safe interruption, multi-sink logging. |
249
- | [`prepare-worktree`](skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md) | **opt-in** | Provision a fully-runnable git worktree for parallel plan work — reads the plan + `.gitignore` + manifests + env / docker config and decides per ignored path whether to **symlink / copy / fork** (dev DB, env files, compose project name). Ships an OS-level write-guard (`sandbox-run.sh` + a Claude Code `PreToolUse` hook) so stray writes to the main checkout fail at the kernel layer. `implement-plan` Step 0 question (c) opts a run into it. |
255
+ | [`prepare-worktree`](skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md) | **opt-in** | Provision a fully-runnable git worktree for parallel plan work — reads the plan + `.gitignore` + manifests + env / docker config and decides per ignored path whether to **symlink / copy / fork** (dev DB, env files, compose project name). Ships an OS-level write-guard (`sandbox-run.sh` + a Claude Code `PreToolUse` hook) so stray writes to the main checkout fail at the kernel layer. `implement-plan` Step 0 question (c) opts a run into it, and parallel phase execution requires it — one lane per concurrent phase. |
250
256
  | [`thermo-nuclear-code-quality-review`](skills/vinta-derive-skills/resources/foundation-skills/thermo-nuclear-code-quality-review/SKILL.md) | **opt-in** | Deliberately harsh structural-maintainability audit of a diff — abstraction quality, giant files, spaghetti-condition growth — hunting "code-judo" reframes that collapse whole branches / helpers / modes / layers. Read-only; hands each fix to `fixer`. `review-phase` Layer 3 runs a condensed lens every phase and escalates to this full audit on core-architecture / ~1000-line / structurally-smelly phases. |
251
257
  | `handoff-to-client` | **opt-in** | (API-only repos) Generate a self-contained API-change handoff doc for the client teams consuming the repo's API — every endpoint / operation added / changed / deprecated / removed vs the default branch, with request/response shapes, auth + error changes, breaking-change flags, one example per operation, and per-platform migration notes. Template-rendered from `skills.handoff-to-client.*` config (client platforms, API style, spec path). |
252
258
 
@@ -572,6 +578,8 @@ vinta-ai-workflows/
572
578
 
573
579
  `vinta-bootstrap-ai-tools` is the entry point — walks a fresh repo, runs the others in order. The rest can also be invoked individually to refresh a single artifact.
574
580
 
581
+ The repository is also a pnpm workspace. `packages/` holds **private, unpublished** packages that are not part of what `install` puts in your project — the `files` whitelist excludes the directory. The one worth knowing about is [`packages/vinta-ai-maestro`](packages/vinta-ai-maestro/README.md): an opt-in daemon that executes the `ai-plans/<feature>.workflow.json` files `plan-feature` emits, scheduling independent phases across worktree lanes. Nothing requires it; the skills path runs the same plans with no daemon installed.
582
+
575
583
  ### Why the `vinta-` prefix?
576
584
 
577
585
  Once installed, these skills sit alongside the user's own project skills in the same `.<vendor>/skills/` directory. The prefix makes ownership obvious in slash menus and on disk: anything under `vinta-*` is managed by this package and gets removed by `uninstall`; anything else belongs to the project.
package/package.json CHANGED
@@ -1,15 +1,11 @@
1
1
  {
2
2
  "name": "vinta-ai-workflows",
3
- "version": "0.6.1",
3
+ "version": "0.7.0-alpha10",
4
4
  "description": "Bootstrap AI tooling (AGENTS.md, skills, sub-agents) across Claude Code, Codex, Cursor, and VS Code + GitHub Copilot.",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "vinta-ai-workflows": "./vinta-ai-workflows.mjs"
8
8
  },
9
- "scripts": {
10
- "check-ai-models": "node scripts/check-ai-models.mjs",
11
- "test": "node --test tests/*.test.mjs"
12
- },
13
9
  "devDependencies": {
14
10
  "yaml": "^2.4.0"
15
11
  },
@@ -25,10 +21,14 @@
25
21
  },
26
22
  "repository": {
27
23
  "type": "git",
28
- "url": "git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git"
24
+ "url": "git+https://github.com/vintasoftware/vinta-ai-workflows.git"
29
25
  },
30
26
  "publishConfig": {
31
27
  "access": "public"
32
28
  },
33
- "license": "MIT"
34
- }
29
+ "license": "MIT",
30
+ "scripts": {
31
+ "check-ai-models": "node scripts/check-ai-models.mjs",
32
+ "test": "node --test tests/*.test.mjs"
33
+ }
34
+ }
package/schemas/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Schemas
2
2
 
3
- JSON Schema (Draft 2020-12) contracts for every YAML file the vinta-ai-workflows toolchain produces or consumes. Every YAML file carries a `schema_version` integer at its top level; that integer matches the suffix on the schema filename.
3
+ JSON Schema (Draft 2020-12) contracts for every YAML or JSON payload the vinta-ai-workflows toolchain produces or consumes. Every payload carries a `schema_version` integer at its top level; that integer matches the suffix on the schema filename.
4
4
 
5
5
  ## Inventory
6
6
 
@@ -12,6 +12,10 @@ JSON Schema (Draft 2020-12) contracts for every YAML file the vinta-ai-workflows
12
12
  | 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` |
13
13
  | 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) |
14
14
  | 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) |
15
+ | 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) |
16
+ | 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) |
17
+
18
+ > `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.
15
19
 
16
20
  ## Versioning rules
17
21
 
@@ -0,0 +1,339 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/vintasoftware/vinta-ai-workflows/schemas/postmortem.v1.schema.json",
4
+ "title": "vinta-ai-maestro plan post-mortem",
5
+ "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.",
6
+ "type": "object",
7
+ "properties": {
8
+ "$schema": {
9
+ "description": "Optional URL of this schema, for editor validation. Ignored at runtime.",
10
+ "type": "string"
11
+ },
12
+ "schema_version": {
13
+ "type": "number",
14
+ "const": 1,
15
+ "description": "Schema major version. Bumped only on breaking changes."
16
+ },
17
+ "run_id": {
18
+ "type": "string",
19
+ "minLength": 1
20
+ },
21
+ "workflow_id": {
22
+ "type": "string",
23
+ "minLength": 1,
24
+ "pattern": "^[a-z0-9][a-z0-9-]*$",
25
+ "description": "The workflow this run executed."
26
+ },
27
+ "plan_ref": {
28
+ "description": "The human-readable plan the workflow was emitted alongside, if it named one.",
29
+ "type": "string"
30
+ },
31
+ "run": {
32
+ "type": "object",
33
+ "properties": {
34
+ "status": {
35
+ "type": "string",
36
+ "enum": [
37
+ "done",
38
+ "failed"
39
+ ]
40
+ },
41
+ "started_at_ms": {
42
+ "type": "integer",
43
+ "minimum": -9007199254740991,
44
+ "maximum": 9007199254740991
45
+ },
46
+ "ended_at_ms": {
47
+ "type": "integer",
48
+ "minimum": -9007199254740991,
49
+ "maximum": 9007199254740991
50
+ },
51
+ "elapsed_ms": {
52
+ "type": "integer",
53
+ "minimum": -9007199254740991,
54
+ "maximum": 9007199254740991
55
+ },
56
+ "node_count": {
57
+ "type": "integer",
58
+ "minimum": 1,
59
+ "maximum": 9007199254740991
60
+ },
61
+ "wave_count": {
62
+ "type": "integer",
63
+ "minimum": 1,
64
+ "maximum": 9007199254740991
65
+ }
66
+ },
67
+ "required": [
68
+ "status",
69
+ "started_at_ms",
70
+ "ended_at_ms",
71
+ "elapsed_ms",
72
+ "node_count",
73
+ "wave_count"
74
+ ],
75
+ "additionalProperties": false,
76
+ "description": "The run this describes. Always finished — an unfinished run has no post-mortem."
77
+ },
78
+ "findings": {
79
+ "type": "object",
80
+ "properties": {
81
+ "unused_dependencies": {
82
+ "type": "array",
83
+ "items": {
84
+ "type": "object",
85
+ "properties": {
86
+ "node": {
87
+ "type": "string",
88
+ "minLength": 1,
89
+ "pattern": "^[a-z0-9][a-z0-9-]*$",
90
+ "description": "The dependent phase."
91
+ },
92
+ "depends_on": {
93
+ "type": "string",
94
+ "minLength": 1,
95
+ "pattern": "^[a-z0-9][a-z0-9-]*$",
96
+ "description": "The upstream phase the edge names."
97
+ }
98
+ },
99
+ "required": [
100
+ "node",
101
+ "depends_on"
102
+ ],
103
+ "additionalProperties": false,
104
+ "description": "One dependency edge, by id. The plan’s own `artifact` prose is deliberately not carried: the reader has the plan, and this file must stay free of repository text."
105
+ },
106
+ "description": "Edges whose artifact the dependent never needed. Empty on every run today: nothing observes dependency use, and the schedule cannot substitute. See `gaps`."
107
+ },
108
+ "missing_dependencies": {
109
+ "type": "array",
110
+ "items": {
111
+ "type": "object",
112
+ "properties": {
113
+ "node": {
114
+ "type": "string",
115
+ "minLength": 1,
116
+ "pattern": "^[a-z0-9][a-z0-9-]*$",
117
+ "description": "The phase that failed and later passed."
118
+ },
119
+ "depends_on": {
120
+ "type": "string",
121
+ "minLength": 1,
122
+ "pattern": "^[a-z0-9][a-z0-9-]*$",
123
+ "description": "The undeclared phase that landed in between."
124
+ },
125
+ "failed_at_ms": {
126
+ "type": "integer",
127
+ "minimum": -9007199254740991,
128
+ "maximum": 9007199254740991,
129
+ "description": "When the phase first failed."
130
+ },
131
+ "landed_at_ms": {
132
+ "type": "integer",
133
+ "minimum": -9007199254740991,
134
+ "maximum": 9007199254740991,
135
+ "description": "When the undeclared phase reached `done`."
136
+ },
137
+ "passed_at_ms": {
138
+ "type": "integer",
139
+ "minimum": -9007199254740991,
140
+ "maximum": 9007199254740991,
141
+ "description": "When the phase finally reached `done`."
142
+ },
143
+ "gate": {
144
+ "description": "The gate whose recorded result is the evidence: it failed at `failed_at_ms` and passed at `passed_at_ms`. Absent when the run recorded no gate result for the phase and the window came from its status transitions instead — a weaker signal, flagged in `gaps`.",
145
+ "type": "string",
146
+ "minLength": 1,
147
+ "pattern": "^[a-z0-9][a-z0-9-]*$"
148
+ }
149
+ },
150
+ "required": [
151
+ "node",
152
+ "depends_on",
153
+ "failed_at_ms",
154
+ "landed_at_ms",
155
+ "passed_at_ms"
156
+ ],
157
+ "additionalProperties": false,
158
+ "description": "A dependency the run discovered and the plan did not declare: the phase failed, an undeclared phase landed, and only then did it pass. The evidence is still ordering — a recorded gate result narrows the window to one gate and rules out an unrelated failure, but it does not prove the undeclared phase is what fixed it. Confirm the edge against the plan before adding it."
159
+ }
160
+ },
161
+ "wave_conflicts": {
162
+ "type": "array",
163
+ "items": {
164
+ "type": "object",
165
+ "properties": {
166
+ "wave": {
167
+ "type": "integer",
168
+ "minimum": 1,
169
+ "maximum": 9007199254740991,
170
+ "description": "The wave whose merge produced the conflict."
171
+ },
172
+ "nodes": {
173
+ "minItems": 2,
174
+ "type": "array",
175
+ "items": {
176
+ "type": "string",
177
+ "minLength": 1,
178
+ "pattern": "^[a-z0-9][a-z0-9-]*$"
179
+ },
180
+ "description": "The phases that both own the contested paths."
181
+ },
182
+ "paths": {
183
+ "type": "array",
184
+ "items": {
185
+ "type": "string"
186
+ },
187
+ "description": "Repository paths that conflicted. Paths, never hunks."
188
+ },
189
+ "fix_rounds": {
190
+ "type": "integer",
191
+ "minimum": 0,
192
+ "maximum": 9007199254740991,
193
+ "description": "Conflict-fixer rounds the resolution took. High is a strong split signal."
194
+ }
195
+ },
196
+ "required": [
197
+ "wave",
198
+ "nodes",
199
+ "paths",
200
+ "fix_rounds"
201
+ ],
202
+ "additionalProperties": false,
203
+ "description": "Two same-wave phases that actually fought over the same code at integration."
204
+ }
205
+ },
206
+ "duration_divergences": {
207
+ "type": "array",
208
+ "items": {
209
+ "type": "object",
210
+ "properties": {
211
+ "node": {
212
+ "type": "string",
213
+ "minLength": 1,
214
+ "pattern": "^[a-z0-9][a-z0-9-]*$"
215
+ },
216
+ "wave": {
217
+ "type": "integer",
218
+ "minimum": 1,
219
+ "maximum": 9007199254740991
220
+ },
221
+ "span_ms": {
222
+ "type": "integer",
223
+ "minimum": -9007199254740991,
224
+ "maximum": 9007199254740991,
225
+ "description": "Dispatch to final settle, including fix rounds."
226
+ },
227
+ "wave_baseline_ms": {
228
+ "type": "integer",
229
+ "minimum": -9007199254740991,
230
+ "maximum": 9007199254740991,
231
+ "description": "Median span of the *other* dispatched phases in the same wave."
232
+ },
233
+ "ratio": {
234
+ "type": "number",
235
+ "description": "`span_ms / wave_baseline_ms`, rounded to two decimals."
236
+ },
237
+ "direction": {
238
+ "type": "string",
239
+ "enum": [
240
+ "longer",
241
+ "shorter"
242
+ ],
243
+ "description": "`longer`: the phase set the wave’s wall clock on its own."
244
+ }
245
+ },
246
+ "required": [
247
+ "node",
248
+ "wave",
249
+ "span_ms",
250
+ "wave_baseline_ms",
251
+ "ratio",
252
+ "direction"
253
+ ],
254
+ "additionalProperties": false,
255
+ "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."
256
+ }
257
+ }
258
+ },
259
+ "required": [
260
+ "unused_dependencies",
261
+ "missing_dependencies",
262
+ "wave_conflicts",
263
+ "duration_divergences"
264
+ ],
265
+ "additionalProperties": false
266
+ },
267
+ "gaps": {
268
+ "type": "array",
269
+ "items": {
270
+ "type": "object",
271
+ "properties": {
272
+ "kind": {
273
+ "type": "string",
274
+ "enum": [
275
+ "dependency_use_unrecorded",
276
+ "gate_result_unrecorded",
277
+ "integration_record_unavailable"
278
+ ]
279
+ },
280
+ "needs": {
281
+ "type": "string",
282
+ "description": "What would have to be recorded for the finding to exist."
283
+ },
284
+ "edges": {
285
+ "description": "The edges the gap applies to.",
286
+ "type": "array",
287
+ "items": {
288
+ "type": "object",
289
+ "properties": {
290
+ "node": {
291
+ "type": "string",
292
+ "minLength": 1,
293
+ "pattern": "^[a-z0-9][a-z0-9-]*$",
294
+ "description": "The dependent phase."
295
+ },
296
+ "depends_on": {
297
+ "type": "string",
298
+ "minLength": 1,
299
+ "pattern": "^[a-z0-9][a-z0-9-]*$",
300
+ "description": "The upstream phase the edge names."
301
+ }
302
+ },
303
+ "required": [
304
+ "node",
305
+ "depends_on"
306
+ ],
307
+ "additionalProperties": false,
308
+ "description": "One dependency edge, by id. The plan’s own `artifact` prose is deliberately not carried: the reader has the plan, and this file must stay free of repository text."
309
+ }
310
+ },
311
+ "nodes": {
312
+ "description": "The phases the gap applies to.",
313
+ "type": "array",
314
+ "items": {
315
+ "type": "string",
316
+ "minLength": 1,
317
+ "pattern": "^[a-z0-9][a-z0-9-]*$"
318
+ }
319
+ }
320
+ },
321
+ "required": [
322
+ "kind",
323
+ "needs"
324
+ ],
325
+ "additionalProperties": false,
326
+ "description": "A finding this run could not produce, and why. Carried in the artifact rather than thrown or defaulted to an empty list: a reader that treats an empty finding as “nothing happened” has to reach past an explicit statement that nothing was recorded."
327
+ }
328
+ }
329
+ },
330
+ "required": [
331
+ "schema_version",
332
+ "run_id",
333
+ "workflow_id",
334
+ "run",
335
+ "findings",
336
+ "gaps"
337
+ ],
338
+ "additionalProperties": false
339
+ }
@@ -312,9 +312,21 @@
312
312
  "default": false
313
313
  },
314
314
  "use_worktree": {
315
- "description": "Default answer to Step 0 question (c) — whether `implement-plan` should provision an isolated git worktree (via `prepare-worktree`) and run every phase's subagent inside it. False = run in the current checkout. True = create one shared worktree at the start of the plan run; all phase branches stack inside it. Per-run prompt still asks; this is the suggested default shown.",
315
+ "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.",
316
316
  "type": "boolean",
317
317
  "default": false
318
+ },
319
+ "parallel_phases": {
320
+ "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.",
321
+ "type": "boolean",
322
+ "default": true
323
+ },
324
+ "max_parallel_lanes": {
325
+ "description": "Upper bound on how many phases `implement-plan` keeps in flight at once, and therefore how many worktree lanes it provisions. Capped at runtime by the widest wave in the plan's dependency graph — a chain-shaped plan provisions one lane regardless. Each lane costs one runnable checkout (deps + forked dev/test DBs + its own compose project), so raise this only on machines with the disk and CPU for it. Ignored when `parallel_phases` is false.",
326
+ "type": "integer",
327
+ "minimum": 1,
328
+ "maximum": 8,
329
+ "default": 3
318
330
  }
319
331
  }
320
332
  },