@sienklogic/plan-build-run 2.34.0 → 2.38.0

package/plugins/pbr/scripts/post-write-dispatch.js

@@ -55,11 +55,12 @@ function checkRoadmapWrite(data) {
   if (!fs.existsSync(filePath)) return null;
 
   const content = fs.readFileSync(filePath, 'utf8');
-  const errors = validateRoadmap(content);
-  if (errors && errors.length > 0) {
+  const result = validateRoadmap(content);
+  const combined = [...(result.errors || []), ...(result.warnings || [])];
+  if (combined.length > 0) {
     return {
       output: {
-        additionalContext: `[ROADMAP Validation] ${errors.join('; ')}`
+        additionalContext: `[ROADMAP Validation] ${combined.join('; ')}`
       }
     };
   }
@@ -127,7 +128,7 @@ function main() {
       const normalizedPath = filePath.replace(/\\/g, '/');
       if (filePath && !normalizedPath.includes('.planning/') && !normalizedPath.includes('.planning\\')) {
         try {
-          const cwd = process.cwd();
+          const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
           const planningDir = path.join(cwd, '.planning');
           const llmConfig = (() => {
             try {

package/plugins/pbr/scripts/pre-write-dispatch.js

@@ -129,7 +129,7 @@ function main() {
         if (phaseMatch) {
           const fs = require('fs');
           const path = require('path');
-          const statePath = path.join(process.cwd(), '.planning', 'STATE.md');
+          const statePath = path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning', 'STATE.md');
           try {
             const stateContent = fs.readFileSync(statePath, 'utf8');
             const currentPhase = stateContent.match(/Phase:\s*(\d+)\s+of/);

package/plugins/pbr/scripts/progress-tracker.js

@@ -18,7 +18,7 @@ const { configLoad } = require('./pbr-tools');
 const { resolveConfig, checkHealth, warmUp } = require('./local-llm/health');
 
 async function main() {
-  const cwd = process.cwd();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
   const planningDir = path.join(cwd, '.planning');
   const stateFile = path.join(planningDir, 'STATE.md');
 

package/plugins/pbr/scripts/suggest-compact.js

@@ -26,7 +26,7 @@ function main() {
   process.stdin.resume();
   process.stdin.on('end', () => {
     try {
-      const cwd = process.cwd();
+      const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
       const planningDir = path.join(cwd, '.planning');
       if (!fs.existsSync(planningDir)) {
         process.exit(0);

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

@@ -4,6 +4,10 @@
  * PostToolUse hook on Read: Tracks cumulative file reads per skill invocation.
  *
  * Maintains a session-scoped counter in .planning/.context-tracker.
+ * Integrates with context-bridge.js: if .planning/.context-budget.json exists
+ * and is fresh (< 60 seconds), uses its tier-based warnings instead of the
+ * heuristic char/file milestones.
+ *
  * Warns only at meaningful thresholds to reduce noise:
  *   - Unique files read crosses milestone (10, 20, 30, ...)
  *   - Total chars read crosses milestone (50k, 100k, 150k, ...)
@@ -18,6 +22,8 @@ const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
 
+const BRIDGE_STALENESS_MS = 60000; // 60 seconds
+
 const UNIQUE_FILE_MILESTONE = 10;    // warn every 10 unique files
 const CHAR_MILESTONE = 50000;        // warn every 50k chars
 const LARGE_FILE_THRESHOLD = 5000;   // warn if single read > 5k chars
@@ -29,7 +35,7 @@ function main() {
   process.stdin.on('data', (chunk) => { input += chunk; });
   process.stdin.on('end', () => {
     try {
-      const cwd = process.cwd();
+      const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
       const planningDir = path.join(cwd, '.planning');
       if (!fs.existsSync(planningDir)) {
         process.exit(0);
@@ -103,6 +109,19 @@ function main() {
         try { fs.unlinkSync(trackerPath + '.' + process.pid); } catch (_e2) { /* best-effort cleanup */ }
       }
 
+      // Check bridge file for tier-based context warnings
+      const bridgeTier = checkBridge(planningDir);
+      if (bridgeTier) {
+        // Bridge is fresh and providing tier warnings — skip heuristic milestones
+        // (the bridge's context-bridge.js already handles tier debounce)
+        logHook('track-context-budget', 'PostToolUse', 'bridge-active', {
+          reads: tracker.reads,
+          total_chars: tracker.total_chars,
+          tier: bridgeTier,
+        });
+        process.exit(0);
+      }
+
       // Check thresholds — only warn at milestone crossings, not every read
       const warnings = [];
 
@@ -165,4 +184,36 @@ function loadTracker(trackerPath) {
   }
 }
 
-main();
+/**
+ * Check the context bridge file for tier-based warnings.
+ * Returns the current tier name if the bridge is fresh, null otherwise.
+ *
+ * @param {string} planningDir - Path to .planning/
+ * @returns {string|null} Tier name if bridge is active and fresh, null if stale/missing
+ */
+function checkBridge(planningDir) {
+  const bridgePath = path.join(planningDir, '.context-budget.json');
+  try {
+    if (!fs.existsSync(bridgePath)) return null;
+
+    const stats = fs.statSync(bridgePath);
+    const ageMs = Date.now() - stats.mtimeMs;
+    if (ageMs > BRIDGE_STALENESS_MS) return null;
+
+    const content = fs.readFileSync(bridgePath, 'utf8');
+    const bridge = JSON.parse(content);
+
+    // Only trust bridge data that has a real source or recent update
+    if (!bridge.estimated_percent && bridge.estimated_percent !== 0) return null;
+
+    const { getTier } = require('./context-bridge');
+    const tier = getTier(bridge.estimated_percent);
+    return tier.name;
+  } catch (_e) {
+    return null;
+  }
+}
+
+module.exports = { checkBridge, BRIDGE_STALENESS_MS };
+
+if (require.main === module || process.argv[1] === __filename) { main(); }

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

@@ -23,6 +23,7 @@ const { logHook } = require('./hook-logger');
 const { resolveConfig } = require('./local-llm/health');
 const { validateTask: llmValidateTask } = require('./local-llm/operations/validate-task');
 const { checkNonPbrAgent } = require('./enforce-pbr-workflow');
+const { KNOWN_AGENTS } = require('./pbr-tools');
 
 /**
  * Load and resolve the local_llm config block from .planning/config.json.
@@ -39,21 +40,6 @@ function loadLocalLlmConfig(cwd) {
   }
 }
 
-const KNOWN_AGENTS = [
-  'researcher',
-  'planner',
-  'plan-checker',
-  'executor',
-  'verifier',
-  'integration-checker',
-  'debugger',
-  'codebase-mapper',
-  'synthesizer',
-  'general',
-  'audit',
-  'dev-sync'
-];
-
 const MAX_DESCRIPTION_LENGTH = 100;
 
 /**
@@ -115,7 +101,7 @@ function checkQuickExecutorGate(data) {
   // Only gate pbr:executor
   if (subagentType !== 'pbr:executor') return null;
 
-  const cwd = process.cwd();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
   const planningDir = path.join(cwd, '.planning');
   const activeSkillFile = path.join(planningDir, '.active-skill');
 
@@ -181,7 +167,7 @@ function checkBuildExecutorGate(data) {
   // Only gate pbr:executor
   if (subagentType !== 'pbr:executor') return null;
 
-  const cwd = process.cwd();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
   const planningDir = path.join(cwd, '.planning');
   const activeSkillFile = path.join(planningDir, '.active-skill');
 
@@ -253,7 +239,7 @@ function checkPlanExecutorGate(data) {
   // Only gate pbr:executor
   if (subagentType !== 'pbr:executor') return null;
 
-  const cwd = process.cwd();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
   const planningDir = path.join(cwd, '.planning');
   const activeSkillFile = path.join(planningDir, '.active-skill');
 
@@ -282,7 +268,7 @@ function checkReviewPlannerGate(data) {
   // Only gate pbr:planner
   if (subagentType !== 'pbr:planner') return null;
 
-  const cwd = process.cwd();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
   const planningDir = path.join(cwd, '.planning');
   const activeSkillFile = path.join(planningDir, '.active-skill');
 
@@ -336,7 +322,7 @@ function checkReviewVerifierGate(data) {
   // Only gate pbr:verifier
   if (subagentType !== 'pbr:verifier') return null;
 
-  const cwd = process.cwd();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
   const planningDir = path.join(cwd, '.planning');
   const activeSkillFile = path.join(planningDir, '.active-skill');
 
@@ -396,7 +382,7 @@ function checkMilestoneCompleteGate(data) {
   const subagentType = toolInput.subagent_type || '';
   const description = toolInput.description || '';
 
-  const cwd = process.cwd();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
   const planningDir = path.join(cwd, '.planning');
   const activeSkillFile = path.join(planningDir, '.active-skill');
 
@@ -503,7 +489,7 @@ function checkBuildDependencyGate(data) {
   // Only gate pbr:executor
   if (subagentType !== 'pbr:executor') return null;
 
-  const cwd = process.cwd();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
   const planningDir = path.join(cwd, '.planning');
   const activeSkillFile = path.join(planningDir, '.active-skill');
 
@@ -607,14 +593,15 @@ function checkDebuggerAdvisory(data) {
   const subagentType = data.tool_input?.subagent_type || '';
   if (subagentType !== 'pbr:debugger') return null;
   // Only advise when spawned from the debug skill
-  const activeSkillPath = path.join(process.cwd(), '.planning', '.active-skill');
+  const debugCwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const activeSkillPath = path.join(debugCwd, '.planning', '.active-skill');
   try {
     const activeSkill = fs.readFileSync(activeSkillPath, 'utf8').trim();
     if (activeSkill !== 'debug') return null;
   } catch (_e) {
     return null; // No .active-skill file — skip advisory
   }
-  const debugDir = path.join(process.cwd(), '.planning', 'debug');
+  const debugDir = path.join(debugCwd, '.planning', 'debug');
   if (!fs.existsSync(debugDir)) {
     return 'Debugger advisory: .planning/debug/ does not exist. Create it before spawning the debugger so output has a target location.';
   }
@@ -627,7 +614,7 @@ function checkCheckpointManifest(data) {
 
   if (subagentType !== 'pbr:executor') return null;
 
-  const cwd = process.cwd();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
   const planningDir = path.join(cwd, '.planning');
   const activeSkillFile = path.join(planningDir, '.active-skill');
 
@@ -676,7 +663,11 @@ function checkActiveSkillIntegrity(data) {
 
   if (typeof subagentType !== 'string' || !subagentType.startsWith('pbr:')) return null;
 
-  const cwd = process.cwd();
+  // Advisory agents that run without an active skill context — exempt from .active-skill checks
+  const EXEMPT_AGENTS = ['pbr:researcher', 'pbr:synthesizer', 'pbr:audit', 'pbr:dev-sync', 'pbr:general'];
+  if (EXEMPT_AGENTS.includes(subagentType)) return null;
+
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
   const planningDir = path.join(cwd, '.planning');
 
   // Only check if .planning/ exists (PBR project)
@@ -815,8 +806,9 @@ function main() {
 
       // LLM task coherence check — advisory only
       try {
-        const llmConfig = loadLocalLlmConfig(process.cwd());
-        const planningDir = path.join(process.cwd(), '.planning');
+        const llmCwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+        const llmConfig = loadLocalLlmConfig(llmCwd);
+        const planningDir = path.join(llmCwd, '.planning');
         const llmResult = await llmValidateTask(llmConfig, planningDir, data.tool_input || {}, data.session_id);
         if (llmResult && !llmResult.coherent) {
           warnings.push('LLM task coherence advisory: ' + (llmResult.issue || 'Task description may not match intended operation.') + ' (confidence: ' + (llmResult.confidence * 100).toFixed(0) + '%)');

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

@@ -137,7 +137,12 @@ For each session:
 ```
 Task({
   subagent_type: "pbr:audit",
-  prompt: "<audit_assignment>
+  prompt: "<files_to_read>
+    CRITICAL: Read these files BEFORE any other action:
+    1. {absolute_path_to_session.jsonl} — session log to analyze
+    2. {subagent log paths, if any} — subagent session logs
+  </files_to_read>
+  <audit_assignment>
     Session JSONL: {absolute_path_to_session.jsonl}
     Subagent logs: {list of subagent jsonl paths, or 'none'}
     Audit mode: {mode}
@@ -173,7 +178,9 @@ Display progress:
 
 ## Step 5 — Collect and Synthesize
 
-As agents complete, collect their findings. Wait for all agents before proceeding.
+As agents complete, check each audit agent's Task() output for `## AUDIT COMPLETE`. If the marker is absent, mark that session as "analysis failed" in the synthesis and skip its findings — do not treat incomplete output as valid analysis. Log: `⚠ Session {id}: audit agent did not return completion marker — skipping.`
+
+Wait for all agents before proceeding.
 
 Synthesize across all sessions:
 
@@ -258,6 +265,15 @@ The report should follow this structure:
 
 ---
 
+## Step 6b — Spot-Check Artifacts
+
+**Before displaying results, verify the report landed on disk:**
+
+1. Glob `.planning/audits/{YYYY-MM-DD}-session-audit.md` to confirm the file exists
+2. If missing: re-attempt the write (Step 6). If still missing, display an error and include findings inline instead.
+
+---
+
 ## Step 7 — Display Summary
 
 After writing the report, display inline (keep it concise — the full report is on disk):
@@ -289,7 +305,7 @@ Full report: .planning/audits/{filename}
 - If todos identified: **Create todos** → `/pbr:todo add "{description}"`
 - Default: **See project status** → `/pbr:status`
 
-`/clear` first → fresh context window
+<sub>`/clear` first → fresh context window</sub>
 ```
 
 ---

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

@@ -220,6 +220,7 @@ Spawn parallel Task() subagents for research. Each researcher writes to `.planni
 ```
 Task({
   subagent_type: "pbr:researcher",
+  // After researcher: check for ## RESEARCH COMPLETE or ## RESEARCH BLOCKED
   prompt: <see researcher prompt template below>
 })
 ```
@@ -234,6 +235,14 @@ For each researcher, construct the prompt by reading the template and filling in
 
 Read `skills/begin/templates/researcher-prompt.md.tmpl` for the prompt structure.
 
+**Prepend this block to the researcher prompt before sending:**
+```
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/REQUIREMENTS.md — scoped requirements (if exists)
+</files_to_read>
+```
+
 **Placeholders to fill:**
 - `{project name from questioning}` — project name gathered in Step 2
 - `{2-3 sentence description from questioning}` — project description from Step 2
@@ -303,10 +312,36 @@ Task({
 
 Read `skills/begin/templates/synthesis-prompt.md.tmpl` for the prompt structure.
 
+**Prepend this block to the synthesizer prompt before sending:**
+```
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/research/*.md — all research output files from Step 5
+</files_to_read>
+```
+
 **Placeholders to fill:**
 - `{List all .planning/research/*.md files that were created}` — list the research files produced in Step 5
 
-**After the synthesizer completes**, display:
+**After the synthesizer completes**, check for completion markers in the Task() output:
+
+- If `## SYNTHESIS COMPLETE` is present: proceed normally
+- If `## SYNTHESIS BLOCKED` is present: warn the user and offer to proceed without synthesis:
+  ```
+  ⚠ Synthesizer reported BLOCKED: {reason from output}
+  Research files are still available individually in .planning/research/.
+  ```
+  Use AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
+    question: "Synthesis was blocked. Continue without synthesis?"
+    header: "Blocked"
+    options:
+      - label: "Yes"  description: "Proceed to requirements — use individual research files"
+      - label: "No"   description: "Stop and investigate"
+  - If "Yes": proceed to Step 7 without SUMMARY.md
+  - If "No": stop and suggest reviewing .planning/research/ files
+- If neither marker is found: warn the user that the synthesizer may not have completed successfully, but proceed if SUMMARY.md exists on disk
+
+If synthesis succeeded, display:
 ```
 ✓ Research synthesis complete — see .planning/research/SUMMARY.md
 ```
@@ -367,6 +402,7 @@ Spawn the planner in roadmap mode:
 ```
 Task({
   subagent_type: "pbr:planner",
+  // After planner: check for ## PLANNING COMPLETE or ## PLANNING FAILED
   prompt: <roadmap prompt>
 })
 ```
@@ -379,12 +415,22 @@ Task({
 
 Read `skills/begin/templates/roadmap-prompt.md.tmpl` for the prompt structure.
 
+**Prepend this block to the roadmap planner prompt before sending:**
+```
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/REQUIREMENTS.md — scoped requirements for phase planning
+2. .planning/research/SUMMARY.md — research synthesis (if exists)
+</files_to_read>
+```
+
 **Placeholders to fill:**
 - `{project name}` — project name from Step 2
 - `{description}` — project description from Step 2
 - `{quick|standard|comprehensive}` — depth setting from Step 3
 
 **After the planner completes:**
+- **Spot-check:** Verify `.planning/ROADMAP.md` exists on disk using Glob before attempting to read it. If missing, the planner may have failed silently — warn: `⚠ ROADMAP.md not found after planner completed. Re-spawning planner...` and retry once.
 - Read `.planning/ROADMAP.md`
 - Count the phases from the roadmap content
 - Verify the roadmap contains a `## Milestone:` section wrapping the phases (the planner should generate this). If not, the initial set of phases constitutes the first milestone — add the section header yourself.
@@ -532,7 +578,7 @@ Delete `.planning/.active-skill` if it exists. This must happen on all paths (su
 
 After all steps complete, present the final summary using the stage banner format from Read `references/ui-formatting.md`:
 
-Display the `PROJECT INITIALIZED ✓` banner with project name, core value, phase list, and requirement counts. Then display the "Next Up" block (see § "Next Up Block" in ui-formatting.md) pointing to `/pbr:discuss 1` with alternatives: `/pbr:explore`, `/pbr:plan 1`, `/pbr:milestone new`, `/pbr:config`.
+Display the `PROJECT INITIALIZED ✓` banner with project name, core value, phase list, and requirement counts. Then display the "Next Up" block (see § "Next Up Block" in ui-formatting.md) pointing to `/pbr:discuss 1` with alternatives: `/pbr:explore`, `/pbr:plan 1`, `/pbr:milestone new`, `/pbr:config`. Include `<sub>/clear first → fresh context window</sub>` inside the Next Up routing block.
 
 ---
 

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

@@ -134,6 +134,8 @@ Phase {N} depends on Phase {M}, which is not complete.
 
 ### Step 2: Load Config (inline)
 
+**Init-first pattern**: When spawning agents, pass the output of `node plugins/pbr/scripts/pbr-tools.js init execute-phase {N}` as context rather than having the agent read multiple files separately. This reduces file reads and prevents context-loading failures.
+
 Read configuration values needed for execution. See `skills/shared/config-loading.md` for the full field reference; build uses: `parallelization.*`, `features.goal_verification`, `features.inline_verify`, `features.atomic_commits`, `features.auto_continue`, `features.auto_advance`, `planning.commit_docs`, `git.commit_format`, `git.branching`.
 
 ---
@@ -303,6 +305,13 @@ Construct the executor prompt:
 ```
 You are the executor agent. Execute the following plan.
 
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/phases/{NN}-{slug}/{plan_id}-PLAN.md — the full plan with task details
+2. .planning/CONTEXT.md — locked decisions and constraints (if exists)
+3. .planning/STATE.md — current project state and progress
+</files_to_read>
+
 <plan_summary>
 [Inline only the ## Summary section from PLAN.md]
 </plan_summary>
@@ -372,7 +381,9 @@ Task({
   prompt: <executor prompt constructed above>
 })
 
-NOTE: The pbr:executor subagent type auto-loads the agent definition. Do NOT inline it.
+NOTE: The pbr:executor subagent type auto-loads the agent definition.
+
+After executor completes, check for completion markers: `## PLAN COMPLETE`, `## PLAN FAILED`, or `## CHECKPOINT: {TYPE}`. Route accordingly — PLAN COMPLETE proceeds to next plan, PLAN FAILED triggers failure handling, CHECKPOINT triggers checkpoint flow. Do NOT inline it.
 ```
 
 **Path resolution**: Before constructing the agent prompt, resolve `${CLAUDE_PLUGIN_ROOT}` to its absolute path. Do not pass the variable literally in prompts — Task() contexts may not expand it. Use the resolved absolute path for any pbr-tools.js or template references included in the prompt.
@@ -408,6 +419,11 @@ After reading each SUMMARY, perform a lightweight verification:
 - If ANY spot-check fails, warn the user before proceeding to the next wave:
   "Spot-check failed for plan {id}: {detail}. Inspect before continuing?"
 
+**Additional wave spot-checks:**
+- Check for `## Self-Check: FAILED` in SUMMARY.md — if present, warn user before proceeding to next wave
+- Between waves: verify no file conflicts from parallel executors (check `git status` for uncommitted changes)
+- If ANY spot-check fails, present user with: **Retry this plan** / **Continue to next wave** / **Abort build**
+
 **Read executor deviations:**
 
 After all executors in the wave complete, read all SUMMARY frontmatter and:
@@ -450,7 +466,14 @@ For each plan that completed successfully in this wave:
 Task({
   subagent_type: "pbr:verifier",
   model: "haiku",
-  prompt: "Targeted inline verification for plan {plan_id}.
+  prompt: "<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/phases/{NN}-{slug}/{plan_id}-PLAN.md — must-haves to verify against
+2. .planning/phases/{NN}-{slug}/SUMMARY-{plan_id}.md — what the executor claims was built
+3. .planning/phases/{NN}-{slug}/VERIFICATION.md — prior verification results (if exists)
+</files_to_read>
+
+Targeted inline verification for plan {plan_id}.
 
 Verify ONLY these files: {comma-separated key_files list}
 
@@ -655,6 +678,8 @@ Task({
 })
 
 NOTE: The pbr:verifier subagent type auto-loads the agent definition. Do NOT inline it.
+
+After verifier completes, check for completion marker: `## VERIFICATION COMPLETE`. Read VERIFICATION.md frontmatter for status.
 ```
 
 **Path resolution**: Before constructing the agent prompt, resolve `${CLAUDE_PLUGIN_ROOT}` to its absolute path. Do not pass the variable literally in prompts — Task() contexts may not expand it. Use the resolved absolute path for any pbr-tools.js or template references included in the prompt.
@@ -663,6 +688,16 @@ NOTE: The pbr:verifier subagent type auto-loads the agent definition. Do NOT inl
 
 Use the same verifier prompt template as defined in `/pbr:review`: read `skills/review/templates/verifier-prompt.md.tmpl` and fill in its placeholders with the phase's PLAN.md must_haves and SUMMARY.md file paths. This avoids maintaining duplicate verifier prompts across skills.
 
+**Prepend this block to the verifier prompt before sending:**
+```
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/phases/{NN}-{slug}/PLAN-*.md — must-haves to verify against
+2. .planning/phases/{NN}-{slug}/SUMMARY-*.md — executor build summaries
+3. .planning/phases/{NN}-{slug}/VERIFICATION.md — prior verification results (if exists)
+</files_to_read>
+```
+
 After the verifier returns, read the VERIFICATION.md frontmatter and display the results:
 
 - If status is `passed`: display `✓ Verifier: {X}/{Y} must-haves verified` (where X = `must_haves_passed` and Y = `must_haves_checked`)
@@ -827,6 +862,8 @@ Then present the appropriate branded banner from Read `references/ui-formatting.
 - **If `passed` + last phase:** Use the "Milestone Complete" template. Fill in phase count.
 - **If `gaps_found`:** Use the "Gaps Found" template. Fill in phase number, name, score, and gap summaries from VERIFICATION.md.
 
+Include `<sub>/clear first → fresh context window</sub>` inside the Next Up routing block of the completion template.
+
 **8g. Display USER-SETUP.md (conditional):**
 
 Check if `.planning/phases/{NN}-{slug}/USER-SETUP.md` exists. If it does:

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

@@ -115,10 +115,11 @@ Use AskUserQuestion:
     - label: "Depth"          description: "quick/standard/comprehensive"
     - label: "Model profile"  description: "quality/balanced/budget/adaptive"
     - label: "Features"       description: "Toggle workflow features, gates, status line"
-    - label: "Git settings"   description: "branching strategy, commit mode"
+    - label: "Git settings"      description: "branching strategy, commit mode"
+    - label: "Save as defaults"  description: "Save current config as user-level defaults for new projects"
   multiSelect: false
 
-Note: The original 7 categories are condensed to 4. "Models" (per-agent) is accessible through "Model profile" with a follow-up option. "Gates", "Parallelization", and "Status Line" are grouped under "Features".
+Note: The original 7 categories are condensed to 5. "Models" (per-agent) is accessible through "Model profile" with a follow-up option. "Gates", "Parallelization", and "Status Line" are grouped under "Features". "Save as defaults" exports to ~/.claude/pbr-defaults.json.
 
 **Follow-up based on selection:**
 
@@ -181,6 +182,15 @@ Use AskUserQuestion:
     - label: "Disabled"    description: "No git integration"
   multiSelect: false
 
+If user selects "Save as defaults":
+Save current project config as user-level defaults for future projects:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" config save-defaults
+```
+
+Display: "Saved your preferences to ~/.claude/pbr-defaults.json. New projects created with /pbr:setup will use these as starting values."
+
 If user types something else (freeform): interpret as a direct setting command and handle via Step 2 argument parsing logic.
 
 ### 4. Apply Changes

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

@@ -213,7 +213,18 @@ Continuing investigation...
 
 ### Step 4: Handle Debugger Results
 
-When the debugger agent completes, display: `✓ Debug session complete — {N} hypotheses tested` (read the hypothesis count from the debug file's Hypotheses table).
+When the debugger agent completes, first check for completion markers in the Task() output before routing:
+
+| Marker in Task() Output | Route To |
+|--------------------------|----------|
+| `## DEBUG COMPLETE` | ROOT CAUSE FOUND + FIX path |
+| `## ROOT CAUSE FOUND` | ROOT CAUSE FOUND (no fix) path |
+| `## DEBUG SESSION PAUSED` | CHECKPOINT path |
+| No marker found | INCONCLUSIVE path |
+
+**Spot-check:** Before routing, verify `.planning/debug/{NNN}-{slug}.md` exists and was recently updated (modified timestamp is newer than the Task() spawn time). If the debug file was not updated, warn: `⚠ Debug file not updated by agent — results may be incomplete.`
+
+Display: `✓ Debug session complete — {N} hypotheses tested` (read the hypothesis count from the debug file's Hypotheses table).
 
 The debugger returns one of four outcomes:
 

package/plugins/pbr/skills/debug/templates/continuation-prompt.md.tmpl

@@ -1,6 +1,13 @@
 <!-- Source: skills/debug/SKILL.md | Purpose: Spawn prompt for continuation debugger investigation -->
 You are debugger. Continue investigating the following issue.
 
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/debug/{NNN}-{slug}.md — the debug session file with all prior findings
+2. .planning/CONTEXT.md — locked decisions and constraints (if exists)
+3. .planning/STATE.md — current project state (if exists)
+</files_to_read>
+
 Debug file: .planning/debug/{NNN}-{slug}.md
 Mode: continuation
 
@@ -13,4 +20,8 @@ Instructions:
 3. Formulate NEW hypotheses based on prior findings
 4. Continue systematic investigation
 5. Update the debug file
-6. Return: ROOT_CAUSE_FOUND, CHECKPOINT, or INCONCLUSIVE
+6. Return one of these markers as a heading in your response:
+   - `## DEBUG COMPLETE` — root cause found + fix applied
+   - `## ROOT CAUSE FOUND` — root cause identified, no fix applied
+   - `## DEBUG SESSION PAUSED` — checkpoint, need user input
+   - If no root cause found after exhausting hypotheses, return without a marker (treated as INCONCLUSIVE)

package/plugins/pbr/skills/debug/templates/initial-investigation-prompt.md.tmpl

@@ -1,6 +1,13 @@
 <!-- Source: skills/debug/SKILL.md | Purpose: Spawn prompt for initial debugger investigation -->
 You are debugger. Investigate the following issue systematically.
 
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/debug/{NNN}-{slug}.md — the debug session file with symptoms and context
+2. .planning/CONTEXT.md — locked decisions and constraints (if exists)
+3. .planning/STATE.md — current project state (if exists)
+</files_to_read>
+
 Debug file: .planning/debug/{NNN}-{slug}.md
 Mode: initial_investigation
 
@@ -20,8 +27,8 @@ Instructions:
    c. Execute the test
    d. Record the result (confirmed, rejected, inconclusive)
 4. Update the debug file with findings
-5. Return one of:
-   - ROOT_CAUSE_FOUND: {cause} + FIX: {what to change}
-   - ROOT_CAUSE_FOUND: {cause} (if find_root_cause_only mode)
-   - CHECKPOINT: {what was found, what to investigate next}
-   - INCONCLUSIVE: {findings so far, suggested next approaches}
+5. Return one of these markers as a heading in your response:
+   - `## DEBUG COMPLETE` — root cause found + fix applied: {cause} + {what was changed}
+   - `## ROOT CAUSE FOUND` — root cause identified, no fix applied (if find_root_cause_only mode): {cause}
+   - `## DEBUG SESSION PAUSED` — checkpoint, need user input: {what was found, what to investigate next}
+   - If no root cause found after exhausting hypotheses, return without a marker (treated as INCONCLUSIVE)

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

@@ -122,7 +122,12 @@ Display to the user: `◐ Spawning researcher...`
 ```
 Task({
   subagent_type: "pbr:researcher",
-  prompt: "<research_assignment>
+  prompt: "<files_to_read>
+    CRITICAL: Read these files BEFORE any other action:
+    1. .planning/CONTEXT.md — locked decisions and constraints (if exists)
+    2. .planning/STATE.md — current project state (if exists)
+  </files_to_read>
+  <research_assignment>
     Topic: {specific research question}
     Output file: .planning/research/{topic-slug}.md
     Mode: project-research
@@ -134,7 +139,13 @@ Task({
 })
 ```
 
-After the researcher completes, display: `✓ Research complete — results in .planning/research/{topic-slug}.md`
+After the researcher completes, check for completion markers in the Task() output:
+
+- If `## RESEARCH COMPLETE` is present: proceed normally
+- If `## RESEARCH BLOCKED` is present: display the blocker reason and offer to retry:
+  `⚠ Research blocked: {reason}. Try a different angle or continue without research.`
+
+Display: `✓ Research complete — results in .planning/research/{topic-slug}.md`
 
 Then:
 - Read ONLY the frontmatter and summary section of the research file (not the full document)