@sienklogic/plan-build-run 2.21.0 → 2.21.1

package/plugins/cursor-pbr/agents/researcher.md

@@ -51,6 +51,8 @@ All claims must be attributed to a source level. Higher levels override lower le
 
 **Attribution rules**: Every factual claim needs a source tag (`[S1]`, `[S2]`, etc.). Version-sensitive information (API signatures, config syntax) MUST come from S1-S3. When citing S2, note the version: `[S2-v14.2]`. Contradictions resolve in favor of higher source level.
 
+**Offline Fallback**: If web tools are unavailable (air-gapped environment, MCP not configured), rely on local sources: codebase analysis via Glob/Grep, existing documentation, and README files. Assign these S3-S4 confidence levels. Do not attempt WebFetch or WebSearch — note in the output header that external sources were unavailable.
+
 ---
 
 ## Confidence Levels
@@ -100,15 +102,15 @@ Before writing output, verify: every claim has source attribution, every recomme
 ## Output Formats
 
 ### Project Research
-Read `${CLAUDE_PLUGIN_ROOT}/templates/research-outputs/project-research.md.tmpl` for format.
+Read `${PLUGIN_ROOT}/templates/research-outputs/project-research.md.tmpl` for format.
 Key sections: User Constraints, Executive Summary, Standard Stack, Architecture Patterns, Common Pitfalls, Code Examples, Integration Points, Coverage Assessment, Open Questions, Sources.
 
 ### Phase Research
-Read `${CLAUDE_PLUGIN_ROOT}/templates/research-outputs/phase-research.md.tmpl` for format.
+Read `${PLUGIN_ROOT}/templates/research-outputs/phase-research.md.tmpl` for format.
 Key sections: User Constraints, Phase Goal, Implementation Approach, Dependencies, Pitfalls, Testing Strategy, Coverage Assessment, Sources.
 
 ### Synthesis
-Read `${CLAUDE_PLUGIN_ROOT}/templates/research-outputs/synthesis.md.tmpl` for format.
+Read `${PLUGIN_ROOT}/templates/research-outputs/synthesis.md.tmpl` for format.
 Key sections: Executive Summary, Key Findings, Contradictions Resolved, Recommended Approach, Risks and Mitigations, Sources.
 
 ### Fallback Format (if templates unreadable)

package/plugins/cursor-pbr/agents/synthesizer.md

@@ -53,7 +53,7 @@ Output to `.planning/research/SUMMARY.md` (or specified path).
 
 ## Output Format
 
-Read `${CLAUDE_PLUGIN_ROOT}/templates/RESEARCH-SUMMARY.md.tmpl` for the complete output format.
+Read `${PLUGIN_ROOT}/templates/RESEARCH-SUMMARY.md.tmpl` for the complete output format.
 
 Key sections: Executive Summary (3-5 sentences), Recommended Stack (table), Architecture Recommendations, Key Patterns, Pitfalls & Warnings, Contradictions Resolved, Open Questions, Sources.
 

package/plugins/cursor-pbr/agents/verifier.md

@@ -47,8 +47,8 @@ Look for an existing `VERIFICATION.md` in the phase directory.
 
 Use `pbr-tools.js` CLI to efficiently load phase data (saves ~500-800 tokens vs. manual parsing):
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js must-haves {phase_number}
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js phase-info {phase_number}
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js must-haves {phase_number}
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js phase-info {phase_number}
 ```
 
 Stop and report error if pbr-tools CLI is unavailable. Also read CONTEXT.md for locked decisions and deferred ideas, and ROADMAP.md for the phase goal and dependencies.
@@ -215,7 +215,7 @@ Read `references/stub-patterns.md` for stub detection patterns by technology. Re
 
 ### Verifier-Specific Anti-Patterns
 1. DO NOT trust SUMMARY.md claims without verifying the actual codebase
-2. DO NOT attempt to fix issues — you have no Write/Edit tools and that is intentional
+2. DO NOT attempt to fix issues — you have no Edit tool and that is intentional; Write access is only for VERIFICATION.md output
 3. DO NOT mark stubs as SUBSTANTIVE — if it has a TODO, it's a stub
 4. DO NOT mark orphaned code as WIRED — if nothing imports it, it's orphaned
 5. DO NOT skip Level 2 or Level 3 checks — existence alone is insufficient

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

@@ -86,7 +86,7 @@ find ~/.claude/projects/{encoded-path}/ -name "*.jsonl" -maxdepth 1 \
 
 For each session file found, also check for subagent logs:
 ```bash
-ls ~/.claude/projects/{encoded-path}/{session-id}/subagents/*.jsonl 2>/dev/null
+ls ~/.claude/projects/{encoded-path}/{session-id}/agents/*.jsonl 2>/dev/null
 ```
 
 Display discovery results:

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

@@ -719,11 +719,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/cursor-pbr/skills/config/SKILL.md

@@ -133,7 +133,7 @@ After setting depth, the profile is automatically resolved. Show the user the ef
   "Depth set to {value}. Effective profile:"
   Then display the profile summary (research, plan-check, verify, scan mappers, debug rounds, inline verify).
 
-To resolve the profile, run: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth`
+To resolve the profile, run: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth`
 
 If the user wants to override a specific profile setting, they can set `depth_profiles.{depth}.{key}` directly.
 For example: to use quick mode but keep plan-checking, the user would set depth to quick and then override:

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

@@ -55,7 +55,7 @@ This handles the case where neither `.planning/` nor `.planning/debug/` exist ye
 
 ### Step 2: Check for Active Debug Sessions
 
-**Load depth profile:** Run `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth` to get `debug.max_hypothesis_rounds`. If the command fails (no config.json or CLI error), default to 5 rounds. Initialize a round counter at 0. This counter increments each time a continuation debugger is spawned.
+**Load depth profile:** Run `node ${PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth` to get `debug.max_hypothesis_rounds`. If the command fails (no config.json or CLI error), default to 5 rounds. Initialize a round counter at 0. This counter increments each time a continuation debugger is spawned.
 
 Scan `.planning/debug/` for existing debug files:
 

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

@@ -360,7 +360,7 @@ If the import process surfaced new locked decisions (from blocker resolutions in
 **8e. Emit workflow event (conditional):**
 If the event-logger script is available:
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js event workflow plan-import --phase {N} --plans {count} --source {filepath_or_user_input}
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js event workflow plan-import --phase {N} --plans {count} --source {filepath_or_user_input}
 ```
 Falls back silently if the command is not available.
 

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

@@ -463,7 +463,7 @@ Use the approve-revise-abort pattern from `skills/shared/gate-prompts.md`:
   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. This continues the build->review->plan->build cycle automatically.
 - **Otherwise:** Suggest next action: `/pbr:build {N}`
 

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

@@ -312,10 +312,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/cursor-pbr/skills/scan/SKILL.md

@@ -28,9 +28,9 @@ This skill **spawns 4 parallel Task(subagent_type: "pbr:codebase-mapper")** agen
 Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
 
 Additionally for this skill:
-- **Never** analyze the codebase yourself — delegate ALL analysis to the 4 parallel codebase-mapper subagents
+- **Never** analyze the codebase yourself — delegate ALL analysis to the 4 parallel codebase-mapper agents
 - **Minimize** reading mapper outputs — read only frontmatter or first 20 lines of each output document
-- **Delegate** all file reading, pattern analysis, and architecture mapping to the codebase-mapper subagents
+- **Delegate** all file reading, pattern analysis, and architecture mapping to the codebase-mapper agents
 
 ---
 
@@ -50,7 +50,7 @@ Check if `.planning/codebase/` directory exists:
 
 First, resolve the depth profile so you know which areas are available:
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
 ```
 Read `profile["scan.mapper_areas"]` to determine available areas (quick: tech, arch; standard/comprehensive: tech, arch, quality, concerns).
 
@@ -93,7 +93,7 @@ Refer to the "Reconnaissance Detection Reference" section of `skills/scan/templa
 
 **Resolve mapper configuration:** Before spawning, resolve the depth profile:
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
 ```
 
 Read `profile["scan.mapper_count"]` and `profile["scan.mapper_areas"]` to determine how many mappers to spawn and which focus areas to cover.

package/plugins/cursor-pbr/skills/shared/config-loading.md

@@ -11,7 +11,7 @@ Standard pattern for loading `.planning/config.json` fields at the start of a sk
 
 Instead of reading and parsing STATE.md, ROADMAP.md, and config.json manually, run:
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js state load
 ```
 This returns a JSON object with `config`, `state`, `roadmap`, `current_phase`, and `progress`. Falls back gracefully if the script is missing -- parse files manually in that case.
 

package/plugins/cursor-pbr/skills/shared/context-budget.md

@@ -1,7 +1,7 @@
 <!-- canonical: ../../../pbr/skills/shared/context-budget.md -->
 # Context Budget Rules
 
-Standard rules for keeping orchestrator context lean. Reference this fragment in skills that spawn Task() subagents.
+Standard rules for keeping orchestrator context lean. Reference this fragment in skills that spawn Task() agents.
 
 See also: `skills/shared/universal-anti-patterns.md` for the complete set of universal rules (context budget + file reading + behavioral rules).
 
@@ -14,7 +14,7 @@ Every skill that spawns agents or reads significant content must follow these ru
 1. **Never** read agent definition files (`agents/*.md`) — `subagent_type` auto-loads them
 2. **Never** inline large files into Task() prompts — tell agents to read files from disk instead
 3. **Minimize** reading subagent output into main context — read only frontmatter, not full content
-4. **Delegate** heavy work to subagents — the orchestrator routes, it doesn't execute
+4. **Delegate** heavy work to agents — the orchestrator routes, it doesn't execute
 5. **Before spawning agents**: If you've already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider running `/pbr:pause` to checkpoint progress." Suggest pause proactively rather than waiting for compaction.
 
 ## Customization
@@ -24,7 +24,7 @@ Skills should add skill-specific rules below the reference line. Common skill-sp
 - **build**: "Minimize reading executor output — read only SUMMARY.md frontmatter, not full content"
 - **plan**: "Minimize reading subagent output — read only plan frontmatter for summaries"
 - **review**: "Minimize reading subagent output — read only VERIFICATION.md frontmatter for summaries"
-- **scan**: "Delegate ALL analysis to the 4 parallel codebase-mapper subagents"
+- **scan**: "Delegate ALL analysis to the 4 parallel codebase-mapper agents"
 - **quick**: "Never implement the task yourself — ALL code changes go through a spawned executor"
 - **debug**: "Never perform investigation work yourself — delegate ALL analysis to the debugger subagent"
 

package/plugins/cursor-pbr/skills/shared/state-loading.md

@@ -42,7 +42,7 @@ Reading order (always this sequence):
    - Do NOT read HISTORY.md for normal build/plan/review operations
    - Read ONLY when: debugging a regression that may trace to a prior phase,
      or when a milestone audit needs historical context
-   - Use: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history load`
+   - Use: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js history load`
    - This returns structured JSON -- do not read the raw file
 ```
 

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

@@ -5,12 +5,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 |
@@ -32,6 +37,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})
@@ -113,8 +121,8 @@ When a milestone completes or a phase is verified, archive historical context to
 
 Use `pbr-tools.js history append`:
 ```
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history append phase "Phase 3 (Auth)" "Verified 2026-02-10. Key decisions: JWT + httpOnly cookies, Discord OAuth."
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history append milestone "v1.0 User Auth" "Phases 1-4. All verified. Core auth flow complete."
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js history append phase "Phase 3 (Auth)" "Verified 2026-02-10. Key decisions: JWT + httpOnly cookies, Discord OAuth."
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js history append milestone "v1.0 User Auth" "Phases 1-4. All verified. Core auth flow complete."
 ```
 
 ### After Archiving

package/plugins/cursor-pbr/skills/shared/universal-anti-patterns.md

@@ -14,7 +14,7 @@ These rules prevent context rot -- quality degradation as the context window fil
 1. **Never** read agent definition files (`agents/*.md`) -- `subagent_type` auto-loads them. Reading agent definitions into the orchestrator wastes main context for content that is automatically injected into subagent sessions.
 2. **Never** inline large files into Task() prompts -- tell agents to read files from disk instead. Agents have their own 200k token context windows.
 3. **Minimize** reading subagent output into main context -- read only frontmatter, status fields, or summaries. Never read full SUMMARY.md, VERIFICATION.md, or RESEARCH.md bodies into the orchestrator unless specifically needed for inline presentation.
-4. **Delegate** heavy work to Task() subagents -- the orchestrator routes, it does not build, analyze, research, investigate, or verify.
+4. **Delegate** heavy work to Task() agents -- the orchestrator routes, it does not build, analyze, research, investigate, or verify.
 5. **Proactive pause warning**: If you have already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider running `/pbr:pause` to checkpoint progress." Suggest pause proactively rather than waiting for compaction.
 
 ## File Reading Rules (apply to every skill)

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

@@ -22,6 +22,13 @@ Phase 01 ──→ Phase 02 ──→ Phase 04
                        └──→ Phase 04
 ```
 
+---
+
+## Milestone: {project name} v1.0
+
+**Goal:** {overall project goal from requirements}
+**Phases:** 1 - {n}
+
 ## Phase Details
 
 ### Phase 01: Project Setup

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

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.21.0",
+  "version": "2.21.1",
   "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/agents/codebase-mapper.md

@@ -27,7 +27,7 @@ You are **codebase-mapper**, the codebase analysis agent for the Plan-Build-Run
 
 ### Forbidden Files
 
-When exploring, NEVER commit or recommend committing:
+When exploring, NEVER write to or include in your output:
 - `.env` files (except `.env.example` or `.env.template`)
 - `*.key`, `*.pem`, `*.pfx`, `*.p12` — private keys and certificates
 - Files containing `credential` or `secret` in their name

package/plugins/pbr/agents/debugger.md

@@ -14,6 +14,8 @@ tools:
 
 # Plan-Build-Run Debugger
 
+> **Memory note:** Project memory is enabled to provide debugging continuity across investigation sessions.
+
 You are **debugger**, the systematic debugging agent. Investigate bugs using the scientific method: hypothesize, test, collect evidence, narrow the search space.
 
 ## Output Budget

package/plugins/pbr/agents/executor.md

@@ -14,6 +14,8 @@ tools:
 
 # Plan-Build-Run Executor
 
+> **Memory note:** Project memory is enabled to provide build history context for deviation awareness.
+
 You are **executor**, the code execution agent for Plan-Build-Run. You receive verified plans and execute them task-by-task, producing working code with atomic commits, deviation handling, and self-verification.
 
 **You are a builder, not a designer.** Plans tell you WHAT to build. You figure out HOW at the code level. You do NOT redesign, skip, reorder, or add scope.
@@ -181,7 +183,7 @@ must_haves:
 ### Completeness Checklist
 
 Before deleting `.PROGRESS-{plan_id}`, verify SUMMARY.md has:
-- [ ] YAML frontmatter with `plan_id`, `status`, `tasks_completed`, `tasks_total`
+- [ ] YAML frontmatter with `plan`, `status`, `tasks_completed`, `tasks_total`
 - [ ] Deviations section (use "None" if empty)
 - [ ] Files Changed listing at least one file
 - [ ] At least one commit hash reference

package/plugins/pbr/agents/general.md

@@ -18,7 +18,8 @@ You are **general**, a lightweight utility agent for the Plan-Build-Run developm
 
 ## When You're Used
 
-- `/pbr:quick` ad-hoc task delegation
+This agent is available for ad-hoc `Task()` calls from skills or custom orchestration. It is not currently spawned by any built-in PBR skill automatically — it must be invoked explicitly.
+
 - Simple file generation or formatting tasks
 - Tasks that need Plan-Build-Run context but not specialized methodology
 - Fallback when a specialized agent would be overkill

package/plugins/pbr/agents/integration-checker.md

@@ -41,6 +41,8 @@ You MUST perform all applicable categories (skip only if zero items exist for th
 4. **E2E Flow Completeness** — Critical user workflows must trace from UI through API to data layer and back without breaks.
 5. **Cross-Phase Dependency Satisfaction** — Phase N's declared dependencies on Phase M must be actually satisfied in code.
 
+> **First-phase edge case**: If no completed phases exist yet, focus on verifying the current phase's internal consistency — exports match imports within the phase, API contracts are self-consistent. Cross-phase checks are not applicable and should be skipped.
+
 ### Agent Contract Compliance
 
 Read `references/agent-contracts.md` to validate agent-to-agent handoffs. Verify that each agent's actual output matches its declared contract schema — especially `provides`/`consumes` fields in SUMMARY.md and status enums in VERIFICATION.md.

package/plugins/pbr/agents/plan-checker.md

@@ -3,7 +3,6 @@ name: plan-checker
 description: "Verifies plans will achieve phase goals before execution. Goal-backward analysis of plan quality across 10 dimensions."
 model: sonnet
 memory: none
-isolation: worktree
 tools:
   - Read
   - Bash

package/plugins/pbr/agents/planner.md

@@ -9,11 +9,12 @@ tools:
   - Bash
   - Glob
   - Grep
-  - WebFetch
 ---
 
 # Plan-Build-Run Planner
 
+> **Memory note:** Project memory is enabled to provide planning continuity and awareness of prior phase decisions.
+
 You are **planner**, the planning agent for the Plan-Build-Run development system. You transform research, phase goals, and user requirements into executable plans that the executor agent can follow mechanically.
 
 ## Core Principle: Context Fidelity

package/plugins/pbr/agents/researcher.md

@@ -60,6 +60,8 @@ All claims must be attributed to a source level. Higher levels override lower le
 
 **Attribution rules**: Every factual claim needs a source tag (`[S1]`, `[S2]`, etc.). Version-sensitive information (API signatures, config syntax) MUST come from S1-S3. When citing S2, note the version: `[S2-v14.2]`. Contradictions resolve in favor of higher source level.
 
+**Offline Fallback**: If web tools are unavailable (air-gapped environment, MCP not configured), rely on local sources: codebase analysis via Glob/Grep, existing documentation, and README files. Assign these S3-S4 confidence levels. Do not attempt WebFetch or WebSearch — note in the output header that external sources were unavailable.
+
 ---
 
 ## Confidence Levels

package/plugins/pbr/agents/synthesizer.md

@@ -6,7 +6,6 @@ memory: none
 tools:
   - Read
   - Write
-  - Bash
 ---
 
 # Plan-Build-Run Synthesizer

package/plugins/pbr/agents/verifier.md

@@ -222,7 +222,7 @@ Read `references/stub-patterns.md` for stub detection patterns by technology. Re
 
 ### Verifier-Specific Anti-Patterns
 1. DO NOT trust SUMMARY.md claims without verifying the actual codebase
-2. DO NOT attempt to fix issues — you have no Write/Edit tools and that is intentional
+2. DO NOT attempt to fix issues — you have no Edit tool and that is intentional; Write access is only for VERIFICATION.md output
 3. DO NOT mark stubs as SUBSTANTIVE — if it has a TODO, it's a stub
 4. DO NOT mark orphaned code as WIRED — if nothing imports it, it's orphaned
 5. DO NOT skip Level 2 or Level 3 checks — existence alone is insufficient

package/plugins/pbr/commands/do.md

@@ -0,0 +1,5 @@
+---
+description: "Route freeform text to the right PBR skill automatically."
+---
+
+This command is provided by the `pbr:do` skill.

package/plugins/pbr/scripts/check-phase-boundary.js

@@ -102,10 +102,7 @@ function main() {
         process.exit(2);
       } else {
         const output = {
-          hookSpecificOutput: {
-            hookEventName: 'PreToolUse',
-            additionalContext: `Warning: editing phase ${filePhase} file but current phase is ${currentPhase}. Ensure this cross-phase edit is intentional.`
-          }
+          additionalContext: `Warning: editing phase ${filePhase} file but current phase is ${currentPhase}. Ensure this cross-phase edit is intentional.`
         };
         process.stdout.write(JSON.stringify(output));
       }
@@ -184,10 +181,7 @@ function checkBoundary(data) {
   return {
     exitCode: 0,
     output: {
-      hookSpecificOutput: {
-        hookEventName: 'PreToolUse',
-        additionalContext: `Warning: editing phase ${filePhase} file but current phase is ${currentPhase}. Ensure this cross-phase edit is intentional.`
-      }
+      additionalContext: `Warning: editing phase ${filePhase} file but current phase is ${currentPhase}. Ensure this cross-phase edit is intentional.`
     }
   };
 }

package/plugins/pbr/scripts/check-plan-format.js

@@ -24,6 +24,7 @@ const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
 const { logEvent } = require('./event-logger');
+const { atomicWrite } = require('./pbr-tools');
 
 function main() {
   let input = '';
@@ -334,9 +335,19 @@ function checkStateWrite(data) {
   if (basename !== 'STATE.md') return null;
   if (!fs.existsSync(filePath)) return null;
 
-  const content = fs.readFileSync(filePath, 'utf8');
+  let content = fs.readFileSync(filePath, 'utf8');
   const result = validateState(content, filePath);
 
+  // Auto-fix frontmatter/body drift: if frontmatter current_phase differs from
+  // the body's "Phase: X of Y" line, rewrite the body to match frontmatter.
+  // This prevents stale status line display when the LLM updates frontmatter
+  // but skips the body under cognitive load.
+  const bodyFixed = syncStateBody(content, filePath);
+  if (bodyFixed) {
+    content = bodyFixed.content;
+    result.warnings.push(bodyFixed.message);
+  }
+
   if (result.warnings.length > 0) {
     logHook('check-plan-format', 'PostToolUse', 'warn', { file: basename, warnings: result.warnings });
     logEvent('workflow', 'state-validated', { file: basename, status: 'warn', warningCount: result.warnings.length });
@@ -348,5 +359,70 @@ function checkStateWrite(data) {
   return null;
 }
 
-module.exports = { validatePlan, validateSummary, validateVerification, validateState, checkPlanWrite, checkStateWrite };
+/**
+ * Detect and fix frontmatter/body drift in STATE.md.
+ * When frontmatter current_phase doesn't match the body's "Phase: X of Y",
+ * rewrite the body line and persist.
+ *
+ * @param {string} content - Full STATE.md content
+ * @param {string} filePath - Absolute path to STATE.md
+ * @returns {null|{content: string, message: string}} null if in sync, otherwise the fixed content + message
+ */
+function syncStateBody(content, filePath) {
+  if (!content.startsWith('---')) return null;
+  const fmEnd = content.indexOf('---', 3);
+  if (fmEnd === -1) return null;
+
+  const fm = content.substring(3, fmEnd);
+  const phaseMatch = fm.match(/^current_phase:\s*(\d+)/m);
+  const totalMatch = fm.match(/^total_phases:\s*(\d+)/m);
+  const slugMatch = fm.match(/^phase_name:\s*"?([^"\r\n]+)"?/m);
+  const statusMatch = fm.match(/^status:\s*"?([^"\r\n]+)"?/m);
+
+  if (!phaseMatch) return null;
+
+  const fmPhase = phaseMatch[1];
+  const fmTotal = totalMatch ? totalMatch[1] : null;
+  const fmName = slugMatch ? slugMatch[1] : null;
+  const fmStatus = statusMatch ? statusMatch[1] : null;
+
+  const bodyPhaseMatch = content.match(/^Phase:\s*(\d+)\s*of\s*(\d+)/m);
+  const bodyStatusMatch = content.match(/^Status:\s*(.+)/m);
+
+  let needsFix = false;
+  let updated = content;
+
+  // Fix phase line drift
+  if (bodyPhaseMatch && bodyPhaseMatch[1] !== fmPhase) {
+    const newPhaseLine = fmTotal
+      ? (fmName ? `Phase: ${fmPhase} of ${fmTotal} (${fmName})` : `Phase: ${fmPhase} of ${fmTotal}`)
+      : `Phase: ${fmPhase} of ${bodyPhaseMatch[2]}`;
+    updated = updated.replace(/^Phase:\s*\d+\s*of\s*\d+.*/m, newPhaseLine);
+    needsFix = true;
+  }
+
+  // Fix status line drift (only when phase also drifted — status text is often richer in body)
+  if (needsFix && bodyStatusMatch && fmStatus) {
+    // Capitalize frontmatter status for display
+    const displayStatus = fmStatus.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+    updated = updated.replace(/^Status:\s*.+/m, `Status: ${displayStatus}`);
+  }
+
+  if (!needsFix) return null;
+
+  try {
+    atomicWrite(filePath, updated);
+    logHook('check-plan-format', 'PostToolUse', 'body-sync', {
+      fromPhase: bodyPhaseMatch[1], toPhase: fmPhase
+    });
+    return {
+      content: updated,
+      message: `Auto-fixed body drift: Phase ${bodyPhaseMatch[1]} → ${fmPhase} (body now matches frontmatter)`
+    };
+  } catch (_e) {
+    return null;
+  }
+}
+
+module.exports = { validatePlan, validateSummary, validateVerification, validateState, checkPlanWrite, checkStateWrite, syncStateBody };
 if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/check-skill-workflow.js

@@ -231,18 +231,10 @@ function checkBuildRules(filePath, isInPlanning, planningDir) {
 
 /**
  * /pbr:statusline rules:
- * - Warn when writing settings.json with hardcoded home directory paths
+ * Content check requires full hook data — handled by checkStatuslineContent() in main()
  */
-function checkStatuslineRules(filePath, _isInPlanning, _planningDir) {
-  const normalizedPath = filePath.replace(/\\/g, '/');
-
-  // Only check settings.json writes
-  if (!normalizedPath.endsWith('settings.json')) return null;
-
-  // Check tool_input content isn't available here — we only have filePath.
-  // The hardcoded path check needs content, which we get from the hook data.
-  // This function is called from checkSkillRules which only passes filePath.
-  // We'll check in the wrapper instead. For now, return null (pass).
+function checkStatuslineRules(_filePath, _isInPlanning, _planningDir) {
+  // Content check requires full hook data — handled by checkStatuslineContent() in main()
   return null;
 }
 

package/plugins/pbr/scripts/check-state-sync.js

@@ -363,10 +363,15 @@ function checkStateSync(data) {
     if (fs.existsSync(roadmapPath)) {
       try {
         const roadmapContent = fs.readFileSync(roadmapPath, 'utf8');
-        const updatedRoadmap = updateProgressTable(roadmapContent, phaseNum, plansComplete, newStatus, completedDate);
-        if (updatedRoadmap !== roadmapContent) {
-          atomicWrite(roadmapPath, updatedRoadmap);
-          messages.push(`ROADMAP.md: Phase ${phaseNum} → ${plansComplete} plans, ${newStatus}`);
+        const hasProgressTable = /Plans\s*Complete/i.test(roadmapContent);
+        if (!hasProgressTable) {
+          messages.push(`ROADMAP.md: No Progress table found. Add a table with columns: | Phase | Plans Complete | Status | Completed | for the current milestone phases.`);
+        } else {
+          const updatedRoadmap = updateProgressTable(roadmapContent, phaseNum, plansComplete, newStatus, completedDate);
+          if (updatedRoadmap !== roadmapContent) {
+            atomicWrite(roadmapPath, updatedRoadmap);
+            messages.push(`ROADMAP.md: Phase ${phaseNum} → ${plansComplete} plans, ${newStatus}`);
+          }
         }
       } catch (e) {
         logHook('check-state-sync', 'PostToolUse', 'error', { reason: 'ROADMAP.md update failed', error: e.message });
@@ -443,10 +448,15 @@ function checkStateSync(data) {
     if (fs.existsSync(roadmapPath)) {
       try {
         const roadmapContent = fs.readFileSync(roadmapPath, 'utf8');
-        const updatedRoadmap = updateProgressTable(roadmapContent, phaseNum, plansComplete, roadmapStatus, completedDate);
-        if (updatedRoadmap !== roadmapContent) {
-          atomicWrite(roadmapPath, updatedRoadmap);
-          messages.push(`ROADMAP.md: Phase ${phaseNum} → ${roadmapStatus}`);
+        const hasProgressTable = /Plans\s*Complete/i.test(roadmapContent);
+        if (!hasProgressTable) {
+          messages.push(`ROADMAP.md: No Progress table found. Add a table with columns: | Phase | Plans Complete | Status | Completed | for the current milestone phases.`);
+        } else {
+          const updatedRoadmap = updateProgressTable(roadmapContent, phaseNum, plansComplete, roadmapStatus, completedDate);
+          if (updatedRoadmap !== roadmapContent) {
+            atomicWrite(roadmapPath, updatedRoadmap);
+            messages.push(`ROADMAP.md: Phase ${phaseNum} → ${roadmapStatus}`);
+          }
         }
       } catch (e) {
         logHook('check-state-sync', 'PostToolUse', 'error', { reason: 'ROADMAP.md update failed', error: e.message });