@sienklogic/plan-build-run 2.51.0 → 2.53.0

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

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

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

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

package/plugins/copilot-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/copilot-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/copilot-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/copilot-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/cursor-pbr/.cursor-plugin/plugin.json

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

@@ -27,7 +27,7 @@ You are **audit**, the session analysis agent for the Plan-Build-Run development
 
 You receive a prompt containing:
 - **Session JSONL path**: Absolute path to the session log file
-- **Subagent paths**: Optional paths to subagent logs in the `subagents/` subdirectory
+- **Subagent paths**: Optional paths to subagent logs in the `agents/` subdirectory
 - **Audit mode**: `compliance` (workflow correctness) or `ux` (user experience) or `full` (both)
 - **Output path**: Where to write findings
 

package/plugins/cursor-pbr/agents/codebase-mapper.md

@@ -184,7 +184,7 @@ Orchestrators pattern-match on these markers to route results. Omitting causes s
 9. DO NOT contradict locked decisions in CONTEXT.md
 10. DO NOT implement deferred ideas from CONTEXT.md
 11. DO NOT consume more than 50% context before producing output
-12. DO NOT read agent .md files from agents/ — auto-loaded via agent:
+12. DO NOT read agent .md files from agents/ — auto-loaded via subagent_type
 
 Additionally for this agent:
 

package/plugins/cursor-pbr/agents/debugger.md

@@ -205,7 +205,7 @@ Reference: `references/common-bug-patterns.md` — covers off-by-one, null/undef
 9. DO NOT contradict locked decisions in CONTEXT.md
 10. DO NOT implement deferred ideas from CONTEXT.md
 11. DO NOT consume more than 50% context before producing output
-12. DO NOT read agent .md files from agents/ — auto-loaded via agent:
+12. DO NOT read agent .md files from agents/ — auto-loaded via subagent_type
 
 ### Debugger-Specific
 

package/plugins/cursor-pbr/agents/dev-sync.md

@@ -33,8 +33,8 @@ Spawned by the orchestrator after edits to PBR plugin files. You receive either:
 |---------|-------------|-----------------|-------------------|
 | `allowed-tools:` frontmatter | KEEP | REMOVE entire line | REMOVE entire line |
 | `argument-hint:` frontmatter | KEEP | KEEP | REMOVE entire line |
-| `${CLAUDE_PLUGIN_ROOT}` | As-is | Replace → `${PLUGIN_ROOT}` | Replace → `${PLUGIN_ROOT}` |
-| "subagent" / "subagents" | As-is | Replace → "agent" / "agents" | Replace → "agent" / "agents" |
+| `${PLUGIN_ROOT}` | As-is | Replace → `${PLUGIN_ROOT}` | Replace → `${PLUGIN_ROOT}` |
+| "subagent" / "agents" | As-is | Replace → "agent" / "agents" | Replace → "agent" / "agents" |
 | `subagent_type:` | As-is | Replace → `agent:` | Replace → `agent:` |
 
 **Paths**:
@@ -57,9 +57,9 @@ Spawned by the orchestrator after edits to PBR plugin files. You receive either:
 
 **Text swaps** (same for both Cursor and Copilot agent bodies):
 
-- `${CLAUDE_PLUGIN_ROOT}` → `${PLUGIN_ROOT}`
+- `${PLUGIN_ROOT}` → `${PLUGIN_ROOT}`
 - "subagent" → "agent" (case-sensitive, whole word when possible)
-- "subagents" → "agents"
+- "agents" → "agents"
 - `subagent_type:` → `agent:`
 
 **Paths**:
@@ -72,8 +72,8 @@ Spawned by the orchestrator after edits to PBR plugin files. You receive either:
 
 These are copied with text swaps only (no frontmatter changes):
 
-- `${CLAUDE_PLUGIN_ROOT}` → `${PLUGIN_ROOT}`
-- "subagent" → "agent", "subagents" → "agents"
+- `${PLUGIN_ROOT}` → `${PLUGIN_ROOT}`
+- "subagent" → "agent", "agents" → "agents"
 - `subagent_type:` → `agent:`
 
 **Paths**:

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 |
@@ -361,7 +359,7 @@ Record timestamps at start and end using `node -e "console.log(new Date().toISOS
 9. DO NOT contradict locked decisions in CONTEXT.md
 10. DO NOT implement deferred ideas from CONTEXT.md
 11. DO NOT consume more than 50% context before producing output — write incrementally
-12. DO NOT read agent .md files from agents/ — they're auto-loaded via agent:
+12. DO NOT read agent .md files from agents/ — they're auto-loaded via subagent_type
 
 ### Executor-Specific
 

package/plugins/cursor-pbr/agents/general.md

@@ -101,7 +101,7 @@ If your task hits any of these, STOP and recommend the appropriate agent:
 9. DO NOT contradict locked decisions in CONTEXT.md
 10. DO NOT implement deferred ideas from CONTEXT.md
 11. DO NOT consume more than 50% context before producing output
-12. DO NOT read agent .md files from agents/ — auto-loaded via agent:
+12. DO NOT read agent .md files from agents/ — auto-loaded via subagent_type
 
 ### Agent-Specific
 1. DO NOT take on large implementation tasks — escalate to executor

package/plugins/cursor-pbr/agents/integration-checker.md

@@ -2,7 +2,7 @@
 name: integration-checker
 description: "Cross-phase integration and E2E flow verification. Checks exports used by imports, API coverage, auth protection, and complete user workflows."
 model: sonnet
-readonly: true
+readonly: false
 ---
 
 <files_to_read>
@@ -143,7 +143,7 @@ See `references/integration-patterns.md` for grep/search patterns by framework.
 9. DO NOT contradict locked decisions in CONTEXT.md
 10. DO NOT implement deferred ideas from CONTEXT.md
 11. DO NOT consume more than 50% context before producing output
-12. DO NOT read agent .md files from agents/ — auto-loaded via agent:
+12. DO NOT read agent .md files from agents/ — auto-loaded via subagent_type
 
 ### Agent-Specific
 - Never attempt to fix issues — you REPORT them

package/plugins/cursor-pbr/agents/plan-checker.md

@@ -2,7 +2,7 @@
 name: plan-checker
 description: "Verifies plans will achieve phase goals before execution. Goal-backward analysis of plan quality across 10 dimensions."
 model: sonnet
-readonly: true
+readonly: false
 ---
 
 <files_to_read>
@@ -238,7 +238,7 @@ Plans: {count} | Tasks: {count} | Blockers: {count} | Warnings: {count} | Info:
 9. DO NOT contradict locked decisions in CONTEXT.md
 10. DO NOT implement deferred ideas from CONTEXT.md
 11. DO NOT consume more than 50% context before producing output
-12. DO NOT read agent .md files from agents/ — auto-loaded via agent:
+12. DO NOT read agent .md files from agents/ — auto-loaded via subagent_type
 
 </anti_patterns>
 

package/plugins/cursor-pbr/agents/planner.md

@@ -322,7 +322,7 @@ One-line task descriptions in `<name>`. File paths in `<files>`, not explanation
 9. DO NOT contradict locked decisions in CONTEXT.md
 10. DO NOT implement deferred ideas from CONTEXT.md
 11. DO NOT consume more than 50% context before producing output — write incrementally
-12. DO NOT read agent .md files from agents/ — they're auto-loaded via agent:
+12. DO NOT read agent .md files from agents/ — they're auto-loaded via subagent_type
 
 ### Planner-Specific Anti-Patterns
 1. DO NOT create plans that violate CONTEXT.md locked decisions

package/plugins/cursor-pbr/agents/researcher.md

@@ -2,7 +2,7 @@
 name: researcher
 description: "Unified research agent for project domains, phase implementation approaches, and synthesis. Follows source-hierarchy methodology with confidence levels."
 model: sonnet
-readonly: true
+readonly: false
 ---
 
 <files_to_read>
@@ -215,7 +215,7 @@ coverage: "complete|partial|minimal"
 9. DO NOT contradict locked decisions in CONTEXT.md
 10. DO NOT implement deferred ideas from CONTEXT.md
 11. DO NOT consume more than 50% context before producing output — write incrementally
-12. DO NOT read agent .md files from agents/ — auto-loaded via agent:
+12. DO NOT read agent .md files from agents/ — they're auto-loaded via subagent_type
 
 Additionally for this agent:
 

package/plugins/cursor-pbr/agents/synthesizer.md

@@ -146,7 +146,7 @@ Use the returned `summary` string as your working copy of that document's findin
 9. DO NOT contradict locked decisions in CONTEXT.md
 10. DO NOT implement deferred ideas from CONTEXT.md
 11. DO NOT consume more than 50% context before producing output
-12. DO NOT read agent .md files from agents/ — auto-loaded via agent:
+12. DO NOT read agent .md files from agents/ — auto-loaded via subagent_type
 
 ### Agent-Specific
 1. DO NOT re-research topics — synthesize what's already been researched

package/plugins/cursor-pbr/agents/verifier.md

@@ -2,7 +2,8 @@
 name: verifier
 description: "Goal-backward phase verification. Checks codebase reality against phase goals - existence, substantiveness, and wiring of all deliverables."
 model: sonnet
-readonly: true
+isolation: worktree
+readonly: false
 ---
 
 <files_to_read>
@@ -332,7 +333,7 @@ Orchestrators pattern-match on these markers to route results. Omitting causes s
 9. DO NOT contradict locked decisions in CONTEXT.md
 10. DO NOT implement deferred ideas from CONTEXT.md
 11. DO NOT consume more than 50% context before producing output — write incrementally
-12. DO NOT read agent .md files from agents/ — they're auto-loaded via agent:
+12. DO NOT read agent .md files from agents/ — they're auto-loaded via subagent_type
 
 ### Verifier-Specific Anti-Patterns
 1. DO NOT trust SUMMARY.md claims without verifying the actual codebase

package/plugins/cursor-pbr/commands/audit.md

@@ -0,0 +1,5 @@
+---
+description: "Review past Claude Code sessions for PBR workflow compliance and UX quality."
+---
+
+This command is provided by the `pbr:audit` skill.

package/plugins/cursor-pbr/commands/begin.md

@@ -0,0 +1,5 @@
+---
+description: "Start a new project. Deep questioning, research, requirements, and roadmap."
+---
+
+This command is provided by the `pbr:begin` skill.

package/plugins/cursor-pbr/commands/build.md

@@ -0,0 +1,5 @@
+---
+description: "Execute all plans in a phase. Spawns agents to build in parallel, commits atomically."
+---
+
+This command is provided by the `pbr:build` skill.

package/plugins/cursor-pbr/commands/config.md

@@ -0,0 +1,5 @@
+---
+description: "Configure Plan-Build-Run settings. Model selection, workflow toggles, depth, gates, and parallelization."
+---
+
+This command is provided by the `pbr:config` skill.

package/plugins/cursor-pbr/commands/continue.md

@@ -0,0 +1,5 @@
+---
+description: "Execute the next logical step automatically. No prompts, no decisions — just do it."
+---
+
+This command is provided by the `pbr:continue` skill.

package/plugins/cursor-pbr/commands/dashboard.md

@@ -0,0 +1,5 @@
+---
+description: "Launch the PBR web dashboard for the current project."
+---
+
+This command is provided by the `pbr:dashboard` skill.

package/plugins/cursor-pbr/commands/debug.md

@@ -0,0 +1,5 @@
+---
+description: "Systematic debugging with hypothesis testing. Persistent across sessions."
+---
+
+This command is provided by the `pbr:debug` skill.

package/plugins/cursor-pbr/commands/discuss.md

@@ -0,0 +1,5 @@
+---
+description: "Talk through a phase before planning. Identifies gray areas and captures your decisions."
+---
+
+This command is provided by the `pbr:discuss` skill.

package/plugins/cursor-pbr/commands/do.md

@@ -0,0 +1,5 @@
+---
+description: "Route freeform text to the right PBR skill automatically."
+---
+
+This command is provided by the `pbr:do` skill.

package/plugins/cursor-pbr/commands/explore.md

@@ -0,0 +1,5 @@
+---
+description: "Explore ideas, think through approaches, and route insights to the right artifacts."
+---
+
+This command is provided by the `pbr:explore` skill.

package/plugins/cursor-pbr/commands/health.md

@@ -0,0 +1,5 @@
+---
+description: "Check planning directory integrity. Find and fix corrupted state."
+---
+
+This command is provided by the `pbr:health` skill.

package/plugins/cursor-pbr/commands/help.md

@@ -0,0 +1,5 @@
+---
+description: "Command reference and workflow guide for Plan-Build-Run."
+---
+
+This command is provided by the `pbr:help` skill.

package/plugins/cursor-pbr/commands/import.md

@@ -0,0 +1,5 @@
+---
+description: "Import an external plan document. Validates against project context, detects conflicts, and generates PLAN.md files."
+---
+
+This command is provided by the `pbr:import` skill.

package/plugins/cursor-pbr/commands/milestone.md

@@ -0,0 +1,5 @@
+---
+description: "Manage milestones: new, complete, audit, gaps."
+---
+
+This command is provided by the `pbr:milestone` skill.

package/plugins/cursor-pbr/commands/note.md

@@ -0,0 +1,5 @@
+---
+description: "Zero-friction idea capture. Append, list, or promote notes to todos."
+---
+
+This command is provided by the `pbr:note` skill.

package/plugins/cursor-pbr/commands/pause.md

@@ -0,0 +1,5 @@
+---
+description: "Save your current session state for later resumption."
+---
+
+This command is provided by the `pbr:pause` skill.

package/plugins/cursor-pbr/commands/plan.md

@@ -0,0 +1,5 @@
+---
+description: "Create a detailed plan for a phase. Research, plan, and verify before building."
+---
+
+This command is provided by the `pbr:plan` skill.

package/plugins/cursor-pbr/commands/quick.md

@@ -0,0 +1,5 @@
+---
+description: "Execute a quick ad-hoc task. Atomic commits + state tracking, skips full plan/review cycle."
+---
+
+This command is provided by the `pbr:quick` skill.

package/plugins/cursor-pbr/commands/resume.md

@@ -0,0 +1,5 @@
+---
+description: "Pick up where you left off. Restores context and suggests next action."
+---
+
+This command is provided by the `pbr:resume` skill.

package/plugins/cursor-pbr/commands/review.md

@@ -0,0 +1,5 @@
+---
+description: "Verify the build matched the plan. Automated checks + walkthrough with you."
+---
+
+This command is provided by the `pbr:review` skill.

package/plugins/cursor-pbr/commands/scan.md

@@ -0,0 +1,5 @@
+---
+description: "Analyze an existing codebase. Maps structure, architecture, conventions, and concerns."
+---
+
+This command is provided by the `pbr:scan` skill.

package/plugins/cursor-pbr/commands/setup.md

@@ -0,0 +1,5 @@
+---
+description: "Interactive onboarding wizard for new Plan-Build-Run projects."
+---
+
+This command is provided by the `pbr:setup` skill.

package/plugins/cursor-pbr/commands/status.md

@@ -0,0 +1,5 @@
+---
+description: "Show current project status and suggest what to do next."
+---
+
+This command is provided by the `pbr:status` skill.

package/plugins/cursor-pbr/commands/statusline.md

@@ -0,0 +1,5 @@
+---
+description: "Install or configure the PBR status line in Claude Code."
+---
+
+This command is provided by the `pbr:statusline` skill.

package/plugins/cursor-pbr/commands/todo.md

@@ -0,0 +1,5 @@
+---
+description: "Persistent file-based todos that survive across sessions. Add, list, and complete todo items."
+---
+
+This command is provided by the `pbr:todo` skill.

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

@@ -196,9 +196,7 @@
           {
             "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'))\" log-subagent.js stop",
-            "statusMessage": "Logging agent completion...",
-            "async": true,
-            "timeout": 30
+            "statusMessage": "Logging agent completion..."
           }
         ]
       },
@@ -207,9 +205,7 @@
           {
             "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'))\" event-handler.js",
-            "statusMessage": "Checking for auto-verification...",
-            "async": true,
-            "timeout": 10
+            "statusMessage": "Checking for auto-verification..."
           }
         ]
       }
@@ -242,12 +238,10 @@
           {
             "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'))\" session-cleanup.js",
-            "statusMessage": "Cleaning up session...",
-            "async": true,
-            "timeout": 30
+            "statusMessage": "Cleaning up session..."
           }
         ]
       }
     ]
   }
-}
+}

package/plugins/cursor-pbr/references/agent-teams.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/agent-teams.md -->
 # Agent Teams Reference
 
 Agent Teams enable parallel specialist perspectives for critical phases. Teams are off by default.

package/plugins/{copilot-pbr/references → cursor-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/cursor-pbr/references/{pbr-rules.md → 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/cursor-pbr/references/common-bug-patterns.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/common-bug-patterns.md -->
 # Common Bug Patterns
 
 Quick reference for the debugger agent. Check these patterns early — they cover ~80% of bugs.

package/plugins/cursor-pbr/references/config-reference.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/config-reference.md -->
 # Config Reference Guide
 
 Complete reference for `.planning/config.json` -- the file that controls all Plan-Build-Run workflow behavior. Created by `/pbr:begin`, modifiable via `/pbr:config` or direct editing. Validated against `config-schema.json`.

package/plugins/cursor-pbr/references/continuation-format.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/continuation-format.md -->
 # Continuation Protocol
 
 How to spawn a fresh executor agent to continue from a checkpoint or partial completion.

package/plugins/cursor-pbr/references/deviation-rules.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/deviation-rules.md -->
 # Deviation Rules
 
 When execution doesn't go exactly as planned, these 5 rules govern what the executor can do on its own versus what requires user approval.

package/plugins/cursor-pbr/references/git-integration.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/git-integration.md -->
 # Git Integration Reference
 
 Plan-Build-Run's commit conventions, commit points, branching strategy, and hook scripts.

package/plugins/cursor-pbr/references/integration-patterns.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/integration-patterns.md -->
 # Integration Patterns Reference
 
 Technology-specific grep/search patterns and E2E flow templates for integration-checker.

package/plugins/cursor-pbr/references/model-profiles.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/model-profiles.md -->
 # Model Profiles Reference
 
 How Plan-Build-Run maps agents to models and how to configure model selection.

package/plugins/cursor-pbr/references/model-selection.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/model-selection.md -->
 # Model Selection Reference
 
 Plan-Build-Run uses adaptive model selection to balance cost and capability.

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

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/plan-authoring.md -->
 # Plan Authoring Guide
 
 Quality guidelines for writing executable plans. Used by planner and plan-checker.

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

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/plan-format.md -->
 # Plan Format Reference
 
 Complete reference for the XML task specification used in Plan-Build-Run plan files.

package/plugins/cursor-pbr/references/reading-verification.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/reading-verification.md -->
 # Reading Verification Reports
 
 A user-friendly guide to understanding verification results. For agent-facing patterns, see `verification-patterns.md`.

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/cursor-pbr/references/stub-patterns.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/stub-patterns.md -->
 # Stub Detection Patterns
 
 Technology-aware patterns for detecting incomplete implementations. Used by the verifier during Layer 2 (Substantiveness) checks.

package/plugins/cursor-pbr/references/wave-execution.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/wave-execution.md -->
 # Wave-Based Execution
 
 How Plan-Build-Run parallelizes plan execution within a phase while respecting dependencies.