@sienklogic/plan-build-run 2.20.0 → 2.21.1

package/plugins/pbr/scripts/status-line.js

@@ -197,6 +197,23 @@ function main() {
   process.exit(0);
 }
 
+/**
+ * Parse YAML frontmatter from STATE.md content.
+ * Returns an object with frontmatter fields, or null if no frontmatter.
+ */
+function parseFrontmatter(content) {
+  if (!content.startsWith('---')) return null;
+  const endIdx = content.indexOf('---', 3);
+  if (endIdx === -1) return null;
+  const fm = content.substring(3, endIdx);
+  const result = {};
+  for (const line of fm.split(/\r?\n/)) {
+    const m = line.match(/^(\w[\w_]*):\s*"?([^"]*)"?\s*$/);
+    if (m) result[m[1]] = m[2];
+  }
+  return result;
+}
+
 function buildStatusLine(content, ctxPercent, cfg, stdinData) {
   const config = cfg || DEFAULTS;
   const sections = config.sections || DEFAULTS.sections;
@@ -205,15 +222,26 @@ function buildStatusLine(content, ctxPercent, cfg, stdinData) {
   const barCfg = config.context_bar || DEFAULTS.context_bar;
   const sd = stdinData || {};
 
+  // Prefer frontmatter (always up-to-date) over body text (may be stale)
+  const fm = parseFrontmatter(content);
+
   const parts = [];
 
   // Phase section (always includes brand text)
   if (sections.includes('phase')) {
+    const fmPhase = fm && fm.current_phase;
+    const fmTotal = fm && fm.total_phases;
+    const fmName = fm && fm.phase_name;
     const phaseMatch = content.match(/Phase:\s*(\d+)\s*of\s*(\d+)\s*(?:\(([^)]+)\))?/);
-    if (phaseMatch) {
-      parts.push(`${c.boldCyan}${brandText}${c.reset} ${c.bold}Phase ${phaseMatch[1]}/${phaseMatch[2]}${c.reset}`);
-      if (phaseMatch[3]) {
-        parts.push(`${c.magenta}${phaseMatch[3]}${c.reset}`);
+
+    const phaseNum = fmPhase || (phaseMatch && phaseMatch[1]);
+    const phaseTotal = fmTotal || (phaseMatch && phaseMatch[2]);
+    const phaseName = fmName || (phaseMatch && phaseMatch[3]);
+
+    if (phaseNum && phaseTotal) {
+      parts.push(`${c.boldCyan}${brandText}${c.reset} ${c.bold}Phase ${phaseNum}/${phaseTotal}${c.reset}`);
+      if (phaseName) {
+        parts.push(`${c.magenta}${phaseName}${c.reset}`);
       }
     } else {
       parts.push(`${c.boldCyan}${brandText}${c.reset}`);
@@ -222,10 +250,14 @@ function buildStatusLine(content, ctxPercent, cfg, stdinData) {
 
   // Plan section
   if (sections.includes('plan')) {
+    const fmComplete = fm && fm.plans_complete;
+    const fmTotal = fm && fm.plans_total;
     const planMatch = content.match(/Plan:\s*(\d+)\s*of\s*(\d+)/);
-    if (planMatch) {
-      const done = parseInt(planMatch[1], 10);
-      const total = parseInt(planMatch[2], 10);
+
+    const done = fmComplete != null ? parseInt(fmComplete, 10) : (planMatch ? parseInt(planMatch[1], 10) : null);
+    const total = fmTotal != null ? parseInt(fmTotal, 10) : (planMatch ? parseInt(planMatch[2], 10) : null);
+
+    if (done != null && total != null && total > 0) {
       const planColor = done === total ? c.green : c.white;
       parts.push(`${planColor}Plan ${done}/${total}${c.reset}`);
     }
@@ -233,9 +265,10 @@ function buildStatusLine(content, ctxPercent, cfg, stdinData) {
 
   // Status section
   if (sections.includes('status')) {
-    const statusMatch = content.match(/Status:\s*(.+)/);
-    if (statusMatch) {
-      const text = statusMatch[1].trim();
+    const fmStatus = fm && fm.status;
+    const statusMatch = content.match(/^Status:\s*(.+)/m);
+    const text = fmStatus || (statusMatch && statusMatch[1].trim());
+    if (text) {
       const short = text.length > maxLen ? text.slice(0, maxLen - 3) + '...' : text;
       parts.push(`${statusColor(text)}${short}${c.reset}`);
     }
@@ -285,4 +318,4 @@ function buildStatusLine(content, ctxPercent, cfg, stdinData) {
 }
 
 if (require.main === module || process.argv[1] === __filename) { main(); }
-module.exports = { buildStatusLine, buildContextBar, getContextPercent, getGitInfo, formatDuration, loadStatusLineConfig, DEFAULTS };
+module.exports = { buildStatusLine, buildContextBar, getContextPercent, getGitInfo, formatDuration, loadStatusLineConfig, parseFrontmatter, DEFAULTS };

package/plugins/pbr/scripts/track-context-budget.js

@@ -77,6 +77,11 @@ function main() {
           unique_files: tracker.files.length,
         });
         const prevCharsTotal = tracker.total_chars;
+        // Emit user-visible warning before resetting (was previously silent)
+        const resetWarning = {
+          additionalContext: `[Context Budget] Tracker reset: ${tracker.files.length} unique files read (~${Math.round(tracker.total_chars / 1000)}k chars). File list cleared but char total preserved. Consider delegating remaining work to a Task() subagent.`
+        };
+        process.stdout.write(JSON.stringify(resetWarning));
         tracker = { skill: currentSkill, reads: 0, total_chars: prevCharsTotal, files: [] };
       }
 

package/plugins/pbr/scripts/validate-commit.js

@@ -178,6 +178,14 @@ function isGitCommit(command) {
 }
 
 function extractCommitMessage(command) {
+  // Try heredoc first: -m "$(cat <<'EOF'\n...\nEOF\n)" or -m "$(cat <<EOF\n...\nEOF\n)"
+  // Must check before generic -m patterns to avoid capturing heredoc syntax as the message
+  const heredocMatch = command.match(/<<'?EOF'?\s*\n([\s\S]*?)\nEOF/);
+  if (heredocMatch) {
+    // First line of heredoc is the commit message
+    return heredocMatch[1].trim().split('\n')[0].trim();
+  }
+
   // Try -m "message" or -m 'message'
   const mFlagMatch = command.match(/-m\s+["']([^"']+)["']/);
   if (mFlagMatch) return mFlagMatch[1];
@@ -186,13 +194,6 @@ function extractCommitMessage(command) {
   const mFlagMatch2 = command.match(/-m\s+"([^"]+)"/);
   if (mFlagMatch2) return mFlagMatch2[1];
 
-  // Try heredoc: -m "$(cat <<'EOF'\n...\nEOF\n)"
-  const heredocMatch = command.match(/<<'?EOF'?\s*\n([\s\S]*?)\nEOF/);
-  if (heredocMatch) {
-    // First line of heredoc is the commit message
-    return heredocMatch[1].trim().split('\n')[0].trim();
-  }
-
   return null;
 }
 

package/plugins/pbr/scripts/validate-skill-args.js

@@ -101,7 +101,8 @@ function checkSkillArgs(data) {
 
   return {
     output: {
-      additionalContext: [
+      decision: 'block',
+      reason: [
         'BLOCKED: /pbr:plan received freeform text instead of a phase number.',
         '',
         'The arguments "' + args.substring(0, 80) + (args.length > 80 ? '...' : '') + '" do not match any valid pattern.',

package/plugins/pbr/scripts/validate-task.js

@@ -567,11 +567,6 @@ function checkBuildDependencyGate(data) {
   return null;
 }
 
-/**
- * Advisory check: when active skill is "build" and an executor is being
- * spawned, warn if .checkpoint-manifest.json is missing in the phase dir.
- * Returns a warning string or null.
- */
 /**
  * Parse VERIFICATION.md frontmatter to extract status field.
  * Returns the status string or 'unknown' if not parseable.

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

@@ -720,11 +720,10 @@ These return `{ success, old_status, new_status }` or `{ success, old_plans, new
 
 **CRITICAL: Update STATE.md NOW with phase completion status. Do NOT skip this step.**
 
-**8b. Update STATE.md:**
-- Phase status: {final_status from Step 8-pre}
-- Plan completion count
-- Last activity timestamp
-- Progress bar
+**8b. Update STATE.md (CRITICAL — update BOTH frontmatter AND body):**
+- Frontmatter: `status`, `plans_complete`, `last_activity`, `progress_percent`, `last_command`
+- Body `## Current Position`: `Phase:` line, `Plan:` line, `Status:` line, `Last activity:` line, `Progress:` bar
+- These MUST stay in sync — the status line reads frontmatter, humans read the body
 
 **8c. Commit planning docs (if configured):**
 Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.

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

@@ -82,7 +82,7 @@ Read the following files to understand what this phase needs to accomplish:
    - What patterns have been established (`patterns` field)
    - What decisions were already made (`key_decisions` field)
 
-3. **REQUIREMENTS.md** (if exists) — Read project requirements relevant to this phase
+3. **REQUIREMENTS.md** (if exists) — Read project requirements relevant to this phase. **CRITICAL**: After reading, display to the user which specific requirements map to this phase. Flag any requirements that could constrain decisions. If the user's discussion decisions later contradict a stated requirement, surface the contradiction immediately — don't wait until planning.
 
 4. **CONTEXT.md** (if exists in the phase directory) — Check if a prior discussion already happened
    - If CONTEXT.md exists, inform the user and use the **context-handling** pattern from `skills/shared/gate-prompts.md`:

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

@@ -209,8 +209,6 @@ This ensures the user can recover the original STATE.md if the fix produces inco
 
 4. If "Skip": Do nothing, continue to the rest of the output.
 
-**Note:** When auto-fix is active, the health skill is no longer strictly read-only. The `allowed-tools` frontmatter must include `Write` and `AskUserQuestion` for auto-fix to work. Update the frontmatter accordingly.
-
 ---
 
 ## Bonus: Recent Decisions

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

@@ -94,6 +94,7 @@ Display the following reference to the user:
 |---------|-------------|
 | `/pbr:milestone new` | Start a new milestone cycle. |
 | `/pbr:milestone complete` | Archive completed milestone. |
+| `/pbr:milestone preview` | Dry-run of complete — show what would happen. |
 | `/pbr:milestone audit` | Verify milestone completion. |
 | `/pbr:milestone gaps` | Create phases to close audit gaps. |
 | `/pbr:todo add\|list\|done` | Persistent file-based todos. |
@@ -153,6 +154,27 @@ Plan-Build-Run includes three behavioral contexts in `contexts/` that adjust how
 
 Skills automatically activate the appropriate context: `/pbr:build` uses dev context, `/pbr:discuss` uses research context, `/pbr:review` uses review context.
 
+## When to Use Quick vs Plan+Build
+
+| Use `/pbr:quick` when... | Use `/pbr:plan` + `/pbr:build` when... |
+|--------------------------|----------------------------------------|
+| Change touches ≤3 files | Change touches 4+ files |
+| ≤100 lines of code | 100+ lines of code |
+| Single subsystem | Multiple subsystems or cross-cutting |
+| No architectural decisions | Requires design choices |
+| Bug fix, small feature, docs | New feature, refactor, migration |
+
+## Setup vs Begin
+
+- **`/pbr:begin`** — Use this to start a new project. It handles everything: questioning, research, requirements, roadmap, AND config initialization. This is the standard entry point.
+- **`/pbr:setup`** — Use this only to reconfigure an existing project's settings (model profiles, gates, depth, parallelization) without re-running the full begin flow.
+
+If you're unsure, start with `/pbr:begin`. It will detect existing config and offer to reuse or overwrite.
+
+## Team Discussions
+
+The `features.team_discussions` config flag (and `/pbr:build --team`) enables **Agent Teams** for complex builds. When enabled, executor agents can coordinate with each other during parallel wave execution — sharing context about what they've built, resolving interface conflicts, and avoiding duplicate work. Best for phases where multiple plans have shared dependencies. Configure via `/pbr:config`.
+
 ## Getting Started
 
 ```

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

@@ -57,6 +57,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,6 +70,7 @@ 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
 ```
@@ -194,6 +196,65 @@ Start a new milestone cycle with new phases.
 
 ---
 
+## Subcommand: `preview`
+
+Dry-run of milestone completion — shows what would happen without making any changes.
+
+### Flow
+
+1. **Determine version:**
+   - Same logic as `complete`: use `$ARGUMENTS` or ask via AskUserQuestion
+
+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)
+
+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
+         └── ...
+     ```
+
+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:**
+   ```
+   ╔══════════════════════════════════════════════════════════════╗
+   ║  MILESTONE PREVIEW — v{version}                              ║
+   ╚══════════════════════════════════════════════════════════════╝
+
+   Phases to archive: {count}
+   ✓ Verified: {verified_count}
+   ⚠ Unverified: {unverified_count}
+   ⚠ Stale verification: {stale_count}
+
+   Archive location: .planning/milestones/v{version}/
+   Git tag: v{version}
+
+   Ready to complete? Run: /pbr:milestone complete v{version}
+   ```
+
+**CRITICAL**: 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.
+
+---
+
 ## Subcommand: `complete`
 
 Archive a completed milestone and prepare for the next one.

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

@@ -492,7 +492,7 @@ Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prom
   4. Update the `Plans Complete` column to `0/{N}` where N = number of plan files just created
   5. Update the `Status` column to `planned`
   6. Save the file — do NOT skip this step
-- Update STATE.md: set current phase plan status to "planned"
+- Update STATE.md **(CRITICAL — update BOTH frontmatter AND body)**: set `status: "planned"`, `plans_total`, `last_command` in frontmatter AND update `Status:`, `Plan:` lines in body `## Current Position`
 - **If `features.auto_advance` is `true` AND `mode` is `autonomous`:** Chain directly to build: `Skill({ skill: "pbr:build", args: "{N}" })`. This continues the build→review→plan→build cycle automatically.
 - **Otherwise:** Suggest next action: `/pbr:build {N}`
 

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

@@ -331,10 +331,10 @@ If all automated checks and UAT items passed:
    4. Update the `Status` column to `verified`
    5. Update the `Completed` column to the current date (YYYY-MM-DD)
    6. Save the file — do NOT skip this step
-2. Update `.planning/STATE.md`:
-   - Phase status: "verified"
-   - Progress updated
-   - Last activity timestamp
+2. Update `.planning/STATE.md` **(CRITICAL — update BOTH frontmatter AND body):**
+   - Frontmatter: `status: "verified"`, `progress_percent`, `last_activity`, `last_command`
+   - Body `## Current Position`: `Status:` line, `Last activity:` line, `Progress:` bar
+   - These MUST stay in sync — see `skills/shared/state-update.md`
    - **STATE.md size limit:** Follow size limit enforcement rules in `skills/shared/state-update.md` (150 lines max).
 3. Update VERIFICATION.md with UAT results (append UAT section)
 3. Present completion:

package/plugins/pbr/skills/shared/error-recovery-strategies.md

@@ -0,0 +1,51 @@
+# Error Recovery Strategies Fragment
+
+Standard recovery patterns for skills and agents when operations fail. Reference `error-reporting.md` for display formats.
+
+## Strategy 1: Retry with Backoff
+
+For transient failures (file locks, network timeouts, tool failures):
+
+1. Wait briefly, then retry the same operation (max 2 retries)
+2. If still failing after retries, fall through to Strategy 2
+
+Use for: git operations, file writes blocked by antivirus, API calls.
+
+## Strategy 2: Degrade Gracefully
+
+When a non-critical step fails, skip it and continue:
+
+1. Log a warning using the recoverable error format
+2. Note the skipped step in SUMMARY.md `deferred` field
+3. Continue with remaining work
+
+Use for: optional validations, dashboard launch, hook logger writes, note/todo updates.
+
+## Strategy 3: Escalate to User
+
+When a critical step fails and no automated fix exists:
+
+1. Display the fatal error format with actionable suggestions
+2. Do NOT attempt workarounds that could corrupt state
+3. Suggest `/pbr:health` as the first diagnostic step
+4. If in an agent context, return the error in the agent's output so the orchestrator can relay it
+
+Use for: STATE.md corruption, missing phase directories, config parse failures, git conflicts.
+
+## Strategy 4: Checkpoint and Abort
+
+When a multi-step operation partially fails:
+
+1. Commit any completed work (don't lose progress)
+2. Update STATE.md with accurate status (not the target status)
+3. Write a `.continue-here.md` breadcrumb if mid-phase
+4. Report what completed and what remains
+
+Use for: build phase with mixed plan results, verification with partial failures.
+
+## Anti-Patterns
+
+- **Never silently swallow errors** in catch blocks — at minimum call `logHook()` with the error message
+- **Never retry destructive operations** (deletes, force-pushes, state resets)
+- **Never auto-fix by deleting user artifacts** — only delete PBR internal state files (.active-skill, .context-tracker, .auto-next)
+- **Never continue building after STATE.md write failure** — state integrity is non-negotiable

package/plugins/pbr/skills/shared/state-update.md

@@ -4,12 +4,17 @@ Standard pattern for updating `.planning/STATE.md`. Include this fragment in ski
 
 ---
 
+**CRITICAL: STATE.md has TWO representations — YAML frontmatter AND markdown body. You MUST update BOTH when changing state. The status line reads frontmatter; humans and hooks read the body. If you only update frontmatter, the body goes stale and the status line shows wrong data. Do NOT skip body updates under any circumstances.**
+
+---
+
 ## When to Update STATE.md
 
 | Event | What to Update |
 |-------|---------------|
-| Phase status changes (planned, building, verified) | Current Position section |
-| Plan completes or fails | Plan counter, status, last activity |
+| Phase status changes (planned, building, verified) | Frontmatter fields AND Current Position section |
+| Plan completes or fails | Frontmatter fields AND Plan counter, status, last activity |
+| Phase advances to next phase | Frontmatter fields AND Phase line, Status, Last activity, Progress bar |
 | New decision made | Accumulated Context > Decisions |
 | Blocker discovered or resolved | Accumulated Context > Blockers/Concerns |
 | Session starts or ends | Session Continuity section |
@@ -31,6 +36,9 @@ See: .planning/PROJECT.md (updated {date})
 Update `Current focus` when phase changes.
 
 ### 2. Current Position (lines 9-14)
+
+**CRITICAL: This section MUST match the frontmatter fields above it. When you update `current_phase` or `status` in frontmatter, you MUST also update the corresponding lines below. A hook will auto-fix drift, but do not rely on it.**
+
 ```
 ## Current Position
 Phase: {N} of {total} ({Phase name})

package/plugins/pbr/templates/ROADMAP.md.tmpl

@@ -28,6 +28,8 @@ Phase 01 ──→ Phase 02 ──→ Phase 04
 **Goal:** {overall project goal from requirements}
 **Phases:** 1 - {n}
 
+## Phase Details
+
 ### Phase 01: Project Setup
 
 **Goal**: {goal statement}