@sienklogic/plan-build-run 2.51.0 → 2.53.0

package/plugins/cursor-pbr/templates/RESEARCH-SUMMARY.md.tmpl

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/templates/RESEARCH-SUMMARY.md.tmpl -->
 # Research Summary
 
 > Synthesized: {date}

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

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/templates/ROADMAP.md.tmpl -->
 # Project Roadmap
 
 > Generated: {date}

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

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/templates/SUMMARY.md.tmpl -->
 # SUMMARY.md Template
 
 > Referenced by: executor agent, build skill, review skill

package/plugins/cursor-pbr/templates/VERIFICATION-DETAIL.md.tmpl

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/templates/VERIFICATION-DETAIL.md.tmpl -->
 <!-- Source: agents/verifier.md | Purpose: Detailed output format for verification reports produced by the verifier agent -->
 
 ```yaml

package/plugins/cursor-pbr/templates/continue-here.md.tmpl

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/templates/continue-here.md.tmpl -->
 <!-- Source: skills/pause/SKILL.md | Purpose: Handoff file for session pause/resume, placed in the active phase directory -->
 
 # Template: Continue Here Handoff File

package/plugins/cursor-pbr/templates/prompt-partials/phase-project-context.md.tmpl

@@ -1,4 +1,3 @@
-<!-- canonical: ../../../pbr/templates/prompt-partials/phase-project-context.md.tmpl -->
 <!-- Source: templates/prompt-partials/ | Purpose: Shared context blocks for agent prompt templates -->
 <!-- Usage: Read this file and fill in placeholders, then include the result in agent prompts. -->
 <!-- Orchestrators should omit sections that don't apply to their agent type. -->

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

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.51.0",
+  "version": "2.53.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/agents/executor.md

@@ -141,8 +141,6 @@ Only append to the LAST commit of the plan — intermediate commits (RED/GREEN i
 
 ## Deviation Rules
 
-Reference: `references/deviation-rules.md` for examples and decision tree.
-
 | Rule | Trigger | Action | Approval |
 |------|---------|--------|----------|
 | 1 — Bug | Code bug (typo, wrong import, syntax) | Auto-fix in same commit. 3 attempts max. | No |

package/plugins/{cursor-pbr/references → pbr/references/archive}/agent-anti-patterns.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/agent-anti-patterns.md -->
 # Universal Agent Anti-Patterns
 
 These anti-patterns apply to ALL Plan-Build-Run agents. Each agent also has role-specific anti-patterns defined in its own agent file.

package/plugins/{copilot-pbr/references → pbr/references/archive}/pbr-rules.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/pbr-rules.md -->
 # Plan-Build-Run Rules
 
 Authoritative rules for all Plan-Build-Run skills, agents, hooks, and workflows.

package/plugins/pbr/references/signal-files.md

@@ -0,0 +1,41 @@
+# Signal Files Reference
+
+Signal files are ephemeral files in `.planning/` that coordinate state between hook scripts
+and skills. They are scoped to either the current session or the current phase/plan.
+
+## Session-Scoped Files
+
+All 5 session signals are consolidated in `.planning/.session.json`. Scripts must read and write
+`.session.json` via `pbr-tools session get|set|clear` — never read the raw `.session.json` file directly.
+The `.session.json` schema is an object with the keys documented below.
+
+| JSON Key | Former File | Written By | Read By | Semantics |
+|----------|-------------|------------|---------|-----------|
+| `activeSkill` | `.active-skill` | Skills (Write tool) | check-skill-workflow, enforce-pbr-workflow, check-subagent-output, log-subagent, block-skill-self-read | Which skill is active. Written at skill start, cleared at skill end (session-cleanup). |
+| `compactCounter` | `.compact-counter` | suggest-compact.js | suggest-compact.js | Write count since last /compact. Resets on SessionStart. |
+| `sessionStart` | `.session-start` | progress-tracker.js | local-llm metrics | ISO timestamp of session start. Used for LLM metrics correlation. |
+| `activeOperation` | `.active-operation` | context-budget-check.js | context-budget-check.js | Current named operation for budget display. |
+| `activePlan` | `.active-plan` | context-budget-check.js | context-budget-check.js | Current plan ID for budget display. |
+
+**Atomic access**: Use `pbr-tools session get|set|clear` for safe reads/writes from hook scripts.
+
+**Lifecycle**: Written during SessionStart (progress-tracker), cleared during SessionEnd (session-cleanup).
+Stale sessions (> 60 min) are auto-cleaned by progress-tracker.js on next SessionStart.
+
+## One-Shot Files
+
+These files are NOT consolidated — they use write-once, delete-on-read semantics.
+
+| File | Written By | Read By | Semantics |
+|------|------------|---------|-----------|
+| `.planning/.auto-next` | auto-continue.js | auto-continue.js (Stop hook) | Next command to run after session stops. Deleted after read. |
+| `.planning/.auto-verify` | event-handler.js | event-handler.js (SubagentStop hook) | Trigger auto-verification after agent completes. Deleted after read. |
+
+## Phase-Scoped Files
+
+These files persist across sessions, scoped to a specific phase or plan.
+
+| File Pattern | Written By | Read By | Semantics |
+|-------------|------------|---------|-----------|
+| `.planning/phases/{id}/.checkpoint-manifest.json` | build skill | validate-task.js, session-cleanup.js | Checkpoint state for a plan in progress. Cleaned up after 24h. |
+| `.planning/phases/{id}/.PROGRESS-{taskId}` | executor agent | validate-task.js | Task progress marker for crash recovery. Orphaned files warn on SessionStart. |

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

@@ -25,6 +25,7 @@ const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
 const { logEvent } = require('./event-logger');
+const { sessionLoad } = require('./pbr-tools');
 
 function main() {
   let input = '';
@@ -80,15 +81,13 @@ function main() {
 }
 
 function readActiveSkill(planningDir) {
-  const skillFile = path.join(planningDir, '.active-skill');
-  if (!fs.existsSync(skillFile)) return null;
-
-  try {
-    const content = fs.readFileSync(skillFile, 'utf8').trim();
-    return content || null;
-  } catch (_e) {
-    return null;
+  // Try .session.json first, fall back to legacy .active-skill
+  let activeSkill = sessionLoad(planningDir).activeSkill || null;
+  if (!activeSkill) {
+    try { activeSkill = fs.readFileSync(path.join(planningDir, '.active-skill'), 'utf8').trim(); } catch (_) { /* legacy file missing */ }
   }
+  // TODO(Phase 55+): Remove legacy .active-skill fallback once .session.json is confirmed stable
+  return activeSkill || null;
 }
 
 /**

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

@@ -20,7 +20,7 @@
 const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
-const { KNOWN_AGENTS } = require('./pbr-tools');
+const { KNOWN_AGENTS, sessionLoad } = require('./pbr-tools');
 const { resolveConfig } = require('./local-llm/health');
 const { classifyError } = require('./local-llm/operations/classify-error');
 
@@ -437,11 +437,12 @@ async function main() {
     process.exit(0);
   }
 
-  // Read active skill
-  let activeSkill = '';
-  try {
-    activeSkill = fs.readFileSync(path.join(planningDir, '.active-skill'), 'utf8').trim();
-  } catch (_e) { /* no active skill */ }
+  // Read active skill — try .session.json first, fall back to legacy .active-skill
+  let activeSkill = sessionLoad(planningDir).activeSkill || '';
+  if (!activeSkill) {
+    try { activeSkill = fs.readFileSync(path.join(planningDir, '.active-skill'), 'utf8').trim(); } catch (_) { /* legacy file missing */ }
+  }
+  // TODO(Phase 55+): Remove legacy .active-skill fallback once .session.json is confirmed stable
 
   // Check for expected outputs
   const found = outputSpec.check(planningDir);

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

@@ -21,7 +21,7 @@ const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
 const { logEvent } = require('./event-logger');
-const { configLoad, tailLines, lockedFileUpdate } = require('./pbr-tools');
+const { configLoad, tailLines, lockedFileUpdate, sessionLoad } = require('./pbr-tools');
 
 function main() {
   const cwd = process.cwd();
@@ -113,6 +113,12 @@ function main() {
 }
 
 function readActiveOperation(planningDir) {
+  // Try .session.json first (new), fall back to legacy .active-operation file
+  try {
+    const session = sessionLoad(planningDir);
+    if (session.activeOperation) return session.activeOperation;
+  } catch (_e) { /* fall through */ }
+
   const activeOpFile = path.join(planningDir, '.active-operation');
   if (!fs.existsSync(activeOpFile)) return '';
   try {
@@ -160,6 +166,12 @@ function readRoadmapSummary(planningDir) {
 }
 
 function readCurrentPlan(planningDir, stateContent) {
+  // Try .session.json first (new), then .active-plan file (legacy)
+  try {
+    const session = sessionLoad(planningDir);
+    if (session.activePlan) return session.activePlan;
+  } catch (_e) { /* fall through */ }
+
   // Prefer .active-plan signal file (definitive) over directory listing (guesswork)
   const activePlanFile = path.join(planningDir, '.active-plan');
   if (fs.existsSync(activePlanFile)) {

package/plugins/pbr/scripts/enforce-pbr-workflow.js

@@ -21,6 +21,7 @@
 const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
+const { sessionLoad } = require('./pbr-tools');
 
 /**
  * Load the enforcement configuration from .planning/config.json.
@@ -73,9 +74,13 @@ function checkUnmanagedSourceWrite(data) {
   // Skip if not a PBR project
   if (!fs.existsSync(planningDir)) return null;
 
-  // Skip if a PBR skill is active
-  const activeSkillFile = path.join(planningDir, '.active-skill');
-  if (fs.existsSync(activeSkillFile)) return null;
+  // Skip if a PBR skill is active — try .session.json first, fall back to legacy .active-skill
+  let activeSkill = sessionLoad(planningDir).activeSkill || '';
+  if (!activeSkill) {
+    try { activeSkill = fs.readFileSync(path.join(planningDir, '.active-skill'), 'utf8').trim(); } catch (_) { /* legacy file missing */ }
+  }
+  // TODO(Phase 55+): Remove legacy .active-skill fallback once .session.json is confirmed stable
+  if (activeSkill) return null;
 
   // Skip if writing inside .planning/
   const normalizedFile = filePath.replace(/\\/g, '/');
@@ -208,9 +213,13 @@ function checkUnmanagedCommit(data) {
   // Skip if not a PBR project
   if (!fs.existsSync(planningDir)) return null;
 
-  // Skip if a PBR skill is active
-  const activeSkillFile = path.join(planningDir, '.active-skill');
-  if (fs.existsSync(activeSkillFile)) return null;
+  // Skip if a PBR skill is active — try .session.json first, fall back to legacy .active-skill
+  let activeSkillCommit = sessionLoad(planningDir).activeSkill || '';
+  if (!activeSkillCommit) {
+    try { activeSkillCommit = fs.readFileSync(path.join(planningDir, '.active-skill'), 'utf8').trim(); } catch (_) { /* legacy file missing */ }
+  }
+  // TODO(Phase 55+): Remove legacy .active-skill fallback once .session.json is confirmed stable
+  if (activeSkillCommit) return null;
 
   const config = loadEnforcementConfig(planningDir);
   if (config.level === 'off') return null;

package/plugins/pbr/scripts/lib/core.js

@@ -450,8 +450,54 @@ function lockedFileUpdate(filePath, updateFn, opts = {}) {
   }
 }
 
+// --- Session state management (.planning/.session.json) ---
+
+const SESSION_ALLOWED_KEYS = ['activeSkill', 'compactCounter', 'sessionStart', 'activeOperation', 'activePlan'];
+
+/**
+ * Load .session.json from .planning/ directory.
+ * Returns parsed object or {} if file is missing or unreadable.
+ *
+ * @param {string} dir - Path to .planning/ directory
+ * @returns {object}
+ */
+function sessionLoad(dir) {
+  const sessionPath = path.join(dir, '.session.json');
+  try {
+    if (!fs.existsSync(sessionPath)) return {};
+    const content = fs.readFileSync(sessionPath, 'utf8');
+    return JSON.parse(content);
+  } catch (_e) {
+    return {};
+  }
+}
+
+/**
+ * Save data to .session.json using atomic write (write .tmp, then rename).
+ * Merges provided data with existing session data.
+ *
+ * @param {string} dir - Path to .planning/ directory
+ * @param {object} data - Key-value pairs to merge into session
+ * @returns {{ success: boolean, error?: string }}
+ */
+function sessionSave(dir, data) {
+  const sessionPath = path.join(dir, '.session.json');
+  const tmpPath = sessionPath + '.tmp';
+  try {
+    const existing = sessionLoad(dir);
+    const merged = Object.assign(existing, data);
+    fs.writeFileSync(tmpPath, JSON.stringify(merged, null, 2), 'utf8');
+    fs.renameSync(tmpPath, sessionPath);
+    return { success: true };
+  } catch (e) {
+    try { if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath); } catch (_) { /* cleanup */ }
+    return { success: false, error: e.message };
+  }
+}
+
 /**
  * Write .active-skill with OS-level mutual exclusion.
+ * Also writes activeSkill to .session.json for consolidated session tracking.
  *
  * @param {string} planningDir - Path to .planning/ directory
  * @param {string} skillName - Skill name to write
@@ -485,9 +531,12 @@ function writeActiveSkill(planningDir, skillName) {
       }
     }
 
-    // Write the skill name
+    // Write the skill name (legacy file — kept for backward compat with reader scripts)
     fs.writeFileSync(skillFile, skillName, 'utf8');
 
+    // Also write to .session.json for consolidated session tracking
+    try { sessionSave(planningDir, { activeSkill: skillName }); } catch (_e) { /* non-fatal */ }
+
     // Release lock
     try { fs.unlinkSync(lockFile); } catch (_e) { /* best effort */ }
 
@@ -585,5 +634,8 @@ module.exports = {
   atomicWrite,
   lockedFileUpdate,
   writeActiveSkill,
+  sessionLoad,
+  sessionSave,
+  SESSION_ALLOWED_KEYS,
   validateObject
 };

package/plugins/pbr/scripts/log-subagent.js

@@ -17,7 +17,7 @@ const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
 const { logEvent } = require('./event-logger');
-const { configLoad } = require('./pbr-tools');
+const { configLoad, sessionLoad } = require('./pbr-tools');
 
 function readStdin() {
   try {
@@ -136,16 +136,13 @@ function buildAgentContext() {
     }
   }
 
-  // Active skill context
-  const activeSkillFile = path.join(planningDir, '.active-skill');
-  if (fs.existsSync(activeSkillFile)) {
-    try {
-      const skill = fs.readFileSync(activeSkillFile, 'utf8').trim();
-      if (skill) parts.push(`Active skill: /pbr:${skill}`);
-    } catch (_e) {
-      // skip
-    }
+  // Active skill context — try .session.json first, fall back to legacy .active-skill
+  let activeSkill = sessionLoad(planningDir).activeSkill || '';
+  if (!activeSkill) {
+    try { activeSkill = fs.readFileSync(path.join(planningDir, '.active-skill'), 'utf8').trim(); } catch (_) { /* legacy file missing */ }
   }
+  // TODO(Phase 55+): Remove legacy .active-skill fallback once .session.json is confirmed stable
+  if (activeSkill) parts.push(`Active skill: /pbr:${activeSkill}`);
 
   // Config highlights
   const config = configLoad(planningDir);

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

@@ -46,6 +46,10 @@
  *   checkpoint init <phase-slug> [--plans "id1,id2"]  — Initialize checkpoint manifest
  *   checkpoint update <phase-slug> --wave N --resolved id [--sha hash]  — Update manifest
  *   seeds match <phase-slug> <phase-number>  — Find matching seed files for a phase
+ *   session get <key>              — Read a key from .planning/.session.json
+ *   session set <key> <value>      — Write a key to .planning/.session.json
+ *   session clear [key]            — Delete .session.json or set key to null
+ *   session dump                   — Print entire .session.json content
  *
  * Environment: PBR_PROJECT_ROOT — Override project root directory (used when hooks fire from subagent cwd)
  */
@@ -68,7 +72,10 @@ const {
   determinePhaseStatus,
   atomicWrite,
   lockedFileUpdate,
-  writeActiveSkill
+  writeActiveSkill,
+  sessionLoad,
+  sessionSave,
+  SESSION_ALLOWED_KEYS
 } = require('./lib/core');
 
 const {
@@ -833,6 +840,45 @@ async function main() {
       const manifestPath = args[1];
       if (!manifestPath) { error('Usage: pbr-tools.js rollback <manifest-path>'); return; }
       output(rollbackPlan(manifestPath));
+    } else if (command === 'session') {
+      const sub = args[1];
+      const key = args[2];
+      const value = args[3];
+      const dir = planningDir;
+      if (sub === 'get') {
+        if (!key) { error('Usage: pbr-tools.js session get <key>'); return; }
+        if (!SESSION_ALLOWED_KEYS.includes(key)) { error(`Unknown session key: ${key}. Allowed: ${SESSION_ALLOWED_KEYS.join(', ')}`); return; }
+        const data = sessionLoad(dir);
+        const val = Object.prototype.hasOwnProperty.call(data, key) ? data[key] : null;
+        output({ key, value: val });
+      } else if (sub === 'set') {
+        if (!key || value === undefined) { error('Usage: pbr-tools.js session set <key> <value>'); return; }
+        if (!SESSION_ALLOWED_KEYS.includes(key)) { error(`Unknown session key: ${key}. Allowed: ${SESSION_ALLOWED_KEYS.join(', ')}`); return; }
+        // Coerce numeric strings
+        let coerced = value;
+        if (/^\d+$/.test(value)) coerced = parseInt(value, 10);
+        else if (value === 'null') coerced = null;
+        const result = sessionSave(dir, { [key]: coerced });
+        if (!result.success) { error(result.error || 'Failed to save session'); return; }
+        output({ ok: true });
+      } else if (sub === 'clear') {
+        const sessionPath = path.join(dir, '.session.json');
+        if (key) {
+          // Clear a specific key — set to null
+          if (!SESSION_ALLOWED_KEYS.includes(key)) { error(`Unknown session key: ${key}. Allowed: ${SESSION_ALLOWED_KEYS.join(', ')}`); return; }
+          const result = sessionSave(dir, { [key]: null });
+          if (!result.success) { error(result.error || 'Failed to clear session key'); return; }
+        } else {
+          // Clear entire session file
+          try { if (fs.existsSync(sessionPath)) fs.unlinkSync(sessionPath); } catch (e) { error(e.message); return; }
+        }
+        output({ ok: true });
+      } else if (sub === 'dump') {
+        const data = sessionLoad(dir);
+        output(data);
+      } else {
+        error('Usage: pbr-tools.js session get|set|clear|dump <key> [value]');
+      }
     } else if (command === 'context-triage') {
       const options = {};
       const agentsIdx = args.indexOf('--agents-done');
@@ -856,7 +902,7 @@ async function main() {
     } else if (command === 'validate-project') {
       output(validateProject());
     } else {
-      error(`Unknown command: ${args.join(' ')}\nCommands: state load|check-progress|update|patch|advance-plan|record-metric, config validate|load-defaults|save-defaults|resolve-depth, validate-project, migrate [--dry-run] [--force], init execute-phase|plan-phase|quick|verify-work|resume|progress, state-bundle <phase>, plan-index, frontmatter, must-haves, phase-info, phase add|remove|list, roadmap update-status|update-plans, history append|load, todo list|get|add|done, event, llm health|status|classify|score-source|classify-error|summarize|metrics [--session <ISO>]|adjust-thresholds, learnings ingest|query|check-thresholds, milestone-stats <version>, context-triage [--agents-done N] [--plans-total N] [--step NAME], ci-poll <run-id> [--timeout <seconds>], rollback <manifest-path>`);
+      error(`Unknown command: ${args.join(' ')}\nCommands: state load|check-progress|update|patch|advance-plan|record-metric, config validate|load-defaults|save-defaults|resolve-depth, validate-project, migrate [--dry-run] [--force], init execute-phase|plan-phase|quick|verify-work|resume|progress, state-bundle <phase>, plan-index, frontmatter, must-haves, phase-info, phase add|remove|list, roadmap update-status|update-plans, history append|load, todo list|get|add|done, event, llm health|status|classify|score-source|classify-error|summarize|metrics [--session <ISO>]|adjust-thresholds, learnings ingest|query|check-thresholds, milestone-stats <version>, context-triage [--agents-done N] [--plans-total N] [--step NAME], ci-poll <run-id> [--timeout <seconds>], rollback <manifest-path>, session get|set|clear|dump`);
     }
   } catch (e) {
     error(e.message);
@@ -864,6 +910,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, initStateBundle: stateBundle, stateBundle, 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, referenceGet, milestoneStats, contextTriage, stalenessCheck, summaryGate, checkpointInit, checkpointUpdate, seedsMatch, ciPoll, rollbackPlan };
+module.exports = { KNOWN_AGENTS, initExecutePhase, initPlanPhase, initQuick, initVerifyWork, initResume, initProgress, initStateBundle: stateBundle, stateBundle, 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, referenceGet, milestoneStats, contextTriage, stalenessCheck, summaryGate, checkpointInit, checkpointUpdate, seedsMatch, ciPoll, rollbackPlan, sessionLoad, sessionSave, SESSION_ALLOWED_KEYS };
 // 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/progress-tracker.js

@@ -14,7 +14,7 @@ const os = require('os');
 const { execSync } = require('child_process');
 const { logHook } = require('./hook-logger');
 const { logEvent } = require('./event-logger');
-const { configLoad } = require('./pbr-tools');
+const { configLoad, sessionSave } = require('./pbr-tools');
 const { resolveConfig, checkHealth, warmUp } = require('./local-llm/health');
 
 async function main() {
@@ -40,9 +40,13 @@ async function main() {
   }
 
   // Write session-start timestamp for local-llm metrics correlation
+  // Primary: write to .session.json (unified session state)
+  // Legacy: also write .session-start file for session-cleanup.js backward compat
+  const sessionStart = new Date().toISOString();
+  try { sessionSave(planningDir, { sessionStart }); } catch (_e) { /* non-fatal */ }
   const sessionStartFile = path.join(planningDir, '.session-start');
   try {
-    fs.writeFileSync(sessionStartFile, new Date().toISOString(), 'utf8');
+    fs.writeFileSync(sessionStartFile, sessionStart, 'utf8');
   } catch (_e) { /* non-fatal */ }
 
   // Local LLM health check (advisory only — never blocks SessionStart)
@@ -217,14 +221,20 @@ function buildContext(planningDir, stateFile) {
   }
 
   // Check for stale .active-skill (multi-session conflict detection)
+  // Try .session.json first (new), fall back to .active-skill file (legacy)
   const activeSkillFile = path.join(planningDir, '.active-skill');
+  const { sessionLoad: _sessionLoad } = require('./pbr-tools');
+  const sessionData = _sessionLoad(planningDir);
+  const sessionActiveSkill = sessionData.activeSkill || null;
+
   if (fs.existsSync(activeSkillFile)) {
     try {
       const stats = fs.statSync(activeSkillFile);
       const ageMs = Date.now() - stats.mtimeMs;
       const ageMinutes = Math.floor(ageMs / 60000);
       if (ageMinutes > 60) {
-        const skill = fs.readFileSync(activeSkillFile, 'utf8').trim();
+        // Prefer skill name from .session.json if available
+        const skill = sessionActiveSkill || fs.readFileSync(activeSkillFile, 'utf8').trim();
         // Auto-cleanup stale .active-skill lock (> 60 minutes = certainly stale)
         try {
           fs.unlinkSync(activeSkillFile);

package/plugins/pbr/scripts/session-cleanup.js

@@ -216,6 +216,12 @@ function main() {
   // NOTE: .auto-next is intentionally NOT cleaned here — it is a one-shot
   // signal consumed by auto-continue.js (Stop hook). SessionEnd cleanup
   // races with the Stop hook and would delete the signal before it is read.
+
+  // Primary: remove .session.json (consolidated session state)
+  if (tryRemove(path.join(planningDir, '.session.json'))) {
+    cleaned.push('.session.json');
+  }
+  // Legacy fallback: also clean individual signal files during transition period
   if (tryRemove(path.join(planningDir, '.active-operation'))) {
     cleaned.push('.active-operation');
   }

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

@@ -20,7 +20,7 @@
 const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
-const { configLoad } = require('./pbr-tools');
+const { configLoad, sessionSave } = require('./pbr-tools');
 const { loadBridge, TIER_MESSAGES } = require('./context-bridge');
 
 const DEFAULT_THRESHOLD = 50;
@@ -155,6 +155,12 @@ function saveCounter(counterPath, counter) {
   } catch (_e) {
     // Best-effort
   }
+  // Mirror to .session.json for consolidated session state tracking
+  // Derive planningDir from counterPath (counterPath is planningDir/.compact-counter)
+  try {
+    const planningDir = path.dirname(counterPath);
+    sessionSave(planningDir, { compactCounter: counter });
+  } catch (_e) { /* non-fatal mirror */ }
 }
 
 function getThreshold(cwd) {
@@ -165,6 +171,12 @@ function getThreshold(cwd) {
 }
 
 function resetCounter(planningDir) {
+  // Primary: reset compactCounter in .session.json to 0
+  try {
+    sessionSave(planningDir, { compactCounter: { count: 0, lastSuggested: 0 } });
+  } catch (_e) { /* best-effort */ }
+
+  // Legacy: also delete .compact-counter file if present
   const counterPath = path.join(planningDir, '.compact-counter');
   try {
     if (fs.existsSync(counterPath)) {

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

@@ -168,7 +168,7 @@ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
 
 **After gathering preferences:**
 
-**CRITICAL: You MUST create the .planning/ directory and write config.json NOW. Do not proceed without this.**
+**CRITICAL (no hook): You MUST create the .planning/ directory and write config.json NOW. Do not proceed without this.**
 
 1. Read the config template from `skills/begin/templates/config.json.tmpl`
 2. Apply the user's choices to the template
@@ -177,7 +177,7 @@ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
 
 **IMPORTANT**: This step MUST happen BEFORE research (Step 5) because depth controls how many researchers to spawn.
 
-**CRITICAL: Write .active-skill NOW.** Write the text "begin" to `.planning/.active-skill` using the Write tool. Verify the file exists before proceeding.
+**CRITICAL (hook-enforced): Write .active-skill NOW.** Write the text "begin" to `.planning/.active-skill` using the Write tool. Verify the file exists before proceeding.
 
 ---
 
@@ -213,7 +213,7 @@ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
 
 Spawn parallel Task() subagents for research. Each researcher writes to `.planning/research/`.
 
-**CRITICAL: Create .planning/research/ directory NOW before spawning researchers. Do NOT skip this step.**
+**CRITICAL (no hook): Create .planning/research/ directory NOW before spawning researchers. Do NOT skip this step.**
 
 **Learnings injection (opt-in):** Before spawning researchers, check if global learnings exist:
 
@@ -258,7 +258,7 @@ Read `skills/begin/templates/researcher-prompt.md.tmpl` for the prompt structure
 
 ```
 <files_to_read>
-CRITICAL: Read these files BEFORE any other action:
+CRITICAL (no hook): Read these files BEFORE any other action:
 1. .planning/REQUIREMENTS.md — scoped requirements (if exists)
 {if learnings_temp_path exists}2. {learnings_temp_path} — cross-project learnings (tech stack patterns from past PBR projects){/if}
 </files_to_read>
@@ -338,7 +338,7 @@ 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:
+CRITICAL (no hook): Read these files BEFORE any other action:
 1. .planning/research/*.md — all research output files from Step 5
 </files_to_read>
 ```
@@ -406,7 +406,7 @@ Each requirement must be:
 
 **7e. Write REQUIREMENTS.md:**
 
-**CRITICAL: Write REQUIREMENTS.md NOW. The roadmap planner depends on this file.**
+**CRITICAL (no hook): Write REQUIREMENTS.md NOW. The roadmap planner depends on this file.**
 
 Read the template from `skills/begin/templates/REQUIREMENTS.md.tmpl` and write `.planning/REQUIREMENTS.md` with:
 - All v1 requirements grouped by category
@@ -441,7 +441,7 @@ 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:
+CRITICAL (no hook): 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>
@@ -477,9 +477,9 @@ CRITICAL: Read these files BEFORE any other action:
 
 Write the project state files from templates:
 
-**CRITICAL: You MUST write all 5 state initialization files (Steps 9a-9e). Do NOT skip any.**
+**CRITICAL (no hook): You MUST write all 5 state initialization files (Steps 9a-9e). Do NOT skip any.**
 
-**CRITICAL: Write PROJECT.md NOW. Do NOT skip this step.**
+**CRITICAL (no hook): Write PROJECT.md NOW. Do NOT skip this step.**
 
 **9a. Write PROJECT.md:**
 1. Read `skills/begin/templates/PROJECT.md.tmpl`
@@ -493,7 +493,7 @@ Write the project state files from templates:
 3. Write to `.planning/PROJECT.md`
 4. Ensure the `## Milestones` section is filled in with the project name and phase count from the roadmap
 
-**CRITICAL: Write STATE.md NOW. Do NOT skip this step.**
+**CRITICAL (no hook): Write STATE.md NOW. Do NOT skip this step.**
 
 **9b. Write STATE.md:**
 1. Read `skills/begin/templates/STATE.md.tmpl`
@@ -507,7 +507,7 @@ Write the project state files from templates:
 4. Fill in the `## Milestone` section with the project name and total phase count
 5. **STATE.md size limit**: Follow size limit enforcement rules in `skills/shared/state-update.md` (150 lines max).
 
-**CRITICAL: Write CONTEXT.md NOW. Do NOT skip this step.**
+**CRITICAL (no hook): Write CONTEXT.md NOW. Do NOT skip this step.**
 
 **9c. Write CONTEXT.md:**
 Create `.planning/CONTEXT.md` from information gathered during questioning:
@@ -533,7 +533,7 @@ Create `.planning/CONTEXT.md` from information gathered during questioning:
 | {feature} | {reason} |
 ```
 
-**CRITICAL: Write HISTORY.md NOW. Do NOT skip this step.**
+**CRITICAL (no hook): Write HISTORY.md NOW. Do NOT skip this step.**
 
 **9d. Write HISTORY.md:**
 Create `.planning/HISTORY.md` with an initial entry:
@@ -548,7 +548,7 @@ Create `.planning/HISTORY.md` with an initial entry:
 - Roadmap: {N} phases planned
 ```
 
-**CRITICAL: Create phase directories NOW. Do NOT skip this step.**
+**CRITICAL (no hook): Create phase directories NOW. Do NOT skip this step.**
 
 **9e. Create phase directories:**
 For each phase in the roadmap, create the directory structure: