@sienklogic/plan-build-run 2.49.0 → 2.50.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to Plan-Build-Run will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.50.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.49.0...plan-build-run-v2.50.0) (2026-03-01)
+
+
+### Features
+
+* **52-04:** replace 4 milestone banners with tmpl refs; condense 5 plan SKILL.md sections to < 600 lines ([3e383c4](https://github.com/SienkLogic/plan-build-run/commit/3e383c45d4cfdb51298a2d2531f51752132368a0))
+* **53-01:** add cleanup section and CRITICAL markers to build, consolidate plan pre-planner briefing ([7c14693](https://github.com/SienkLogic/plan-build-run/commit/7c14693e7790728e00d5e4d080e19f54648bc156))
+* **53-02:** GREEN - implement ciPoll and rollback in lib/build.js ([d2ffa30](https://github.com/SienkLogic/plan-build-run/commit/d2ffa309eab8bf10981e88ded12c8e2b4029ad28))
+* **53-02:** register ci-poll and rollback in pbr-tools.js dispatcher ([88c551e](https://github.com/SienkLogic/plan-build-run/commit/88c551e82d3acb1d807bd302c758d041cb0577c0))
+
+
+### Bug Fixes
+
+* **52-05:** remove blank lines to bring build SKILL.md to 868 lines (< 870 target) ([6cd9549](https://github.com/SienkLogic/plan-build-run/commit/6cd954972c33540462cb08f6a192604879b8e6df))
+
 ## [2.49.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.48.0...plan-build-run-v2.49.0) (2026-03-01)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.49.0",
+  "version": "2.50.0",
   "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
   "keywords": [
     "claude-code",

package/plugins/copilot-pbr/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.49.0",
+  "version": "2.50.0",
   "description": "Plan-Build-Run — Structured development workflow for GitHub Copilot CLI. Solves context rot through disciplined agent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/copilot-pbr/skills/build/SKILL.md

@@ -669,6 +669,8 @@ This ensures that `/pbr:review` after a `--gaps-only` build sees the updated ver
 
 **8-pre-c. Codebase map incremental update (conditional):**
 
+**CRITICAL (no hook): Run codebase map update if conditions are met. Do NOT skip this step.**
+
 Only run if ALL of these are true:
 - `.planning/codebase/` directory exists (project was previously scanned with `/pbr:scan`)
 - Build was not aborted
@@ -779,6 +781,8 @@ Write `.planning/.auto-next` containing the next logical command (e.g., `/pbr:pl
 
 **8e-ii. Check Pending Todos:**
 
+**CRITICAL (no hook): Check pending todos after build. Do NOT skip this step.**
+
 After completing the build, check if any pending todos are now satisfied:
 
 1. Check if `.planning/todos/pending/` exists and contains files
@@ -895,3 +899,9 @@ If `git.branching` is `phase` but we're not on the phase branch:
 | `.planning/STATE.md` | Updated progress | Steps 6f, 8b |
 | `.planning/.auto-next` | Next command signal (if auto_continue enabled) | Step 8e |
 | Project source files | Actual code | Step 6 (executors) |
+
+---
+
+## Cleanup
+
+Delete `.planning/.active-skill` if it exists. This must happen on all paths (success, partial, and failure) before reporting results.

package/plugins/copilot-pbr/skills/plan/SKILL.md

@@ -243,61 +243,51 @@ After the researcher completes, check the agent output for a completion marker:
 
 ---
 
-### Step 4.5: Seed Scanning (inline, before planning)
-
-Before invoking the planner, scan `.planning/seeds/` for seeds whose trigger matches the current phase:
-
-1. Glob for `.planning/seeds/*.md`
-2. For each seed file, read its frontmatter and check the `trigger` field
-3. A seed matches if ANY of these are true:
-   - `trigger` equals the phase slug (e.g., `trigger: authentication`) — **preferred**
-   - `trigger` is a substring of the phase directory name (e.g., `trigger: auth` matches `03-authentication`)
-   - `trigger` equals the current phase number as integer (e.g., `trigger: 3`) — backward compatible but NOT recommended for new seeds (breaks with decimal phases like 3.1)
-   - `trigger` equals `*` (always matches)
-4. If matching seeds are found, present them to the user:
-   ```
-   Found {N} seeds related to Phase {NN}:
-     - {seed_name}: {seed description}
-     - {seed_name}: {seed description}
-   ```
-
-   Use the yes-no-pick pattern from `skills/shared/gate-prompts.md`:
-     question: "Include these {N} seeds in planning?"
-     header: "Seeds?"
-     options:
-       - label: "Yes, all"     description: "Include all {N} matching seeds"
-       - label: "Let me pick"  description: "Choose which seeds to include"
-       - label: "No"           description: "Proceed without seeds"
-5. If "Yes, all": include all matching seed content in the planner's context
-6. If "Let me pick": present individual seeds for selection
-7. If "No" or "Other": proceed without seeds
-8. If no matching seeds found: proceed silently
+### Step 4.5: Pre-Planner Briefing (delegated)
 
----
+**CRITICAL (no hook): Run pre-planner briefing before spawning the planner. Do NOT skip this step.**
+
+Consolidate seed scanning and deferred idea surfacing into a single lightweight Task():
+
+```
+Task({
+  subagent_type: "pbr:general",
+  model: "haiku",
+  prompt: "Pre-planner briefing for Phase {NN} ({phase-slug}).
+
+1. SEED SCANNING:
+   Run: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js seeds match {phase-slug} {phase-number}`
+   If `matched` is non-empty, output a ## Seeds section listing each seed name, description, and content.
+   If empty, output: ## Seeds\nNo matching seeds found.
+
+2. DEFERRED IDEAS:
+   Read `.planning/CONTEXT.md`. If it has a section containing 'deferred' or 'ideas' (case-insensitive),
+   extract items that mention Phase {NN} or keywords matching the phase slug.
+   If relevant items found, output a ## Deferred Ideas section listing them.
+   If none found, output: ## Deferred Ideas\nNo relevant deferred items.
+
+Output format: Return both sections as markdown. End with ## BRIEFING COMPLETE."
+})
+```
 
-### Step 4.6: Surface Deferred Ideas (inline, before planning)
-
-Before invoking the planner, check `.planning/CONTEXT.md` for deferred ideas that may be relevant to this phase:
-
-1. If `.planning/CONTEXT.md` does NOT exist, skip this step silently
-2. If it exists, scan for sections named "Deferred Ideas", "Deferred", "Ideas", or "Seeds" (case-insensitive heading match)
-3. For each deferred item found, check relevance to the current phase by comparing the item text against the phase goal, requirements, and slug
-4. If relevant deferred items are found, present them to the user:
-   ```
-   Found {N} deferred idea(s) from previous discussions that may be relevant to Phase {NN}:
-     - {deferred item summary}
-     - {deferred item summary}
-   ```
-   Use the yes-no pattern from `skills/shared/gate-prompts.md`:
-     question: "Include these deferred ideas in the planning context?"
-     header: "Deferred Ideas"
-     options:
-       - label: "Yes"  description: "Pass relevant deferred ideas to the planner"
-       - label: "No"   description: "Proceed without deferred ideas"
-5. If "Yes": append the relevant deferred items to the context bundle for the planner prompt (add them to the `<project_context>` block under a `Deferred ideas to consider:` heading)
-6. If "No" or no relevant items found: proceed without changes
-
-This is a lightweight relevance filter — do NOT invoke an agent for this. Just match keywords from the deferred items against the phase goal and requirement text.
+After the Task() completes:
+- If `## Seeds` section contains matches: present them to the user via the yes-no-pick pattern from `skills/shared/gate-prompts.md`:
+  question: "Include these {N} seeds in planning?"
+  header: "Seeds?"
+  options:
+    - label: "Yes, all"     description: "Include all {N} matching seeds"
+    - label: "Let me pick"  description: "Choose which seeds to include"
+    - label: "No"           description: "Proceed without seeds"
+- If "Yes, all": include seed content in planner context
+- If "Let me pick": present individual seeds for selection
+- If "No": proceed without seeds
+
+- If `## Deferred Ideas` section has items: present via the yes-no pattern from `skills/shared/gate-prompts.md`:
+  question: "Include these deferred ideas in planning context?"
+- If "Yes": append to planner context under `Deferred ideas to consider:`
+- If "No": proceed without changes
+
+- If both sections are empty: proceed silently to Step 5 (no AskUserQuestion needed)
 
 ---
 

package/plugins/cursor-pbr/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.49.0",
+  "version": "2.50.0",
   "description": "Plan-Build-Run — Structured development workflow for Cursor. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/cursor-pbr/skills/build/SKILL.md

@@ -670,6 +670,8 @@ This ensures that `/pbr:review` after a `--gaps-only` build sees the updated ver
 
 **8-pre-c. Codebase map incremental update (conditional):**
 
+**CRITICAL (no hook): Run codebase map update if conditions are met. Do NOT skip this step.**
+
 Only run if ALL of these are true:
 - `.planning/codebase/` directory exists (project was previously scanned with `/pbr:scan`)
 - Build was not aborted
@@ -780,6 +782,8 @@ Write `.planning/.auto-next` containing the next logical command (e.g., `/pbr:pl
 
 **8e-ii. Check Pending Todos:**
 
+**CRITICAL (no hook): Check pending todos after build. Do NOT skip this step.**
+
 After completing the build, check if any pending todos are now satisfied:
 
 1. Check if `.planning/todos/pending/` exists and contains files
@@ -894,3 +898,9 @@ If `git.branching` is `phase` but we're not on the phase branch:
 | `.planning/STATE.md` | Updated progress | Steps 6f, 8b |
 | `.planning/.auto-next` | Next command signal (if auto_continue enabled) | Step 8e |
 | Project source files | Actual code | Step 6 (executors) |
+
+---
+
+## Cleanup
+
+Delete `.planning/.active-skill` if it exists. This must happen on all paths (success, partial, and failure) before reporting results.

package/plugins/cursor-pbr/skills/plan/SKILL.md

@@ -244,61 +244,51 @@ After the researcher completes, check the agent output for a completion marker:
 
 ---
 
-### Step 4.5: Seed Scanning (inline, before planning)
-
-Before invoking the planner, scan `.planning/seeds/` for seeds whose trigger matches the current phase:
-
-1. Glob for `.planning/seeds/*.md`
-2. For each seed file, read its frontmatter and check the `trigger` field
-3. A seed matches if ANY of these are true:
-   - `trigger` equals the phase slug (e.g., `trigger: authentication`) — **preferred**
-   - `trigger` is a substring of the phase directory name (e.g., `trigger: auth` matches `03-authentication`)
-   - `trigger` equals the current phase number as integer (e.g., `trigger: 3`) — backward compatible but NOT recommended for new seeds (breaks with decimal phases like 3.1)
-   - `trigger` equals `*` (always matches)
-4. If matching seeds are found, present them to the user:
-   ```
-   Found {N} seeds related to Phase {NN}:
-     - {seed_name}: {seed description}
-     - {seed_name}: {seed description}
-   ```
-
-   Use the yes-no-pick pattern from `skills/shared/gate-prompts.md`:
-     question: "Include these {N} seeds in planning?"
-     header: "Seeds?"
-     options:
-       - label: "Yes, all"     description: "Include all {N} matching seeds"
-       - label: "Let me pick"  description: "Choose which seeds to include"
-       - label: "No"           description: "Proceed without seeds"
-5. If "Yes, all": include all matching seed content in the planner's context
-6. If "Let me pick": present individual seeds for selection
-7. If "No" or "Other": proceed without seeds
-8. If no matching seeds found: proceed silently
+### Step 4.5: Pre-Planner Briefing (delegated)
 
----
+**CRITICAL (no hook): Run pre-planner briefing before spawning the planner. Do NOT skip this step.**
+
+Consolidate seed scanning and deferred idea surfacing into a single lightweight Task():
+
+```
+Task({
+  subagent_type: "pbr:general",
+  model: "haiku",
+  prompt: "Pre-planner briefing for Phase {NN} ({phase-slug}).
+
+1. SEED SCANNING:
+   Run: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js seeds match {phase-slug} {phase-number}`
+   If `matched` is non-empty, output a ## Seeds section listing each seed name, description, and content.
+   If empty, output: ## Seeds\nNo matching seeds found.
+
+2. DEFERRED IDEAS:
+   Read `.planning/CONTEXT.md`. If it has a section containing 'deferred' or 'ideas' (case-insensitive),
+   extract items that mention Phase {NN} or keywords matching the phase slug.
+   If relevant items found, output a ## Deferred Ideas section listing them.
+   If none found, output: ## Deferred Ideas\nNo relevant deferred items.
+
+Output format: Return both sections as markdown. End with ## BRIEFING COMPLETE."
+})
+```
 
-### Step 4.6: Surface Deferred Ideas (inline, before planning)
-
-Before invoking the planner, check `.planning/CONTEXT.md` for deferred ideas that may be relevant to this phase:
-
-1. If `.planning/CONTEXT.md` does NOT exist, skip this step silently
-2. If it exists, scan for sections named "Deferred Ideas", "Deferred", "Ideas", or "Seeds" (case-insensitive heading match)
-3. For each deferred item found, check relevance to the current phase by comparing the item text against the phase goal, requirements, and slug
-4. If relevant deferred items are found, present them to the user:
-   ```
-   Found {N} deferred idea(s) from previous discussions that may be relevant to Phase {NN}:
-     - {deferred item summary}
-     - {deferred item summary}
-   ```
-   Use the yes-no pattern from `skills/shared/gate-prompts.md`:
-     question: "Include these deferred ideas in the planning context?"
-     header: "Deferred Ideas"
-     options:
-       - label: "Yes"  description: "Pass relevant deferred ideas to the planner"
-       - label: "No"   description: "Proceed without deferred ideas"
-5. If "Yes": append the relevant deferred items to the context bundle for the planner prompt (add them to the `<project_context>` block under a `Deferred ideas to consider:` heading)
-6. If "No" or no relevant items found: proceed without changes
-
-This is a lightweight relevance filter — do NOT invoke an agent for this. Just match keywords from the deferred items against the phase goal and requirement text.
+After the Task() completes:
+- If `## Seeds` section contains matches: present them to the user via the yes-no-pick pattern from `skills/shared/gate-prompts.md`:
+  question: "Include these {N} seeds in planning?"
+  header: "Seeds?"
+  options:
+    - label: "Yes, all"     description: "Include all {N} matching seeds"
+    - label: "Let me pick"  description: "Choose which seeds to include"
+    - label: "No"           description: "Proceed without seeds"
+- If "Yes, all": include seed content in planner context
+- If "Let me pick": present individual seeds for selection
+- If "No": proceed without seeds
+
+- If `## Deferred Ideas` section has items: present via the yes-no pattern from `skills/shared/gate-prompts.md`:
+  question: "Include these deferred ideas in planning context?"
+- If "Yes": append to planner context under `Deferred ideas to consider:`
+- If "No": proceed without changes
+
+- If both sections are empty: proceed silently to Step 5 (no AskUserQuestion needed)
 
 ---
 

package/plugins/pbr/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.49.0",
+  "version": "2.50.0",
   "description": "Plan-Build-Run — Structured development workflow for Claude Code. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/pbr/scripts/lib/build.js

@@ -12,10 +12,13 @@
  *   checkpointInit(phaseSlug, plans, planningDir) — Initialize checkpoint manifest
  *   checkpointUpdate(phaseSlug, opts, planningDir) — Update checkpoint manifest
  *   seedsMatch(phaseSlug, phaseNumber, planningDir) — Find matching seed files
+ *   ciPoll(runId, timeoutSecs, planningDir)  — Single-check GitHub Actions CI run status
+ *   rollback(manifestPath, planningDir)      — Rollback failed plan via checkpoint manifest
  */
 
 const fs = require('fs');
 const path = require('path');
+const { execSync } = require('child_process');
 
 /**
  * Resolve the .planning directory from the given planningDir or env/cwd fallback.
@@ -441,6 +444,236 @@ function parseSeedFrontmatter(content) {
   return result;
 }
 
+// ---------------------------------------------------------------------------
+// ciPoll
+// ---------------------------------------------------------------------------
+
+/**
+ * Single-check GitHub Actions CI run status (not a polling loop).
+ * The build skill calls this repeatedly when needed.
+ *
+ * @param {string|null} runId - GitHub Actions run ID
+ * @param {number} [timeoutSecs=300] - Max seconds allowed (used only to detect timeout already exceeded)
+ * @param {string} [planningDir] - Unused; kept for signature consistency
+ * @returns {{ status: string, conclusion: string|null, url: string, next_action: string, elapsed_seconds: number, error?: string }}
+ */
+function ciPoll(runId, timeoutSecs, _planningDir) {
+  const startMs = Date.now();
+  const timeout = (typeof timeoutSecs === 'number' && !isNaN(timeoutSecs)) ? timeoutSecs : 300;
+
+  if (!runId) {
+    return {
+      status: 'error',
+      conclusion: null,
+      url: '',
+      next_action: 'abort',
+      elapsed_seconds: 0,
+      error: 'Missing run-id. Usage: ci-poll <run-id> [--timeout <seconds>]'
+    };
+  }
+
+  // If timeout already exceeded (caller sets 0 to signal timeout)
+  if (timeout <= 0) {
+    return {
+      status: 'timed_out',
+      conclusion: null,
+      url: '',
+      next_action: 'abort',
+      elapsed_seconds: 0,
+      error: 'CI timeout exceeded'
+    };
+  }
+
+  let raw;
+  try {
+    raw = execSync(`gh run view ${runId} --json status,conclusion,url`, {
+      encoding: 'utf8',
+      timeout: 10000
+    });
+  } catch (e) {
+    const elapsed = Math.round((Date.now() - startMs) / 1000);
+    return {
+      status: 'error',
+      conclusion: null,
+      url: '',
+      next_action: 'abort',
+      elapsed_seconds: elapsed,
+      error: e.message || 'gh command failed'
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (_e) {
+    const elapsed = Math.round((Date.now() - startMs) / 1000);
+    return {
+      status: 'error',
+      conclusion: null,
+      url: '',
+      next_action: 'abort',
+      elapsed_seconds: elapsed,
+      error: 'Failed to parse gh output: ' + raw
+    };
+  }
+
+  const elapsed = Math.round((Date.now() - startMs) / 1000);
+  const ghStatus = parsed.status || '';
+  const conclusion = parsed.conclusion || null;
+  const url = parsed.url || '';
+
+  if (ghStatus === 'completed') {
+    const passed = conclusion === 'success';
+    return {
+      status: passed ? 'passed' : 'failed',
+      conclusion,
+      url,
+      next_action: passed ? 'continue' : 'abort',
+      elapsed_seconds: elapsed
+    };
+  }
+
+  // in_progress, queued, waiting, etc.
+  return {
+    status: ghStatus,
+    conclusion: null,
+    url,
+    next_action: 'wait',
+    elapsed_seconds: elapsed
+  };
+}
+
+// ---------------------------------------------------------------------------
+// rollback
+// ---------------------------------------------------------------------------
+
+/**
+ * Rollback a failed plan using checkpoint manifest.
+ * Reads manifest, runs git reset --soft, invalidates downstream SUMMARY.md files.
+ *
+ * @param {string} manifestPath - Absolute path to .checkpoint-manifest.json
+ * @param {string} [planningDir]
+ * @returns {{ ok: boolean, rolled_back_to: string|null, plans_invalidated: string[], files_deleted: string[], warnings: string[], error?: string }}
+ */
+function rollback(manifestPath, _planningDir) {
+  // Step 1: Read manifest
+  if (!fs.existsSync(manifestPath)) {
+    return {
+      ok: false,
+      rolled_back_to: null,
+      plans_invalidated: [],
+      files_deleted: [],
+      warnings: [],
+      error: 'Manifest not found: ' + manifestPath
+    };
+  }
+
+  let manifest;
+  try {
+    const raw = fs.readFileSync(manifestPath, 'utf8');
+    manifest = JSON.parse(raw);
+  } catch (e) {
+    return {
+      ok: false,
+      rolled_back_to: null,
+      plans_invalidated: [],
+      files_deleted: [],
+      warnings: [],
+      error: 'Cannot parse manifest: ' + e.message
+    };
+  }
+
+  // Step 2: Extract last_good_commit
+  const lastGoodCommit = manifest.last_good_commit || null;
+  if (!lastGoodCommit) {
+    return {
+      ok: false,
+      rolled_back_to: null,
+      plans_invalidated: [],
+      files_deleted: [],
+      warnings: [],
+      error: 'No rollback point available (last_good_commit is missing or null). Use abort instead.'
+    };
+  }
+
+  const phaseDir = path.dirname(manifestPath);
+  const filesDeleted = [];
+  const plansInvalidated = [];
+  const warnings = [];
+
+  // Step 3: git reset --soft to last good commit
+  try {
+    execSync(`git reset --soft ${lastGoodCommit}`, { encoding: 'utf8', timeout: 15000 });
+  } catch (e) {
+    return {
+      ok: false,
+      rolled_back_to: null,
+      plans_invalidated: [],
+      files_deleted: [],
+      warnings: [],
+      error: 'git reset --soft failed: ' + e.message
+    };
+  }
+
+  // Step 4: Identify failed plan
+  const failedPlan = manifest.failed_plan || null;
+
+  // Step 5: Delete failed plan's SUMMARY.md if it exists
+  if (failedPlan) {
+    const failedSummary = path.join(phaseDir, `SUMMARY-${failedPlan}.md`);
+    if (fs.existsSync(failedSummary)) {
+      try {
+        fs.unlinkSync(failedSummary);
+        filesDeleted.push(failedSummary);
+      } catch (e) {
+        warnings.push(`Could not delete ${failedSummary}: ${e.message}`);
+      }
+    }
+  }
+
+  // Step 6: Scan for downstream plans and invalidate them
+  // downstream_of maps planId -> [deps]. A plan is downstream if failedPlan is in its deps.
+  const downstreamOf = manifest.downstream_of || {};
+  const resolved = Array.isArray(manifest.checkpoints_resolved) ? manifest.checkpoints_resolved : [];
+
+  for (const planId of resolved) {
+    if (planId === failedPlan) continue;
+    const deps = downstreamOf[planId] || [];
+    if (failedPlan && deps.includes(failedPlan)) {
+      plansInvalidated.push(planId);
+      const summaryPath = path.join(phaseDir, `SUMMARY-${planId}.md`);
+      if (fs.existsSync(summaryPath)) {
+        try {
+          fs.unlinkSync(summaryPath);
+          filesDeleted.push(summaryPath);
+        } catch (e) {
+          warnings.push(`Could not delete ${summaryPath}: ${e.message}`);
+        }
+      }
+    }
+  }
+
+  // Step 7: Write updated manifest back
+  const updatedManifest = Object.assign({}, manifest, {
+    checkpoints_resolved: resolved.filter(p =>
+      p !== failedPlan && !plansInvalidated.includes(p)
+    )
+  });
+  try {
+    fs.writeFileSync(manifestPath, JSON.stringify(updatedManifest, null, 2), 'utf8');
+  } catch (e) {
+    warnings.push('Could not update manifest: ' + e.message);
+  }
+
+  return {
+    ok: true,
+    rolled_back_to: lastGoodCommit,
+    plans_invalidated: plansInvalidated,
+    files_deleted: filesDeleted,
+    warnings
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Exports
 // ---------------------------------------------------------------------------
@@ -450,5 +683,7 @@ module.exports = {
   summaryGate,
   checkpointInit,
   checkpointUpdate,
-  seedsMatch
+  seedsMatch,
+  ciPoll,
+  rollback
 };

package/plugins/pbr/scripts/pbr-tools.js

@@ -163,7 +163,9 @@ const {
   summaryGate: _summaryGate,
   checkpointInit: _checkpointInit,
   checkpointUpdate: _checkpointUpdate,
-  seedsMatch: _seedsMatch
+  seedsMatch: _seedsMatch,
+  ciPoll: _ciPoll,
+  rollback: _rollback
 } = require('./lib/build');
 
 // --- Local LLM imports (not extracted — separate module tree) ---
@@ -341,6 +343,8 @@ function summaryGate(phaseSlug, planId) { return _summaryGate(phaseSlug, planId,
 function checkpointInit(phaseSlug, plans) { return _checkpointInit(phaseSlug, plans, planningDir); }
 function checkpointUpdate(phaseSlug, opts) { return _checkpointUpdate(phaseSlug, opts, planningDir); }
 function seedsMatch(phaseSlug, phaseNum) { return _seedsMatch(phaseSlug, phaseNum, planningDir); }
+function ciPoll(runId, timeoutSecs) { return _ciPoll(runId, timeoutSecs, planningDir); }
+function rollbackPlan(manifestPath) { return _rollback(manifestPath, planningDir); }
 
 // --- validateProject stays here (cross-cutting across modules) ---
 
@@ -819,6 +823,16 @@ async function main() {
       } else {
         error('Usage: seeds match <phase-slug> <phase-number>'); process.exit(1);
       }
+    } else if (command === 'ci-poll') {
+      const runId = args[1];
+      const timeoutIdx = args.indexOf('--timeout');
+      const timeoutSecs = timeoutIdx !== -1 ? parseInt(args[timeoutIdx + 1], 10) : 300;
+      if (!runId) { error('Usage: pbr-tools.js ci-poll <run-id> [--timeout <seconds>]'); return; }
+      output(ciPoll(runId, timeoutSecs));
+    } else if (command === 'rollback') {
+      const manifestPath = args[1];
+      if (!manifestPath) { error('Usage: pbr-tools.js rollback <manifest-path>'); return; }
+      output(rollbackPlan(manifestPath));
     } else if (command === 'context-triage') {
       const options = {};
       const agentsIdx = args.indexOf('--agents-done');
@@ -842,7 +856,7 @@ async function main() {
     } else if (command === 'validate-project') {
       output(validateProject());
     } else {
-      error(`Unknown command: ${args.join(' ')}\nCommands: state load|check-progress|update|patch|advance-plan|record-metric, config validate|load-defaults|save-defaults|resolve-depth, validate-project, migrate [--dry-run] [--force], init execute-phase|plan-phase|quick|verify-work|resume|progress, state-bundle <phase>, plan-index, frontmatter, must-haves, phase-info, phase add|remove|list, roadmap update-status|update-plans, history append|load, todo list|get|add|done, event, llm health|status|classify|score-source|classify-error|summarize|metrics [--session <ISO>]|adjust-thresholds, learnings ingest|query|check-thresholds, milestone-stats <version>, context-triage [--agents-done N] [--plans-total N] [--step NAME]`);
+      error(`Unknown command: ${args.join(' ')}\nCommands: state load|check-progress|update|patch|advance-plan|record-metric, config validate|load-defaults|save-defaults|resolve-depth, validate-project, migrate [--dry-run] [--force], init execute-phase|plan-phase|quick|verify-work|resume|progress, state-bundle <phase>, plan-index, frontmatter, must-haves, phase-info, phase add|remove|list, roadmap update-status|update-plans, history append|load, todo list|get|add|done, event, llm health|status|classify|score-source|classify-error|summarize|metrics [--session <ISO>]|adjust-thresholds, learnings ingest|query|check-thresholds, milestone-stats <version>, context-triage [--agents-done N] [--plans-total N] [--step NAME], ci-poll <run-id> [--timeout <seconds>], rollback <manifest-path>`);
     }
   } catch (e) {
     error(e.message);
@@ -850,6 +864,6 @@ async function main() {
 }
 
 if (require.main === module || process.argv[1] === __filename) { main().catch(err => { process.stderr.write(err.message + '\n'); process.exit(1); }); }
-module.exports = { KNOWN_AGENTS, initExecutePhase, initPlanPhase, initQuick, initVerifyWork, initResume, initProgress, initStateBundle: stateBundle, stateBundle, statePatch, stateAdvancePlan, stateRecordMetric, parseStateMd, parseRoadmapMd, parseYamlFrontmatter, parseMustHaves, countMustHaves, stateLoad, stateCheckProgress, configLoad, configClearCache, configValidate, lockedFileUpdate, planIndex, determinePhaseStatus, findFiles, atomicWrite, tailLines, frontmatter, mustHavesCollect, phaseInfo, stateUpdate, roadmapUpdateStatus, roadmapUpdatePlans, updateLegacyStateField, updateFrontmatterField, updateTableRow, findRoadmapRow, resolveDepthProfile, DEPTH_PROFILE_DEFAULTS, historyAppend, historyLoad, VALID_STATUS_TRANSITIONS, validateStatusTransition, writeActiveSkill, validateProject, phaseAdd, phaseRemove, phaseList, loadUserDefaults, saveUserDefaults, mergeUserDefaults, USER_DEFAULTS_PATH, todoList, todoGet, todoAdd, todoDone, migrate, spotCheck, referenceGet, milestoneStats, contextTriage, stalenessCheck, summaryGate, checkpointInit, checkpointUpdate, seedsMatch };
+module.exports = { KNOWN_AGENTS, initExecutePhase, initPlanPhase, initQuick, initVerifyWork, initResume, initProgress, initStateBundle: stateBundle, stateBundle, statePatch, stateAdvancePlan, stateRecordMetric, parseStateMd, parseRoadmapMd, parseYamlFrontmatter, parseMustHaves, countMustHaves, stateLoad, stateCheckProgress, configLoad, configClearCache, configValidate, lockedFileUpdate, planIndex, determinePhaseStatus, findFiles, atomicWrite, tailLines, frontmatter, mustHavesCollect, phaseInfo, stateUpdate, roadmapUpdateStatus, roadmapUpdatePlans, updateLegacyStateField, updateFrontmatterField, updateTableRow, findRoadmapRow, resolveDepthProfile, DEPTH_PROFILE_DEFAULTS, historyAppend, historyLoad, VALID_STATUS_TRANSITIONS, validateStatusTransition, writeActiveSkill, validateProject, phaseAdd, phaseRemove, phaseList, loadUserDefaults, saveUserDefaults, mergeUserDefaults, USER_DEFAULTS_PATH, todoList, todoGet, todoAdd, todoDone, migrate, spotCheck, referenceGet, milestoneStats, contextTriage, stalenessCheck, summaryGate, checkpointInit, checkpointUpdate, seedsMatch, ciPoll, rollbackPlan };
 // NOTE: validateProject, phaseAdd, phaseRemove, phaseList were previously CLI-only (not exported).
 // They are now exported for testability. This is additive and backwards-compatible.

package/plugins/pbr/skills/build/SKILL.md

@@ -374,7 +374,6 @@ Use AskUserQuestion with the three options. Route:
 - Between waves: verify no file conflicts from parallel executors (`git status` for uncommitted changes)
 
 **Read executor deviations:**
-
 After all executors in the wave complete, read all SUMMARY frontmatter and:
 - Collect `deferred` items into a running list (append to `.checkpoint-manifest.json` deferred array)
 - Flag any deviation-rule-4 (architectural) stops — these require user attention
@@ -395,9 +394,7 @@ Wave {W} Results:
 
 **Skip if** the depth profile has `features.inline_verify: false`.
 
-To check: use the resolved depth profile. Only `comprehensive` mode enables inline verification by default.
-
-When inline verification is enabled, each completed plan gets a targeted verification pass before the orchestrator proceeds to the next wave. This catches issues early — before dependent plans build on a broken foundation.
+To check: use the resolved depth profile. Only `comprehensive` mode enables inline verification by default. When inline verification is enabled, each completed plan gets a targeted verification pass before the orchestrator proceeds to the next wave — catching issues early before dependent plans build on a broken foundation.
 
 For each plan that completed successfully in this wave:
 
@@ -643,6 +640,8 @@ This ensures that `/pbr:review` after a `--gaps-only` build sees the updated ver
 
 **8-pre-c. Codebase map incremental update (conditional):**
 
+**CRITICAL (no hook): Run codebase map update if conditions are met. Do NOT skip this step.**
+
 Only run if ALL of these are true:
 - `.planning/codebase/` directory exists (project was previously scanned with `/pbr:scan`)
 - Build was not aborted
@@ -753,6 +752,8 @@ Write `.planning/.auto-next` containing the next logical command (e.g., `/pbr:pl
 
 **8e-ii. Check Pending Todos:**
 
+**CRITICAL (no hook): Check pending todos after build. Do NOT skip this step.**
+
 After completing the build, check if any pending todos are now satisfied:
 
 1. Check if `.planning/todos/pending/` exists and contains files
@@ -869,3 +870,9 @@ If `git.branching` is `phase` but we're not on the phase branch:
 | `.planning/STATE.md` | Updated progress | Steps 6f, 8b |
 | `.planning/.auto-next` | Next command signal (if auto_continue enabled) | Step 8e |
 | Project source files | Actual code | Step 6 (executors) |
+
+---
+
+## Cleanup
+
+Delete `.planning/.active-skill` if it exists. This must happen on all paths (success, partial, and failure) before reporting results.

package/plugins/pbr/skills/milestone/SKILL.md

@@ -162,39 +162,7 @@ Start a new milestone cycle with new phases.
    docs(planning): start milestone "{name}" (phases {start}-{end})
    ```
 
-10. **Confirm** with branded output:
-    ```
-    ╔══════════════════════════════════════════════════════════════╗
-    ║  PLAN-BUILD-RUN ► MILESTONE CREATED ✓                        ║
-    ╚══════════════════════════════════════════════════════════════╝
-
-    **Milestone: {name}** — {count} phases
-
-    Phases:
-    {N}. {name}
-    {N+1}. {name}
-    ...
-
-
-
-    ╔══════════════════════════════════════════════════════════════╗
-    ║  ▶ NEXT UP                                                   ║
-    ╚══════════════════════════════════════════════════════════════╝
-
-    **Phase {N}: {name}** — start with discussion or planning
-
-    `/pbr:discuss {N}`
-
-    <sub>`/clear` first → fresh context window</sub>
-
-
-
-    **Also available:**
-    - `/pbr:plan {N}` — skip discussion, plan directly
-    - `/pbr:status` — see project status
-
-
-    ```
+10. **Confirm** with branded output — read `skills/milestone/templates/new-output.md.tmpl` and fill in `{name}` (milestone name), `{count}` (phase count), `{N}` (first phase number).
 
 ---
 
@@ -482,42 +450,7 @@ If `config.deployment.smoke_test_command` is set and non-empty:
 
    This is advisory only — the milestone is already archived. Surface it as a potential issue for the user to investigate.
 
-10. **Confirm** with branded output:
-    ```
-    ╔══════════════════════════════════════════════════════════════╗
-    ║  PLAN-BUILD-RUN ► MILESTONE COMPLETE 🎉                      ║
-    ╚══════════════════════════════════════════════════════════════╝
-
-    **{version}**
-
-    Stats:
-    - {count} phases, {count} plans
-    - {count} commits, {lines} lines of code
-    - {duration} days
-
-    Archived to: .planning/milestones/{version}/
-    Git tag: {version}
-
-
-
-    ╔══════════════════════════════════════════════════════════════╗
-    ║  ▶ NEXT UP                                                   ║
-    ╚══════════════════════════════════════════════════════════════╝
-
-    **Start the next milestone** — plan new features
-
-    `/pbr:milestone new`
-
-    <sub>`/clear` first → fresh context window</sub>
-
-
-
-    **Also available:**
-    - `/pbr:status` — see project status
-    - `/pbr:help` — see all commands
-
-
-    ```
+10. **Confirm** with branded output — read `skills/milestone/templates/complete-output.md.tmpl` and fill in `{version}`, `{count}` (phases, plans, commits), `{lines}`, `{duration}`.
 
 ---
 
@@ -561,91 +494,7 @@ Verify milestone completion with cross-phase integration checks.
 
    **Spot-check:** After writing, verify `.planning/{version}-MILESTONE-AUDIT.md` exists on disk using Glob. If missing, re-attempt the write. If still missing, display an error and include findings inline.
 
-7. **Report to user** using branded banners:
-
-   **If PASSED:**
-   ```
-   ╔══════════════════════════════════════════════════════════════╗
-   ║  PLAN-BUILD-RUN ► MILESTONE AUDIT PASSED ✓                   ║
-   ╚══════════════════════════════════════════════════════════════╝
-
-   All phases verified, integration checks passed, requirements covered.
-
-
-
-   ╔══════════════════════════════════════════════════════════════╗
-   ║  ▶ NEXT UP                                                   ║
-   ╚══════════════════════════════════════════════════════════════╝
-
-   **Complete the milestone** — archive and tag
-
-   `/pbr:milestone complete {version}`
-
-   <sub>`/clear` first → fresh context window</sub>
-
-
-
-   **Also available:**
-   - `/pbr:milestone gaps` — address any minor issues first
-   - `/pbr:status` — see project status
-
-
-   ```
-
-   **If GAPS FOUND:**
-   ```
-   ╔══════════════════════════════════════════════════════════════╗
-   ║  PLAN-BUILD-RUN ► MILESTONE AUDIT — GAPS FOUND ⚠             ║
-   ╚══════════════════════════════════════════════════════════════╝
-
-   Found {count} gaps:
-   - {gap 1}
-   - {gap 2}
-
-
-
-   ╔══════════════════════════════════════════════════════════════╗
-   ║  ▶ NEXT UP                                                   ║
-   ╚══════════════════════════════════════════════════════════════╝
-
-   **Close the gaps** — create fix phases
-
-   `/pbr:milestone gaps`
-
-   <sub>`/clear` first → fresh context window</sub>
-
-
-
-   **Also available:**
-   - `/pbr:milestone complete` — proceed despite gaps
-   - `/pbr:status` — see project status
-
-
-   ```
-
-   **If TECH DEBT:**
-   ```
-   ╔══════════════════════════════════════════════════════════════╗
-   ║  PLAN-BUILD-RUN ► MILESTONE AUDIT — TECH DEBT ⚠              ║
-   ╚══════════════════════════════════════════════════════════════╝
-
-   Milestone functional but has {count} tech debt items.
-
-
-
-   ╔══════════════════════════════════════════════════════════════╗
-   ║  ▶ NEXT UP                                                   ║
-   ╚══════════════════════════════════════════════════════════════╝
-
-   **Address tech debt or proceed**
-
-   `/pbr:milestone gaps` — create cleanup phases
-   `/pbr:milestone complete` — proceed as-is
-
-   <sub>`/clear` first → fresh context window</sub>
-
-
-   ```
+7. **Report to user** using branded banners — read `skills/milestone/templates/audit-output.md.tmpl`. The template contains all 3 variants (PASSED, GAPS FOUND, TECH DEBT). Select the appropriate section based on audit result. Fill in `{version}`, `{count}`, `{gap 1}`, `{gap 2}` as applicable.
 
 ---
 
@@ -725,35 +574,7 @@ Create phases to close gaps found during an audit.
    docs(planning): add gap-closure phases from milestone audit
    ```
 
-9. **Confirm** with branded output:
-   ```
-   ╔══════════════════════════════════════════════════════════════╗
-   ║  PLAN-BUILD-RUN ► GAP PHASES CREATED ✓                       ║
-   ╚══════════════════════════════════════════════════════════════╝
-
-   Created {count} gap-closure phase(s):
-   - Phase {N}: {name}
-   - Phase {N+1}: {name}
-
-
-
-   ╔══════════════════════════════════════════════════════════════╗
-   ║  ▶ NEXT UP                                                   ║
-   ╚══════════════════════════════════════════════════════════════╝
-
-   **Plan the first gap-closure phase**
-
-   `/pbr:plan {N}`
-
-   <sub>`/clear` first → fresh context window</sub>
-
-
-
-   **Also available:**
-   - `/pbr:status` — see project status
-
-
-   ```
+9. **Confirm** with branded output — read `skills/milestone/templates/gaps-output.md.tmpl` and fill in `{count}` (gap-closure phases created), `{N}` (first gap phase number), `{name}` (phase name).
 
 ---
 

package/plugins/pbr/skills/plan/SKILL.md

@@ -165,34 +165,7 @@ Collect all of this into a context bundle that will be passed to subagents.
 
 **IMPORTANT**: This step is FREE (no subagents). It happens entirely inline.
 
-Before spawning any agents, present your assumptions about how this phase should be approached:
-
-```
-Phase {N}: {Name}
-Goal: {from roadmap}
-
-My assumptions about this phase:
-
-1. **Approach**: I'm assuming we'll {approach}
-   - Correct? [yes/no/adjust]
-
-2. **Key technology**: I'm assuming we'll use {tech}
-   - Correct? [yes/no/adjust]
-
-3. **Architecture**: I'm assuming {architectural assumption}
-   - Correct? [yes/no/adjust]
-
-4. **Scope boundary**: I'm assuming {scope assumption}
-   - Correct? [yes/no/adjust]
-```
-
-For each assumption the user corrects:
-- Record the correction
-- These corrections become additional CONTEXT.md entries
-
-After all assumptions are confirmed/corrected:
-- Update `.planning/CONTEXT.md` with any new locked decisions
-- Continue to Step 4
+Before spawning any agents, present 4 assumptions to the user — one each for: approach (how the phase will be implemented), key technology, architecture, and scope boundary. For each, ask the user to confirm or correct. Record corrections as new CONTEXT.md locked decisions. After all assumptions are confirmed/corrected, continue to Step 4.
 
 ---
 
@@ -252,101 +225,61 @@ After the researcher completes, check the Task() output for a completion marker:
 
 ---
 
-### Step 4.5: Seed Scanning (inline, before planning)
-
-Before spawning the planner, scan `.planning/seeds/` for seeds whose trigger matches the current phase:
-
-1. Run seed matcher CLI:
-   ```bash
-   node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js seeds match {phase-slug} {phase-number}
-   ```
-   Returns `{ matched: [{ name, description, trigger, path }] }`.
-2. If `matched` is empty: proceed silently.
-3. If `matched` is non-empty: present to user (see step 4 below).
-4. If matching seeds are found, present them to the user:
-   ```
-   Found {N} seeds related to Phase {NN}:
-     - {seed_name}: {seed description}
-     - {seed_name}: {seed description}
-   ```
-
-   Use AskUserQuestion (pattern: yes-no-pick from `skills/shared/gate-prompts.md`):
-     question: "Include these {N} seeds in planning?"
-     header: "Seeds?"
-     options:
-       - label: "Yes, all"     description: "Include all {N} matching seeds"
-       - label: "Let me pick"  description: "Choose which seeds to include"
-       - label: "No"           description: "Proceed without seeds"
-5. If "Yes, all": include all matching seed content in the planner's context
-6. If "Let me pick": present individual seeds for selection
-7. If "No" or "Other": proceed without seeds
-8. If no matching seeds found: proceed silently
-
----
-
-### Step 4.6: Surface Deferred Ideas (inline, before planning)
-
-Before spawning the planner, check `.planning/CONTEXT.md` for deferred ideas that may be relevant to this phase:
-
-1. If `.planning/CONTEXT.md` does NOT exist, skip this step silently
-2. If it exists, scan for sections named "Deferred Ideas", "Deferred", "Ideas", or "Seeds" (case-insensitive heading match)
-3. For each deferred item found, check relevance to the current phase by comparing the item text against the phase goal, requirements, and slug
-4. If relevant deferred items are found, present them to the user:
-   ```
-   Found {N} deferred idea(s) from previous discussions that may be relevant to Phase {NN}:
-     - {deferred item summary}
-     - {deferred item summary}
-   ```
-   Use AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
-     question: "Include these deferred ideas in the planning context?"
-     header: "Deferred Ideas"
-     options:
-       - label: "Yes"  description: "Pass relevant deferred ideas to the planner"
-       - label: "No"   description: "Proceed without deferred ideas"
-5. If "Yes": append the relevant deferred items to the context bundle for the planner prompt (add them to the `<project_context>` block under a `Deferred ideas to consider:` heading)
-6. If "No" or no relevant items found: proceed without changes
-
-This is a lightweight relevance filter — do NOT spawn a subagent for this. Just match keywords from the deferred items against the phase goal and requirement text.
-
----
-
-### Step 5: Planning (delegated)
+### Step 4.5: Pre-Planner Briefing (delegated)
 
-#### Team Mode (--teams)
+**CRITICAL (no hook): Run pre-planner briefing before spawning the planner. Do NOT skip this step.**
 
-Reference: `references/agent-teams.md` for team role definitions and coordination details.
+Consolidate seed scanning and deferred idea surfacing into a single lightweight Task():
 
-If `--teams` flag is set OR `config.parallelization.use_teams` is true:
+```
+Task({
+  subagent_type: "pbr:general",
+  model: "haiku",
+  prompt: "Pre-planner briefing for Phase {NN} ({phase-slug}).
+
+1. SEED SCANNING:
+   Run: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js seeds match {phase-slug} {phase-number}`
+   If `matched` is non-empty, output a ## Seeds section listing each seed name, description, and content.
+   If empty, output: ## Seeds\nNo matching seeds found.
+
+2. DEFERRED IDEAS:
+   Read `.planning/CONTEXT.md`. If it has a section containing 'deferred' or 'ideas' (case-insensitive),
+   extract items that mention Phase {NN} or keywords matching the phase slug.
+   If relevant items found, output a ## Deferred Ideas section listing them.
+   If none found, output: ## Deferred Ideas\nNo relevant deferred items.
+
+Output format: Return both sections as markdown. End with ## BRIEFING COMPLETE."
+})
+```
 
-1. Create the team output directory: `.planning/phases/{NN}-{slug}/team/`
-2. Display to the user: `◐ Spawning 3 planners in parallel (architect, security, test)...`
+After the Task() completes:
+- If `## Seeds` section contains matches: present them to the user via AskUserQuestion (pattern: yes-no-pick from `skills/shared/gate-prompts.md`):
+  question: "Include these {N} seeds in planning?"
+  header: "Seeds?"
+  options:
+    - label: "Yes, all"     description: "Include all {N} matching seeds"
+    - label: "Let me pick"  description: "Choose which seeds to include"
+    - label: "No"           description: "Proceed without seeds"
+- If "Yes, all": include seed content in planner context
+- If "Let me pick": present individual seeds for selection
+- If "No": proceed without seeds
 
-   Spawn THREE planner agents in parallel using Task():
+- If `## Deferred Ideas` section has items: present via AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
+  question: "Include these deferred ideas in planning context?"
+- If "Yes": append to planner context under `Deferred ideas to consider:`
+- If "No": proceed without changes
 
-   **Agent 1 -- Architect**:
-   - subagent_type: "pbr:planner"
-   - Prompt includes: "You are the ARCHITECT role in a planning team. Focus on: structure, file boundaries, dependency ordering, wave assignment. Write your output to `.planning/phases/{NN}-{slug}/team/architect-PLAN.md`. Do NOT write final PLAN.md files -- your output will be synthesized."
-   - Include phase goal, research doc paths, CONTEXT.md path in the prompt
+- If both sections are empty: proceed silently to Step 5 (no AskUserQuestion needed)
 
-   **Agent 2 -- Security Reviewer**:
-   - subagent_type: "pbr:planner"
-   - Prompt includes: "You are the SECURITY REVIEWER role in a planning team. Focus on: authentication checks, input validation tasks, secrets handling, permission boundaries. Write your output to `.planning/phases/{NN}-{slug}/team/security-PLAN.md`. Do NOT write final PLAN.md files."
-   - Include same context as Agent 1
+---
 
-   **Agent 3 -- Test Designer**:
-   - subagent_type: "pbr:planner"
-   - Prompt includes: "You are the TEST DESIGNER role in a planning team. Focus on: test strategy, coverage targets, edge cases, which tasks should use TDD, integration test boundaries. Write your output to `.planning/phases/{NN}-{slug}/team/test-PLAN.md`. Do NOT write final PLAN.md files."
-   - Include same context as Agent 1
+### Step 5: Planning (delegated)
 
-3. Wait for all three to complete
-4. Display to the user: `◐ Spawning synthesizer...`
+#### Team Mode (--teams)
 
-   Spawn the synthesizer agent:
-   - subagent_type: "pbr:synthesizer"
-   - Prompt: "Read all files in `.planning/phases/{NN}-{slug}/team/`. Synthesize them into unified PLAN.md files in `.planning/phases/{NN}-{slug}/`. The architect output provides structure, the security output adds security-related tasks or checks, and the test output informs TDD flags and test tasks. Resolve any contradictions by preferring the architect's structure with security and test additions."
-5. Proceed to plan checking as normal
+If `--teams` flag is set OR `config.parallelization.use_teams` is true, spawn 3 parallel planner agents (architect, security, test) then a synthesizer to merge their outputs. See `references/agent-teams.md` for agent role definitions, output paths (`.planning/phases/{NN}-{slug}/team/`), and prompt content for each role.
 
-If `--teams` is NOT set and `config.parallelization.use_teams` is false or unset, proceed with the existing single-planner flow below.
+If `--teams` is NOT set and `config.parallelization.use_teams` is false or unset, proceed with the single-planner flow below.
 
 #### Single-Planner Flow (default)
 
@@ -501,25 +434,7 @@ Follow the revision loop pattern with:
 
 **If approval is needed:**
 
-Present a summary of all plans to the user:
-
-```
-Phase {N}: {name}
-Plans: {count}
-
-Plan {phase}-01: {plan name} (Wave {W}, {task_count} tasks)
-  Must-haves: {list truths}
-  Files: {list files_modified}
-  Tasks:
-    1. {task name}
-    2. {task name}
-
-Plan {phase}-02: {plan name} (Wave {W}, {task_count} tasks)
-  ...
-
-Wave execution order:
-  Wave 1: Plan 01, Plan 02 (parallel)
-  Wave 2: Plan 03 (depends on 01, 02)
+Present a summary of all plans to the user. For each plan include: plan name, wave, task count, must-haves, files_modified. For each task include the task name. Add a wave execution order summary (Wave 1: Plan 01, 02 (parallel), Wave 2: Plan 03, etc.).
 
 Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prompts.md`):
   question: "Approve these {count} plans for Phase {N}?"
@@ -528,7 +443,6 @@ Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prom
     - label: "Approve"          description: "Proceed to build phase"
     - label: "Request changes"  description: "Discuss adjustments before proceeding"
     - label: "Abort"            description: "Cancel planning for this phase"
-```
 
 **If user selects 'Request changes' or 'Other':**
 - Discuss what needs to change
@@ -539,14 +453,7 @@ Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prom
 - **CONTEXT.md compliance reporting**: If `.planning/CONTEXT.md` exists, compare all locked decisions against the generated plans. Print: "CONTEXT.md compliance: {M}/{N} locked decisions mapped to tasks" where M = locked decisions that are reflected in at least one task, N = total locked decisions. If any locked decisions are unmapped, list them as warnings.
 - **Dependency fingerprinting**: For each dependency phase (phases that this phase depends on, per ROADMAP.md):
   1. Find all SUMMARY.md files in the dependency phase directory
-  2. Compute a simple hash of each SUMMARY.md file (e.g., first 8 chars of a SHA-256 of the file content, or a simpler approach: use the file's byte length + last-modified timestamp as a fingerprint string)
-  3. Add a `dependency_fingerprints` field to each plan's YAML frontmatter:
-     ```yaml
-     dependency_fingerprints:
-       "01-01": "len:4856-mod:2025-02-08T09:40"
-       "01-02": "len:4375-mod:2025-02-08T09:43"
-     ```
-  4. This allows the build skill to detect if dependency phases were re-built after this plan was created
+  2. Compute a fingerprint string for each: `"len:{bytes}-mod:{mtime}"` and add as a `dependency_fingerprints` map in each plan's YAML frontmatter — this allows the build skill to detect stale plans if dependencies were rebuilt.
 - **Update ROADMAP.md Progress table** (REQUIRED — do this BEFORE updating STATE.md):
 
   **Tooling shortcut**: Use the CLI for atomic updates: