@sienklogic/plan-build-run 2.40.1 → 2.41.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.41.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.40.1...plan-build-run-v2.41.0) (2026-02-28)
+
+
+### Features
+
+* **47-01:** expand stateUpdate to cover all 9 STATE.md frontmatter fields ([de6a6b3](https://github.com/SienkLogic/plan-build-run/commit/de6a6b3b3f577c436396927a4b5511b5163a527c))
+* **47-02:** add [@file](https://github.com/file): escape hatch tests and documentation ([6634f50](https://github.com/SienkLogic/plan-build-run/commit/6634f504c7e64f25caaecb0b06561c3a03b88d35))
+
+
+### Bug Fixes
+
+* **47-01:** update stale state update usage hint to list all 9 fields ([e0d0e39](https://github.com/SienkLogic/plan-build-run/commit/e0d0e39fa11c8a210b7f44f1e311f80ce761b6c6))
+
+
+### Documentation
+
+* **46-02:** add agent contract compliance audit for phase 46 ([78bca43](https://github.com/SienkLogic/plan-build-run/commit/78bca43bb1c37375c9b7bd3704d874d957f61b26))
+
 ## [2.40.1](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.40.0...plan-build-run-v2.40.1) (2026-02-27)
 
 

package/package.json

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

package/plugins/copilot-pbr/agents/dev-sync.agent.md

@@ -6,6 +6,14 @@ infer: true
 target: "github-copilot"
 ---
 
+<files_to_read>
+CRITICAL: If your spawn prompt contains a files_to_read block,
+you MUST Read every listed file BEFORE any other action.
+Skipping this causes hallucinated context and broken output.
+</files_to_read>
+
+> Default files: the changed pbr/ file path(s) provided in the spawn prompt
+
 # Cross-Plugin Sync Agent
 
 You are **dev-sync**, a specialized agent for the Plan-Build-Run project. Your sole job is to take changes made in `plugins/pbr/` and apply the equivalent changes to `plugins/cursor-pbr/` and `plugins/copilot-pbr/`, adjusting for each derivative's format requirements.

package/plugins/copilot-pbr/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.40.1",
+  "version": "2.41.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/plan-authoring.md

@@ -201,6 +201,43 @@ Two plans CONFLICT if their `files_modified` lists overlap. Conflicting plans:
 
 ---
 
+## @file: Output Pattern (Large Payloads)
+
+When a `pbr-tools` CLI command produces output exceeding 50,000 characters, the tool writes
+the JSON payload to a temporary file instead of emitting it inline. It then prints a single
+line of the form:
+
+```
+@file:/tmp/pbr-1234567890.json
+```
+
+This prevents stdout overflow in environments with limited buffer sizes (hooks, Task() runners).
+
+### Verify Step Pattern
+
+If a plan's `<verify>` step calls `pbr-tools` and inspects the output, guard against the
+`@file:` case:
+
+```bash
+OUT=$(node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load)
+if echo "$OUT" | grep -q '^@file:'; then
+  OUT=$(cat "${OUT#@file:}")
+fi
+echo "$OUT" | grep '"status"'
+```
+
+### Agent Prompt Handling
+
+When an agent receives `@file:` output from a spawned tool call, it must read the referenced
+file to obtain the actual JSON payload. The `@file:` prefix is a signal — not a path fragment
+to be appended to another command.
+
+Plan actions that spawn `pbr-tools` subcommands should instruct the agent:
+
+> If the output starts with `@file:`, read the file at that path to get the full JSON response.
+
+---
+
 ## Context Fidelity Checklist
 
 Before writing plan files, verify context compliance:

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

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.40.1",
+  "version": "2.41.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/dev-sync.md

@@ -5,6 +5,14 @@ model: sonnet
 readonly: false
 ---
 
+<files_to_read>
+CRITICAL: If your spawn prompt contains a files_to_read block,
+you MUST Read every listed file BEFORE any other action.
+Skipping this causes hallucinated context and broken output.
+</files_to_read>
+
+> Default files: the changed pbr/ file path(s) provided in the spawn prompt
+
 # Cross-Plugin Sync Agent
 
 You are **dev-sync**, a specialized agent for the Plan-Build-Run project. Your sole job is to take changes made in `plugins/pbr/` and apply the equivalent changes to `plugins/cursor-pbr/` and `plugins/copilot-pbr/`, adjusting for each derivative's format requirements.

package/plugins/cursor-pbr/references/plan-authoring.md

@@ -201,6 +201,43 @@ Two plans CONFLICT if their `files_modified` lists overlap. Conflicting plans:
 
 ---
 
+## @file: Output Pattern (Large Payloads)
+
+When a `pbr-tools` CLI command produces output exceeding 50,000 characters, the tool writes
+the JSON payload to a temporary file instead of emitting it inline. It then prints a single
+line of the form:
+
+```
+@file:/tmp/pbr-1234567890.json
+```
+
+This prevents stdout overflow in environments with limited buffer sizes (hooks, Task() runners).
+
+### Verify Step Pattern
+
+If a plan's `<verify>` step calls `pbr-tools` and inspects the output, guard against the
+`@file:` case:
+
+```bash
+OUT=$(node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load)
+if echo "$OUT" | grep -q '^@file:'; then
+  OUT=$(cat "${OUT#@file:}")
+fi
+echo "$OUT" | grep '"status"'
+```
+
+### Agent Prompt Handling
+
+When an agent receives `@file:` output from a spawned tool call, it must read the referenced
+file to obtain the actual JSON payload. The `@file:` prefix is a signal — not a path fragment
+to be appended to another command.
+
+Plan actions that spawn `pbr-tools` subcommands should instruct the agent:
+
+> If the output starts with `@file:`, read the file at that path to get the full JSON response.
+
+---
+
 ## Context Fidelity Checklist
 
 Before writing plan files, verify context compliance:

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

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.40.1",
+  "version": "2.41.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/dev-sync.md

@@ -12,6 +12,14 @@ tools:
   - Grep
 ---
 
+<files_to_read>
+CRITICAL: If your spawn prompt contains a files_to_read block,
+you MUST Read every listed file BEFORE any other action.
+Skipping this causes hallucinated context and broken output.
+</files_to_read>
+
+> Default files: the changed pbr/ file path(s) provided in the spawn prompt
+
 # Cross-Plugin Sync Agent
 
 You are **dev-sync**, a specialized agent for the Plan-Build-Run project. Your sole job is to take changes made in `plugins/pbr/` and apply the equivalent changes to `plugins/cursor-pbr/` and `plugins/copilot-pbr/`, adjusting for each derivative's format requirements.

package/plugins/pbr/references/plan-authoring.md

@@ -200,6 +200,43 @@ Two plans CONFLICT if their `files_modified` lists overlap. Conflicting plans:
 
 ---
 
+## @file: Output Pattern (Large Payloads)
+
+When a `pbr-tools` CLI command produces output exceeding 50,000 characters, the tool writes
+the JSON payload to a temporary file instead of emitting it inline. It then prints a single
+line of the form:
+
+```
+@file:/tmp/pbr-1234567890.json
+```
+
+This prevents stdout overflow in environments with limited buffer sizes (hooks, Task() runners).
+
+### Verify Step Pattern
+
+If a plan's `<verify>` step calls `pbr-tools` and inspects the output, guard against the
+`@file:` case:
+
+```bash
+OUT=$(node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load)
+if echo "$OUT" | grep -q '^@file:'; then
+  OUT=$(cat "${OUT#@file:}")
+fi
+echo "$OUT" | grep '"status"'
+```
+
+### Agent Prompt Handling
+
+When an agent receives `@file:` output from a spawned tool call, it must read the referenced
+file to obtain the actual JSON payload. The `@file:` prefix is a signal — not a path fragment
+to be appended to another command.
+
+Plan actions that spawn `pbr-tools` subcommands should instruct the agent:
+
+> If the output starts with `@file:`, read the file at that path to get the full JSON response.
+
+---
+
 ## Context Fidelity Checklist
 
 Before writing plan files, verify context compliance:

package/plugins/pbr/scripts/check-plan-format.js

@@ -56,7 +56,7 @@ async function main() {
 
       // Determine file type
       const basename = path.basename(filePath);
-      const isPlan = /PLAN.*\.md$/i.test(basename);
+      const isPlan = /^PLAN.*\.md$/.test(basename);
       const isSummary = basename.includes('SUMMARY') && basename.endsWith('.md');
       const isVerification = basename === 'VERIFICATION.md';
       const isRoadmap = basename === 'ROADMAP.md';
@@ -276,7 +276,7 @@ function validateSummary(content, _filePath) {
 async function checkPlanWrite(data) {
   const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
   const basename = path.basename(filePath);
-  const isPlan = /PLAN.*\.md$/i.test(basename);
+  const isPlan = /^PLAN.*\.md$/.test(basename);
   const isSummary = basename.includes('SUMMARY') && basename.endsWith('.md');
   const isVerification = basename === 'VERIFICATION.md';
   const isRoadmap = basename === 'ROADMAP.md';

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

@@ -281,7 +281,8 @@ function stateCheckProgress(planningDir) {
  * Atomically update a field in STATE.md using lockedFileUpdate.
  * Supports both legacy and frontmatter (v2) formats.
  *
- * @param {string} field - One of: current_phase, status, plans_complete, last_activity
+ * @param {string} field - One of: current_phase, status, plans_complete, last_activity,
+ *   progress_percent, phase_slug, total_phases, last_command, blockers
  * @param {string} value - New value (use 'now' for last_activity to auto-timestamp)
  * @param {string} [planningDir] - Path to .planning directory
  */
@@ -292,7 +293,18 @@ function stateUpdate(field, value, planningDir) {
     return { success: false, error: 'STATE.md not found' };
   }
 
-  const validFields = ['current_phase', 'status', 'plans_complete', 'last_activity'];
+  // All 9 STATE.md frontmatter fields supported by stateUpdate
+  const validFields = [
+    'current_phase',
+    'status',
+    'plans_complete',
+    'last_activity',
+    'progress_percent',
+    'phase_slug',
+    'total_phases',
+    'last_command',
+    'blockers'
+  ];
   if (!validFields.includes(field)) {
     return { success: false, error: `Invalid field: ${field}. Valid fields: ${validFields.join(', ')}` };
   }

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

@@ -417,7 +417,7 @@ async function main() {
       const field = args[2];
       const value = args[3];
       if (!field || value === undefined) {
-        error('Usage: pbr-tools.js state update <field> <value>\nFields: current_phase, status, plans_complete, last_activity');
+        error('Usage: pbr-tools.js state update <field> <value>\nFields: current_phase, status, plans_complete, last_activity, progress_percent, phase_slug, total_phases, last_command, blockers');
       }
       output(stateUpdate(field, value));
     } else if (command === 'config' && subcommand === 'validate') {