@sienklogic/plan-build-run 2.21.1 → 2.21.2

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

@@ -1,6 +1,6 @@
 # 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`.
+Complete reference for `.planning/config.json` -- the file that controls all Plan-Build-Run workflow behavior. Created by `/pbr:new-project`, modifiable via `/pbr:settings` or direct editing. Validated against `config-schema.json`.
 
 ---
 
@@ -12,6 +12,13 @@ Complete reference for `.planning/config.json` -- the file that controls all Pla
 | `context_strategy` | string | `aggressive`, `conservative`, `balanced` | `aggressive` | How aggressively PBR manages the context budget |
 | `mode` | string | `interactive`, `autonomous` | `interactive` | Whether PBR pauses for user input or runs hands-free |
 | `depth` | string | `quick`, `standard`, `comprehensive` | `standard` | Controls thoroughness of research, planning, and verification |
+| `session_phase_limit` | integer | `0`-`20` | `3` | Maximum phases to complete per session before auto-pause. Set to `0` to disable. Only effective when `features.auto_continue` is `true`. |
+| `context_window_tokens` | integer | `100000`-`2000000` | `200000` | Context window size in tokens for the active Claude model. Scales hook thresholds and agent budgets. Set to `1000000` for 1M-context models. |
+| `agent_checkpoint_pct` | integer | `40`-`80` | `50` | Context usage % at which agents checkpoint. Set to `65` for 1M-context models. |
+| `ceremony_level` | string | `auto`, `low`, `medium`, `high` | `auto` | Override risk-based ceremony. `auto` = classifier decides per task. |
+| `orchestrator_budget_pct` | integer | `15`-`50` | `25` | Percentage of context window reserved for the orchestrator. Higher values enable more inline work. |
+| `session_cycling` | string | `tmux`, `compact-first`, `compact`, `manual` | `compact` | What happens when session phase limit is reached. `tmux` auto-cycles via tmux send-keys; `compact-first` tries `/compact` before cycling (recommended for 1M); `compact` instructs user to compact and resume; `manual` shows a banner only. |
+| `skip_rag_max_lines` | integer | `1000`-`500000` | `50000` | Maximum project LOC for Skip-RAG eligibility. Projects under this threshold can load entire codebase into context when `features.skip_rag` is enabled. |
 
 ### context_strategy
 
@@ -38,6 +45,57 @@ Complete reference for `.planning/config.json` -- the file that controls all Pla
 
 See [depth_profiles](#depth_profiles) for the exact feature overrides each depth level applies.
 
+### context_window_tokens
+
+Sets the active model's context window size in tokens. This is the single source of truth for context scaling across all PBR subsystems.
+
+| Value | Meaning |
+|-------|---------|
+| `200000` | Default — Claude Sonnet, Haiku, and most standard models |
+| `1000000` | Claude models with 1M extended context (set by `quality` model profile) |
+
+Arbitrary integer values between `100000` and `2000000` are valid. Set to your model's actual context window size for accurate threshold scaling.
+
+### agent_checkpoint_pct
+
+The context usage percentage at which agents should stop work and return output (checkpoint). Higher values let agents do more work per invocation at the cost of less headroom before context compaction.
+
+| Value | Meaning |
+|-------|---------|
+| `50` | Default — agents checkpoint at 50% usage (standard for 200k models) |
+| `65` | Recommended for 1M-context models — agents can safely work to 65% |
+
+Valid range: `40`–`80`. Values outside this range are rejected by schema validation. Set by the `quality` profile to `65`; all other profiles default to `50`.
+
+### ceremony_level
+
+| Value | Behavior |
+|-------|----------|
+| `auto` | Risk-classifier decides ceremony per task (default) |
+| `low` | Inline execution, no plan file generated |
+| `medium` | Lightweight plan, minimal verification |
+| `high` | Full plan-build-verify cycle for every task |
+
+### orchestrator_budget_pct
+
+Controls how much of the context window the orchestrator (main skill) reserves for its own use before delegating to subagents. Higher values allow more inline work; lower values force earlier delegation.
+
+| Value | Meaning |
+|-------|---------|
+| `25` | Default for 200k models -- delegates early |
+| `35` | Recommended for 1M models -- more inline work before delegation |
+
+### session_cycling
+
+Controls the behavior when the session reaches its `session_phase_limit`.
+
+| Value | Behavior |
+|-------|----------|
+| `tmux` | Auto-cycle via tmux `send-keys` (requires TMUX environment) |
+| `compact-first` | Try `/compact` before cycling; recommended for 1M context models |
+| `compact` | Instruct user to run `/compact` then `/pbr:resume-work` (default) |
+| `manual` | Show banner only; user decides next action |
+
 ---
 
 ## features
@@ -60,12 +118,15 @@ Boolean toggles that enable or disable specific workflow capabilities. All defau
 | `auto_advance` | `false` | Chain build, review, and plan automatically (requires `mode: autonomous`) |
 | `team_discussions` | `false` | Enable team-based discussion workflows (never used for execution) |
 | `inline_verify` | `false` | Per-task verification after each executor commit; adds ~10-20s latency per plan |
+| `extended_context` | `false` | Enable aggressive 1M context optimizations: higher concurrency (5 agents vs 3), default team review, always-parallel scan, pre-load build steps. Auto-set by quality profile. Safe optimizations (parallel research, full SUMMARY reads) use `context_window_tokens >= 500000` instead. |
 
 **Notable interactions:**
-- `goal_verification: false` skips post-build verification; the build skill suggests running `/pbr:review` manually.
-- `auto_continue: true` writes `.planning/.auto-next` containing the next command (e.g., `/pbr:plan 4`).
+- `goal_verification: false` skips post-build verification; the build skill suggests running `/pbr:verify-work` manually.
+- `auto_continue: true` writes `.planning/.auto-next` containing the next command (e.g., `/pbr:plan-phase 4`).
 - `auto_advance: true` requires `mode: autonomous` to function. Hard stops at checkpoints, verification gaps, errors, and milestone boundaries.
 - `inline_verify: true` spawns a haiku-model verifier after each plan within a wave, catching issues before dependent plans run.
+- `session_phase_limit: N` (top-level) triggers auto-pause after N phases when `auto_continue: true`. In TMUX, the pause auto-cycles to a fresh session.
+- `extended_context: true` enables aggressive parallelization and deeper context usage. Requires `context_window_tokens >= 500000` to have any effect. Automatically set by the `quality` model profile. Safe optimizations (parallel researcher+seed-scan, full SUMMARY reads, pre-load steps) remain gated on `context_window_tokens >= 500000` only — they do not require this flag.
 
 ---
 
@@ -142,6 +203,20 @@ Controls planning behavior and documentation.
 
 When `commit_docs: true`, after all plans in a phase complete, the build orchestrator stages and commits planning artifacts with the message format `docs({phase}): add build summaries and verification`.
 
+**Auto-detection:** If `.planning/` is gitignored, `commit_docs` is automatically `false` regardless of `config.json`. This prevents git errors when users have `.planning/` in `.gitignore`.
+
+### search_gitignored Behavior
+
+When `false` (default): Standard ripgrep behavior respects `.gitignore`. Direct path searches (`rg "pattern" .planning/`) still work, but broad searches (`rg "pattern"`) skip gitignored directories. When `true`: Adds `--no-ignore` to broad searches that should include `.planning/`.
+
+### Uncommitted Mode Setup
+
+To keep planning artifacts out of version control:
+
+1. Set `"planning": { "commit_docs": false, "search_gitignored": true }` in config
+2. Add `.planning/` to `.gitignore`
+3. If `.planning/` was previously tracked: `git rm -r --cached .planning/ && git commit -m "chore: stop tracking planning docs"`
+
 ---
 
 ## git
@@ -150,26 +225,38 @@ Controls git integration and branching strategy.
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `branching` | string | `none` | Branching strategy: `none`, `phase`, `milestone`, `disabled` |
-| `commit_format` | string | `{type}({phase}-{plan}): {description}` | Commit message template |
+| `branching` | string | `none` | Branching strategy: `none`, `phase`, `milestone`, `disabled`. Recommended: `phase` -- enables safe undo via phase manifests and clean PR history |
+| `commit_format` | string | `{type}({scope}): {description}` | Commit message template. Use a short descriptive word as the scope (e.g., `auth`, `config`, `executor`) rather than phase-plan numbers. |
 | `phase_branch_template` | string | `plan-build-run/phase-{phase}-{slug}` | Phase branch name pattern |
 | `milestone_branch_template` | string | `plan-build-run/{milestone}-{slug}` | Milestone branch name pattern |
 | `mode` | string | `enabled` | Git mode: `enabled` or `disabled` |
+| `auto_pr` | boolean | `false` | Create a GitHub PR after successful phase verification when branching is enabled |
 
 When `git.mode` is `disabled`, no git commands run at all -- no commits, branching, or hook validation. Useful for prototyping or non-git projects. See `references/git-integration.md` for full branching strategy details.
 
 ---
 
+## ci
+
+Controls CI integration for build gates.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `ci.gate_enabled` | boolean | `false` | Block wave advancement until CI passes |
+| `ci.wait_timeout_seconds` | number | `120` | Max seconds to wait for CI completion |
+
+---
+
 ## gates
 
 Confirmation gates that pause execution to ask the user before proceeding. Setting a gate to `false` makes that step automatic.
 
 | Property | Default | When Triggered |
 |----------|---------|----------------|
-| `confirm_project` | `true` | Before creating a new PBR project (`/pbr:begin`) |
+| `confirm_project` | `true` | Before creating a new PBR project (`/pbr:new-project`) |
 | `confirm_roadmap` | `true` | Before finalizing a roadmap |
 | `confirm_plan` | `true` | Before finalizing plans for a phase |
-| `confirm_execute` | `false` | Before starting phase execution (`/pbr:build`) |
+| `confirm_execute` | `false` | Before starting phase execution (`/pbr:execute-phase`) |
 | `confirm_transition` | `true` | Before transitioning to the next phase |
 | `issues_review` | `true` | Before proceeding when issues are detected |
 
@@ -187,7 +274,7 @@ Safety controls for destructive or external operations.
 | `always_confirm_external_services` | boolean | `true` | Always ask before calling external APIs or services |
 | `enforce_phase_boundaries` | boolean | `true` | Prevent agents from working outside their assigned phase scope |
 
-The `always_confirm_destructive` and `always_confirm_external_services` flags cannot be disabled via `/pbr:config`; they require direct editing of `config.json` as a deliberate action.
+The `always_confirm_destructive` and `always_confirm_external_services` flags cannot be disabled via `/pbr:settings`; they require direct editing of `config.json` as a deliberate action.
 
 ---
 
@@ -219,6 +306,16 @@ This value is overridden by the active depth profile if a `depth_profiles` entry
 
 ---
 
+## deployment
+
+Controls post-milestone deployment verification.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `deployment.smoke_test_command` | string | `""` | Bash command to run after milestone completion (e.g., `"curl -sf https://myapp.com/health"`) |
+
+---
+
 ## depth_profiles
 
 Override the built-in depth profile defaults. Each key (`quick`, `standard`, `comprehensive`) maps to an object of settings that take effect when that depth is active.
@@ -250,6 +347,23 @@ User overrides in `depth_profiles` merge on top of these defaults. For example,
 
 ---
 
+## session_phase_limit
+
+Controls how many phases PBR completes in a single session before suggesting a pause-and-resume cycle. This prevents context degradation in long autonomous runs.
+
+| Value | Behavior |
+|-------|----------|
+| `0` | Disabled -- PBR never auto-pauses for session cycling |
+| `1`-`20` | After completing this many phases, PBR writes `/pbr:pause-work` to `.auto-next` and triggers a session cycle |
+
+**Interaction with TMUX:** When running inside a TMUX session, the auto-pause automatically sends `/clear` and `/pbr:resume-work` to the current pane after a 3-second delay, creating a seamless session cycle. Outside TMUX, a banner instructs the user to manually run `/clear` then `/pbr:resume-work`.
+
+**Tracking:** Phase completions are tracked in `.planning/.session-tracker` (reset each session start). The counter increments when an executor subagent completes successfully.
+
+See `references/archive/tmux-setup.md` for TMUX environment setup.
+
+---
+
 ## spinner_tips
 
 Custom spinner tips shown during agent execution. Requires Claude Code 2.1.45+.
@@ -285,6 +399,253 @@ Controls the visual context budget bar.
 
 ---
 
+## autonomy
+
+Progressive autonomy control for agent behavior.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `level` | string | `supervised` | Autonomy level: `supervised` (human approves all), `guided` (AI acts, human reviews async), `collaborative` (AI handles routine, escalates novel), `adaptive` (AI adjusts own autonomy per task confidence) |
+| `error_strategy` | string | `retry` | How agents handle errors: `retry` or `stop` |
+| `max_retries` | integer | `2` | Maximum retry attempts for autonomous error recovery |
+
+---
+
+## model_profiles
+
+User-defined custom model profiles. Each key is a profile name (e.g., `budget`, `quality`); the value maps agent names to model strings (`sonnet`, `opus`, `haiku`, `inherit`). Partial profiles are allowed -- omitted agents fall back to the active profile defaults.
+
+```json
+{
+  "model_profiles": {
+    "budget": {
+      "researcher": "haiku",
+      "planner": "sonnet",
+      "executor": "sonnet",
+      "verifier": "haiku"
+    }
+  }
+}
+```
+
+Agent keys match the `models` section: `researcher`, `planner`, `executor`, `verifier`, `integration_checker`, `debugger`, `mapper`, `synthesizer`.
+
+---
+
+## workflow
+
+Controls workflow-level execution behavior including inline execution, speculative planning, and phase boundaries.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `autonomous` | boolean | `false` | Enable `/pbr:autonomous` for hands-free multi-phase execution |
+| `enforce_pbr_skills` | string | `advisory` | PBR workflow compliance enforcement: `advisory` (warn), `block` (prevent non-PBR edits), `off` (disabled) |
+| `inline_execution` | boolean | `false` | Trivial plans execute inline without spawning a subagent |
+| `inline_max_tasks` | integer | `2` | Maximum tasks for inline execution eligibility (1-5) |
+| `inline_max_files` | integer | `5` | Maximum files for inline execution eligibility (1-20) |
+| `inline_max_lines` | integer | `50` | Maximum estimated lines of change for inline execution (10-500) |
+| `inline_context_cap_pct` | integer | `40` | Context usage % above which always spawn subagent (10-80) |
+| `max_phases_in_context` | integer | `3` | Max phase plans held simultaneously by orchestrator (1-10) |
+| `phase_boundary_clear` | string | `off` | `/clear` at phase boundaries: `recommend` (advisory), `enforce` (block without `/clear`), `off` |
+| `phase_replay` | boolean | `false` | Failed verification triggers replay with enriched context |
+| `speculative_planning` | boolean | `false` | Plan phase N+1 while executor runs phase N |
+| `speculative_depth` | integer | `2` | How many phases ahead to speculatively plan (1-5) |
+| `validate_phase` | boolean | `true` | Validate phase structure before execution |
+
+---
+
+## verification
+
+Controls post-build verification behavior.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `confidence_gate` | boolean | `false` | Skip verification if executor reports 100% must-have completion and tests pass |
+| `confidence_threshold` | number | `1.0` | Minimum completion confidence (0.5-1.0) required to skip verification |
+| `qa_rounds` | integer | `1` | Number of build-QA-build iteration rounds (1-5). 1 = current behavior (single build + verify). Higher values enable progressive deepening: round 1 standard (L1-L3), round 2 thorough (L1-L4), round 3+ thorough + live verification if enabled. |
+| `live_tools` | string[] | `["chrome-mcp"]` | MCP tool providers for live interaction verification. Currently only `chrome-mcp` is supported. |
+| `live_timeout_ms` | integer | `60000` | Maximum time in milliseconds for each live interaction verification check (minimum 5000). |
+
+When `confidence_gate` is `true` and the executor SUMMARY reports all must-haves as DONE with commit SHAs, the build skill can auto-mark the phase as verified without spawning a verifier agent.
+
+### features.live_verification
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `features.live_verification` | boolean | `false` | Opt-in flag to enable live browser/API testing during verification. Requires Chrome MCP tools to be configured. |
+
+When enabled, the verifier agent gains access to `live_tools` (e.g., `chrome-mcp`) for browser automation during verification rounds. This is gated behind a feature flag because it requires external MCP tool providers and adds latency. Only effective when `verification.qa_rounds >= 3` or when explicitly requested by the plan.
+
+---
+
+## context_budget
+
+Controls context budget warning thresholds.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `threshold_curve` | string | `linear` | Warning threshold scaling: `linear` (fixed 50/70/85%) or `adaptive` (shifts up for 1M context: 60/75/85%) |
+
+Use `adaptive` with `context_window_tokens >= 500000` to reduce premature compaction warnings.
+
+---
+
+## context_ledger
+
+Tracks what files are loaded in context and when they become stale.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `enabled` | boolean | `false` | Enable context composition tracking via `track-context-budget.js` |
+| `stale_after_minutes` | integer | `60` | Minutes before a context read is considered stale for compact suggestions (5-1440) |
+
+When enabled, the hook records file path, timestamp, estimated tokens, and active phase per Read call in `.planning/.context-ledger.json`.
+
+---
+
+## hook_server
+
+Persistent HTTP hook server for faster hook execution. When enabled, hooks POST to the server instead of spawning per-hook Node.js processes.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `enabled` | boolean | `false` | Route hooks through the persistent HTTP server |
+| `port` | integer | `19836` | TCP port the hook server listens on (127.0.0.1 only, 1024-65535) |
+| `event_log` | boolean | `true` | Append all hook events to `.planning/.hook-events.jsonl` |
+
+---
+
+## intel
+
+Persistent codebase intelligence system providing architecture maps and file dependency graphs.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `enabled` | boolean | `false` | Enable the intel system. When `false`, all intel features are no-ops. |
+| `auto_update` | boolean | `false` | PostToolUse hooks queue intel updates when code files change |
+| `inject_on_start` | boolean | `false` | SessionStart hook injects `.planning/intel/arch.md` summary into context |
+
+When fully enabled, the `/pbr:intel` skill generates architecture maps, module graphs, and convention summaries in `.planning/intel/`.
+
+---
+
+## learnings
+
+Cross-phase knowledge transfer system. Executors write `LEARNINGS.md` files; planners read prior learnings for context.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `enabled` | boolean | `false` | Enable cross-phase learning |
+| `read_depth` | integer | `3` | Number of prior phases' LEARNINGS.md files the planner reads (1-20) |
+| `cross_project_knowledge` | boolean | `false` | Copy learnings marked `cross_project: true` to `~/.claude/pbr-knowledge/` for reuse across projects |
+
+---
+
+## dashboard
+
+Web UI for browsing `.planning/` state.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `auto_launch` | boolean | `false` | Automatically launch dashboard when starting a PBR session |
+| `port` | integer | `3141` | TCP port for the dashboard server (1024-65535) |
+
+Launch manually with: `npm run dashboard -- --dir /path/to/project --port 3141`
+
+---
+
+## developer_profile
+
+Behavioral profiling from session history with optional prompt injection for personalized agent communication.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `enabled` | boolean | `false` | Enable developer profiling. When `true`, `/pbr:profile-user` skill generates behavioral profiles. |
+| `inject_prompts` | boolean | `false` | Inject `USER-PROFILE.md` summary into agent prompts for personalized communication |
+
+---
+
+## prd
+
+Settings for PRD (Product Requirements Document) import via `/pbr:import --prd`.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `auto_extract` | boolean | `false` | Skip the confirmation gate during PRD import and write files immediately |
+
+---
+
+## timeouts
+
+Timeout limits for various operations in milliseconds.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `task_default_ms` | integer | `300000` | Default timeout per task (5 minutes). Minimum: 30000. |
+| `build_max_ms` | integer | `600000` | Maximum time for entire build command (10 minutes). Minimum: 60000. |
+| `verify_max_ms` | integer | `300000` | Maximum time for verification (5 minutes). Minimum: 30000. |
+
+---
+
+## ui
+
+Controls the UI design pipeline for frontend projects.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `enabled` | boolean | `false` | Enable UI design pipeline. When `true`, `/pbr:ui-phase` and `/pbr:ui-review` skills are available. Auto-detected for frontend projects unless explicitly set. |
+
+---
+
+## worktree
+
+Settings for agents running with `isolation: worktree` in their agent definition.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `sparse_paths` | string[] | `[]` | Glob patterns for sparse checkout in worktrees (e.g., `["src/**", "package.json", ".planning/**"]`). Empty array = full checkout. |
+
+---
+
+## audit
+
+Audit system configuration for `/pbr:audit`. Controls which audit dimensions run and their thresholds.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `preset` | string | `standard` | Audit preset: `minimal`, `standard`, `comprehensive`, `custom` |
+| `categories` | object | *(all true)* | Per-category enable/disable toggles (overrides preset defaults) |
+| `overrides` | object | `{}` | Per-dimension enable/disable by ID (e.g., `"SI-01": false`) |
+| `thresholds` | object | *(see below)* | Tunable numeric thresholds referenced by audit dimensions |
+
+### audit.categories
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `self_integrity` | `true` | Self-integrity checks |
+| `infrastructure` | `true` | Infrastructure health checks |
+| `error_analysis` | `true` | Error pattern analysis |
+| `workflow_compliance` | `true` | PBR workflow compliance |
+| `behavioral_compliance` | `true` | Agent behavioral compliance |
+| `session_quality` | `true` | Session quality metrics |
+| `feature_verification` | `true` | Feature flag verification |
+| `quality_metrics` | `true` | Code quality metrics |
+
+### audit.thresholds
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `hook_performance_ms` | integer | `500` | Hook execution time warning threshold |
+| `session_duration_warn_ms` | integer | `3600000` | Session duration warning (1 hour) |
+| `tool_failure_rate_warn` | number | `0.10` | Tool failure rate warning threshold (0-1) |
+| `stale_file_age_hours` | integer | `24` | Hours before a planning file is considered stale |
+| `retry_pattern_min_count` | integer | `3` | Minimum retries before flagging a retry pattern |
+| `agent_timeout_ms` | integer | `600000` | Agent execution timeout (10 minutes) |
+| `disk_usage_warn_mb` | integer | `50` | `.planning/` disk usage warning in MB |
+| `log_rotation_max_days` | integer | `30` | Maximum age for log files before rotation |
+
+---
+
 ## Common Configurations
 
 ### Quick Solo Development
@@ -407,13 +768,29 @@ Hands-free execution with no gates and automatic phase chaining. Suitable for CI
 
 ---
 
+## Global Defaults File
+
+PBR supports user-level default preferences stored at `~/.claude/pbr-defaults.json`. When creating a new project via `/pbr:new-project` or `/pbr:settings` Quick Start, these defaults pre-populate configuration fields instead of hardcoded values.
+
+**Location:** `~/.claude/pbr-defaults.json` (created by `config save-defaults`)
+
+**Commands:**
+- `pbr-tools.js config save-defaults` -- Save current project config as global defaults (only portable keys: mode, depth, features, models, parallelization, planning, git, gates, safety, hooks, dashboard, status_line)
+- `pbr-tools.js config load-defaults` -- Load global defaults (returns JSON or `{ exists: false }`)
+
+**Portable keys saved:** mode, depth, context_strategy, features, models, parallelization, planning, git, gates, safety, hooks, dashboard, status_line. Project-specific state (version, schema_version) is excluded.
+
+**Precedence:** Global defaults < project config.json < CLI arguments. Global defaults only affect new project creation and Quick Start flow.
+
+---
+
 ## Troubleshooting
 
 ### Validation Errors
 
-Run validation with: `node plugins/pbr/scripts/pbr-tools.js config validate`
+Run validation with: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config validate`
 
-**"config.json not found"** -- No `.planning/config.json` exists. Run `/pbr:begin` to create one, or create the file manually.
+**"config.json not found"** -- No `.planning/config.json` exists. Run `/pbr:new-project` to create one, or create the file manually.
 
 **"config.json is not valid JSON"** -- Syntax error in the JSON file. Check for trailing commas, missing quotes, or unescaped characters.
 

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

@@ -10,6 +10,7 @@ When an executor hits a checkpoint, it STOPS and returns. A new, fresh agent mus
 1. The checkpoint may require user input that changes the execution path
 2. Context isolation prevents accumulated state from causing issues
 3. Fresh agents have full context budget for remaining work
+4. Claude Code deprecated the Agent tool's `resume` parameter. PBR's fresh-spawn pattern via `Task()` with `subagent_type` is the recommended approach. For cases where agent continuation is needed (not currently used in PBR), use `SendMessage({to: agentId})` instead of the deprecated `resume` parameter.
 
 ---
 

package/plugins/pbr/references/decimal-phase-calculation.md

@@ -0,0 +1,65 @@
+# Decimal Phase Calculation
+
+Calculate the next decimal phase number for urgent insertions.
+
+## Using pbr-tools
+
+```bash
+# Get next decimal phase after phase 6
+node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" phase next-decimal 6
+```
+
+Output:
+```json
+{
+  "found": true,
+  "base_phase": "06",
+  "next": "06.1",
+  "existing": []
+}
+```
+
+With existing decimals:
+```json
+{
+  "found": true,
+  "base_phase": "06",
+  "next": "06.3",
+  "existing": ["06.1", "06.2"]
+}
+```
+
+## Extract Values
+
+```bash
+DECIMAL_INFO=$(node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" phase next-decimal "${AFTER_PHASE}")
+DECIMAL_PHASE=$(printf '%s\n' "$DECIMAL_INFO" | jq -r '.next')
+BASE_PHASE=$(printf '%s\n' "$DECIMAL_INFO" | jq -r '.base_phase')
+```
+
+Or with --raw flag:
+```bash
+DECIMAL_PHASE=$(node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" phase next-decimal "${AFTER_PHASE}" --raw)
+# Returns just: 06.1
+```
+
+## Examples
+
+| Existing Phases | Next Phase |
+|-----------------|------------|
+| 06 only | 06.1 |
+| 06, 06.1 | 06.2 |
+| 06, 06.1, 06.2 | 06.3 |
+| 06, 06.1, 06.3 (gap) | 06.4 |
+
+## Directory Naming
+
+Decimal phase directories use the full decimal number:
+
+```bash
+SLUG=$(node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" generate-slug "$DESCRIPTION" --raw)
+PHASE_DIR=".planning/phases/${DECIMAL_PHASE}-${SLUG}"
+mkdir -p "$PHASE_DIR"
+```
+
+Example: `.planning/phases/06.1-fix-critical-auth-bug/`

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

@@ -2,6 +2,18 @@
 
 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.
 
+## Taxonomy Reference
+
+When documenting deviations in SUMMARY.md, use this structured format:
+
+```yaml
+deviations:
+  - rule: 1          # 1=Bug, 2=Missing Dependency, 3=Critical Gap, 4=Architectural, 5=Scope Creep
+    description: "What happened"
+    action: "auto"   # auto (Rules 1-3, 5) | ask (Rule 4)
+    justification: "Why this action was taken"
+```
+
 ---
 
 ## Rule 1: Bug Discovered

package/plugins/pbr/references/few-shot-examples/audit.md

@@ -0,0 +1,77 @@
+---
+component: audit
+version: 1
+last_calibrated: 2026-03-24
+---
+
+# Audit Few-Shot Examples
+
+## Positive Examples
+
+### Example 1: Executor task skipping detected with specific evidence
+
+**Input:** Session JSONL for a `/pbr:build` invocation. PLAN.md has 7 tasks (T1-T7). SUMMARY.md reports 4 tasks complete.
+
+**Output:**
+
+> **Code: WC-03 (Plan Execution Completeness)**
+> Status: fail
+> Evidence:
+> - PLAN.md contains tasks T1 through T7 (7 total)
+> - SUMMARY.md frontmatter lists commits for T1, T2, T3, T5 only (4 of 7)
+> - Tasks T4, T6, T7 have no corresponding commit SHA and no entry in SUMMARY.md task results table
+> - T4 action was "add error handling to hook-logger.js" -- no changes to hook-logger.js in `git log --oneline`
+> - No deviation entry explains the skipped tasks
+> Recommendation: Re-run executor for tasks T4, T6, T7 or document deviations explaining why they were skipped.
+
+**Why this is good:** The auditor cross-referenced the plan task list against the SUMMARY.md output, identified exactly which tasks were missing (T4, T6, T7), verified with git log that the expected file changes never happened, and noted the absence of deviation documentation. Every claim has a specific source.
+
+### Example 2: Stale active-skill file traced as root cause of hook failures
+
+**Input:** Session JSONL shows 4 consecutive PreToolUse blocks with reason "Workflow violation: /pbr:plan should only write to .planning/ files."
+
+**Output:**
+
+> **Code: EF-03 (Active-Skill Conflicts)**
+> Status: fail
+> Evidence:
+> - JSONL lines 412, 418, 425, 431: Four consecutive PreToolUse blocks on Write tool
+> - Block reason references `/pbr:plan` as active skill, but session shows `/pbr:build` was invoked at line 380
+> - `.planning/.active-skill` contained "plan" (stale from prior session that crashed at 17:42:03Z without cleanup)
+> - No `session-cleanup.js` firing evidence between the prior session end and current session start
+> Root cause: Prior session terminated without firing the Stop hook, leaving `.active-skill` set to "plan". Current `/pbr:build` session inherited the stale marker.
+> Recommendation: Check that `session-cleanup.js` fires on all exit paths. Consider adding `.active-skill` staleness check to `progress-tracker.js` SessionStart.
+
+**Why this is good:** The auditor traced a pattern of failures (4 blocks) back to a specific root cause (stale file from crashed session) with timestamps and JSONL line numbers. It identified the gap in the cleanup mechanism and suggested two specific preventive measures.
+
+## Negative Examples
+
+### Example 1: Vague quality assessment with no metrics or evidence
+
+**Input:** Session JSONL with 200+ entries across a 45-minute session.
+
+**Output:**
+
+> **Session Quality: Good**
+> The session ran smoothly with no major issues. Hooks appeared to fire correctly and the workflow was followed. No concerns identified.
+> Dimensions checked: 88, passed: 88
+
+**Why this is bad:** The auditor claimed 88/88 dimensions passed with zero evidence. No JSONL line references, no timestamps, no specific hook events cited. "Hooks appeared to fire correctly" is speculation -- the auditor should cite specific `hook_progress` entries. Reporting 88 passed dimensions with no findings is statistically implausible and suggests the auditor skipped the actual checks.
+
+### Example 2: Every commit flagged as a concern despite correct format
+
+**Input:** Session with 6 commits: `feat(hooks): add context tier tracking`, `fix(hooks): handle null config gracefully`, `test(tests): add context-bridge coverage`, `refactor(hooks): extract threshold logic`, `docs(refs): update hook ordering reference`, `chore(ci): bump Node matrix to 22`.
+
+**Output:**
+
+> **Code: WC-05 (Commit Format)**
+> Status: warn
+> Evidence:
+> - 6 commits analyzed, all flagged for review
+> - `feat(hooks): add context tier tracking` -- scope "hooks" may be too broad
+> - `fix(hooks): handle null config gracefully` -- description could be more specific
+> - `test(tests): add context-bridge coverage` -- redundant scope "tests" for test type
+> - (continues for all 6)
+> Recommendation: Tighten commit message specificity across all commits.
+
+**Why this is bad:** All 6 commits follow the enforced format `{type}({scope}): {description}` perfectly. The auditor invented subjective concerns ("may be too broad", "could be more specific") that do not correspond to any documented rule violation. This is noise that drowns out real issues and wastes the user's attention on false positives.