vinta-ai-workflows 0.2.0-alpha3 → 0.2.0-alpha5

package/skills/vinta-derive-skills/resources/{implement-plan-template-modular-substitutions.md → plan-execution/partials/commit-strategy/modular.md}

@@ -1,36 +1,29 @@
-# Modular-commits substitutions for `implement-plan-template.md`
+<!-- Partial: commit-strategy / modular-commits. Folds in the former implement-plan-template-modular-substitutions.md. Blocks consumed by implement-phase (PER_PHASE_COMMIT) + integrate-phase (BRANCH_NAMING, PR_OPEN_TIMING) + conductor (CHECKLIST). All git calls use `git -C <WORKROOT>`; the first executed phase branches off `<BASE_BRANCH>` — both resolved once by the conductor (see worktree-seam.md#WORKROOT_RESOLUTION). The rendering-guidance appendix at the bottom is read by derive-skills to resolve the {{MODULAR_*}} placeholders; it is NOT part of any shipped block. -->
 
-This file holds the substitution bodies for the `{{COMMIT_STRATEGY_*}}` placeholder family when `policies.commit_strategy = modular-commits`. The `stacked-branches` substitutions are inline in the parent placeholder table in [SKILL.md](../SKILL.md). The `ask` variant emits **both** the stacked and the modular bodies gated by inline runtime markers — see [Phase 4 ask-mode substitutions](#ask-mode-substitutions) at the bottom.
-
-Each section below is delimited by `<!-- substitution: {{PLACEHOLDER}} -->` markers so derive-skills can extract the block by name. The block's content is everything between the open and close markers, **excluding** the markers themselves.
-
-## `{{BRANCH_NAMING_BLOCK}}` (modular)
-
-<!-- substitution-begin: BRANCH_NAMING_BLOCK -->
+<!-- block-begin: BRANCH_NAMING -->
 Branch naming: `plan/{plan-id-kebab}` (one branch for the whole plan — no per-phase suffix).
 
-**First executed phase** (branches from `{{DEFAULT_BRANCH}}`):
+**First executed phase** (branches from `<BASE_BRANCH>`, already made current by the conductor):
+
 ```bash
-git checkout {{DEFAULT_BRANCH}}
-git pull --ff-only
-git checkout -b plan/{plan-id-kebab}
+git -C <WORKROOT> checkout <BASE_BRANCH>
+git -C <WORKROOT> checkout -b plan/{plan-id-kebab}
 # subagent's atomic unit commits land on this branch
-git push -u origin plan/{plan-id-kebab}
+git -C <WORKROOT> push -u origin plan/{plan-id-kebab}
 ```
 
 **Subsequent phases** (stay on the same plan branch — no new branch):
+
 ```bash
-git checkout plan/{plan-id-kebab}
+git -C <WORKROOT> checkout plan/{plan-id-kebab}
 # subagent's atomic unit commits land on this branch
-git push origin plan/{plan-id-kebab}
+git -C <WORKROOT> push origin plan/{plan-id-kebab}
 ```
 
 The branch carries every phase's commits in plan order. Reviewers read the commit log top-to-bottom as a table of contents of the implementation.
-<!-- substitution-end: BRANCH_NAMING_BLOCK -->
+<!-- block-end: BRANCH_NAMING -->
 
-## `{{PER_PHASE_COMMIT_BLOCK}}` (modular)
-
-<!-- substitution-begin: PER_PHASE_COMMIT_BLOCK -->
+<!-- block-begin: PER_PHASE_COMMIT -->
 7. **Plan commit units before staging.** List the logical units this phase produces (e.g. `3 services + 1 use case update + 1 init export`). Each unit = **one** commit. Tests for that unit travel **in the same commit** as the code they test — never a separate commit.
 8. For each unit, in order:
    a. Stage exactly that unit's files: `git add <explicit paths>` (NEVER `git add -A` — {{ANTI_GIT_ADD_ALL_REASON}}). Tests for the unit go in the same `git add`.
@@ -76,11 +69,35 @@ Tests for a unit belong **in the same commit** as that unit. Never commit tests
 | "The user can squash later" | Squashing destroys the logical history this discipline exists to preserve. |
 | "It's faster to do one commit" | Planning units takes 2 minutes; reviewing a 2000-line blob takes much longer. |
 | "The changes are all related" | Related ≠ same unit. Services that depend on each other still get separate commits. |
-<!-- substitution-end: PER_PHASE_COMMIT_BLOCK -->
+<!-- block-end: PER_PHASE_COMMIT -->
+
+<!-- block-begin: PR_OPEN_TIMING -->
+**PR opens once — after Phase 1 passes review.** Subsequent phases push their atomic unit commits to the same plan branch (`plan/{plan-id-kebab}`); the orchestrator re-runs [open-pr.sh](../open-pr-from-context/scripts/open-pr.sh) against the same plan-level prs-context file at `.vinta-ai-workflows/prs-context/{feature-kebab}/plan.md`. The script is idempotent for already-open PRs — it updates the body, appends new inline comments, and posts a `Phase {N} complete — pushed M commits` PR comment.
+<!-- block-end: PR_OPEN_TIMING -->
+
+<!-- block-begin: CHECKLIST -->
+- [ ] Commit units listed upfront before any staging.
+- [ ] Each commit covers exactly one logical unit (no "and" in commit messages).
+- [ ] Tests landed in the same commit as the code they cover (never a separate test-only commit).
+- [ ] All unit commits pushed to `plan/{plan-id-kebab}` at end of phase.
+<!-- block-end: CHECKLIST -->
+
+<!-- Single-line values (derive-skills substitutes these into the shells directly):
+     BRANCH_PUSH_HEADING            = Push to plan branch
+     BRANCH_NAMING_PATTERN_SUMMARY  = plan branch (one branch for whole plan: `plan/{plan-id-kebab}`)
+     PRS_CONTEXT_FILE_PATH          = a single `.vinta-ai-workflows/prs-context/{feature-kebab}/plan.md` file (one PR per plan, not per phase)
+     TRACKING_BRANCH_FIELD          = top-level `plan_branch:` field
+     TRACKING_PHASE_BRANCH_FIELD    = (empty — no per-phase branch under modular)
+     FINAL_REPORT_BRANCH_SUMMARY    = single plan branch `plan/{plan-id-kebab}` with commit log organized by phase
+     BRANCH_CHECKLIST_LINE          = Plan branch updated with phase commits; pushed. -->
+
+<!-- ===================================================================== -->
+<!-- rendering-guidance (read by derive-skills; NOT shipped in any block)  -->
+<!-- ===================================================================== -->
 
 ### Conditional example messages (driven by `policies.commit_style`)
 
-derive-skills resolves the six `{{MODULAR_EXAMPLE_*}}` placeholders + the `{{MODULAR_COMMIT_MESSAGE_FORMAT_BLOCK}}` from this table when rendering `{{PER_PHASE_COMMIT_BLOCK}}`:
+derive-skills resolves the six `{{MODULAR_EXAMPLE_*}}` placeholders + the `{{MODULAR_COMMIT_MESSAGE_FORMAT_BLOCK}}` from this table when rendering the `PER_PHASE_COMMIT` block above:
 
 | Placeholder | `commit_style = conventional` | `commit_style = imperative` | `commit_style = other` |
 |---|---|---|---|
@@ -147,52 +164,3 @@ WIP
 add stuff
 Implement full record copy feature   ← too broad, should be split
 ```
-
-## `{{PR_OPEN_TIMING_BLOCK}}` (modular)
-
-<!-- substitution-begin: PR_OPEN_TIMING_BLOCK -->
-**PR opens once — after Phase 1 passes review.** Subsequent phases push their atomic unit commits to the same plan branch (`plan/{plan-id-kebab}`); the orchestrator re-runs [open-pr.sh](../foundation-skills/open-pr-from-context/scripts/open-pr.sh) against the same plan-level prs-context file at `.vinta-ai-workflows/prs-context/{feature-kebab}/plan.md`. The script is idempotent for already-open PRs — it updates the body, appends new inline comments, and posts an `Phase {N} complete — pushed M commits` PR comment.
-
-<!-- substitution-end: PR_OPEN_TIMING_BLOCK -->
-
-## `{{COMMIT_STRATEGY_CHECKLIST_BLOCK}}` (modular)
-
-<!-- substitution-begin: COMMIT_STRATEGY_CHECKLIST_BLOCK -->
-- [ ] Commit units listed upfront before any staging.
-- [ ] Each commit covers exactly one logical unit (no "and" in commit messages).
-- [ ] Tests landed in the same commit as the code they cover (never a separate test-only commit).
-- [ ] All unit commits pushed to `plan/{plan-id-kebab}` at end of phase.
-<!-- substitution-end: COMMIT_STRATEGY_CHECKLIST_BLOCK -->
-
-## Other modular substitutions (single-line — listed for completeness)
-
-| Placeholder | Modular substitution |
-|---|---|
-| `{{BRANCH_PUSH_HEADING}}` | `Push to plan branch` |
-| `{{BRANCH_NAMING_PATTERN_SUMMARY}}` | ``plan branch (one branch for whole plan: `plan/{plan-id-kebab}`)`` |
-| `{{PRS_CONTEXT_FILE_PATH_DESCRIPTION}}` | `` a single `.vinta-ai-workflows/prs-context/{feature-kebab}/plan.md` file (one PR per plan, not per phase) `` |
-| `{{TRACKING_BRANCH_FIELD}}` | `top-level \`plan_branch:\` field` |
-| `{{TRACKING_PHASE_BRANCH_FIELD}}` | empty string (no per-phase branch under modular) |
-| `{{FINAL_REPORT_BRANCH_SUMMARY}}` | ``single plan branch `plan/{plan-id-kebab}` with commit log organized by phase`` |
-| `{{BRANCH_CHECKLIST_LINE}}` | `Plan branch updated with phase commits; pushed.` |
-| `{{COMMIT_STRATEGY_STEP0_QUESTION}}` | empty string (modular is set as the project default; nothing to ask) |
-| `{{COMMIT_STRATEGY_STEP0_TRAILER}}` | empty string |
-| `{{COMMIT_STRATEGY_CONFIRM_NOTE}}` | empty string |
-
-## Ask-mode substitutions
-
-When `policies.commit_strategy = ask`, derive-skills renders **both** the stacked-branches and the modular-commits bodies for each multi-line placeholder, gated by inline runtime markers the agent reads at execution time:
-
-```markdown
-**If `run_options.commit_strategy_resolved = "modular-commits"`:**
-
-<modular substitution body here>
-
-**Else (`run_options.commit_strategy_resolved = "stacked-branches"`):**
-
-<stacked substitution body here>
-```
-
-Single-line placeholders under ask use the same gating pattern but inline (`If modular: <a> · Else (stacked): <b>`).
-
-For the Step 0 question itself (`{{COMMIT_STRATEGY_STEP0_QUESTION}}`), the ask substitution is the AskUserQuestion block documented in the parent placeholder table in [SKILL.md](../SKILL.md) — same content used to populate the resolved value.

package/skills/vinta-derive-skills/resources/plan-execution/partials/commit-strategy/stacked.md

@@ -0,0 +1,46 @@
+<!-- Partial: commit-strategy / stacked-branches. Blocks consumed by implement-phase (PER_PHASE_COMMIT) + integrate-phase (BRANCH_NAMING, PR_OPEN_TIMING) + conductor (CHECKLIST). All git calls use `git -C <WORKROOT>`; the first executed phase branches off `<BASE_BRANCH>` — both resolved once by the conductor (see worktree-seam.md#WORKROOT_RESOLUTION). -->
+
+<!-- block-begin: BRANCH_NAMING -->
+Branch naming: `plan/{plan-id-kebab}/phase-{phase.id}` (one branch + one PR per phase, stacked).
+
+**First executed phase** (branches from `<BASE_BRANCH>`, already made current by the conductor):
+
+```bash
+git -C <WORKROOT> checkout <BASE_BRANCH>
+git -C <WORKROOT> checkout -b plan/{plan-id-kebab}/phase-{phase.id}
+# subagent's commits land on this branch
+git -C <WORKROOT> push -u origin plan/{plan-id-kebab}/phase-{phase.id}
+```
+
+**Subsequent phases** (stacked on the previous phase's branch):
+
+```bash
+git -C <WORKROOT> checkout plan/{plan-id-kebab}/phase-{prev.id}
+git -C <WORKROOT> checkout -b plan/{plan-id-kebab}/phase-{phase.id}
+git -C <WORKROOT> push -u origin plan/{plan-id-kebab}/phase-{phase.id}
+```
+<!-- block-end: BRANCH_NAMING -->
+
+<!-- block-begin: PER_PHASE_COMMIT -->
+7. Stage the right files (NEVER `git add -A` — {{ANTI_GIT_ADD_ALL_REASON}}). Stage explicitly: `git add {{STAGE_PATTERN}}`.
+8. Commit with the repo's style — look at `git log -10 --oneline` first. {{COMMIT_STYLE_LINE}}.
+9. {{COAUTHOR_INSTRUCTION_LINE}}
+10. {{PUSH_INSTRUCTION_LINE}}
+<!-- block-end: PER_PHASE_COMMIT -->
+
+<!-- block-begin: PR_OPEN_TIMING -->
+One PR per phase — the [Open PR via context file](#open-pr-via-context-file) step runs after this phase passes review, writing `.vinta-ai-workflows/prs-context/{feature-kebab}/phase-{phase.id}.md`.
+<!-- block-end: PR_OPEN_TIMING -->
+
+<!-- block-begin: CHECKLIST -->
+<!-- stacked adds no extra commit-discipline checklist items beyond the branch line -->
+<!-- block-end: CHECKLIST -->
+
+<!-- Single-line values (derive-skills substitutes these into the shells directly):
+     BRANCH_PUSH_HEADING            = Push stacked branch
+     BRANCH_NAMING_PATTERN_SUMMARY  = branch naming pattern (default: `plan/{plan-id-kebab}/phase-{phase-id}`)
+     PRS_CONTEXT_FILE_PATH          = `.vinta-ai-workflows/prs-context/{feature-kebab}/phase-{phase.id}.md`
+     TRACKING_BRANCH_FIELD          = (empty — per-phase branch lives inline under TRACKING_PHASE_BRANCH_FIELD)
+     TRACKING_PHASE_BRANCH_FIELD    = , branch, base
+     FINAL_REPORT_BRANCH_SUMMARY    = branches pushed (with bases, in stack order)
+     BRANCH_CHECKLIST_LINE          = Stacked branch created; pushed. -->

package/skills/vinta-derive-skills/resources/plan-execution/partials/implementer-prompt.md

@@ -0,0 +1,78 @@
+<!-- Partial: implementer-prompt — the token-efficient per-phase prompt. FULL = the forward-implementation prompt used by implement-phase. INNER_OUTER_LOOP = the read→edit→inner→outer verification steps (1–6), reused verbatim by amend-plan's 4b (which appends its own amend-specific commit / no-push tail instead of the commit-strategy block). The {If run_options.use_worktree = true:} markers are runtime gates the agent reads at execution time; derive-skills strips them entirely when foundation_skills.prepare-worktree is disabled (use_worktree can only ever be false). -->
+
+<!-- block-begin: FULL -->
+```
+You are implementing {phase.id}: {phase.title} of plan {plan.id}.
+
+## Repo
+{{PROJECT_NAME}} ({{STACK_SUMMARY}}).
+
+## Working location
+Work entirely inside `<WORKROOT>`. `cd` into it before any command. Every `git`,
+every lint / test / build / migrate call runs there.
+{If run_options.use_worktree = true:}
+  `<WORKROOT>` is an isolated git worktree — do NOT touch the main checkout; its DB,
+  env, and compose stack are intentionally separated. See `<WORKROOT>/WORKTREE.md` for
+  what's forked vs shared (deps, dev DB, test DB, compose project name, env file).
+  {If run_options.sandbox_tier = enforced:} Writes to the main checkout are OS-blocked —
+  if you see `Operation not permitted` / `EROFS` on a write, you used a main-checkout
+  path by mistake; redo it against this worktree path.
+Branch base for this phase: `<phase-specific base>` — the orchestrator already created
+your phase branch there; commit straight to it.
+
+## Read first
+1. AGENTS.md — repo conventions.
+2. {{PLAN_DIR}}/{plan-filename}, the **Goals + Non-goals**, **Guiding Decisions**, **Data Model Changes** sections and YOUR phase body inside **Phased Rollout**.
+{If run_options.use_worktree = true:} 3. `WORKTREE.md` at the worktree root — fork map (which dirs symlink to main vs are independent copies).
+
+## Plan-level decisions (from Goals + Non-goals + Guiding Decisions)
+{Goals + Non-goals verbatim}
+{Guiding Decisions table verbatim}
+{If feature flag declared:}
+  Feature flag: `{flag-key}` — scope `{per-tenant|per-request}`, default `{false|true}`.
+  Wire reads + writes per the plan's **Guiding Decisions** entry. Off-flag path = byte-for-byte pre-feature behavior.
+
+## What was already implemented in prior phases
+{Tracking file "Completed Phases" section. First executed phase: "Nothing yet — this is the first phase."}
+
+## Your tasks (Phase {id} only)
+{phase.body verbatim, including Goal / Spec use-case / Feature flag / Changes / Tests / Acceptance lines}
+
+## Reusable skills you SHOULD invoke
+{phase.reusable_skills — for each, instruct the agent to first read ai-tools/skills/{name}/SKILL.md, then follow that pattern.}
+
+Project skills available: {{PROJECT_SKILLS_LIST}}
+
+{{DEPENDENCY_LICENSE_BLOCK}}
+
+<!-- include: partials/implementer-prompt.md#INNER_OUTER_LOOP -->
+{{PER_PHASE_COMMIT_BLOCK}}
+
+## Required output (single final report)
+- Status: SUCCESS or FAILURE (and why).
+- Files created/modified (paths only).
+- 5–15 line summary of what you implemented and key decisions.
+{{E2E_REPORT_FIELD}}
+- Deviations from the plan body and reasoning.
+- Anything you couldn't do (with explanation).
+```
+
+**Don't** dump the full plan into every prompt. Tracking summaries replace prior phases as context. Always include the **Goals + Non-goals** and **Guiding Decisions** sections plus the relevant **Data Model Changes** subsection — load-bearing decisions; phases reach back frequently.
+<!-- block-end: FULL -->
+
+<!-- block-begin: INNER_OUTER_LOOP -->
+## Working instructions
+1. Read existing code paths your changes touch — do not write before reading.
+2. Implement using Read/Edit/Write. Match existing patterns.
+3. **Inner loop — fast iteration.** Scoped to files/apps you touched:
+   a. `{{LINT_CMD}}` until clean.
+   b. {{NEW_TEST_CMD_PATTERN}} for new tests individually.
+   c. Scoped suite: {{SCOPED_TEST_PATTERN}}.
+4. Iterate 2–3 until **new tests pass individually** and the scoped suite is green. Do **not** advance to step 5 with red scoped tests.
+5. **Outer gate — local verification, only after step 4 is green.** All MUST pass before staging:
+   a. **Type / build:** `{{BUILD_CMD}}` — repo-wide, always.
+   b. **Tests:** by default run only the **scoped suite** `{{SCOPED_TEST_PATTERN}}` for the apps/files you touched — the new tests already passed individually in step 4b, so this re-confirms the touched surface without paying for the whole repo.
+      {If run_options.full_test_suite = true:} run the **full test suite** `{{TEST_CMD}}` instead of the scoped suite — this phase guards against regressions in untouched code too.
+   {{E2E_OUTER_GATE_LINE}}
+6. Outer gate fails → return step 2 (fix regression), re-run inner loop, then 5a/5b/5c. **Never** commit, push, or proceed while any gate is red.
+<!-- block-end: INNER_OUTER_LOOP -->

package/skills/vinta-derive-skills/resources/plan-execution/partials/model-pick.md

@@ -0,0 +1,19 @@
+<!-- Partial: model-pick — the plan-owns-model-selection rules. Included by implement-phase; referenced (linked, not included) by amend-plan's Tier-4 rule. -->
+<!-- block-begin: MODEL_PICK -->
+## Pick the model from the plan's per-phase suggestion
+
+**The plan owns model selection — this skill does not re-derive tiers and doesn't assume a vendor.** Each phase carries a `**Suggested AI model**:` line listing one model per vendor.
+
+Pick:
+
+1. Read the line, parse out **all** vendor suggestions.
+2. **Filter to what's actually available in the runtime.** Different harnesses expose different sets.
+3. From the surviving suggestions, **pick the cheapest / fastest** the runner can use.
+4. Translate the chosen model to whatever form the runner's spawning tool expects.
+5. Phase suggestion straddles tiers → pick the higher-tier suggestion.
+6. Line missing / malformed → **ask the user**. Don't silently re-derive tier.
+
+**Retry escalation (no user prompt):** the picked model fails on a clear capability gap → step **one tier up** and retry once. After Tier 4 fails, STOP. Update tracking with `❌`, post the agent's report to the user, ask how to proceed.
+
+Record the **model actually used** + the **plan's suggested tier** in tracking.
+<!-- block-end: MODEL_PICK -->

package/skills/vinta-derive-skills/resources/plan-execution/partials/pr-context.md

@@ -0,0 +1,61 @@
+<!-- Partial: pr-context — the "Open PR via context file" body (former 1f), decoupled from commit-strategy. Included by integrate-phase. The commit-strategy-specific PR-open timing + prs-context file path come from commit-strategy/<resolved>.md (PR_OPEN_TIMING block + PRS_CONTEXT_FILE_PATH value). generate_inline_comments is a runtime flag whose only effect is localized here (whether the `# Comments` block is populated). -->
+
+<!-- block-begin: PR_CONTEXT -->
+This is the **only** PR-creation path. PRs always go through {{PRS_CONTEXT_FILE_PATH}} + the bundled [open-pr.sh](../open-pr-from-context/scripts/open-pr.sh) script — even when inline comments are not requested. The file is the durable record; the script is the publisher. Subagents never open PRs themselves; the orchestrator does, after review passes.
+
+{{PR_OPEN_TIMING_BLOCK}}
+
+Two project-level signals decide the actual behavior:
+
+| `{{PR_POLICY_BLOCK}}` policy | `run_options.generate_inline_comments` | What this step does |
+|---|---|---|
+| agents create PRs | false | Write minimal context file (`# Title`, `# Description`, empty `# Comments`). Run `open-pr.sh` → PR opened, no inline comments. |
+| agents create PRs | true  | Write full context file (title + description + 3–10 inline comments). Run `open-pr.sh` → PR opened, all comments posted. |
+| branches only     | false | **Skip this step entirely.** Human will open the PR manually from the pushed branch. |
+| branches only     | true  | Write full context file (durable record). **Don't run `open-pr.sh`.** Human can publish later from a CLI-equipped session via [open-pr-from-context](../open-pr-from-context/SKILL.md). Surface this in the user update. |
+
+### Steps
+
+1. **Skip if neither column applies** (policy = branches only AND `generate_inline_comments = false`). Return to the conductor's tracking step.
+
+2. **Honor existing PR / MR templates.** Read `project.pr_template_paths` from `.vinta-ai-workflows.yaml`. For each entry:
+   - **One template** → load it; the prs-context `# Description` body must follow that template's section structure verbatim. Fill each section with phase-specific content drawn from the plan's **Goals + Non-goals**, **Guiding Decisions**, and the phase body. Preserve any `<!-- HTML comments -->` placeholders; do not strip the template's checklists. Sections you can't fill from phase data → leave the template's placeholder/prompt untouched (don't fabricate).
+   - **Multiple templates** (`PULL_REQUEST_TEMPLATE/` directory) → ask once via `AskUserQuestion`: list each template + its filename, ask which to use for this run. Cache the choice in tracking under `run_options.pr_template_used` so subsequent phases of the same plan use the same one without re-asking.
+   - **Empty array** → free-form description. Default sections: `## Summary` (1–3 sentences), `## Plan reference` (link / phase id), `## Test plan` (commands the reviewer can run).
+
+   When the project's PR template includes a checkbox checklist (e.g. `- [ ] Tests added`, `- [ ] Docs updated`), tick the boxes the phase's diff actually satisfies and leave unsatisfied ones unticked — never auto-tick everything.
+
+   GitHub also honors `?template=<name>` in the PR-create URL when the project has a multi-template directory. `gh pr create --body-file` writes the body directly so the URL trick isn't needed; the body must match the chosen template's structure regardless.
+
+3. **Pick comment targets** (only when `generate_inline_comments = true`). Read the phase diff via `git -C <WORKROOT> diff <BASE_BRANCH>...HEAD` (or the previous phase branch for stacked phases). Select 3–10 spots that benefit from a one-paragraph context note — typically:
+   - A subtle invariant the diff relies on (cite the plan's **Goals + Non-goals** / **Guiding Decisions** entries — by name, never use `§` shorthand).
+   - A workaround for a known framework / library limitation.
+   - A naming choice driven by an upstream contract.
+   - The off-flag short-circuit when a feature flag is in **Guiding Decisions**.
+   - Why a seemingly-cleaner refactor wasn't made (out of scope per **Goals + Non-goals**).
+   - Cross-phase coupling (this hook is consumed by phase N+k).
+
+   Skip lint/format churn, boilerplate matching nearby files, standard patterns from AGENTS.md, and self-explanatory test names. **A clean phase produces few comments — that's fine. Don't pad.**
+
+   When `generate_inline_comments = false`: skip this step. The file's `# Comments` block stays empty.
+
+4. **Write the prs-context file** at {{PRS_CONTEXT_FILE_PATH}}, following [resources/prs-context-template.md](../../prs-context-template.md). Frontmatter: `plan_id`, `feature_name`, `phase_id`, `phase_title`, `branch`, `base`, `created_at`, `status: pending`, empty `pr_url`. Body sections: `# Title` (single-line PR title), `# Description` (Markdown body — uses the project's PR template structure from step 2 when one exists), `# Comments` (YAML list of `{file, start_line, end_line?, side, body}` — empty list when comments are off).
+
+5. **Confirm `.vinta-ai-workflows/prs-context/` is in `.gitignore`.** [vinta-install-ai-tools-setup](../../../vinta-install-ai-tools-setup/SKILL.md) runs the multi-vendor setup script which appends `.vinta-ai-workflows/prs-context/` on its first invocation. If an older bootstrap missed it, append it now.
+
+6. **Run `open-pr.sh`** (only when policy = agents create PRs). Detect a usable CLI (`gh` for GitHub, `glab` for GitLab) plus the script's other deps (`yq`, `jq`):
+
+   ```bash
+   bash ai-tools/skills/open-pr-from-context/scripts/open-pr.sh {{PRS_CONTEXT_FILE_PATH}}
+   ```
+
+   The script opens the PR (or detects an existing one), posts each inline comment, rewrites the file's frontmatter to `status: published` + populated `pr_url`, appends a publish log. Exit codes:
+
+   - `0` — PR up, all comments (if any) posted. Capture `pr_url` for the user update.
+   - `1` — PR up, ≥1 comment failed. Surface the failed `(file:line)` list to the user; continue to the tracking step.
+   - `2` — Hard failure (deps missing, branch not pushed, CLI unauthed, file invalid). Surface the script's stderr; treat the phase as having no PR. The file stays `status: pending` so the user can re-run after fixing the gap.
+
+   When policy = "branches only": **don't run the script.** File stays `status: pending`.
+
+7. **Skill wrapper** — [open-pr-from-context](../open-pr-from-context/SKILL.md) is available for ad-hoc invocation (after the run, on a different machine, etc.). The orchestrator can call the script directly here; the skill is for humans.
+<!-- block-end: PR_CONTEXT -->

package/skills/vinta-derive-skills/resources/plan-execution/partials/review-layers.md

@@ -0,0 +1,50 @@
+<!-- Partial: review-layers — the three-layer review + fix loop. Included by review-phase. amend-plan and systematic-debugging reuse it by INVOKING review-phase (not by including this partial). The orchestrator running review-phase never edits code itself — every issue surfaces as a fix-up subagent task. -->
+
+<!-- block-begin: LAYERS -->
+Three layers, all required, in order. The reviewing orchestrator never edits — every issue surfaces as a fix-up subagent task.
+
+## Layer 1 — Mechanical checks
+
+1. `git -C <WORKROOT> status` + `git -C <WORKROOT> diff --stat`: confirm the file list matches the agent's report.
+2. **Read the full diff** for every changed file using `git -C <WORKROOT> diff`. Spot-checking is not enough.
+3. **Verify the outer gate** ran + green. By default that is `{{BUILD_CMD}}` (repo-wide) AND the scoped suite `{{SCOPED_TEST_PATTERN}}` covering the touched apps. {If run_options.full_test_suite = true:} the outer gate runs `{{BUILD_CMD}}` AND the full `{{TEST_CMD}}` instead — verify that. Look in the report for explicit confirmation the applicable gate was executed + passed{{E2E_LAYER1_NOTE}}. Vague confirmation → **re-run yourself** (in `<WORKROOT>`).
+4. **Scope creep**: file touched outside the expected surface area? Unrelated formatting churn? Surface it.
+5. **No-secrets scan**: `git -C <WORKROOT> diff` for `password|secret|token|api_key|AKIA|BEGIN [A-Z]+ KEY`.
+6. <!-- include: partials/worktree-seam.md#STRAY_WRITE_CHECK -->
+{{DEPENDENCY_LICENSE_LAYER1_CHECK}}
+{{COAUTHOR_LAYER1_CHECK}}
+
+## Layer 2 — Plan compliance walkthrough
+
+Open the phase body alongside the diff and walk:
+
+1. **Every numbered "Changes" item implemented.**
+2. **Every "Tests" entry materialized**, with assertions actually exercising the called-out behavior.
+3. **Acceptance line satisfiable** by the diff.
+4. **Repo conventions** from AGENTS.md.
+5. **Reusable-skill compliance.**
+{{E2E_LAYER2_CHECK}}
+6. **Feature-flag wiring** if the plan's **Guiding Decisions** declared a flag — flag-OFF is byte-for-byte pre-feature behavior, ≥1 test asserts it.
+7. **Cross-phase consistency** with prior tracking summaries.
+8. **Comment hygiene** — new or changed comments and doc blocks in the diff read as Simple English, one idea per sentence, no AI-slop vocabulary or negative framing, per the `deslop-comments` skill ([ai-tools/skills/deslop-comments/SKILL.md](ai-tools/skills/deslop-comments/SKILL.md)). Flag any that need rewriting; the fix loop dispatches a fixer to run `deslop-comments` on the phase's touched files.
+
+## Layer 3 — Independent reviewer subagent
+
+After Layers 1–2 pass, spawn a **separate** subagent (different session, no implementation context) using the project's `reviewer` agent type ([ai-tools/agents/reviewer.md](ai-tools/agents/reviewer.md)). Read-only by design.
+
+Reviewer prompt template — see the reviewer agent's body for the standard form. Triage findings:
+- **BLOCKER**: must fix before the phase is pushed (the conductor's integrate step).
+- **SHOULD-FIX**: fix in-phase if cheap; else follow-up issue + tracking note.
+- **NIT**: ignore unless trivially cheap.
+
+The reviewer also applies a condensed **structural-simplification lens** — one question: is there an obvious "code-judo" reframe that would make whole branches, helpers, modes, or layers disappear, rather than polishing what's there? Routine phases stop at that one question. When the phase touched core architecture, pushed a file past ~1,000 lines, or the lens surfaces a structural smell too big to resolve inline, escalate to the full [thermo-nuclear-code-quality-review](ai-tools/skills/thermo-nuclear-code-quality-review/SKILL.md) skill against the phase diff — an opt-in deep audit, run deliberately, never on every phase.
+
+The reviewer finds nothing on a >300-LoC multi-file phase → suspicious. Read once more.
+
+## Fix loop
+
+1. Spawn a **new** subagent — the project's `fixer` agent type ([ai-tools/agents/fixer.md](ai-tools/agents/fixer.md)). The fix prompt quotes the finding verbatim. For comment-hygiene findings (Layer 2 item 8), the fix prompt tells the fixer to run the `deslop-comments` skill ([ai-tools/skills/deslop-comments/SKILL.md](ai-tools/skills/deslop-comments/SKILL.md)) scoped to the phase's touched files — comment-only edits, no behavior change.
+2. The `fixer`'s system prompt mandates re-running the inner loop + outer gate (in `<WORKROOT>`).
+3. After the fixer returns, redo Layer 1 in full + the affected portion of Layer 2.
+4. Loop until Layers 1, 2, 3 are all clean.
+<!-- block-end: LAYERS -->

package/skills/vinta-derive-skills/resources/plan-execution/partials/worktree-seam.md

@@ -0,0 +1,68 @@
+<!-- Partial: worktree-seam — the WORKROOT abstraction. Collapses the former scattered `if use_worktree` conditionals into one resolution (conductor) + two local, data-driven checks (implement-phase spawn wrap, review-phase stray-write). Blocks: WORKROOT_RESOLUTION (conductors), WORKROOT_TOPOLOGY_RULE (conductors + integrate-phase), SANDBOX_WRAP (implement-phase), STRAY_WRITE_CHECK (review-phase). -->
+
+<!-- block-begin: WORKROOT_RESOLUTION -->
+## Step 0.5 — Resolve `WORKROOT`
+
+Resolve three values **once**, before any phase runs, and record them in tracking. Every later step uses them as data — no step re-derives worktree state.
+
+| Value | `run_options.use_worktree = false` | `run_options.use_worktree = true` |
+|---|---|---|
+| `WORKROOT` | the main checkout root (the repo the skill was invoked from) | `<worktree_path>` returned by prepare-worktree |
+| `BASE_BRANCH` | `{{DEFAULT_BRANCH}}` | `<worktree_branch>` prepare-worktree created |
+| `SANDBOX_TIER` | `none` | `enforced` or `none` (probed by prepare-worktree) |
+
+**When `use_worktree = false`:** set `WORKROOT` = main checkout, `BASE_BRANCH = {{DEFAULT_BRANCH}}`, `SANDBOX_TIER = none`. Make `BASE_BRANCH` current + up to date: `git -C <WORKROOT> checkout {{DEFAULT_BRANCH}} && git -C <WORKROOT> pull --ff-only`. Jump to Step 1.
+
+**When `use_worktree = true`:** invoke [prepare-worktree](../prepare-worktree/SKILL.md) **once**:
+
+1. **Inputs.** Plan path (so prepare-worktree can read it for deps / migrations / env / compose churn — see prepare-worktree's **Plan inspection** step), suggested worktree name = `plan-{plan-id-kebab}`, plan-driven mode.
+2. **Pre-run sanity.** Confirm no existing worktree at the target path (`git worktree list | grep <name>` — refuse if collision). Confirm `git -C <main_checkout> status` of the main checkout (warn if dirty; defer to prepare-worktree's **Sanity checks** step for the call).
+3. **Run prepare-worktree.** Pass the plan file + worktree name. It returns:
+   - `worktree_path` → `WORKROOT`.
+   - `worktree_branch` → `BASE_BRANCH` (prepare-worktree based it on `origin/{{DEFAULT_BRANCH}}`, so it is already current).
+   - `worktree_summary` — `.vinta-ai-workflows/worktrees/<name>.yaml` (read by teardown).
+   - `sandbox_tier` → `SANDBOX_TIER`: `enforced` (the [Filesystem sandbox](../prepare-worktree/SKILL.md#step-55--filesystem-sandbox-os-level-write-guard) step found `sandbox-exec` / `bwrap` and will OS-block main-checkout writes) or `none` (no sandbox tool — prevention degrades to the review-phase stray-write backstop).
+4. **Persist to tracking.** Write `run_options.worktree_path`, `run_options.worktree_branch`, `run_options.worktree_summary`, `run_options.sandbox_tier` into `{{PLAN_DIR}}/TRACKING_{plan-id}.md`. All later phases read them — never re-provision mid-plan.
+5. **Report to user.** Quote the prepare-worktree summary back: which dirs symlinked vs copied vs forked; which DB(s) forked + their names; compose project name; teardown command. Hold here until the user confirms (`AskUserQuestion`: `Looks good — start phase 1`, `Stop — let me adjust`).
+
+Failure modes:
+- **prepare-worktree returns an error** (disk full, branch exists, DB clone failed) → surface to the user; do NOT fall back to "just run in the main checkout" silently — that defeats the opt-in. Ask: `Retry`, `Run in main checkout instead (flip use_worktree to false)`, `Stop`.
+- **User cancels at the confirmation gate** → tear the worktree down (run the teardown command from prepare-worktree's report) before exiting, so the next run starts clean.
+<!-- block-end: WORKROOT_RESOLUTION -->
+
+<!-- block-begin: WORKROOT_TOPOLOGY_RULE -->
+**`WORKROOT` topology rule.** Every phase branches off the previous phase (first executed phase off `<BASE_BRANCH>`), and **every** `git` / lint / test / build / migrate call runs with `git -C <WORKROOT>` (or after `cd <WORKROOT>`). When `use_worktree = false`, `WORKROOT` is the main checkout and this is exactly today's in-place behavior; when `true`, `WORKROOT` is the worktree and branches / commits stack inside it, never touching the main checkout's working tree. One uniform path — no per-step worktree branching.
+<!-- block-end: WORKROOT_TOPOLOGY_RULE -->
+
+<!-- block-begin: SANDBOX_WRAP -->
+**Sandbox the spawn — only when `SANDBOX_TIER = enforced`.** The prompt tells the subagent to stay in `WORKROOT`, but that's cooperative — a smaller model can resolve a path back to the main checkout and silently write there (the review-phase stray-write check catches this reactively). When `SANDBOX_TIER = enforced` **and** the runtime spawns subagents as **subprocesses** (it shells out to an agent CLI — e.g. `codex exec …`, a `claude -p …` child, a custom runner), wrap that launch command in the worktree's bundled guard so the OS blocks main-checkout writes regardless of harness:
+
+```bash
+ai-tools/skills/prepare-worktree/scripts/sandbox-run.sh \
+  --deny  <main_checkout> \
+  --allow <WORKROOT> \
+  --allow <main_checkout>/.vinta-ai-workflows \
+  --allow <main_checkout>/.git \
+  -- <the agent spawn command>
+```
+
+`<main_checkout>` is the repo root the skill was invoked from (never `WORKROOT` when a worktree is in use). A stray write then fails with `Operation not permitted` / `EROFS`; the subagent retries against the worktree. `<main_checkout>/.git` must be allowed because git worktrees write commits into the main repo's `.git` (shared objects/refs, `.git/worktrees/<name>/index.lock`); omitting it makes the subagent's own `git commit` fail.
+
+- **In-process subagent runtimes** (orchestrator and subagent share one OS process — e.g. claude-code's Task tool) can't wrap a single spawn. Two options: (a) install a runtime pre-write guard hook scoped to `WORKROOT` (prepare-worktree ships `scripts/claude-worktree-write-guard.py` + `scripts/gen-claude-sandbox-settings.sh` for claude-code); or (b) run the **entire** invocation under `sandbox-run.sh` with the same `--deny` / `--allow` set. Pick whichever the runtime supports.
+- **`SANDBOX_TIER = none`** (no sandbox tool, or `use_worktree = false`) → skip wrapping; prevention falls back entirely to the review-phase stray-write check. Surface this once to the user when a worktree run is unsandboxed so the weaker guarantee is explicit.
+<!-- block-end: SANDBOX_WRAP -->
+
+<!-- block-begin: STRAY_WRITE_CHECK -->
+**Stray main-checkout writes — only when `WORKROOT != <main_checkout>` (i.e. a worktree run).** A subagent told to work inside the worktree can resolve an absolute path back to the **main checkout** and silently edit files there; because worktrees have independent working trees, those edits never reach the phase commit — they sit as uncommitted thrash in the main checkout and read as a silent implementer/fixer failure. **When `SANDBOX_TIER = enforced`, the OS sandbox already blocks these writes and this becomes a cheap backstop (a clean `git status` is the expected result). When `SANDBOX_TIER = none`, it is the *only* defense — run it religiously.** After **every** implementer **and** fixer subagent returns, run:
+
+```bash
+git -C <main_checkout> status --short | grep -vE '^\?\?'   # tracked modifications only
+```
+
+Any output is a BLOCKER for this phase:
+- Diff the stray files (`git -C <main_checkout> diff -- <path>`) to recover intent.
+- If the edit belongs in the worktree, re-dispatch the fixer/implementer with an explicit instruction to write to `WORKROOT` (the change is missing from the phase commit until it does).
+- Once recovered (or confirmed superseded by the correctly-committed worktree version), discard the stray edits with `git -C <main_checkout> restore -- <path>` so the main checkout returns clean. Never leave the main checkout dirty between phases — a later phase can't tell new thrash from old.
+
+`<main_checkout>` is the repo root the skill was invoked from (NOT `WORKROOT`). When `WORKROOT == <main_checkout>` (`use_worktree = false`), skip this check entirely — your work legitimately lives in that tree.
+<!-- block-end: STRAY_WRITE_CHECK -->