@sienklogic/plan-build-run 2.42.0 → 2.43.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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.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)
+
+
+### Bug Fixes
+
+* **48-02:** use atomicWrite from core.js in circuit-state.js ([b294fe9](https://github.com/SienkLogic/plan-build-run/commit/b294fe96b4a9384293850180560184b3ac2cf8fc))
+
 ## [2.42.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.41.0...plan-build-run-v2.42.0) (2026-02-28)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.42.0",
+  "version": "2.43.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.0",
+  "version": "2.43.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/cursor-pbr/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.42.0",
+  "version": "2.43.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/pbr/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.42.0",
+  "version": "2.43.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/lib/circuit-state.js

@@ -11,6 +11,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { atomicWrite } = require('./core');
 
 const STALE_TTL_MS = 30 * 60 * 1000; // 30 minutes
 const STATE_FILENAME = 'local-llm-circuit.json';
@@ -68,9 +69,7 @@ function saveCircuitState(planningDir, state) {
       fs.mkdirSync(logsDir, { recursive: true });
     }
     const statePath = _statePath(planningDir);
-    const tmpPath = statePath + '.tmp.' + process.pid;
-    fs.writeFileSync(tmpPath, JSON.stringify(state, null, 2), 'utf8');
-    fs.renameSync(tmpPath, statePath);
+    atomicWrite(statePath, JSON.stringify(state, null, 2));
   } catch (_e) {
     // Best-effort — never crash the calling hook
   }

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(); }