@sienklogic/plan-build-run 2.52.0 → 2.53.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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.53.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.52.0...plan-build-run-v2.53.0) (2026-03-01)
+
+
+### Features
+
+* **54-03:** archive 5 dead reference docs and create signal-files.md ([4dff42d](https://github.com/SienkLogic/plan-build-run/commit/4dff42db3690b89dee04306bfe1562c0da789c60))
+* **54-04:** migrate signal file readers to sessionLoad with legacy fallback ([02d6ae9](https://github.com/SienkLogic/plan-build-run/commit/02d6ae9405ead3fdbe18239687ec312e02310e1e))
+
+
+### Bug Fixes
+
+* **54-04:** add comments to empty catch blocks to satisfy ESLint no-empty rule ([8280c54](https://github.com/SienkLogic/plan-build-run/commit/8280c5412b79bf61ca5ccdcb7cf82b9b3ca13be3))
+
 ## [2.52.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.51.0...plan-build-run-v2.52.0) (2026-03-01)
 
 

package/package.json

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

package/plugins/copilot-pbr/agents/executor.agent.md

@@ -132,8 +132,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/copilot-pbr/plugin.json

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

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.52.0",
+  "version": "2.53.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/agents/executor.md

@@ -134,8 +134,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/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/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.52.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/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/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/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);