@sienklogic/plan-build-run 2.42.1 → 2.44.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to Plan-Build-Run will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.44.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.43.0...plan-build-run-v2.44.0) (2026-02-28)
+
+
+### Features
+
+* **49-03:** add CRITICAL spot-check CLI marker to build SKILL.md Step 6c ([255ee65](https://github.com/SienkLogic/plan-build-run/commit/255ee65506334a972ceb472b2fa90f1ba94eca80))
+* **49-03:** GREEN - refactor check-subagent-output.js to SKILL_CHECKS lookup table ([fb4b272](https://github.com/SienkLogic/plan-build-run/commit/fb4b272a8a02dd22d27745e5a9d98bb9fc57ef26))
+
+
+### Bug Fixes
+
+* **49-03:** sync spot-check CRITICAL marker to cursor-pbr and copilot-pbr ([994ef46](https://github.com/SienkLogic/plan-build-run/commit/994ef46aa13afde61ffa0e38e0332ab13be8863d))
+
+## [2.43.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.42.1...plan-build-run-v2.43.0) (2026-02-28)
+
+
+### Features
+
+* **49-01:** add spot-check subcommand to pbr-tools.js dispatcher ([8a01f3a](https://github.com/SienkLogic/plan-build-run/commit/8a01f3aaff45b48b5a239e3bdc8e4a0213524bc8))
+* **49-01:** GREEN - implement spotCheck() in lib/spot-check.js ([d0d9d51](https://github.com/SienkLogic/plan-build-run/commit/d0d9d51b5a7467be7156243fbba9f05d1a624a12))
+* **49-02:** GREEN - add tier-aware bridge warnings to suggest-compact ([e145372](https://github.com/SienkLogic/plan-build-run/commit/e145372272ab3d3f6709ec87970f7a4e19226e9e))
+
 ## [2.42.1](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.42.0...plan-build-run-v2.42.1) (2026-02-28)
 
 

package/package.json

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

package/plugins/copilot-pbr/plugin.json

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

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

@@ -407,15 +407,40 @@ For each completed executor:
 
 **Spot-check executor claims:**
 
-After reading each SUMMARY, perform a lightweight verification:
-- Pick 2-3 files from the SUMMARY's `key_files` list and verify they exist (`ls`)
-- Run `git log --oneline -n {commit_count}` and confirm the count matches the claimed commits
-- For each spot-checked file, verify it has >10 lines (`wc -l`): warn if trivially small
-- For each spot-checked file, search for TODO/FIXME/placeholder/stub markers: warn if found
-- Check SUMMARY.md frontmatter for `self_check_failures`: if present, warn the user:
-  "Plan {id} reported self-check failures: {list failures}. Inspect before continuing?"
-- If ANY spot-check fails, warn the user before proceeding to the next wave:
-  "Spot-check failed for plan {id}: {detail}. Inspect before continuing?"
+CRITICAL: Before reading results or advancing to the next wave, run the spot-check CLI for each completed plan.
+
+For each completed plan in this wave:
+
+```bash
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js spot-check {phaseSlug} {planId}
+```
+
+Where `{phaseSlug}` is the phase directory name (e.g., `49-build-workflow-hardening`) and `{planId}` is the plan identifier (e.g., `49-01`).
+
+The command returns JSON: `{ ok, summary_exists, key_files_checked, commits_present, detail }`
+
+**If `ok` is `false` for ANY plan: STOP.** Do NOT advance to the next wave. Present the user with:
+
+```
+Spot-check FAILED for plan {planId}: {detail}
+
+Choose an action:
+  Retry   — Re-spawn executor for this plan
+  Continue — Skip this plan and proceed to next wave (may leave phase incomplete)
+  Abort   — Stop the build entirely
+```
+
+Use AskUserQuestion with the three options. Route:
+
+- Retry: Re-spawn the executor for this plan (go back to Step 6a for this plan only)
+- Continue: Log the failure, skip the plan, proceed
+- Abort: Stop all build work, leave phase in partial state
+
+**If `ok` is `true` for all plans:**
+
+- Also check SUMMARY.md frontmatter for `self_check_failures`: if present, warn the user: "Plan {id} reported self-check failures: {list}. Inspect before continuing?"
+- Also search SUMMARY.md for `## Self-Check: FAILED` marker — if present, warn before next wave
+- Between waves: verify no file conflicts from parallel executors (`git status` for uncommitted changes)
 
 **Additional wave spot-checks:**
 - Check for `## Self-Check: FAILED` in SUMMARY.md — if present, warn user before proceeding to next wave

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

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

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

@@ -408,15 +408,40 @@ For each completed executor:
 
 **Spot-check executor claims:**
 
-After reading each SUMMARY, perform a lightweight verification:
-- Pick 2-3 files from the SUMMARY's `key_files` list and verify they exist (`ls`)
-- Run `git log --oneline -n {commit_count}` and confirm the count matches the claimed commits
-- For each spot-checked file, verify it has >10 lines (`wc -l`): warn if trivially small
-- For each spot-checked file, search for TODO/FIXME/placeholder/stub markers: warn if found
-- Check SUMMARY.md frontmatter for `self_check_failures`: if present, warn the user:
-  "Plan {id} reported self-check failures: {list failures}. Inspect before continuing?"
-- If ANY spot-check fails, warn the user before proceeding to the next wave:
-  "Spot-check failed for plan {id}: {detail}. Inspect before continuing?"
+CRITICAL: Before reading results or advancing to the next wave, run the spot-check CLI for each completed plan.
+
+For each completed plan in this wave:
+
+```bash
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js spot-check {phaseSlug} {planId}
+```
+
+Where `{phaseSlug}` is the phase directory name (e.g., `49-build-workflow-hardening`) and `{planId}` is the plan identifier (e.g., `49-01`).
+
+The command returns JSON: `{ ok, summary_exists, key_files_checked, commits_present, detail }`
+
+**If `ok` is `false` for ANY plan: STOP.** Do NOT advance to the next wave. Present the user with:
+
+```
+Spot-check FAILED for plan {planId}: {detail}
+
+Choose an action:
+  Retry   — Re-spawn executor for this plan
+  Continue — Skip this plan and proceed to next wave (may leave phase incomplete)
+  Abort   — Stop the build entirely
+```
+
+Use AskUserQuestion with the three options. Route:
+
+- Retry: Re-spawn the executor for this plan (go back to Step 6a for this plan only)
+- Continue: Log the failure, skip the plan, proceed
+- Abort: Stop all build work, leave phase in partial state
+
+**If `ok` is `true` for all plans:**
+
+- Also check SUMMARY.md frontmatter for `self_check_failures`: if present, warn the user: "Plan {id} reported self-check failures: {list}. Inspect before continuing?"
+- Also search SUMMARY.md for `## Self-Check: FAILED` marker — if present, warn before next wave
+- Between waves: verify no file conflicts from parallel executors (`git status` for uncommitted changes)
 
 **Additional wave spot-checks:**
 - Check for `## Self-Check: FAILED` in SUMMARY.md — if present, warn user before proceeding to next wave

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

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

package/plugins/pbr/scripts/check-subagent-output.js

@@ -322,6 +322,74 @@ function checkSummaryCommits(planningDir, foundFiles, warnings) {
   }
 }
 
+// Skill-specific check lookup table keyed by 'activeSkill:agentType'
+const SKILL_CHECKS = {
+  'begin:pbr:planner': {
+    description: 'begin planner core files',
+    check: (planningDir, _found, warnings) => {
+      const coreFiles = ['REQUIREMENTS.md', 'ROADMAP.md', 'STATE.md'];
+      for (const f of coreFiles) {
+        if (!fs.existsSync(path.join(planningDir, f))) {
+          warnings.push(`Begin planner: ${f} was not created. The project may be in an incomplete state.`);
+        }
+      }
+    }
+  },
+  'plan:pbr:researcher': {
+    description: 'plan researcher phase-level RESEARCH.md',
+    check: (planningDir, found, warnings) => {
+      const phaseResearch = findInPhaseDir(planningDir, /^RESEARCH\.md$/i);
+      if (found.length === 0 && phaseResearch.length === 0) {
+        warnings.push('Plan researcher: No research output found in .planning/research/ or in the phase directory.');
+      }
+    }
+  },
+  'scan:pbr:codebase-mapper': {
+    description: 'scan codebase-mapper 4 focus areas',
+    check: (planningDir, _found, warnings) => {
+      const expectedAreas = ['tech', 'arch', 'quality', 'concerns'];
+      const codebaseDir = path.join(planningDir, 'codebase');
+      if (fs.existsSync(codebaseDir)) {
+        try {
+          const files = fs.readdirSync(codebaseDir).map(f => f.toLowerCase());
+          for (const area of expectedAreas) {
+            if (!files.some(f => f.includes(area))) {
+              warnings.push(`Scan mapper: No output file containing "${area}" found in .planning/codebase/. One of the 4 mappers may have failed.`);
+            }
+          }
+        } catch (_e) { /* best-effort */ }
+      }
+    }
+  },
+  'review:pbr:verifier': {
+    description: 'review verifier VERIFICATION.md status',
+    check: (planningDir, _found, warnings) => {
+      const verFiles = findInPhaseDir(planningDir, /^VERIFICATION\.md$/i);
+      for (const vf of verFiles) {
+        try {
+          const content = fs.readFileSync(path.join(planningDir, vf), 'utf8');
+          const statusMatch = content.match(/^status:\s*(\S+)/mi);
+          if (statusMatch && statusMatch[1] === 'gaps_found') {
+            warnings.push('Review verifier: VERIFICATION.md has status "gaps_found" — ensure gaps are surfaced to the user.');
+          }
+        } catch (_e) { /* best-effort */ }
+      }
+    }
+  },
+  'build:pbr:executor': {
+    description: 'build executor SUMMARY commits',
+    check: (planningDir, found, warnings) => {
+      checkSummaryCommits(planningDir, found, warnings);
+    }
+  },
+  'quick:pbr:executor': {
+    description: 'quick executor SUMMARY commits',
+    check: (planningDir, found, warnings) => {
+      checkSummaryCommits(planningDir, found, warnings);
+    }
+  }
+};
+
 function readStdin() {
   try {
     const input = fs.readFileSync(0, 'utf8').trim();
@@ -406,57 +474,11 @@ async function main() {
     skillWarnings.push(`${label} output may be stale — no recent output files detected.`);
   }
 
-  // GAP-04: Begin planner must produce core files
-  if (activeSkill === 'begin' && agentType === 'pbr:planner') {
-    const coreFiles = ['REQUIREMENTS.md', 'ROADMAP.md', 'STATE.md'];
-    for (const f of coreFiles) {
-      if (!fs.existsSync(path.join(planningDir, f))) {
-        skillWarnings.push(`Begin planner: ${f} was not created. The project may be in an incomplete state.`);
-      }
-    }
-  }
-
-  // GAP-05: Plan researcher should produce phase-level RESEARCH.md
-  if (activeSkill === 'plan' && agentType === 'pbr:researcher') {
-    const phaseResearch = findInPhaseDir(planningDir, /^RESEARCH\.md$/i);
-    if (found.length === 0 && phaseResearch.length === 0) {
-      skillWarnings.push('Plan researcher: No research output found in .planning/research/ or in the phase directory.');
-    }
-  }
-
-  // GAP-08: Scan codebase-mapper should produce all 4 focus areas
-  if (activeSkill === 'scan' && agentType === 'pbr:codebase-mapper') {
-    const expectedAreas = ['tech', 'arch', 'quality', 'concerns'];
-    const codebaseDir = path.join(planningDir, 'codebase');
-    if (fs.existsSync(codebaseDir)) {
-      try {
-        const files = fs.readdirSync(codebaseDir).map(f => f.toLowerCase());
-        for (const area of expectedAreas) {
-          if (!files.some(f => f.includes(area))) {
-            skillWarnings.push(`Scan mapper: No output file containing "${area}" found in .planning/codebase/. One of the 4 mappers may have failed.`);
-          }
-        }
-      } catch (_e) { /* best-effort */ }
-    }
-  }
-
-  // GAP-07: Review verifier should produce meaningful VERIFICATION.md status
-  if (activeSkill === 'review' && agentType === 'pbr:verifier') {
-    const verFiles = findInPhaseDir(planningDir, /^VERIFICATION\.md$/i);
-    for (const vf of verFiles) {
-      try {
-        const content = fs.readFileSync(path.join(planningDir, vf), 'utf8');
-        const statusMatch = content.match(/^status:\s*(\S+)/mi);
-        if (statusMatch && statusMatch[1] === 'gaps_found') {
-          skillWarnings.push('Review verifier: VERIFICATION.md has status "gaps_found" — ensure gaps are surfaced to the user.');
-        }
-      } catch (_e) { /* best-effort */ }
-    }
-  }
-
-  // GAP-06: Build/quick executor SUMMARY should have commits
-  if ((activeSkill === 'build' || activeSkill === 'quick') && agentType === 'pbr:executor') {
-    checkSummaryCommits(planningDir, found, skillWarnings);
+  // Skill-specific dispatch via SKILL_CHECKS lookup
+  const skillCheckKey = `${activeSkill}:${agentType}`;
+  const skillCheck = SKILL_CHECKS[skillCheckKey];
+  if (skillCheck) {
+    skillCheck.check(planningDir, found, skillWarnings);
   }
 
   // Output logic: avoid duplicating warnings
@@ -526,5 +548,5 @@ async function main() {
   process.exit(0);
 }
 
-module.exports = { AGENT_OUTPUTS, findInPhaseDir, findInQuickDir, checkSummaryCommits, isRecent, getCurrentPhase, checkRoadmapStaleness };
+module.exports = { AGENT_OUTPUTS, SKILL_CHECKS, findInPhaseDir, findInQuickDir, checkSummaryCommits, isRecent, getCurrentPhase, checkRoadmapStaleness };
 if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/lib/spot-check.js

@@ -0,0 +1,118 @@
+'use strict';
+
+/**
+ * lib/spot-check.js — Machine-enforced wave gate spot check.
+ *
+ * Verifies that a completed plan's SUMMARY file exists, lists real key_files
+ * that exist on disk, and has a non-empty commits field.
+ *
+ * Used by pbr-tools.js `spot-check <phaseSlug> <planId>` subcommand.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { parseYamlFrontmatter } = require('./core');
+
+/**
+ * Perform a spot-check on a completed plan's SUMMARY artifact.
+ *
+ * @param {string} planningDir  - Absolute path to the .planning/ directory
+ * @param {string} phaseSlug    - Phase directory name (e.g. "49-build-workflow-hardening")
+ * @param {string} planId       - Plan identifier (e.g. "49-01")
+ * @returns {{
+ *   ok: boolean,
+ *   summary_exists: boolean,
+ *   key_files_checked: Array<{path: string, exists: boolean}>,
+ *   commits_present: boolean,
+ *   detail: string
+ * }}
+ */
+function spotCheck(planningDir, phaseSlug, planId) {
+  const summaryPath = path.join(planningDir, 'phases', phaseSlug, 'SUMMARY-' + planId + '.md');
+
+  // Check 1: SUMMARY file must exist
+  if (!fs.existsSync(summaryPath)) {
+    return {
+      ok: false,
+      summary_exists: false,
+      key_files_checked: [],
+      commits_present: false,
+      detail: 'SUMMARY-' + planId + '.md not found'
+    };
+  }
+
+  // Read and parse SUMMARY frontmatter
+  let content;
+  try {
+    content = fs.readFileSync(summaryPath, 'utf8');
+  } catch (e) {
+    return {
+      ok: false,
+      summary_exists: true,
+      key_files_checked: [],
+      commits_present: false,
+      detail: 'Failed to read SUMMARY: ' + e.message
+    };
+  }
+
+  const fm = parseYamlFrontmatter(content);
+  const failures = [];
+
+  // Check 2: key_files — check first 2 entries for existence on disk
+  // key_files are repo-relative paths; resolve them relative to the repo root (planningDir/..)
+  const repoRoot = path.resolve(path.join(planningDir, '..'));
+  const rawKeyFiles = Array.isArray(fm.key_files) ? fm.key_files : [];
+  const toCheck = rawKeyFiles.slice(0, 2);
+
+  const key_files_checked = toCheck.map(kf => {
+    const absPath = path.resolve(repoRoot, kf);
+    const exists = fs.existsSync(absPath);
+    return { path: kf, exists };
+  });
+
+  const missingFiles = key_files_checked.filter(kf => !kf.exists);
+  if (missingFiles.length > 0) {
+    failures.push('missing key_files: ' + missingFiles.map(kf => kf.path).join(', '));
+  }
+
+  // Check 3: commits field must be non-empty
+  // Re-parse the raw frontmatter block for the commits field to match check-subagent-output.js pattern
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  let commits_present = false;
+
+  if (fmMatch) {
+    const fmBlock = fmMatch[1];
+    const commitsMatch = fmBlock.match(/commits:\s*(\[.*?\]|.*)/);
+    if (commitsMatch) {
+      const commitsVal = commitsMatch[1].trim();
+      // Treat these as empty: [], '', ~, null
+      commits_present = !(
+        commitsVal === '[]' ||
+        commitsVal === '' ||
+        commitsVal === '~' ||
+        commitsVal === 'null' ||
+        commitsVal === '""'
+      );
+    }
+  } else {
+    // No frontmatter found at all
+    failures.push('no frontmatter found in SUMMARY');
+  }
+
+  if (!commits_present) {
+    failures.push('commits field is empty or missing');
+  }
+
+  const ok = missingFiles.length === 0 && commits_present && (fmMatch !== null);
+  const detail = failures.length === 0 ? 'all checks passed' : failures.join('; ');
+
+  return {
+    ok,
+    summary_exists: true,
+    key_files_checked,
+    commits_present,
+    detail
+  };
+}
+
+module.exports = { spotCheck };

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

@@ -40,6 +40,7 @@
  *   learnings ingest <json-file>  — Ingest a learning entry into global store
  *   learnings query [--tags X] [--min-confidence Y] [--stack S] [--type T] — Query learnings
  *   learnings check-thresholds   — Check deferral trigger conditions
+ *   spot-check <phaseSlug> <planId>  — Verify SUMMARY, key_files, and commits exist for a plan
  *
  * Environment: PBR_PROJECT_ROOT — Override project root directory (used when hooks fire from subagent cwd)
  */
@@ -132,6 +133,10 @@ const {
   applyMigrations: _applyMigrations
 } = require('./lib/migrate');
 
+const {
+  spotCheck: _spotCheck
+} = require('./lib/spot-check');
+
 const {
   learningsIngest: _learningsIngest,
   learningsQuery: _learningsQuery,
@@ -282,6 +287,10 @@ function migrate(options) {
   return _applyMigrations(planningDir, options);
 }
 
+function spotCheck(phaseDir, planId) {
+  return _spotCheck(planningDir, phaseDir, planId);
+}
+
 // --- validateProject stays here (cross-cutting across modules) ---
 
 /**
@@ -711,6 +720,15 @@ async function main() {
         error('Usage: learnings <ingest|query|check-thresholds>');
         process.exit(1);
       }
+    } else if (command === 'spot-check') {
+      // spot-check <phaseSlug> <planId>
+      // Returns JSON: { ok, summary_exists, key_files_checked, commits_present, detail }
+      const phaseSlug = args[1];
+      const planId = args[2];
+      if (!phaseSlug || !planId) {
+        error('Usage: spot-check <phaseSlug> <planId>');
+      }
+      output(spotCheck(phaseSlug, planId));
     } else if (command === 'validate-project') {
       output(validateProject());
     } else {
@@ -722,6 +740,6 @@ async function main() {
 }
 
 if (require.main === module || process.argv[1] === __filename) { main().catch(err => { process.stderr.write(err.message + '\n'); process.exit(1); }); }
-module.exports = { KNOWN_AGENTS, initExecutePhase, initPlanPhase, initQuick, initVerifyWork, initResume, initProgress, statePatch, stateAdvancePlan, stateRecordMetric, parseStateMd, parseRoadmapMd, parseYamlFrontmatter, parseMustHaves, countMustHaves, stateLoad, stateCheckProgress, configLoad, configClearCache, configValidate, lockedFileUpdate, planIndex, determinePhaseStatus, findFiles, atomicWrite, tailLines, frontmatter, mustHavesCollect, phaseInfo, stateUpdate, roadmapUpdateStatus, roadmapUpdatePlans, updateLegacyStateField, updateFrontmatterField, updateTableRow, findRoadmapRow, resolveDepthProfile, DEPTH_PROFILE_DEFAULTS, historyAppend, historyLoad, VALID_STATUS_TRANSITIONS, validateStatusTransition, writeActiveSkill, validateProject, phaseAdd, phaseRemove, phaseList, loadUserDefaults, saveUserDefaults, mergeUserDefaults, USER_DEFAULTS_PATH, todoList, todoGet, todoAdd, todoDone, migrate };
+module.exports = { KNOWN_AGENTS, initExecutePhase, initPlanPhase, initQuick, initVerifyWork, initResume, initProgress, statePatch, stateAdvancePlan, stateRecordMetric, parseStateMd, parseRoadmapMd, parseYamlFrontmatter, parseMustHaves, countMustHaves, stateLoad, stateCheckProgress, configLoad, configClearCache, configValidate, lockedFileUpdate, planIndex, determinePhaseStatus, findFiles, atomicWrite, tailLines, frontmatter, mustHavesCollect, phaseInfo, stateUpdate, roadmapUpdateStatus, roadmapUpdatePlans, updateLegacyStateField, updateFrontmatterField, updateTableRow, findRoadmapRow, resolveDepthProfile, DEPTH_PROFILE_DEFAULTS, historyAppend, historyLoad, VALID_STATUS_TRANSITIONS, validateStatusTransition, writeActiveSkill, validateProject, phaseAdd, phaseRemove, phaseList, loadUserDefaults, saveUserDefaults, mergeUserDefaults, USER_DEFAULTS_PATH, todoList, todoGet, todoAdd, todoDone, migrate, spotCheck };
 // NOTE: validateProject, phaseAdd, phaseRemove, phaseList were previously CLI-only (not exported).
 // They are now exported for testability. This is additive and backwards-compatible.

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

@@ -4,9 +4,13 @@
  * PostToolUse hook on Write|Edit: Tracks tool call count per session
  * and suggests /compact when approaching context limits.
  *
+ * Primary path: reads .planning/.context-budget.json (written by context-bridge.js)
+ * and emits tier-labeled warnings (DEGRADING/POOR/CRITICAL) when bridge data is
+ * fresh (<60s old). CRITICAL tier always emits; others use REMINDER_INTERVAL debounce.
+ *
+ * Fallback: when bridge is absent or stale, uses call-count threshold.
  * Counter stored in .planning/.compact-counter (JSON).
  * Threshold configurable via config.json hooks.compactThreshold (default: 50).
- * After first suggestion, re-suggests every 25 calls.
  * Counter resets on SessionStart (via progress-tracker.js).
  *
  * Exit codes:
@@ -17,6 +21,7 @@ const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
 const { configLoad } = require('./pbr-tools');
+const { loadBridge, TIER_MESSAGES } = require('./context-bridge');
 
 const DEFAULT_THRESHOLD = 50;
 const REMINDER_INTERVAL = 25;
@@ -43,8 +48,41 @@ function main() {
   });
 }
 
+/**
+ * Check the context bridge for the current tier.
+ * Returns { tier, message } for actionable tiers (DEGRADING/POOR/CRITICAL),
+ * or null if bridge is absent, stale (>60s), or tier is PEAK/GOOD (<50%).
+ * @param {string} planningDir - Path to .planning/ directory
+ * @returns {{ tier: string, message: string }|null}
+ */
+function checkBridgeTier(planningDir) {
+  const bridgePath = path.join(planningDir, '.context-budget.json');
+  const bridge = loadBridge(bridgePath);
+  if (!bridge) return null;
+
+  // Check staleness: if timestamp is older than 60 seconds, treat as stale
+  if (bridge.timestamp) {
+    const ageMs = Date.now() - new Date(bridge.timestamp).getTime();
+    if (ageMs > 60000) return null;
+  }
+
+  const percent = bridge.estimated_percent || 0;
+
+  if (percent >= 85) {
+    return { tier: 'CRITICAL', message: TIER_MESSAGES.CRITICAL };
+  } else if (percent >= 70) {
+    return { tier: 'POOR', message: TIER_MESSAGES.POOR };
+  } else if (percent >= 50) {
+    return { tier: 'DEGRADING', message: TIER_MESSAGES.DEGRADING };
+  }
+
+  // PEAK tier (<50%) — no tier message needed
+  return null;
+}
+
 /**
  * Increment tool call counter and return a suggestion if threshold is reached.
+ * Checks bridge tier first; falls back to call-count when bridge is absent or stale.
  * @param {string} planningDir - Path to .planning/ directory
  * @param {string} cwd - Current working directory (for config loading)
  * @returns {Object|null} Hook output with additionalContext, or null
@@ -57,6 +95,28 @@ function checkCompaction(planningDir, cwd) {
   counter.count += 1;
   saveCounter(counterPath, counter);
 
+  // Check bridge tier first
+  const bridgeTier = checkBridgeTier(planningDir);
+  if (bridgeTier !== null) {
+    const { tier, message } = bridgeTier;
+    const isFirstSuggestion = !counter.lastSuggested;
+    const callsSinceSuggestion = counter.count - (counter.lastSuggested || 0);
+    const shouldEmit = tier === 'CRITICAL' || isFirstSuggestion || callsSinceSuggestion >= REMINDER_INTERVAL;
+
+    if (shouldEmit) {
+      counter.lastSuggested = counter.count;
+      saveCounter(counterPath, counter);
+
+      logHook('suggest-compact', 'PostToolUse', 'tier-suggest', { tier, count: counter.count });
+
+      return {
+        additionalContext: `[Context Budget - ${tier}] ${message}`
+      };
+    }
+    return null;
+  }
+
+  // Fall back to counter-based suggestion when bridge is absent or stale
   if (counter.count < threshold) return null;
 
   const isFirstSuggestion = !counter.lastSuggested;
@@ -115,5 +175,5 @@ function resetCounter(planningDir) {
   }
 }
 
-module.exports = { checkCompaction, loadCounter, saveCounter, getThreshold, resetCounter, DEFAULT_THRESHOLD, REMINDER_INTERVAL };
+module.exports = { checkCompaction, checkBridgeTier, loadCounter, saveCounter, getThreshold, resetCounter, DEFAULT_THRESHOLD, REMINDER_INTERVAL };
 if (require.main === module || process.argv[1] === __filename) { main(); }

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

@@ -409,15 +409,40 @@ For each completed executor:
 
 **Spot-check executor claims:**
 
-After reading each SUMMARY, perform a lightweight verification:
-- Pick 2-3 files from the SUMMARY's `key_files` list and verify they exist (`ls`)
-- Run `git log --oneline -n {commit_count}` and confirm the count matches the claimed commits
-- For each spot-checked file, verify it has >10 lines (`wc -l`): warn if trivially small
-- For each spot-checked file, search for TODO/FIXME/placeholder/stub markers: warn if found
-- Check SUMMARY.md frontmatter for `self_check_failures`: if present, warn the user:
-  "Plan {id} reported self-check failures: {list failures}. Inspect before continuing?"
-- If ANY spot-check fails, warn the user before proceeding to the next wave:
-  "Spot-check failed for plan {id}: {detail}. Inspect before continuing?"
+CRITICAL: Before reading results or advancing to the next wave, run the spot-check CLI for each completed plan.
+
+For each completed plan in this wave:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js spot-check {phaseSlug} {planId}
+```
+
+Where `{phaseSlug}` is the phase directory name (e.g., `49-build-workflow-hardening`) and `{planId}` is the plan identifier (e.g., `49-01`).
+
+The command returns JSON: `{ ok, summary_exists, key_files_checked, commits_present, detail }`
+
+**If `ok` is `false` for ANY plan: STOP.** Do NOT advance to the next wave. Present the user with:
+
+```
+Spot-check FAILED for plan {planId}: {detail}
+
+Choose an action:
+  Retry   — Re-spawn executor for this plan
+  Continue — Skip this plan and proceed to next wave (may leave phase incomplete)
+  Abort   — Stop the build entirely
+```
+
+Use AskUserQuestion with the three options. Route:
+
+- Retry: Re-spawn the executor for this plan (go back to Step 6a for this plan only)
+- Continue: Log the failure, skip the plan, proceed
+- Abort: Stop all build work, leave phase in partial state
+
+**If `ok` is `true` for all plans:**
+
+- Also check SUMMARY.md frontmatter for `self_check_failures`: if present, warn the user: "Plan {id} reported self-check failures: {list}. Inspect before continuing?"
+- Also search SUMMARY.md for `## Self-Check: FAILED` marker — if present, warn before next wave
+- Between waves: verify no file conflicts from parallel executors (`git status` for uncommitted changes)
 
 **Additional wave spot-checks:**
 - Check for `## Self-Check: FAILED` in SUMMARY.md — if present, warn user before proceeding to next wave