@sienklogic/plan-build-run 2.18.1 → 2.19.1

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

@@ -26,11 +26,17 @@ You are running the **milestone** skill. Milestones represent significant projec
 
 This skill runs **inline** for most subcommands, but spawns agents for `audit`.
 
+## References
+
+- `references/questioning.md` — Questioning patterns for milestone review decisions
+- `references/ui-brand.md` — Status symbols, banners, milestone celebration format
+
 ---
 
 ## Context Budget
 
 Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
+Reference: `skills/shared/agent-type-resolution.md` for agent type fallback when spawning Task() subagents.
 
 Additionally for this skill:
 - **Never** perform integration checks yourself — delegate to the integration-checker subagent
@@ -39,6 +45,22 @@ Additionally for this skill:
 
 ---
 
+## Multi-Session Sync
+
+Before any phase-modifying operations (archiving phases, updating ROADMAP.md/STATE.md/PROJECT.md), acquire a claim:
+
+```
+acquireClaim(planningDir, sessionId)
+```
+
+If the claim fails (another session owns this project), display: "Another session owns this project. Use `/pbr:progress` to see active claims."
+
+On completion or error (including all exit paths), release the claim:
+
+```
+releaseClaim(planningDir, sessionId)
+```
+
 ## Core Principle
 
 **Milestones are the rhythm of the project.** They force you to step back, verify everything works together, and create a clean snapshot before moving on. Never skip the audit — integration issues hide at milestone boundaries.
@@ -57,6 +79,7 @@ Examples:
   "new User Auth"    → subcommand=new, arg="User Auth"
   "complete v1.0"    → subcommand=complete, arg="v1.0"
   "complete 1.0"     → subcommand=complete, arg="v1.0" (auto-prefix v)
+  "preview v1.0"     → subcommand=preview, arg="v1.0"
   "audit v1.0"       → subcommand=audit, arg="v1.0"
   "audit"            → subcommand=audit, arg=current milestone
   "gaps"             → subcommand=gaps, arg=most recent audit
@@ -69,10 +92,29 @@ Usage: /pbr:milestone <subcommand> [version]
 Subcommands:
   new [name]       — Start a new milestone cycle
   complete [ver]   — Archive completed milestone
+  preview [ver]    — Dry-run of complete (show what would happen)
   audit [ver]      — Verify milestone completion
   gaps             — Create phases to close audit gaps
 ```
 
+**CRITICAL — After parsing the subcommand, run init command before any manual state reads:**
+
+```bash
+node plugins/pbr/scripts/pbr-tools.js init milestone
+```
+
+Store the JSON result as `blob`. This single call replaces multiple file reads across all subcommands:
+- `blob.state.current_phase`, `blob.state.status` — current phase and status from STATE.md
+- `blob.state.last_milestone_version`, `blob.state.last_milestone_completed` — milestone history
+- `blob.has_roadmap` — whether ROADMAP.md exists
+- `blob.has_project` — whether PROJECT.md exists
+- `blob.milestones` — array of milestone sections parsed from ROADMAP.md (each with `name` and `phases_range`)
+- `blob.existing_archives` — array of existing archive directory names
+- `blob.phase_count` — total phase count
+- `blob.config.mode`, `blob.config.planning`, `blob.config.git` — config settings
+
+If `blob.error` is set, display the error banner and stop (no project found).
+
 ---
 
 ## Subcommand: `new`
@@ -81,10 +123,11 @@ Start a new milestone cycle with new phases.
 
 ### Flow
 
-1. **Read current state:**
-   - Read ROADMAP.md to see existing phases
-   - Read STATE.md for current position
-   - Read PROJECT.md if it exists (milestone history)
+1. **Read current state from init blob:**
+   - `blob.milestones` for existing milestone sections from ROADMAP.md
+   - `blob.state.current_phase` and `blob.state.status` for current position
+   - `blob.has_project` to check if PROJECT.md exists (read it for milestone history if needed)
+   - `blob.phase_count` for total phase count
 
 2. **Get milestone details** via AskUserQuestion:
    - "What's the name/goal for this new milestone?"
@@ -97,7 +140,7 @@ Start a new milestone cycle with new phases.
    - Example: if phases 1-5 exist, new milestone starts at phase 6
 
 4. **Mini roadmap session:**
-   Run a condensed version of the `/pbr:begin` questioning flow:
+   Run a condensed version of the `/pbr:new-project` questioning flow:
 
    a. Ask about major components needed (via AskUserQuestion):
       - "What are the 2-5 major areas of work for this milestone?"
@@ -123,8 +166,8 @@ Start a new milestone cycle with new phases.
 
    ### Phase {N}: {name}
    **Goal:** {goal}
-   **Requirements:** {list}
-   **Success criteria:** {criteria}
+   **Requirements:** {REQ-IDs mapped to this phase}
+   **Success Criteria:** {verifiable conditions for phase completion}
    **Depends on:** {prior phases}
 
    ### Phase {N+1}: {name}
@@ -149,48 +192,107 @@ Start a new milestone cycle with new phases.
    - **Status:** In progress
    ```
 
+**CRITICAL (no hook) -- DO NOT SKIP: Update STATE.md frontmatter AND body with new milestone info.**
+
 8. **Update STATE.md:**
    - Set current phase to the first new phase
    - Update milestone info
 
+**CRITICAL (no hook) -- DO NOT SKIP: Generate root MILESTONE.md file.**
+
+8b. **Generate root MILESTONE.md:**
+   Read the current milestone section from ROADMAP.md (the `## Milestone:` section just created in Step 5) and STATE.md for current phase and status. Write `MILESTONE.md` at the project root with:
+
+   ```markdown
+   # Current Milestone: {name}
+   **Version:** {version} | **Status:** In Progress | **Created:** {date}
+
+   **Goal:** {goal}
+
+   ## Phases
+   | Phase | Goal | Status |
+   |-------|------|--------|
+   | {N}. {name} | {goal} | Pending |
+   ...
+
+   ---
+   *Auto-generated by `/pbr:milestone new`. Updated by `/pbr:autonomous`.*
+   ```
+
+   - Read the phase list from the ROADMAP.md section just written in Step 5
+   - Status column: "Pending" for all new phases
+
+**Milestone branch creation (when git.branching is 'milestone'):**
+When starting a new milestone and `git.branching` is `milestone`:
+- Create branch: `git switch -c pbr/milestone-v{version}`
+- All phase work happens on this branch
+- Branch is merged when `/pbr:milestone complete` is run
+
 9. **Commit** if `planning.commit_docs: true`:
    ```
    docs(planning): start milestone "{name}" (phases {start}-{end})
    ```
 
-10. **Confirm** with branded output:
-    ```
-    ╔══════════════════════════════════════════════════════════════╗
-    ║  PLAN-BUILD-RUN ► MILESTONE CREATED ✓                        ║
-    ╚══════════════════════════════════════════════════════════════╝
+10. **Confirm** with branded output — read `${CLAUDE_SKILL_DIR}/templates/new-output.md.tmpl` and fill in `{name}` (milestone name), `{count}` (phase count), `{N}` (first phase number).
 
-    **Milestone: {name}** — {count} phases
+---
 
-    Phases:
-    {N}. {name}
-    {N+1}. {name}
-    ...
+## Subcommand: `preview`
 
+Dry-run of milestone completion — shows what would happen without making any changes.
 
+### Flow
 
-    ╔══════════════════════════════════════════════════════════════╗
-║  ▶ NEXT UP                                                   ║
-╚══════════════════════════════════════════════════════════════╝
+1. **Determine version:**
+   - Same logic as `complete`: use `$ARGUMENTS` or ask via AskUserQuestion
 
-    **Phase {N}: {name}** — start with discussion or planning
+2. **Identify milestone phases:**
+   - Read ROADMAP.md to find phases belonging to this milestone
+   - List each phase with its current status (from STATE.md or VERIFICATION.md)
 
-    `/pbr:discuss {N}`
+3. **Verification status check:**
+   - For each milestone phase, check if VERIFICATION.md exists and its `result` frontmatter
+   - Flag phases that are unverified or have stale verification (SUMMARY.md newer than VERIFICATION.md)
+
+4. **Preview archive structure:**
+   - Show what the archive directory would look like:
+     ```
+     .planning/milestones/v{version}/
+     ├── ROADMAP.md (snapshot)
+     ├── STATS.md (would be generated)
+     ├── REQUIREMENTS.md (snapshot)
+     └── phases/
+         ├── {NN}-{slug}/ (moved from .planning/phases/)
+         │   ├── PLAN-01.md
+         │   ├── SUMMARY.md
+         │   └── VERIFICATION.md
+         └── ...
+     ```
 
-    <sub>`/clear` first → fresh context window</sub>
+5. **Show what would change:**
+   - Which phase directories would be moved
+   - What ROADMAP.md section would be collapsed
+   - What STATE.md updates would occur
+   - What git tag would be created
 
+6. **Display summary:**
+   ```
+   ╔══════════════════════════════════════════════════════════════╗
+   ║  PLAN-BUILD-RUN ► MILESTONE PREVIEW — v{version}             ║
+   ╚══════════════════════════════════════════════════════════════╝
 
+   Phases to archive: {count}
+   ✓ Verified: {verified_count}
+   ⚠ Unverified: {unverified_count}
+   ⚠ Stale verification: {stale_count}
 
-    **Also available:**
-    - `/pbr:plan {N}` — skip discussion, plan directly
-    - `/pbr:status` — see project status
+   Archive location: .planning/milestones/v{version}/
+   Git tag: v{version}
 
+   Ready to complete? Run: /pbr:complete-milestone v{version}
+   ```
 
-    ```
+**CRITICAL (no hook)**: This subcommand is READ-ONLY. Do not create directories, move files, modify STATE.md, modify ROADMAP.md, or create git tags. Only read and display.
 
 ---
 
@@ -204,9 +306,19 @@ Archive a completed milestone and prepare for the next one.
    - If provided in `$ARGUMENTS`: use it (auto-prefix `v` if missing)
    - If not provided: ask via AskUserQuestion: "What version number for this milestone? (e.g., v1.0)"
 
-2. **Verify all phases are complete:**
-   - Read ROADMAP.md to find milestone phases
-   - For each phase, check for VERIFICATION.md
+2. **Check verification debt across ALL phases:**
+   - Use `blob.milestones` to find the target milestone's phase range
+   - For each phase in the range, check VERIFICATION.md status:
+     - `gaps_found` or `human_needed` or `partial` → verification debt exists
+   - If verification debt found, display warning:
+     ```
+     Verification Debt:
+       - Phase {N}: {status} ({count} outstanding items)
+     ```
+   - This is non-blocking but prominently displayed before the completion decision
+
+3. **Verify all phases are complete:**
+   - For each phase in the range, check for VERIFICATION.md
    - If any phase lacks VERIFICATION.md:
 
      Present the warning context:
@@ -214,12 +326,13 @@ Archive a completed milestone and prepare for the next one.
        - Phase {N}: {name}
        - Phase {M}: {name}
 
+     **CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding:
      Use AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
        question: "{count} phases haven't been verified. Continue with milestone completion?"
        header: "Unverified"
        options:
          - label: "Continue anyway"  description: "Proceed despite unverified phases (not recommended)"
-         - label: "Stop and review"  description: "Run /pbr:review for unverified phases first"
+         - label: "Stop and review"  description: "Run /pbr:verify-work for unverified phases first"
      - If "Stop and review" or "Other": stop and suggest the review commands for each unverified phase
      - If "Continue anyway": proceed with warning noted
 
@@ -229,11 +342,12 @@ Archive a completed milestone and prepare for the next one.
    - Warn: "Phase {N} ({name}) was modified after verification. The VERIFICATION.md may not reflect the current code state."
    - List affected phases with their freshness details
 
+   **CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding:
    Use AskUserQuestion (pattern: stale-continue from `skills/shared/gate-prompts.md`):
      question: "{count} phases were modified after verification. Re-verify or continue?"
      header: "Stale"
      options:
-       - label: "Re-verify"        description: "Run /pbr:review for affected phases (recommended)"
+       - label: "Re-verify"        description: "Run /pbr:verify-work for affected phases (recommended)"
        - label: "Continue anyway"   description: "Proceed with potentially outdated verification"
    - If "Re-verify" or "Other": suggest the review commands for affected phases and stop
    - If "Continue anyway": proceed with warning noted
@@ -264,12 +378,32 @@ Archive a completed milestone and prepare for the next one.
    - Collect `patterns` fields
    - Collect `tech_stack` union
 
+**Milestone branching (config-gated):**
+Read `blob.config.git.branching` (or fall back to reading config if blob unavailable).
+- If `milestone`:
+  a. Check if milestone branch exists: `git branch --list pbr/milestone-v{version}`
+  b. If branch exists:
+    - Use AskUserQuestion:
+      question: "Milestone v{version} complete. Merge branch `pbr/milestone-v{version}` to main?"
+      header: "Merge milestone branch?"
+      options:
+        - label: "Yes, merge"   description: "Merge milestone branch to main and delete it"
+        - label: "No, keep"     description: "Keep the branch for manual review"
+    - If "Yes, merge":
+      1. `git switch main`
+      2. `git merge --no-ff pbr/milestone-v{version}` (no-ff to preserve milestone history)
+      3. `git branch -d pbr/milestone-v{version}`
+      4. Log: "Milestone branch merged and deleted"
+    - If "No, keep": leave branch as-is
+  c. If branch does not exist: no action (phases were on main or individual phase branches)
+- If `none`, `phase`, or `disabled`: no milestone branch operations
+
 5. **Archive milestone documents:**
 
-   **CRITICAL: Pre-flight safety checks BEFORE archiving. Do NOT skip this step.**
+   **CRITICAL (no hook): Pre-flight safety checks BEFORE archiving. Do NOT skip this step.**
 
    Before creating or moving anything, verify the destination is safe:
-   - Check if `.planning/milestones/{version}/` already exists
+   - Check `blob.existing_archives` to see if the version directory already exists
    - If it exists AND contains files (phases/, STATS.md, etc.), STOP and display:
      ```
      ╔══════════════════════════════════════════════════════════════╗
@@ -286,23 +420,43 @@ Archive a completed milestone and prepare for the next one.
    - Verify each source phase directory exists before attempting to move it
    - If any source phase directory is missing, warn but continue with the phases that do exist
 
-   **CRITICAL: Create the archive directory .planning/milestones/{version}/ NOW. Do NOT skip this step.**
+   **CRITICAL (no hook): Back up ROADMAP.md BEFORE any destructive operations. Do NOT skip this step.**
+
+   Use the compound init-milestone command to atomically create the archive directory, copy ROADMAP.md, copy REQUIREMENTS.md (if present), and update STATE.md:
+
+   ```bash
+   node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js compound init-milestone {version} --name "{milestone_name}" --phases "{start}-{end}"
+   ```
+
+   This MUST happen before any of the following: moving phase directories, collapsing ROADMAP.md sections, or further STATE.md updates.
 
-   Create a versioned archive directory and move phase directories into it:
-   - `.planning/milestones/{version}/ROADMAP.md` — snapshot of ROADMAP.md at completion
-   - `.planning/milestones/{version}/REQUIREMENTS.md` — **CRITICAL: Copy REQUIREMENTS.md to archive NOW. Do NOT skip this step.** Snapshot of REQUIREMENTS.md
+   The compound command creates the archive directory and copies ROADMAP.md + REQUIREMENTS.md. Now move phase directories and create STATS.md:
    - `.planning/milestones/{version}/STATS.md` — milestone statistics
    - `.planning/milestones/{version}/phases/{NN}-{slug}/` — move each milestone phase directory from `.planning/phases/` into the archive
 
-   **CRITICAL: Move phase directories from .planning/phases/ to archive NOW. Do NOT skip this step.**
+   **CRITICAL (no hook): Move phase directories from .planning/phases/ to archive NOW. Do NOT skip this step.**
 
    **Move phases:** For each phase belonging to this milestone, move (not copy) its directory from `.planning/phases/{NN}-{slug}/` to `.planning/milestones/{version}/phases/{NN}-{slug}/`. This keeps the active phases directory clean for the next milestone.
 
-   **CRITICAL: Write STATS.md to .planning/milestones/{version}/STATS.md NOW. Do NOT skip this step.**
+   **CRITICAL (no hook): Write STATS.md to .planning/milestones/{version}/STATS.md NOW. Do NOT skip this step.**
 
    **Stats file content:**
 
-   Read `skills/milestone/templates/stats-file.md.tmpl` for the stats file format. Fill in all `{variable}` placeholders with actual data gathered in Steps 3-4.
+   Read `${CLAUDE_SKILL_DIR}/templates/stats-file.md.tmpl` for the stats file format. Fill in all `{variable}` placeholders with actual data gathered in Steps 3-4.
+
+5b. **Archive stale research data:**
+
+   After archiving phase directories, prune stale research/intel/codebase data that predates the milestone:
+
+   ```bash
+   node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js data prune --before {milestone_start_date}
+   ```
+
+   Where `{milestone_start_date}` is the earliest phase start date from the milestone (derived from the first SUMMARY.md `start_time` or the milestone creation date).
+
+   - Log the count of archived files (e.g., "Archived 12 stale research files")
+   - If no files to archive, log "No stale research files to archive"
+   - Note: SUMMARY.md, STACK.md, and FEATURES.md are preserved (never pruned) since they are canonical references for active work
 
 6. **Update PROJECT.md:**
    - Move milestone from "Active" to "Completed"
@@ -319,232 +473,311 @@ Archive a completed milestone and prepare for the next one.
 
    - Move validated requirements from active to completed section
 
-**CRITICAL: Update ROADMAP.md with collapsed milestone section NOW. Do NOT skip this step.**
+**CRITICAL (no hook): Run PROJECT.md evolution review NOW. Do NOT skip this step.**
+
+6b. **PROJECT.md Evolution Review:**
+   After moving the milestone to completed status, review and evolve the project definition:
+
+   1. **Move completed Active Requirements to Validated** — Any requirement from the completed milestone that was satisfied (per VERIFICATION.md) should move from Active to Validated section
+   2. **Review Out of Scope** — Check if any previously out-of-scope items are now unblocked by the completed milestone's deliverables. If so, note them for the user's consideration (do not move them automatically)
+   3. **Annotate Key Decisions with outcomes** — For each Key Decision in PROJECT.md that relates to the completed milestone, add an Outcome column value: `Good` (decision worked well), `Revisit` (decision caused issues), or `Pending` (outcome not yet clear)
+   4. **Update Constraints** — Remove or update any constraints that changed during the milestone (e.g., a technology constraint that was relaxed)
+   5. **Refresh Core Value** — If the project direction shifted meaningfully during the milestone, suggest an updated Core Value statement to the user via AskUserQuestion
+
+**CRITICAL (no hook): Update ROADMAP.md with collapsed milestone section NOW. Do NOT skip this step.**
 
 7. **Collapse completed phases in ROADMAP.md:**
-   Replace detailed phase entries with collapsed summaries:
+   Replace detailed phase entries with a `<details>` collapsed summary (backward compat: also recognized by `-- COMPLETED` text):
 
    ```markdown
-   ## Milestone: {name} ({version}) -- COMPLETED
-
-   Phases {start}-{end} completed on {date}. See `.planning/milestones/{version}/ROADMAP.md` for details.
+   <details>
+   <summary>## Milestone: {name} ({version}) — SHIPPED {date}</summary>
 
    | Phase | Status |
    |-------|--------|
    | {N}. {name} | Completed |
    | {N+1}. {name} | Completed |
+
+   Completed: {date} | Archive: `.planning/milestones/{version}/`
+
+   </details>
    ```
 
-**CRITICAL: Update STATE.md to mark milestone as complete NOW. Do NOT skip this step.**
+7a. **Update milestone index:**
+   After collapsing the milestone, update or create a `## Milestones` index section near the top of ROADMAP.md (after the title, before the first active milestone). Each entry is one line:
 
-7b. **Update STATE.md:**
-   - Update `.planning/STATE.md` to mark the milestone as complete
-   - Clear the current milestone field or set status to "completed"
-   - Update last activity timestamp
-   - Record the milestone version in the history/completed section
-
-7c. **Update HISTORY.md:**
-   - Append a milestone completion entry to `.planning/HISTORY.md`:
-     ```markdown
-     ## {date} — Milestone {version} Completed
-
-     - Milestone: {name}
-     - Phases: {start} - {end}
-     - Duration: {duration} days
-     - Key deliverables: {summary from Step 4}
-     ```
+   ```markdown
+   ## Milestones
 
-8. **Git tag:**
-   ```bash
-   git tag -a {version} -m "Milestone: {name}"
+   | Version | Name | Status | Date |
+   |---------|------|--------|------|
+   | {version} | {name} | SHIPPED | {date} |
    ```
 
-9. **Commit:**
-   ```bash
-   git add .planning/milestones/ .planning/phases/ .planning/ROADMAP.md .planning/PROJECT.md .planning/STATE.md .planning/HISTORY.md
-   git commit -m "docs(planning): complete milestone {version}"
-   ```
+   If the section already exists, append a row. If it does not exist, create it.
 
-10. **Confirm** with branded output:
-    ```
-    ╔══════════════════════════════════════════════════════════════╗
-    ║  PLAN-BUILD-RUN ► MILESTONE COMPLETE 🎉                      ║
-    ╚══════════════════════════════════════════════════════════════╝
+**CRITICAL (no hook): Update STATE.md to mark milestone as complete NOW. Do NOT skip this step.**
 
-    **{version}**
+7b. **Update STATE.md:**
+   - Update `.planning/STATE.md` frontmatter to reset to idle state:
+     - `current_phase: null`
+     - `phase_slug: null`
+     - `phase_name: null`
+     - `phases_total: 0`
+     - `status: "idle"`
+     - `progress_percent: 0`
+     - `plans_total: 0`
+     - `plans_complete: 0`
+     - `last_activity: "{date} Milestone {version} complete"`
+   - Update the body section to reflect idle state (no active phase)
+
+7c. **Record milestone completion in STATE.md frontmatter:**
+   - Update STATE.md frontmatter with milestone completion data:
+     - Set `last_milestone_version: "{version}"`
+     - Set `last_milestone_completed: "{ISO datetime}"`
+   - **Do NOT write to a ## History section in STATE.md** — History has been removed from STATE.md to keep it lean. Milestone completion records are preserved in the archive's STATS.md and ROADMAP.md snapshot.
+   - If a ## History section exists in STATE.md (from a prior version), remove it during milestone completion to enforce the new format.
+
+**Run state reconcile after archival** to reset phases_total and current_phase to reflect the next milestone's phases:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state reconcile
+```
 
-    Stats:
-    - {count} phases, {count} plans
-    - {count} commits, {lines} lines of code
-    - {duration} days
+This command re-derives phase counts from ROADMAP.md and reports any phantom phase rows (progress table rows with no corresponding directory on disk). Review and remove phantom rows manually if no longer needed.
 
-    Archived to: .planning/milestones/{version}/
-    Git tag: {version}
+**CRITICAL (no hook): Reconcile ROADMAP phase statuses NOW. Do NOT skip this step.**
 
+7c2. **ROADMAP Reconciliation:**
+   After state reconcile, run a full reconciliation pass to fix any stale phase statuses across the entire ROADMAP:
 
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js roadmap reconcile
+```
 
-    ╔══════════════════════════════════════════════════════════════╗
-║  ▶ NEXT UP                                                   ║
-╚══════════════════════════════════════════════════════════════╝
+   - Log the output (number of entries fixed)
+   - This catches phase status mismatches that accumulated during the milestone lifecycle
+   - Covers both the just-completed milestone and any prior stale entries
 
-    **Start the next milestone** — plan new features
+7d. **Aggregate learnings into KNOWLEDGE.md from milestone phases:**
 
-    `/pbr:milestone new`
+**CRITICAL (no hook): Run learnings aggregation NOW. Do NOT skip this step.**
 
-    <sub>`/clear` first → fresh context window</sub>
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/milestone-learnings.js .planning/milestones/{version} --project {project-name-from-STATE.md}
+```
 
+This script aggregates SUMMARY.md patterns, decisions, and deferred items into the project-scoped `.planning/KNOWLEDGE.md` (table format with K/P/L-prefixed IDs). It also writes to the global `~/.claude/learnings.jsonl` for cross-project use.
 
+- If the script outputs an error, log it but do NOT abort milestone completion — learnings aggregation is advisory.
+- Display the aggregation summary line to the user (e.g., "KNOWLEDGE.md: 5 new entries, 2 duplicates skipped").
+- After aggregation, check for triggered deferral thresholds:
 
-    **Also available:**
-    - `/pbr:status` — see project status
-    - `/pbr:help` — see all commands
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js learnings check-thresholds
+```
 
+If any thresholds are triggered, display each as a notification:
 
-    ```
+```
+Note: Learnings threshold met — {key}: {trigger}. Consider implementing the deferred feature.
+```
 
----
+8. **Git tag:**
+   ```bash
+   git tag -a {version} -m "Milestone: {name}"
+   ```
 
-## Subcommand: `audit`
+9. **Generate RETROSPECTIVE.md:**
 
-Verify milestone completion with cross-phase integration checks.
+   The CLI (`pbr-tools.js milestone complete`) auto-generates a RETROSPECTIVE.md entry. Verify it exists at `.planning/RETROSPECTIVE.md`. If the CLI was not used (manual completion), create the entry using `${CLAUDE_PLUGIN_ROOT}/templates/RETROSPECTIVE.md.tmpl` as the format reference. Fill in `{version}`, `{name}`, `{date}`, and the "What Was Built" section from MILESTONES.md accomplishments. Leave other sections as placeholders for the user to fill.
 
-### Flow
+9aa. **Insights integration:**
 
-1. **Determine target:**
-   - If version provided: audit that specific milestone
-   - If no version: audit the current milestone (most recent active)
+   Check for a recent /insights HTML report:
 
-2. **Read all VERIFICATION.md files** for milestone phases:
-   - Collect verification results
-   - Note any `gaps_found` statuses
-   - Note any phases without verification
+   ```bash
+   find ~/.claude/insights/ -name "*.html" -mtime -7 2>/dev/null | head -1
+   ```
 
-3. **Spawn integration checker:**
+   **If a recent report exists (modified within 7 days):**
+   1. Read the HTML file and extract key workflow findings (friction patterns, efficiency suggestions, recurring issues)
+   2. Append a "## Workflow Insights" section to `.planning/RETROSPECTIVE.md` with 3-5 bullet points summarizing the most relevant insights for this milestone's work
+   3. Add the RETROSPECTIVE.md to the git staging area
 
-   Display to the user: `◐ Spawning integration checker...`
+   **If no recent report exists:**
+   Display this suggestion after the RETROSPECTIVE.md is generated:
 
-   Spawn `Task(subagent_type: "pbr:integration-checker")` with:
+   ```
+   Tip: Run /insights to capture workflow patterns from this milestone's sessions.
+        Insights feed into future audits and help the planner avoid repeated friction.
+   ```
 
+9a. **Commit:**
+   ```bash
+   git add .planning/milestones/ .planning/phases/ .planning/ROADMAP.md .planning/PROJECT.md .planning/STATE.md .planning/RETROSPECTIVE.md
+   git commit -m "docs(planning): complete milestone {version}"
    ```
-   You are integration-checker. Perform cross-phase integration verification.
 
-   Milestone: {version or "current"}
-   Phases to check: {list of phase directories}
+**CRITICAL (no hook): Generate changelog entry NOW. Do NOT skip this step.**
 
-   Instructions:
-   1. Read all SUMMARY.md files for the milestone phases
-   2. Build a dependency graph from provides/affects/requires fields
-   3. Verify integration points:
-      a. Every "requires" in a later phase is "provided" by an earlier phase
-      b. Every "affects" target still exists and hasn't been broken
-      c. No circular dependencies
-      d. No orphaned provides (things built but never consumed)
-   4. Check for:
-      - Broken imports/references between phases
-      - API contract mismatches
-      - Missing error handling at integration points
-      - Configuration inconsistencies
-   5. Return findings as a structured report
-   ```
+9b. **Generate changelog entry:**
 
-4. **Check requirements coverage:**
-   - Read REQUIREMENTS.md
-   - For each requirement tagged for this milestone:
-     - Search VERIFICATION.md files for coverage
-     - Search SUMMARY.md `provides` fields
-     - Flag uncovered requirements
+   Generate a user-facing changelog entry for this milestone. Read all SUMMARY.md files from the milestone phases (now in `.planning/milestones/{version}/phases/`) and categorize deliverables into Keep a Changelog sections:
 
-5. **Write audit report:**
+   - **Added** — New features, commands, capabilities (from SUMMARY.md `provides` fields)
+   - **Changed** — Modifications to existing behavior, UI updates, performance improvements
+   - **Fixed** — Bug fixes, error corrections (from commits with `fix:` type)
 
-   Create `.planning/{version}-MILESTONE-AUDIT.md` using the template:
+   Format each entry with a **bolded feature name** followed by an em-dash and description:
+   ```markdown
+   ### Added
+   - **Feature name** — What it does and why it matters
+   - **Another feature** — Description focusing on user impact
+   ```
 
-   Read `skills/milestone/templates/audit-report.md.tmpl` for the audit report format. Fill in all `{variable}` placeholders with actual data from the audit.
+   Rules for good entries:
+   - Lead with the user-visible impact, not the implementation detail
+   - Group related commits into a single entry (e.g., 5 commits for "auth" become one "Authentication system" entry)
+   - Use bold feature names, not commit scopes
+   - No commit hashes — this is prose, not a git log
+   - No internal scopes (phase-plan numbers, TDD markers)
+   - End with install line: `Install/upgrade: \`npx @sienklogic/plan-build-run@latest\``
 
-6. **Report to user** using branded banners:
+   Draft the full entry and present it to the user for review:
 
-   **If PASSED:**
+   Use AskUserQuestion:
+   ```
+   question: "Here's the draft changelog for {version}. Want to edit it before writing?"
+   header: "Changelog"
+   options:
+     - label: "Looks good"        description: "Write this to CHANGELOG.md as-is"
+     - label: "Edit"              description: "I'll provide corrections"
+     - label: "Skip changelog"    description: "Don't update the changelog for this release"
+   ```
+
+   - If "Looks good": write the entry to CHANGELOG.md (insert after the header, before any existing version entries)
+   - If "Edit" or "Other": apply the user's corrections, then present again for final confirmation
+   - If "Skip changelog": proceed without changelog update
+
+   If writing to CHANGELOG.md:
+   ```bash
+   git add CHANGELOG.md
+   git commit -m "docs: update changelog for {version}"
    ```
-   ╔══════════════════════════════════════════════════════════════╗
-   ║  PLAN-BUILD-RUN ► MILESTONE AUDIT PASSED ✓                   ║
-   ╚══════════════════════════════════════════════════════════════╝
 
-   All phases verified, integration checks passed, requirements covered.
+9c. **Push milestone to remote:**
 
+Use AskUserQuestion to ask the user how they want to publish the milestone:
 
+```
+question: "How should this milestone be published to GitHub?"
+header: "Publish"
+options:
+  - label: "Push tag + commits"    description: "Push the v{version} tag and any unpushed commits to origin"
+  - label: "Skip for now"          description: "Keep everything local — push later manually"
+```
 
-   ╔══════════════════════════════════════════════════════════════╗
-║  ▶ NEXT UP                                                   ║
-╚══════════════════════════════════════════════════════════════╝
+- If "Push tag + commits": run `git push origin main --follow-tags` to push both commits and the annotated tag in one command. Display success or error.
+- If "Skip for now": display reminder: "Tag v{version} is local only. Push when ready: `git push origin main --follow-tags`"
+- If "Other": follow user instructions (e.g., create a PR, push to a different branch, etc.)
 
-   **Complete the milestone** — archive and tag
+9d. **Automatic npm release:**
 
-   `/pbr:milestone complete {version}`
+After pushing, automatically run the npm release to publish this milestone:
 
-   <sub>`/clear` first → fresh context window</sub>
+```bash
+npm run release -- --minor
+```
 
+Display the output to the user. The `--minor` flag is used because milestone completions always represent new features.
 
+- If the release succeeds: display the new version number and GitHub Release URL
+- If the release fails: show the error as an advisory warning — the milestone is already archived. Suggest the user run `npm run release` manually after fixing the issue.
 
-   **Also available:**
-   - `/pbr:milestone gaps` — address any minor issues first
-   - `/pbr:status` — see project status
+### Post-Completion Smoke Test
 
+If `config.deployment.smoke_test_command` is set and non-empty:
 
-   ```
+1. Run the command via Bash
+2. If exit code 0: display "Smoke test passed" with command output
+3. If exit code non-zero: display advisory warning:
 
-   **If GAPS FOUND:**
    ```
-   ╔══════════════════════════════════════════════════════════════╗
-   ║  PLAN-BUILD-RUN ► MILESTONE AUDIT — GAPS FOUND ⚠             ║
-   ╚══════════════════════════════════════════════════════════════╝
+   ⚠ Smoke test failed (exit code {N})
+   Command: {smoke_test_command}
+   Output: {first 20 lines of output}
+   ```
 
-   Found {count} gaps:
-   - {gap 1}
-   - {gap 2}
+   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 — read `${CLAUDE_SKILL_DIR}/templates/complete-output.md.tmpl` and fill in `{version}`, `{count}` (phases, plans, commits), `{lines}`, `{duration}`.
 
+**NEXT UP block after milestone complete:**
 
-   ╔══════════════════════════════════════════════════════════════╗
+After displaying the branded complete-output banner, always display a NEXT UP routing block:
+
+```
+╔══════════════════════════════════════════════════════════════╗
 ║  ▶ NEXT UP                                                   ║
 ╚══════════════════════════════════════════════════════════════╝
 
-   **Close the gaps** — create fix phases
+**Start the next milestone** — continue development with new phases
 
-   `/pbr:milestone gaps`
+`/pbr:milestone new`
 
-   <sub>`/clear` first → fresh context window</sub>
+**Also available:**
+- `/pbr:release` — tag and publish this milestone as a GitHub Release
+- `/pbr:status` — review project state before continuing
 
+<sub>`/clear` first → fresh context window</sub>
+```
 
+This ensures the milestone complete subcommand never ends in a routing dead end.
 
-   **Also available:**
-   - `/pbr:milestone complete` — proceed despite gaps
-   - `/pbr:status` — see project status
+---
 
+## Subcommand: `audit`
 
-   ```
+Verify milestone completion with cross-phase integration checks.
 
-   **If TECH DEBT:**
-   ```
-   ╔══════════════════════════════════════════════════════════════╗
-   ║  PLAN-BUILD-RUN ► MILESTONE AUDIT — TECH DEBT ⚠              ║
-   ╚══════════════════════════════════════════════════════════════╝
+### Flow
+
+1. **Determine target:**
+   - If version provided: audit that specific milestone
+   - If no version: audit the current milestone (use `blob.milestones` to identify the most recent active milestone)
+
+2. **Read all VERIFICATION.md files** for milestone phases (use `blob.milestones` to identify the phase range):
+   - Collect verification results
+   - Note any `gaps_found` statuses
+   - Note any phases without verification
 
-   Milestone functional but has {count} tech debt items.
+3. **Spawn integration checker:**
 
+   Display to the user: `◆ Spawning integration checker...`
 
+   Spawn `Task(subagent_type: "pbr:integration-checker")`. Read `${CLAUDE_SKILL_DIR}/templates/integration-checker-prompt.md.tmpl`, fill in `{version or "current"}`, `{list of phase directories}`, and `{phase SUMMARY.md paths}`, then use the filled template as the Task() prompt.
 
-   ╔══════════════════════════════════════════════════════════════╗
-║  ▶ NEXT UP                                                   ║
-╚══════════════════════════════════════════════════════════════╝
+4. **Check integration-checker completion:**
 
-   **Address tech debt or proceed**
+   After the integration-checker completes, check for `## INTEGRATION CHECK COMPLETE` in the Task() output. If the marker is absent, warn: `⚠ Integration checker did not return completion marker — results may be incomplete.` Proceed with whatever findings were returned but note the incomplete status in the audit report.
 
-   `/pbr:milestone gaps` — create cleanup phases
-   `/pbr:milestone complete` — proceed as-is
+5. **Check requirements coverage:**
+   - Read REQUIREMENTS.md
+   - For each requirement tagged for this milestone:
+     - Search VERIFICATION.md files for coverage
+     - Search SUMMARY.md `provides` fields
+     - Flag uncovered requirements
 
-   <sub>`/clear` first → fresh context window</sub>
+6. **Write audit report:**
 
+   Create `.planning/{version}-MILESTONE-AUDIT.md` using the structured template:
 
-   ```
+   Read `${CLAUDE_PLUGIN_ROOT}/templates/MILESTONE-AUDIT.md.tmpl` for the audit report format with YAML frontmatter scores. Fill in all `{variable}` placeholders with actual data from the audit. The YAML frontmatter MUST include `scores` (requirements, phases, integration, flows), `gaps` array, and `tech_debt` array.
+
+   **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 — read `${CLAUDE_SKILL_DIR}/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.
 
 ---
 
@@ -557,7 +790,7 @@ Create phases to close gaps found during an audit.
 1. **Find most recent audit:**
    - Search for `*-MILESTONE-AUDIT.md` in `.planning/`
    - If multiple, use the most recent
-   - If none: "No audit found. Run `/pbr:milestone audit` first."
+   - If none: "No audit found. Run `/pbr:audit-milestone` first."
 
 2. **Read audit report:**
    - Extract all gaps and tech debt items
@@ -584,6 +817,7 @@ Create phases to close gaps found during an audit.
    Nice to fix ({count}):
    - {gap}: {description}
 
+   **CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding:
    Use AskUserQuestion (pattern: multi-option-priority from `skills/shared/gate-prompts.md`):
      question: "Which gaps should we address? ({must_count} must-fix, {should_count} should-fix, {nice_count} nice-to-fix)"
      header: "Priority"
@@ -624,41 +858,13 @@ 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 `${CLAUDE_SKILL_DIR}/templates/gaps-output.md.tmpl` and fill in `{count}` (gap-closure phases created), `{N}` (first gap phase number), `{name}` (phase name).
 
 ---
 
 ## State Integration
 
-All subcommands update STATE.md:
+All subcommands use `blob.state` and `blob.config` from the init call for reading state. All subcommands update STATE.md on write:
 - `new`: Sets current milestone, resets phase
 - `complete`: Clears current milestone, updates history
 - `audit`: Notes audit status and date
@@ -670,7 +876,7 @@ All subcommands update STATE.md:
 
 Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
 
-All subcommands commit if `planning.commit_docs: true`:
+All subcommands commit if `blob.config.planning.commit_docs` is true:
 - `new`: `docs(planning): start milestone "{name}" (phases {start}-{end})`
 - `complete`: `docs(planning): complete milestone {version}`
 - `audit`: `docs(planning): audit milestone {version} - {status}`
@@ -681,60 +887,12 @@ Tags (complete only):
 
 ---
 
-## Edge Cases
-
-### No ROADMAP.md exists
-- For `new`: Create one from scratch (this is a fresh start)
-- For others, display:
-```
-╔══════════════════════════════════════════════════════════════╗
-║  ERROR                                                       ║
-╚══════════════════════════════════════════════════════════════╝
-
-No roadmap found.
-
-**To fix:** Run `/pbr:begin` or `/pbr:milestone new` first.
-```
-
-### Milestone has no phases
-Display:
-```
-╔══════════════════════════════════════════════════════════════╗
-║  ERROR                                                       ║
-╚══════════════════════════════════════════════════════════════╝
+Reference: `skills/shared/error-reporting.md` for branded error output patterns.
 
-No phases found for this milestone.
-
-**To fix:**
-- For `complete`: Nothing to complete — add phases first.
-- For `audit`: Nothing to audit — build phases first.
-```
-
-### Audit finds no gaps
-- Status: PASSED
-- Skip the recommendations section
-- Suggest proceeding to complete
-
-### Version already exists (tag collision)
-Display:
-```
-╔══════════════════════════════════════════════════════════════╗
-║  ERROR                                                       ║
-╚══════════════════════════════════════════════════════════════╝
-
-Git tag {version} already exists.
-
-**To fix:** Use a different version number (e.g., {version}.1).
-```
-Ask for alternative via AskUserQuestion.
-
-### Partially verified milestone
-- `complete` warns but allows proceeding with user confirmation
-- `audit` treats unverified phases as gaps
+## Edge Cases
 
-### Large milestone (8+ phases)
-- `audit` may take longer due to integration checking
-- Warn: "This milestone has {count} phases. The audit may take a few minutes."
+For all edge case handling, see `${CLAUDE_SKILL_DIR}/templates/edge-cases.md`.
+Key scenarios: no ROADMAP.md, no phases, no gaps found, version collision, partially verified, large milestone (8+ phases).
 
 ---