vinta-ai-workflows 0.2.0-alpha2 → 0.2.0-alpha4

package/CHANGELOG.md

@@ -7,6 +7,205 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [0.2.0] — YYYY-MM-DD
 
+<!-- pre-release: 0.2.0-alpha4 on 2026-07-08 -->
+
+### Added
+
+- **`implement-plan` outer-gate test scope is now configurable — and defaults
+  to the quick path.** Each phase's outer gate still always runs the repo-wide
+  type/build gate, but for tests it now runs **only the scoped suite** covering
+  the apps/files that phase touched by default, instead of the whole repo suite
+  every phase (new tests still pass individually in the inner loop). This
+  **flips the previous default** (full suite every phase → scoped) to make
+  multi-phase plans materially faster. Opt back into the full suite per run via
+  the new Step 0 question (d), or set the default in
+  `.vinta-ai-workflows.yaml` under
+  `run_options.implement-plan.full_test_suite: true`. New config field
+  (`run_options.implement-plan.full_test_suite`, boolean, default `false`);
+  threaded from the conductor into `implement-phase` (outer-gate marker in the
+  implementer prompt) and `review-phase` (Layer 1 verifies whichever gate the
+  flag selects); recorded in `TRACKING_{plan-id}.md` `run_options`.
+
+- **`deslop-comments` foundation skill — Simple-English comment cleanup, now
+  part of the review flow.** Rewrites comments + doc blocks touched during a
+  task into Simple English (strips AI-slop vocabulary and negative framing;
+  comment-only — no renames, no behavior change). Ships at
+  [skills/vinta-derive-skills/resources/foundation-skills/deslop-comments/SKILL.md](skills/vinta-derive-skills/resources/foundation-skills/deslop-comments/SKILL.md).
+  Wired as an **always-ship** bucket-A skill (new
+  `foundation_skills.deslop-comments` enum, added to the derive-skills bucket-A
+  table + always-on note, the bootstrap always-copy-verbatim list + outputs
+  tree + Step 0.5 YAML, and both foundation-shape replace lists) because
+  `review-phase` now depends on it: **Layer 2 gains a comment-hygiene check**
+  and the **fix loop dispatches a `fixer` to run `deslop-comments`** on the
+  phase's touched files for any comment-slop finding. Also invokable
+  standalone ("deslop these comments"). **Consumers**: re-sync to pick up the
+  skill and the `review-phase` comment-hygiene step.
+
+- **`thermo-nuclear-code-quality-review` foundation skill — opt-in deep
+  structural-maintainability audit.** A deliberately harsh, on-demand review
+  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. Copy-verbatim foundation skill
+  (bucket A), read-only — it reports findings and hands each fix to the
+  `fixer` agent. Ships at
+  [skills/vinta-derive-skills/resources/foundation-skills/thermo-nuclear-code-quality-review/SKILL.md](skills/vinta-derive-skills/resources/foundation-skills/thermo-nuclear-code-quality-review/SKILL.md).
+  Wired as **opt-in / ask-first**: new `foundation_skills.thermo-nuclear-code-quality-review`
+  enum in `schemas/vinta-ai-workflows-config.v1.schema.json`, a new
+  question 6 in the bootstrap **Optional foundation skills** interview, and
+  the derive-skills bucket-A + foundation-shape lists. The `review-phase`
+  Layer 3 reviewer now applies a **condensed structural-simplification lens**
+  on every phase and escalates to this full audit only when a phase touches
+  core architecture, crosses ~1,000 lines, or surfaces a structural smell too
+  big to resolve inline — the deep pass never auto-runs on every diff.
+  **Consumers**: re-sync; the bootstrap now asks one more optional-skill
+  question, and `review-phase` gains the escalation hook.
+
+- **`prepare-worktree` — write-guard for *in-process* subagent runtimes
+  (claude-code's Task tool).** `sandbox-run.sh` confines a *process*, so it
+  only works when the harness spawns subagents as subprocesses (`codex exec`,
+  a `claude -p` child). Claude Code runs subagents in-process — same OS
+  process, same tool pipeline, no child command to wrap — so a new
+  harness-config guard covers it instead. Two bundled scripts:
+  `prepare-worktree/scripts/claude-worktree-write-guard.py` (a `PreToolUse`
+  hook that fires for the orchestrator **and** every in-process Task subagent,
+  blocking the file-editing tools — `Edit`/`Write`/`MultiEdit`/`NotebookEdit`
+  — from writing outside the worktree; filesystem-only, no network impact) and
+  `prepare-worktree/scripts/gen-claude-sandbox-settings.sh` (generates the
+  worktree's `.claude/settings.json` wiring that hook, and optionally
+  Claude Code's **native** OS sandbox via `sandbox.filesystem.denyWrite`/
+  `allowWrite` under `--os-sandbox` to also block Bash-issued writes — noting
+  the native sandbox forces network isolation, so registry + git-remote hosts
+  must be allow-listed via `--allow-domain`). Same deny-main/allow-rest model
+  as `sandbox-run.sh`. Step 5.5 of `prepare-worktree` gains an *In-process
+  runtimes (claude-code)* subsection; `implement-plan` §1c makes the
+  previously hand-wavy "in-process runtime" branch concrete. **Consumers**:
+  re-sync `prepare-worktree` + `implement-plan` — the two new scripts ship
+  with the foundation-skill dir.
+
+### Fixed
+
+- **`prepare-worktree/scripts/sandbox-run.sh` — two correctness bugs.**
+  (1) The macOS profile temp file used `mktemp -t vinta-sandbox`, which fails
+  with "too few X's in template" under GNU `mktemp` (present on any machine
+  with coreutils on `PATH`, including many macOS setups) — the whole sandbox
+  path errored out; now uses an explicit `…/vinta-sandbox.XXXXXX` template
+  portable across BSD + GNU `mktemp`. (2) Callers must now pass
+  `--allow <main>/.git`: git worktrees write every commit into the main repo's
+  `.git` (`.git/worktrees/<name>/index.lock`, shared objects/refs), so a
+  deny-main that omits it made the subagent's own `git commit` fail with
+  `Operation not permitted`. `implement-plan` §1c's documented invocation +
+  checklist + rules are updated to include `<main>/.git` in the allow-set.
+
+### Changed
+
+- **`implement-plan` / `amend-plan` decomposed into a modular "plan-execution
+  unit" of deterministic sub-skills.** The single ~440-line
+  `implement-plan-template.md` (and its `implement-plan-template-modular-substitutions.md`
+  sister file) are replaced by a thin **conductor** plus three co-shipped
+  single-purpose sub-skills, all rendered from
+  [skills/vinta-derive-skills/resources/plan-execution/](skills/vinta-derive-skills/resources/plan-execution/)
+  (`shell/` templates that `<!-- include -->` shared `partials/`):
+  - `implement-plan` — conductor: parse → classify → resolve one `WORKROOT`
+    → per-phase loop (dispatch) → track → report.
+  - `implement-phase` — compose prompt + pick model + spawn the implementer.
+  - `review-phase` — the three-layer review + fix loop, now shared by
+    `implement-plan`, `amend-plan`, **and** `systematic-debugging` (one review
+    implementation instead of three).
+  - `integrate-phase` — push + open PR via context file, rendered
+    commit-strategy-resolved.
+  The scattered runtime `if use_worktree` branches collapse into a single
+  `WORKROOT` / `BASE_BRANCH` / `SANDBOX_TIER` seam the conductor resolves once
+  and passes to every sub-skill as data; only two local, data-driven checks
+  remain (the sandbox spawn-wrap in `implement-phase`, the stray-write
+  backstop in `review-phase`). Under `commit_strategy = ask`, the former
+  dual-rendered branch/commit/PR bodies become **two** rendered
+  `integrate-phase-stacked` / `integrate-phase-modular` skills the conductor
+  dispatches by name — no more both-paths-in-one-file. `amend-plan` reuses
+  `review-phase` verbatim + the shared inner/outer verification loop, and
+  picks up the same `WORKROOT` uniformity, while keeping its own
+  history-rewriting topology. **Consumers**: re-sync — the target now gets
+  five plan-execution SKILL.md files (`implement-plan`, `implement-phase`,
+  `review-phase`, `integrate-phase` [or the two `ask` variants], `amend-plan`)
+  instead of two. The three new sub-skills are a co-shipped unit: always
+  generated with `implement-plan`, not individually opt-in (no new
+  `foundation_skills` enum entry, no new interview question). Runtime
+  behavior is unchanged; the decomposition is for reviewability + determinism.
+
+<!-- pre-release: 0.2.0-alpha3 on 2026-06-23 -->
+
+### Added
+
+- **`plan-feature` AI model tier table extracted to a data resource +
+  nightly freshness job.** The per-tier model recommendations that used to
+  be hard-coded in `plan-feature/SKILL.md` now live in
+  `plan-feature/resources/ai-models.yaml` (ships verbatim with the skill;
+  schema: `schemas/ai-models.v1.schema.json`). The SKILL.md body keeps the
+  *tier-selection rubric* (stable judgement) and points at the resource for
+  concrete model IDs, so the prose no longer goes stale. A source-side
+  nightly GitHub Action (`.github/workflows/check-ai-models.yml`, runner
+  `scripts/check-ai-models.mjs`) checks the cited IDs against a **free,
+  no-key model aggregator** (models.dev, LiteLLM JSON as fallback) — no
+  vendor API keys required — flags IDs that disappear or that a newer
+  same-family model has superseded, and on drift has an LLM propose an
+  updated table that it opens as a reviewable PR (the optional LLM step is
+  the only one that uses a key). **Consumers**: re-sync the
+  `plan-feature` skill to pick up a refreshed table; the resource's
+  `last_verified` date signals how current it is.
+
+- **`prepare-worktree` — OS-level filesystem sandbox that *prevents*
+  stray main-checkout writes (harness-agnostic).** The prompt instruction
+  "stay in the worktree" is cooperative only; a smaller phase subagent can
+  resolve a path back to the main checkout and silently write there. A new
+  bundled script `prepare-worktree/scripts/sandbox-run.sh` confines the
+  *process* (not the agent tool) at the kernel layer — `sandbox-exec` on
+  macOS, `bwrap` (bubblewrap) on Linux — using a **deny-main, allow-rest**
+  model: the whole filesystem stays writable except the main checkout, with
+  the worktree (nested under it) and `.vinta-ai-workflows` punched back to
+  writable, so package managers / caches / `$HOME` behave normally and no
+  per-stack allowlist tuning is needed. A stray main-checkout write fails
+  with `Operation not permitted` / `EROFS` regardless of which harness
+  (claude-code, Codex, …) issued it. `prepare-worktree` adds a capability
+  probe + a `sandbox` block in its summary YAML recording the achieved tier
+  (`enforced` / `none`); `implement-plan` wraps each subprocess subagent
+  spawn in the script when `sandbox_tier = enforced`, threads the tier
+  through tracking + the re-running-mid-plan resume path, and downgrades its
+  existing Layer 1 stray-write check from sole defense to a backstop. On
+  machines without a sandbox tool (`tier = none`) the script runs the
+  command unsandboxed with a loud warning and the Layer 1 check remains the
+  guard. Escape hatch: `VINTA_SANDBOX=off`. **Consumers**: re-sync
+  `prepare-worktree` + `implement-plan` to pick up the guard; the whole
+  `prepare-worktree/` dir now ships (SKILL.md + `scripts/sandbox-run.sh`),
+  so re-run the foundation-skill copy, not just the SKILL.md.
+
+### Changed
+
+- **`plan-feature` — per-phase PR-size target raised from ~100–300 LoC to
+  up to 1500 LoC** (tests included). The old "reviewer reads the diff in
+  30 minutes / ~100–300 LoC" guidance forced excessive phase splitting:
+  trivial use-cases became standalone PRs and the phase count ballooned
+  past what a reviewer wants to track. The new ceiling — "reviewer reads
+  ≤1500 LoC and understands the phase in isolation" — keeps phases
+  MR-sized and single-concern while letting a coherent unit of work land
+  in one PR. Pairs with the new **Phase granularity** Step 0 choice
+  below: bundled phases also cap at 1500 LoC. Plan-shape checklist
+  updated to match.
+
+- **`plan-feature` — "one use-case per phase" is now a Step 0 choice, not
+  a hard mandate.** Added a **Phase granularity** question to the Scope
+  group (default: one use-case per phase). The rule, its apply-even-when
+  list, and the checklist item now branch on the answer — opting into
+  bundling lets closely-related use-cases share a phase as long as each
+  phase stays MR-sized, single-concern, and independently mergeable.
+
+- **E2E content is stripped from no-e2e projects.** `create-qa-use-cases`
+  now ships **only when `add-e2e-test` is enabled** (it seeds e2e specs),
+  and `plan-feature`'s Playwright / `QA_USE_CASES.md` / `pr-screenshots/`
+  sections are wrapped in `<!-- e2e:start/end -->` markers that
+  `vinta-derive-skills` strips when `add-e2e-test` is disabled. The
+  bootstrap `add-e2e-test` answer now also sets
+  `foundation_skills.create-qa-use-cases`. Result: projects marked as
+  having no e2e tests get foundation skills with zero e2e references.
+  
 <!-- pre-release: 0.2.0-alpha2 on 2026-06-13 -->
 
 ### Changed

package/README.md

@@ -222,8 +222,11 @@ Land at `ai-tools/skills/<name>/SKILL.md`. Always-on unless flagged optional.
 | [`plan-feature`](skills/vinta-derive-skills/resources/foundation-skills/plan-feature/SKILL.md) | always | Phased delivery plan from the matching spec → `ai-plans/YYYY-MM-DD-FEATURE_NAME_PLAN.md`. |
 | [`create-qa-use-cases`](skills/vinta-derive-skills/resources/foundation-skills/create-qa-use-cases/SKILL.md) | always | Bootstrap `QA_USE_CASES.md` from the active spec / plan. Called by `plan-feature` when missing. |
 | [`open-pr-from-context`](skills/vinta-derive-skills/resources/foundation-skills/open-pr-from-context/SKILL.md) | always | Publish a `.vinta-ai-workflows/prs-context/<feature>/<phase>.md` file as a real PR + inline comments via `gh` / `glab`. Bundles [`open-pr.sh`](skills/vinta-derive-skills/resources/foundation-skills/open-pr-from-context/scripts/open-pr.sh). |
-| `implement-plan` | always (generated) | Phase-by-phase plan execution. Generated from a template with project commands + branch / PR / co-author policy. |
-| `amend-plan` | always (generated) | History-rewriting companion to `implement-plan` — revises in-flight plans, amends prior-phase commits, force-pushes, rebases stacked downstream branches. |
+| `implement-plan` | always (generated) | Phase-by-phase plan execution. Thin **conductor**: parses the plan, resolves one `WORKROOT`, and runs a fixed pipeline per phase (`implement-phase` → `review-phase` → `integrate-phase`), tracking + reporting. Generated from a template with project commands + branch / PR / co-author policy. |
+| `implement-phase` | always (unit) | Plan-execution sub-skill co-shipped with `implement-plan`: compose the implementer prompt, pick the model, spawn one implementer subagent for a single phase. |
+| `review-phase` | always (unit) | Plan-execution sub-skill: the three-layer review (mechanical / plan-compliance / independent reviewer) + fix loop. Shared by `implement-plan`, `amend-plan`, and `systematic-debugging`. |
+| `integrate-phase` | always (unit) | Plan-execution sub-skill: push the reviewed phase along the project's commit strategy + open the PR via context file. Under `commit_strategy = ask`, ships as `integrate-phase-stacked` + `integrate-phase-modular`. |
+| `amend-plan` | always (generated) | History-rewriting companion to `implement-plan` — revises in-flight plans, amends prior-phase commits, force-pushes, rebases stacked downstream branches. Reuses `review-phase` + `implement-phase`'s shared prompt loop. |
 | `systematic-debugging` | **opt-in** | Root-cause-first debugging with project-specific repro commands + MCP evidence-gathering (error tracking, traces, logs, metrics, alerts). Renders from a catalogue of observability MCP servers the user declares. |
 | `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. |
 | `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). |

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "vinta-ai-workflows",
-  "version": "0.2.0-alpha2",
+  "version": "0.2.0-alpha4",
   "description": "Bootstrap AI tooling (AGENTS.md, skills, sub-agents) across Claude Code, Codex, Cursor, and VS Code + GitHub Copilot.",
   "type": "module",
   "bin": {
     "vinta-ai-workflows": "./vinta-ai-workflows.mjs"
   },
+  "scripts": {
+    "check-ai-models": "node scripts/check-ai-models.mjs"
+  },
+  "devDependencies": {
+    "yaml": "^2.4.0"
+  },
   "files": [
     "vinta-ai-workflows.mjs",
     "skills",

package/schemas/README.md

@@ -11,6 +11,7 @@ JSON Schema (Draft 2020-12) contracts for every YAML file the vinta-ai-workflows
 | PR-context frontmatter | top-of-file YAML in `.vinta-ai-workflows/prs-context/{feature-kebab}/phase-{phase.id}.md` | [`prs-context-frontmatter.v1.schema.json`](prs-context-frontmatter.v1.schema.json) | `implement-plan` / `amend-plan` | `open-pr.sh` |
 | PR-context inline comments | YAML inside the ` ```yaml ... ``` ` fence under `# Comments` of the same file | [`prs-context-comments.v1.schema.json`](prs-context-comments.v1.schema.json) | `implement-plan` / `amend-plan` | `open-pr.sh` |
 | 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) |
 
 ## Versioning rules
 

package/schemas/ai-models.v1.schema.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/vintasoftware/vinta-ai-workflows/schemas/ai-models.v1.schema.json",
+  "title": "AI model tier table",
+  "description": "Per-tier AI model recommendations consumed by the plan-feature skill and maintained by the nightly check-ai-models job. Source of truth for concrete model IDs; the SKILL.md body carries only selection guidance.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "last_verified", "source", "tiers"],
+  "properties": {
+    "schema_version": {
+      "const": 1,
+      "description": "Matches the v1 suffix on this schema filename."
+    },
+    "last_verified": {
+      "type": "string",
+      "format": "date",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "Date every model id below was last confirmed to still exist against the aggregator."
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["primary"],
+      "description": "Free, no-key model-list aggregators the checker queries. Vendors tracked are derived from the `models` keys under `tiers`.",
+      "properties": {
+        "primary": {
+          "type": "string",
+          "format": "uri",
+          "description": "Primary aggregator JSON (e.g. models.dev/api.json), vendor-keyed with a `.models` map per provider."
+        },
+        "fallback": {
+          "type": "string",
+          "format": "uri",
+          "description": "Fallback aggregator JSON used when the primary is unreachable (e.g. LiteLLM price/context JSON)."
+        }
+      }
+    },
+    "tiers": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["tier", "label", "use_for", "models"],
+        "properties": {
+          "tier": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Tier number, cheapest/fastest (1) → architectural/hard."
+          },
+          "label": {
+            "type": "string",
+            "description": "Short tier name."
+          },
+          "use_for": {
+            "type": "string",
+            "description": "When to reach for this tier."
+          },
+          "models": {
+            "type": "object",
+            "description": "Vendor key → ordered list of recommended models for this tier. Keys should match entries in the top-level `vendors` map.",
+            "minProperties": 1,
+            "additionalProperties": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["id"],
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "description": "Vendor model id as it appears in the vendor's model-list API."
+                  },
+                  "note": {
+                    "type": "string",
+                    "description": "Optional caveat (fallback, variant, when-to-step-up)."
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -188,7 +188,11 @@
       "properties": {
         "plan-feature": { "type": "string", "enum": ["enabled", "disabled"] },
         "create-spec": { "type": "string", "enum": ["enabled", "disabled"] },
-        "create-qa-use-cases": { "type": "string", "enum": ["enabled", "disabled"] },
+        "create-qa-use-cases": {
+          "description": "Bootstrap `QA_USE_CASES.md` from the active spec/plan. Coupled to `add-e2e-test`: QA use-cases seed e2e specs, so ship (and set `enabled`) only when `add-e2e-test` is `enabled`. When `add-e2e-test` is `disabled`, set this `disabled` too — derive-skills won't ship the skill and strips the e2e regions from `plan-feature`.",
+          "type": "string",
+          "enum": ["enabled", "disabled"]
+        },
         "implement-plan": { "type": "string", "enum": ["enabled", "disabled"] },
         "amend-plan": { "type": "string", "enum": ["enabled", "disabled"] },
         "open-pr-from-context": { "type": "string", "enum": ["enabled", "disabled"] },
@@ -208,6 +212,16 @@
           "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.",
           "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.",
+          "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.",
+          "type": "string",
+          "enum": ["enabled", "disabled"]
         }
       }
     },
@@ -246,6 +260,11 @@
           "properties": {
             "pause_between_phases": { "type": "boolean", "default": false },
             "generate_inline_comments": { "type": "boolean", "default": false },
+            "full_test_suite": {
+              "description": "Default answer to Step 0 question (d) — what each phase's outer gate runs for tests. False (default) = quick path: the outer gate runs only the scoped test suite covering the apps/files the phase touched (new tests still pass individually in the inner loop). True = run the full repo test suite in every phase's outer gate, guarding against regressions in untouched code at the cost of slower phases. The repo-wide type/build gate runs every phase either way. Per-run prompt still asks; this is the suggested default shown.",
+              "type": "boolean",
+              "default": false
+            },
             "use_worktree": {
               "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.",
               "type": "boolean",

package/skills/vinta-analyze-codebase/SKILL.md

@@ -155,7 +155,7 @@ This is a load-bearing input for the rest of the bootstrap flow — surface ever
 For each skill, also classify:
 
 - `vinta-managed` — directory name starts with `vinta-` (installed by `vinta-ai-workflows`; can be left alone or refreshed via that CLI).
-- `foundation-shape` — name matches the Vinta foundation set (`plan-feature`, `create-spec`, `create-qa-use-cases`, `implement-plan`, `add-e2e-test`, `add-env-var`).
+- `foundation-shape` — name matches the Vinta foundation set (`plan-feature`, `create-spec`, `create-qa-use-cases`, `implement-plan`, `implement-phase`, `review-phase`, `integrate-phase`, `amend-plan`, `add-e2e-test`, `add-env-var`). `implement-phase` / `review-phase` / `integrate-phase` are the plan-execution sub-skills co-shipped with `implement-plan`.
 - `project-custom` — anything else; written by the team.
 
 **Sub-agents** — list every agent file with its name + description:

package/skills/vinta-bootstrap-ai-tools/SKILL.md

@@ -83,9 +83,9 @@ These bleed across sub-skills, so capture once now:
 
 ### D. Optional foundation skills
 
-Five skills are part of the foundation set but aren't always needed. Ask explicitly:
+Six skills are part of the foundation set but aren't always needed. Ask explicitly:
 
-1. **`add-e2e-test`** — does the project have e2e tests (Playwright / Cypress / similar) or plan to add them? `AskUserQuestion` options: `Yes — already has them`, `Yes — planning to add`, `No — skip`. If yes, [vinta-derive-skills](../vinta-derive-skills/SKILL.md)'s **Optional — ask the user** bucket follows up to ask whether the user has a template or wants to draft from scratch.
+1. **`add-e2e-test`** — does the project have e2e tests (Playwright / Cypress / similar) or plan to add them? `AskUserQuestion` options: `Yes — already has them`, `Yes — planning to add`, `No — skip`. If yes, [vinta-derive-skills](../vinta-derive-skills/SKILL.md)'s **Optional — ask the user** bucket follows up to ask whether the user has a template or wants to draft from scratch. **This answer also governs `create-qa-use-cases` and the e2e content inside `plan-feature`**: on `No — skip`, set `foundation_skills.create-qa-use-cases: disabled` too — derive-skills won't ship `create-qa-use-cases` and strips `plan-feature`'s `<!-- e2e:start/end -->` regions so no-e2e projects carry zero Playwright / `QA_USE_CASES.md` / `pr-screenshots/` references. On either `Yes`, set both `add-e2e-test` and `create-qa-use-cases` to `enabled`.
 2. **`add-env-var`** — does the project have a non-trivial env-var propagation flow (multiple files / build configs / CI updates per new var) or a single `.env` file is enough? `AskUserQuestion` options: `Yes — non-trivial flow`, `No — single .env is enough`. Skip if `No`.
 3. **`systematic-debugging`** — should agents follow a root-cause-first debugging flow that mandates pulling evidence from the project's observability MCP servers before proposing any fix? `AskUserQuestion` options: `Yes — enable`, `No — skip`. Recommend enabling whenever any observability MCP server is wired up — the skill bakes the project's real test / lint / build commands into the rendered checklist and instructs the agent to discover available calls on those servers at runtime (so it stays correct even as MCP servers add or rename tools).
 4. **`add-one-off-script`** — does the project ever need one-off operational scripts (backfills, cleanups, ad-hoc data fixes) that mutate production data outside the regular migration / ETL / cron path? `AskUserQuestion` options: `Yes — enable`, `No — skip`. Recommend `Yes` for any project with a relational DB or large user dataset; the bundled `BaseOneOffScript` template enforces the safety contract (dry-run by default, idempotent re-runs, batched DB ops, streamed reads, segmented CSV backups capped at 1M cells per file with one set of files per affected table, interruption-safe signal handlers, console + filesystem + S3 logs that survive an interruption). Skip for read-only projects or projects whose only writes go through a migration tool.
@@ -112,7 +112,9 @@ Five skills are part of the foundation set but aren't always needed. Ask explici
    - Do **not** seed the cache file at bootstrap. The first debug run preflights all configured servers and writes the file then. An empty / missing `.vinta-ai-workflows/cache.yaml` is a valid initial state.
    - Mention to the user how to refresh: delete the file to re-preflight everything, or edit one entry's `status` to `dirty` to refresh that one server. Token rotated → cache will catch the auth error on the next call and flip the entry to `dirty` automatically.
 
-If the user answers "No" to any of the five, that skill won't ship. If the user answers "Yes" to `add-e2e-test` / `add-env-var` but doesn't have a template, derive-skills drafts one via interview. `systematic-debugging` is always template-rendered — no per-project drafting interview, just the MCP-server inventory above. `add-one-off-script` is copied verbatim from [vinta-derive-skills/resources/foundation-skills/add-one-off-script/](../vinta-derive-skills/resources/foundation-skills/add-one-off-script/) — its body is project-agnostic; the per-project variability lives in the `skills.add-one-off-script.*` config block above and in env vars consumed at runtime. `prepare-worktree` is also copied verbatim from [vinta-derive-skills/resources/foundation-skills/prepare-worktree/](../vinta-derive-skills/resources/foundation-skills/prepare-worktree/) — same pattern: project-agnostic body, per-project defaults under `skills.prepare-worktree.*`.
+6. **`thermo-nuclear-code-quality-review`** — does the team want an opt-in, deliberately harsh structural-maintainability audit available on demand (abstraction quality, giant files, spaghetti-condition growth), separate from the standard per-phase review? `AskUserQuestion` options: `Yes — enable`, `No — skip`. Recommend `Yes` for long-lived codebases where structural drift is a real cost, or teams that already run deep quality passes before merging large work. It ships as a user-invoked skill and is also the escalation target for the `review-phase` Layer 3 structural-simplification lens; it is never auto-run on every diff. No follow-up config — the body is project-agnostic.
+
+If the user answers "No" to any of the six, that skill won't ship. If the user answers "Yes" to `add-e2e-test` / `add-env-var` but doesn't have a template, derive-skills drafts one via interview. `systematic-debugging` is always template-rendered — no per-project drafting interview, just the MCP-server inventory above. `add-one-off-script` is copied verbatim from [vinta-derive-skills/resources/foundation-skills/add-one-off-script/](../vinta-derive-skills/resources/foundation-skills/add-one-off-script/) — its body is project-agnostic; the per-project variability lives in the `skills.add-one-off-script.*` config block above and in env vars consumed at runtime. `prepare-worktree` is also copied verbatim from [vinta-derive-skills/resources/foundation-skills/prepare-worktree/](../vinta-derive-skills/resources/foundation-skills/prepare-worktree/) — same pattern: project-agnostic body, per-project defaults under `skills.prepare-worktree.*`. `thermo-nuclear-code-quality-review` is copied verbatim from [vinta-derive-skills/resources/foundation-skills/thermo-nuclear-code-quality-review/](../vinta-derive-skills/resources/foundation-skills/thermo-nuclear-code-quality-review/) with no follow-up config — its body is fully project-agnostic.
 
 ### E. Existing AI artifacts (per-artifact disposition)
 
@@ -132,7 +134,7 @@ For each artifact, read it (frontmatter + body), then ask the user via `AskUserQ
   - `Keep in current vendor path, don't touch` — leaves it where it is. AGENTS.md may reference it; downstream skill setup won't manage it.
   - `Drop` — delete (rare; usually the user wants to migrate).
 
-  Foundation-shape skills (name matches `plan-feature`, `create-spec`, `create-qa-use-cases`, `implement-plan`, `add-e2e-test`, `add-env-var`, `add-one-off-script`, `prepare-worktree`) get an extra option: `Replace with Vinta foundation version` — overwrites with the canonical foundation content, preserving the user's name. Useful when the existing version is stale.
+  Foundation-shape skills (name matches `plan-feature`, `create-spec`, `create-qa-use-cases`, `implement-plan`, `implement-phase`, `review-phase`, `integrate-phase`, `amend-plan`, `add-e2e-test`, `add-env-var`, `add-one-off-script`, `prepare-worktree`, `thermo-nuclear-code-quality-review`, `deslop-comments`) get an extra option: `Replace with Vinta foundation version` — overwrites with the canonical foundation content, preserving the user's name. Useful when the existing version is stale. (`implement-phase` / `review-phase` / `integrate-phase` are the plan-execution sub-skills co-shipped with `implement-plan`; replace them as a unit.)
 
 - **Sub-agents** (each under any vendor `agents/` dir):
   - `Migrate to ai-tools/agents/<name>.yaml` — converts vendor-specific format → canonical YAML; `setup-ai-tools.mjs` re-emits per-vendor copies.
@@ -250,6 +252,8 @@ foundation_skills:
   systematic-debugging: <Optional foundation skills → systematic-debugging answer → enabled | disabled>
   add-one-off-script: <Optional foundation skills → add-one-off-script answer → enabled | disabled>
   prepare-worktree: <Optional foundation skills → prepare-worktree answer → enabled | disabled>
+  thermo-nuclear-code-quality-review: <Optional foundation skills → thermo-nuclear-code-quality-review answer → enabled | disabled>
+  deslop-comments: enabled  # always ships — review-phase Layer 2 comment-hygiene + fix loop depend on it
 
 foundation_agents:
   implementer: enabled
@@ -263,6 +267,7 @@ run_options:
   implement-plan:
     pause_between_phases: false
     generate_inline_comments: false
+    full_test_suite: false  # default: each phase's outer gate runs scoped tests only; set true to run the full suite every phase
     use_worktree: <Optional foundation skills → prepare-worktree follow-up → default for Step 0 question (c); false unless team opted in>
   amend-plan:
     blast_radius_signal_threshold: 2
@@ -340,8 +345,12 @@ ai-tools/
 │   ├── plan-feature/SKILL.md            ← always (copied verbatim from derive-skills resources)
 │   ├── create-spec/SKILL.md             ← always (copied verbatim)
 │   ├── create-qa-use-cases/SKILL.md     ← always (copied verbatim)
-│   ├── implement-plan/SKILL.md          ← always (generated from template, project-specific)
-│   ├── amend-plan/SKILL.md              ← always (generated from template, project-specific)
+│   ├── deslop-comments/SKILL.md         ← always (copied verbatim; review-phase Layer 2 comment-hygiene + fix loop depend on it)
+│   ├── implement-plan/SKILL.md          ← always (conductor; generated from template, project-specific)
+│   ├── implement-phase/SKILL.md         ← always (plan-execution unit; co-shipped with implement-plan)
+│   ├── review-phase/SKILL.md            ← always (plan-execution unit; shared by implement-plan / amend-plan / systematic-debugging)
+│   ├── integrate-phase/SKILL.md         ← always (plan-execution unit; push + PR. Under commit_strategy=ask: integrate-phase-stacked/ + integrate-phase-modular/ instead)
+│   ├── amend-plan/SKILL.md              ← always (conductor; generated from template, project-specific)
 │   ├── add-e2e-test/SKILL.md            ← optional — only if user opts in
 │   ├── add-env-var/SKILL.md             ← optional — only if user opts in
 │   ├── systematic-debugging/SKILL.md    ← optional — only if user opts in (template-rendered)
@@ -351,6 +360,7 @@ ai-tools/
 │   │       ├── one_off_script_base.py
 │   │       └── one_off_script_base.ts
 │   ├── prepare-worktree/SKILL.md       ← optional — only if user opts in (verbatim copy; project-agnostic body, defaults under skills.prepare-worktree.*)
+│   ├── thermo-nuclear-code-quality-review/SKILL.md ← optional — only if user opts in (verbatim copy; deep structural-maintainability audit, escalation target for review-phase Layer 3)
 │   ├── run-one-off-script-django/       ← optional sister skill — only when stack matches + user supplies template (authors Jupyter notebook / mgmt command runner + JupyterRuntime / DjangoMgmtRuntime adapter in the per-script folder)
 │   ├── run-one-off-script-medplum/      ← optional sister skill — only when stack matches + user supplies template (authors Medplum bot + MedplumBotRuntime adapter in the per-script folder)
 │   └── <stack-specific skills>/SKILL.md ← only if user supplied templates
@@ -379,9 +389,9 @@ Plus the symlinks + per-vendor generated files, set up by the install step.
 
 Foundation skills break into three buckets — see [vinta-derive-skills](../vinta-derive-skills/SKILL.md) for the full mechanics:
 
-- **Always copy verbatim**: `plan-feature`, `create-spec`, `create-qa-use-cases`. Bundled with the bootstrap skill set; project-agnostic enough to ship as-is (with light path scrubs).
-- **Always generate**: `implement-plan`, `amend-plan`. Bodies have too much project-specific content (test commands, branch convention, PR + co-author policy, agent dispatch) — generated from parameterized templates using interview answers + inventory.
-- **Optional, ask first**: `add-e2e-test`, `add-env-var`, `systematic-debugging`, `add-one-off-script`, `prepare-worktree`. Skipped by default; orchestrator asks via `AskUserQuestion` whether the project has the relevant flow at all. `add-e2e-test` / `add-env-var`: if yes + user has a template → copy + adapt; if yes + no template → draft from scratch via interview; if no → don't ship. `systematic-debugging`: if yes → render the bundled template plus the per-tool MCP catalogue blocks for the observability tools selected in its follow-up; if no → don't ship. `add-one-off-script`: if yes → copy the bundled SKILL.md verbatim plus the language-specific `BaseOneOffScript` template (`one_off_script_base.py` / `one_off_script_base.ts`) chosen via its follow-up; if no → don't ship. `prepare-worktree`: if yes → copy the bundled SKILL.md verbatim, populate `skills.prepare-worktree.*` defaults from its follow-ups, and (when the user opted in via the worktree-default follow-up) flip `run_options.implement-plan.use_worktree` to `true` so `implement-plan`'s Step 0 question (c) defaults to yes; if no → don't ship.
+- **Always copy verbatim**: `plan-feature`, `create-spec`, `create-qa-use-cases`, `deslop-comments`. Bundled with the bootstrap skill set; project-agnostic enough to ship as-is (with light path scrubs). `deslop-comments` always ships because `review-phase`'s Layer 2 comment-hygiene check + fix loop dispatch it.
+- **Always generate**: the plan-execution unit — `implement-plan` (conductor) + its co-shipped sub-skills `implement-phase` / `review-phase` / `integrate-phase`, plus `amend-plan` (conductor). Bodies have too much project-specific content (test commands, branch convention, PR + co-author policy, agent dispatch) — generated from parameterized templates + shared partials using interview answers + inventory. The sub-skills are not independently opt-in; they always ship with the conductors.
+- **Optional, ask first**: `add-e2e-test`, `add-env-var`, `systematic-debugging`, `add-one-off-script`, `prepare-worktree`, `thermo-nuclear-code-quality-review`. Skipped by default; orchestrator asks via `AskUserQuestion` whether the project has the relevant flow at all. `add-e2e-test` / `add-env-var`: if yes + user has a template → copy + adapt; if yes + no template → draft from scratch via interview; if no → don't ship. `systematic-debugging`: if yes → render the bundled template plus the per-tool MCP catalogue blocks for the observability tools selected in its follow-up; if no → don't ship. `add-one-off-script`: if yes → copy the bundled SKILL.md verbatim plus the language-specific `BaseOneOffScript` template (`one_off_script_base.py` / `one_off_script_base.ts`) chosen via its follow-up; if no → don't ship. `prepare-worktree`: if yes → copy the bundled SKILL.md verbatim, populate `skills.prepare-worktree.*` defaults from its follow-ups, and (when the user opted in via the worktree-default follow-up) flip `run_options.implement-plan.use_worktree` to `true` so `implement-plan`'s Step 0 question (c) defaults to yes; if no → don't ship. `thermo-nuclear-code-quality-review`: if yes → copy the bundled SKILL.md verbatim (no follow-up config); if no → don't ship.
 
 Stack-specific skills + agents land in the target only when the user provides templates for them. If they don't have templates yet, the orchestrator records the detected stacks + skill categories as a TODO list the user can address later via [vinta-derive-skills](../vinta-derive-skills/SKILL.md) / [vinta-derive-subagents](../vinta-derive-subagents/SKILL.md) standalone runs.