@sienklogic/plan-build-run 2.21.1 → 2.22.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ 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.22.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.21.1...plan-build-run-v2.22.0) (2026-02-23)
+
+
+### Features
+
+* **24-01:** add check-agent-state-write.js module ([b73ab69](https://github.com/SienkLogic/plan-build-run/commit/b73ab69d8893970595d538a6289d8183b7b08b2b))
+* **24-01:** wire agent state write blocker into pre-write-dispatch ([9f46053](https://github.com/SienkLogic/plan-build-run/commit/9f460530d21e4c3f37389f0bd2731ad0fd99e593))
+* **24-02:** add .auto-next fallback writes to auto_advance hard stops in build skill ([9d59fc1](https://github.com/SienkLogic/plan-build-run/commit/9d59fc13b494cacdbe71e4e236d89bba0724a412))
+* **25-01:** add ROADMAP.md read to continue skill for milestone boundary detection ([49482c2](https://github.com/SienkLogic/plan-build-run/commit/49482c2a7c0fbe49a39b215bf9070381295daa1c))
+* **25-01:** GREEN - add validateRoadmap and ROADMAP.md validation to check-plan-format ([73256de](https://github.com/SienkLogic/plan-build-run/commit/73256dea9ea9c86a55dbd63fe057678e9757a798))
+* **25-01:** GREEN - PLAN.md writes trigger ROADMAP Planning status without regression ([e8e028a](https://github.com/SienkLogic/plan-build-run/commit/e8e028ae3528a856a8c406a3b508802550e0f75f))
+* **25-02:** GREEN - add checkRoadmapWrite routing to post-write-dispatch ([c7db2e0](https://github.com/SienkLogic/plan-build-run/commit/c7db2e0a4433a962a4f499941b29927a16583425))
+* **25-02:** GREEN - implement isHighRisk with status regression and phase gap detection ([cea48b4](https://github.com/SienkLogic/plan-build-run/commit/cea48b4ccce2554a7c698af280e2725a233e69cb))
+* **25-02:** GREEN - implement validatePostMilestone for milestone completion checks ([c666de8](https://github.com/SienkLogic/plan-build-run/commit/c666de84530eb7a6310a8def7744cec4ff5f8358))
+* **26-02:** GREEN - add 150-line advisory warning to checkStateWrite ([9374009](https://github.com/SienkLogic/plan-build-run/commit/937400997580e9666f9efa18b4e0a80c5fe3b668))
+* **26-02:** GREEN - add cross-plugin sync advisory hook ([a55ad12](https://github.com/SienkLogic/plan-build-run/commit/a55ad1273a7193cc521cd6e953ea185f51e7af50))
+* **27-01:** add PreToolUse Read hook to block SKILL.md self-reads ([afe6acd](https://github.com/SienkLogic/plan-build-run/commit/afe6acd8a55a0807e28266b35b2f4fe961c9ecf5))
+* **27-01:** add session length guard to auto-continue with warn at 3, hard-stop at 6 ([fd394d8](https://github.com/SienkLogic/plan-build-run/commit/fd394d893f2e7d93ad4a4bb29acd0a889da3fd67))
+
+
+### Bug Fixes
+
+* **24-01:** remove building from ADVANCED_STATUSES gate ([6e1fdf7](https://github.com/SienkLogic/plan-build-run/commit/6e1fdf7fb3897efdb1dca2ef77dbab78bab13ed2))
+* **24-02:** raise consecutive-continue guard threshold from 3 to 6 ([918394c](https://github.com/SienkLogic/plan-build-run/commit/918394c34356f84772a4454061b312601f8ca26d))
+* **24-02:** remove .auto-next cleanup from session-cleanup to prevent race with Stop hook ([d86e39e](https://github.com/SienkLogic/plan-build-run/commit/d86e39e48b51a3765e42c2807ee7ef277f8d3a5d))
+* **25-02:** remove unused path import and result variable (lint) ([f84764a](https://github.com/SienkLogic/plan-build-run/commit/f84764ae3b4a5fce09a7d126624bb1719c57c10b))
+* **26-01:** add CRITICAL dual-update markers to import Step 8b and milestone new Step 8 ([36bd68c](https://github.com/SienkLogic/plan-build-run/commit/36bd68c42d2fc556581de8f2f23a7b9d6447392b))
+* **26-01:** add CRITICAL frontmatter update marker to pause skill STATE.md step ([ec35f3b](https://github.com/SienkLogic/plan-build-run/commit/ec35f3b529c1fe2b2928bb8ef97d768b101f2f0b))
+* **26-02:** sync cross-plugin-sync hook to cursor-pbr and copilot-pbr hooks.json ([2083a1d](https://github.com/SienkLogic/plan-build-run/commit/2083a1d11c1ced3c7f2b4dc83df2c2a4ed684529))
+
+
+### Documentation
+
+* **27-01:** add no-reread anti-pattern to executor agents across all plugins ([8b572fa](https://github.com/SienkLogic/plan-build-run/commit/8b572fa6f43dfc3fe1a0ae8caf167ce2351f46f9))
+
 ## [2.21.1](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.21.0...plan-build-run-v2.21.1) (2026-02-23)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.21.1",
+  "version": "2.22.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

@@ -254,6 +254,7 @@ Record timestamps at start and end using `node -e "console.log(new Date().toISOS
 11. DO NOT continue past a checkpoint — STOP means STOP
 12. DO NOT re-execute completed tasks when continuing
 13. DO NOT force-push or amend commits
+14. DO NOT re-read PLAN.md or PLAN files if the plan was already provided in your prompt context — this wastes tokens on redundant reads
 
 ---
 

package/plugins/copilot-pbr/hooks/hooks.json

@@ -91,6 +91,18 @@
       }
     ],
     "preToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" block-skill-self-read.js",
+            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') block-skill-self-read.js",
+            "cwd": ".",
+            "timeoutSec": 15
+          }
+        ]
+      },
       {
         "matcher": "Bash",
         "hooks": [
@@ -103,6 +115,18 @@
           }
         ]
       },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" check-cross-plugin-sync.js",
+            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') check-cross-plugin-sync.js",
+            "cwd": ".",
+            "timeoutSec": 15
+          }
+        ]
+      },
       {
         "matcher": "Write|Edit",
         "hooks": [

package/plugins/copilot-pbr/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.21.1",
+  "version": "2.22.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

@@ -751,9 +751,9 @@ Chain to the next skill directly within this session. This eliminates manual pha
 |-------------|-------------|-----|
 | Verification passed, more phases | Plan next phase | `Skill({ skill: "pbr:plan", args: "{N+1}" })` |
 | Verification skipped | Run review | `Skill({ skill: "pbr:review", args: "{N}" })` |
-| Verification gaps found | **HARD STOP** — present gaps to user | Do NOT auto-advance past failures |
-| Last phase in current milestone | **HARD STOP** — milestone boundary | Suggest `/pbr:milestone audit`. Explain: "auto_advance pauses at milestone boundaries — your sign-off is required." |
-| Build errors occurred | **HARD STOP** — errors need human review | Do NOT auto-advance past errors |
+| Verification gaps found | **HARD STOP** — present gaps to user | If `auto_continue` also true: write `.planning/.auto-next` with `/pbr:review {N}` before stopping. Do NOT auto-advance past failures. |
+| Last phase in current milestone | **HARD STOP** — milestone boundary | If `auto_continue` also true: write `.planning/.auto-next` with `/pbr:milestone complete` before stopping. Suggest `/pbr:milestone audit`. Explain: "auto_advance pauses at milestone boundaries — your sign-off is required." |
+| Build errors occurred | **HARD STOP** — errors need human review | If `auto_continue` also true: write `.planning/.auto-next` with `/pbr:build {N}` before stopping. Do NOT auto-advance past errors. |
 
 After invoking the chained skill, it runs within the same session. When it completes, the chained skill may itself chain further (review→plan, plan→build) if auto_advance remains true. This creates the full cycle: build→review→plan→build→...
 

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

@@ -48,6 +48,12 @@ Read `.planning/STATE.md` and determine current position:
 - Current plan progress
 - Phase status (planning, building, reviewing, complete)
 
+Then read `.planning/ROADMAP.md` to identify the current milestone boundary:
+- Find which `## Milestone:` section contains the current phase
+- Determine if the current phase is the **last phase** in that milestone section
+- If this is the last phase and it is verified/complete, warn: "This is the final phase of milestone {name}. After verification, run `/pbr:milestone` to complete it."
+- If the current phase's `Depends on` references a phase from the **previous** milestone that is not yet complete, warn: "Cross-milestone dependency: Phase {N} depends on Phase {M} from milestone {prev}, which is not yet complete."
+
 If STATE.md doesn't exist, display:
 ```
 ERROR
@@ -67,10 +73,10 @@ Before proceeding to priority evaluation, check for runaway continue chains:
    - Check `.planning/.active-skill` file — if it contains `continue`, treat as a chained continue
    - Check STATE.md `last_action` field — if it contains `continue`, treat as a chained continue
    - If neither source is available, assume this is the first invocation (do not warn)
-4. **If this is the 3rd consecutive `/pbr:continue` in a row**, display:
+4. **If this is the 6th consecutive `/pbr:continue` in a row**, display:
 
 ```
-WARNING: Context budget warning: 3 consecutive auto-continues detected.
+WARNING: Context budget warning: 6 consecutive auto-continues detected.
 Recommend running /pbr:pause then resuming in a fresh session.
 ```
 

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

@@ -337,6 +337,8 @@ Perform all state updates in this order:
 5. Update the `Status` column to `planned`
 6. Save the file — do NOT skip this step
 
+**CRITICAL -- DO NOT SKIP: Update STATE.md frontmatter AND body with import status.**
+
 **8b. Update STATE.md:**
 - Set current phase plan status to "planned"
 - Note source: "imported from {filepath}" or "imported from user input"

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

@@ -146,6 +146,8 @@ Start a new milestone cycle with new phases.
    - **Status:** In progress
    ```
 
+**CRITICAL -- DO NOT SKIP: Update STATE.md frontmatter AND body with new milestone info.**
+
 8. **Update STATE.md:**
    - Set current phase to the first new phase
    - Update milestone info

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

@@ -130,7 +130,13 @@ Read `skills/pause/templates/continue-here.md.tmpl` for the handoff file format.
 
 ### Step 5: Update STATE.md
 
-Update the Session Continuity section of STATE.md:
+**CRITICAL -- DO NOT SKIP: Update STATE.md frontmatter AND body. Both must be updated atomically.**
+
+First, update the STATE.md YAML frontmatter:
+- Set `last_command: "/pbr:pause"`
+- Set `last_activity: {ISO datetime}`
+
+Then update the Session Continuity section of STATE.md:
 
 ```markdown
 ### Session Continuity

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

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.21.1",
+  "version": "2.22.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

@@ -253,6 +253,7 @@ Record timestamps at start and end using `node -e "console.log(new Date().toISOS
 11. DO NOT continue past a checkpoint — STOP means STOP
 12. DO NOT re-execute completed tasks when continuing
 13. DO NOT force-push or amend commits
+14. DO NOT re-read PLAN.md or PLAN files if the plan was already provided in your prompt context — this wastes tokens on redundant reads
 
 ---
 

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

@@ -77,6 +77,16 @@
       }
     ],
     "PreToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" block-skill-self-read.js",
+            "statusMessage": "Checking skill self-read..."
+          }
+        ]
+      },
       {
         "matcher": "Bash",
         "hooks": [
@@ -87,6 +97,16 @@
           }
         ]
       },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" check-cross-plugin-sync.js",
+            "statusMessage": "Checking cross-plugin sync..."
+          }
+        ]
+      },
       {
         "matcher": "Write|Edit",
         "hooks": [

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

@@ -752,9 +752,9 @@ Chain to the next skill directly within this session. This eliminates manual pha
 |-------------|-------------|-----|
 | Verification passed, more phases | Plan next phase | `Skill({ skill: "pbr:plan", args: "{N+1}" })` |
 | Verification skipped | Run review | `Skill({ skill: "pbr:review", args: "{N}" })` |
-| Verification gaps found | **HARD STOP** — present gaps to user | Do NOT auto-advance past failures |
-| Last phase in current milestone | **HARD STOP** — milestone boundary | Suggest `/pbr:milestone audit`. Explain: "auto_advance pauses at milestone boundaries — your sign-off is required." |
-| Build errors occurred | **HARD STOP** — errors need human review | Do NOT auto-advance past errors |
+| Verification gaps found | **HARD STOP** — present gaps to user | If `auto_continue` also true: write `.planning/.auto-next` with `/pbr:review {N}` before stopping. Do NOT auto-advance past failures. |
+| Last phase in current milestone | **HARD STOP** — milestone boundary | If `auto_continue` also true: write `.planning/.auto-next` with `/pbr:milestone complete` before stopping. Suggest `/pbr:milestone audit`. Explain: "auto_advance pauses at milestone boundaries — your sign-off is required." |
+| Build errors occurred | **HARD STOP** — errors need human review | If `auto_continue` also true: write `.planning/.auto-next` with `/pbr:build {N}` before stopping. Do NOT auto-advance past errors. |
 
 After invoking the chained skill, it runs within the same session. When it completes, the chained skill may itself chain further (review→plan, plan→build) if auto_advance remains true. This creates the full cycle: build→review→plan→build→...
 

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

@@ -48,6 +48,12 @@ Read `.planning/STATE.md` and determine current position:
 - Current plan progress
 - Phase status (planning, building, reviewing, complete)
 
+Then read `.planning/ROADMAP.md` to identify the current milestone boundary:
+- Find which `## Milestone:` section contains the current phase
+- Determine if the current phase is the **last phase** in that milestone section
+- If this is the last phase and it is verified/complete, warn: "This is the final phase of milestone {name}. After verification, run `/pbr:milestone` to complete it."
+- If the current phase's `Depends on` references a phase from the **previous** milestone that is not yet complete, warn: "Cross-milestone dependency: Phase {N} depends on Phase {M} from milestone {prev}, which is not yet complete."
+
 If STATE.md doesn't exist, display:
 ```
 ERROR
@@ -67,10 +73,10 @@ Before proceeding to priority evaluation, check for runaway continue chains:
    - Check `.planning/.active-skill` file — if it contains `continue`, treat as a chained continue
    - Check STATE.md `last_action` field — if it contains `continue`, treat as a chained continue
    - If neither source is available, assume this is the first invocation (do not warn)
-4. **If this is the 3rd consecutive `/pbr:continue` in a row**, display:
+4. **If this is the 6th consecutive `/pbr:continue` in a row**, display:
 
 ```
-WARNING: Context budget warning: 3 consecutive auto-continues detected.
+WARNING: Context budget warning: 6 consecutive auto-continues detected.
 Recommend running /pbr:pause then resuming in a fresh session.
 ```
 

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

@@ -338,6 +338,8 @@ Perform all state updates in this order:
 5. Update the `Status` column to `planned`
 6. Save the file — do NOT skip this step
 
+**CRITICAL -- DO NOT SKIP: Update STATE.md frontmatter AND body with import status.**
+
 **8b. Update STATE.md:**
 - Set current phase plan status to "planned"
 - Note source: "imported from {filepath}" or "imported from user input"

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

@@ -147,6 +147,8 @@ Start a new milestone cycle with new phases.
    - **Status:** In progress
    ```
 
+**CRITICAL -- DO NOT SKIP: Update STATE.md frontmatter AND body with new milestone info.**
+
 8. **Update STATE.md:**
    - Set current phase to the first new phase
    - Update milestone info

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

@@ -130,7 +130,13 @@ Read `skills/pause/templates/continue-here.md.tmpl` for the handoff file format.
 
 ### Step 5: Update STATE.md
 
-Update the Session Continuity section of STATE.md:
+**CRITICAL -- DO NOT SKIP: Update STATE.md frontmatter AND body. Both must be updated atomically.**
+
+First, update the STATE.md YAML frontmatter:
+- Set `last_command: "/pbr:pause"`
+- Set `last_activity: {ISO datetime}`
+
+Then update the Session Continuity section of STATE.md:
 
 ```markdown
 ### Session Continuity

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

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.21.1",
+  "version": "2.22.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

@@ -260,6 +260,7 @@ Record timestamps at start and end using `node -e "console.log(new Date().toISOS
 11. DO NOT continue past a checkpoint — STOP means STOP
 12. DO NOT re-execute completed tasks when continuing
 13. DO NOT force-push or amend commits
+14. DO NOT re-read PLAN.md or PLAN files if the plan was already provided in your prompt context — this wastes tokens on redundant reads
 
 ---
 

package/plugins/pbr/hooks/hooks.json

@@ -77,6 +77,16 @@
       }
     ],
     "PreToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" block-skill-self-read.js",
+            "statusMessage": "Checking skill self-read..."
+          }
+        ]
+      },
       {
         "matcher": "Bash",
         "hooks": [
@@ -87,6 +97,16 @@
           }
         ]
       },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" check-cross-plugin-sync.js",
+            "statusMessage": "Checking cross-plugin sync..."
+          }
+        ]
+      },
       {
         "matcher": "Write|Edit",
         "hooks": [

package/plugins/pbr/scripts/auto-continue.js

@@ -63,6 +63,9 @@ function main() {
       } catch (_todoErr) {
         // Ignore errors scanning todos
       }
+      // Reset continue count on normal session stop (no signal)
+      const countPathNoSig = path.join(planningDir, '.continue-count');
+      try { fs.unlinkSync(countPathNoSig); } catch (_e) { /* ignore */ }
       logHook('auto-continue', 'Stop', 'no-signal', {});
       process.exit(0);
     }
@@ -97,19 +100,40 @@ function main() {
       process.exit(0);
     }
 
+    // Track consecutive continues for session length guard
+    const countPath = path.join(planningDir, '.continue-count');
+    let continueCount = 0;
+    try {
+      continueCount = parseInt(fs.readFileSync(countPath, 'utf8').trim(), 10) || 0;
+    } catch (_e) { /* file missing — start at 0 */ }
+    continueCount++;
+    try { fs.writeFileSync(countPath, String(continueCount)); } catch (_e) { /* ignore */ }
+
+    // Hard stop after 6 consecutive continues — context is likely degraded
+    if (continueCount > 6) {
+      logHook('auto-continue', 'Stop', 'hard-stop-session-length', { count: continueCount });
+      process.exit(0);
+    }
+
     // Extract last_assistant_message for richer continuation context
     const lastMsg = hookInput.last_assistant_message || '';
     const msgSuffix = lastMsg
       ? ` (last message excerpt: ${lastMsg.slice(0, 200)})`
       : '';
 
-    logHook('auto-continue', 'Stop', 'continue', { next: nextCommand, hasLastMsg: !!lastMsg });
+    logHook('auto-continue', 'Stop', 'continue', { next: nextCommand, hasLastMsg: !!lastMsg, continueCount });
+
+    // Build reason string with optional advisory
+    let reasonStr = `Auto-continue: execute ${nextCommand}${msgSuffix}`;
+    if (continueCount > 3) {
+      reasonStr += `\n\n[pbr] Advisory: ${continueCount} consecutive continues. Consider /pbr:pause + fresh session to avoid context degradation.`;
+    }
 
     // Block the stop and inject the next command as Claude's continuation reason.
     // Claude Code Stop hooks use { decision: "block", reason: "..." } to keep going.
     const output = {
       decision: 'block',
-      reason: `Auto-continue: execute ${nextCommand}${msgSuffix}`
+      reason: reasonStr
     };
     process.stdout.write(JSON.stringify(output));
     process.exit(0);

package/plugins/pbr/scripts/block-skill-self-read.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse Read hook: blocks skills from re-reading their own SKILL.md.
+ *
+ * Skills are already loaded into context by Claude Code — re-reading
+ * wastes ~13k tokens. This hook checks .planning/.active-skill to
+ * determine the current skill and blocks if the Read target matches.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+function main() {
+  try {
+    let hookInput = {};
+    try {
+      const stdin = fs.readFileSync(0, 'utf8').trim();
+      if (stdin) hookInput = JSON.parse(stdin);
+    } catch (_parseErr) {
+      // No stdin or invalid JSON
+    }
+
+    const cwd = hookInput.cwd || process.cwd();
+    const toolInput = hookInput.tool_input || {};
+    const filePath = toolInput.file_path || '';
+
+    if (!filePath) {
+      process.exit(0);
+    }
+
+    // Read .active-skill to get current skill name
+    const activeSkillPath = path.join(cwd, '.planning', '.active-skill');
+    let skillName = '';
+    try {
+      skillName = fs.readFileSync(activeSkillPath, 'utf8').trim();
+    } catch (_readErr) {
+      // No .active-skill file — nothing to block
+      process.exit(0);
+    }
+
+    if (!skillName) {
+      process.exit(0);
+    }
+
+    // Check if file_path ends with skills/{skill-name}/SKILL.md
+    const normalized = filePath.replace(/\\/g, '/');
+    const pattern = `skills/${skillName}/SKILL.md`.toLowerCase();
+    const match = normalized.toLowerCase().endsWith(pattern);
+
+    if (match) {
+      logHook('block-skill-self-read', 'PreToolUse', 'block', { skill: skillName, file: filePath });
+      const output = {
+        decision: 'block',
+        reason: `SKILL.md self-read blocked.\n\nThe active skill (${skillName}) attempted to read its own SKILL.md. Skills are already loaded into context by Claude Code \u2014 re-reading wastes ~13k tokens.\n\nNo action needed. The skill content is already available in your prompt.`
+      };
+      process.stdout.write(JSON.stringify(output));
+    } else {
+      logHook('block-skill-self-read', 'PreToolUse', 'allow', { skill: skillName, file: filePath });
+    }
+
+    process.exit(0);
+  } catch (_e) {
+    // Don't block on errors
+    process.exit(0);
+  }
+}
+
+main();

package/plugins/pbr/scripts/check-agent-state-write.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse hook: Blocks subagents (except pbr:general) from writing STATE.md.
+ *
+ * STATE.md is the source of truth for project position and should only be
+ * written by skills (orchestrators) or the general agent, never by specialized
+ * agents like executor, planner, or verifier.
+ *
+ * Detection: reads .planning/.active-agent (written by log-subagent.js).
+ *
+ * Exit codes:
+ *   0 = allowed or not applicable
+ *   2 = blocked (agent not allowed to write STATE.md)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const BLOCKED_AGENTS = [
+  'pbr:executor',
+  'pbr:planner',
+  'pbr:verifier',
+  'pbr:researcher',
+  'pbr:plan-checker',
+  'pbr:integration-checker',
+  'pbr:debugger',
+  'pbr:codebase-mapper',
+  'pbr:synthesizer',
+  'pbr:audit',
+];
+
+function checkAgentStateWrite(data) {
+  const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+  if (!filePath) return null;
+
+  const normalized = filePath.replace(/\\/g, '/');
+  if (!normalized.endsWith('.planning/STATE.md')) return null;
+
+  // Check if we're inside a subagent
+  const cwd = process.cwd();
+  const agentFile = path.join(cwd, '.planning', '.active-agent');
+
+  let agent;
+  try {
+    agent = fs.readFileSync(agentFile, 'utf8').trim();
+  } catch (_e) {
+    // No .active-agent file — not in an agent context
+    return null;
+  }
+
+  if (!agent || !BLOCKED_AGENTS.includes(agent)) return null;
+
+  return {
+    exitCode: 2,
+    output: {
+      decision: 'block',
+      reason: `Agent write to STATE.md blocked.\n\n${agent} is not allowed to write STATE.md. Only skills (orchestrators) and pbr:general may update this file to prevent state corruption.\n\nReturn results to the calling skill and let it update STATE.md.`
+    }
+  };
+}
+
+module.exports = { checkAgentStateWrite, BLOCKED_AGENTS };