@sienklogic/plan-build-run 2.18.1 → 2.19.1

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,16 @@ 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 |
+| `multi_layer_validation` | `false` | **(DEPRECATED)** Parallel BugBot-style review passes. Never integrated; removed in plan 100-01. Key retained for backward compatibility. |
+| `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 +204,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 +226,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 +275,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 +307,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 +348,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 +400,250 @@ 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 |
+
+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.
+
+---
+
+## validation_passes (DEPRECATED)
+
+> **DEPRECATED**: The `multi_layer_validation` feature was never integrated and was removed in plan 100-01. This config key is retained for backward compatibility. The array has no effect.
+
+Defined which review passes would run with the multi-layer validation feature. Options included: `correctness`, `security`, `performance`, `style`, `tests`, `accessibility`, `docs`, `deps`.
+
+---
+
+## 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 +766,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.
 
@@ -439,3 +814,90 @@ Run validation with: `node plugins/pbr/scripts/pbr-tools.js config validate`
 | `tdd_mode: true` + `depth: quick` | quick depth skips verification, which conflicts with TDD's verify-first approach |
 | `git.mode: disabled` + `atomic_commits: true` | atomic_commits has no effect when git is disabled |
 | `git.branching: phase` + `git.mode: disabled` | Branching settings are ignored when git is disabled |
+
+---
+
+## local_llm (DEPRECATED)
+
+> **DEPRECATED**: This feature has been removed as of v14.0. The config key is retained for backward compatibility. Setting `enabled: true` has no effect.
+
+Offloads selected PBR inference tasks to a locally running Ollama instance, reducing frontier model usage and latency for fast classification calls. The key `enabled` defaults to `false`, so users without Ollama see no change — all LLM calls continue routing to Claude as normal. When enabled, PBR uses a `local_first` routing strategy: fast tasks (artifact classification, task validation) go to the local model; complex tasks (planning, execution) stay on the frontier model.
+
+### Quick setup
+
+1. Install Ollama:
+   - **Linux/macOS**: `curl -fsSL https://ollama.com/install.sh | sh`
+   - **Windows**: Download from [ollama.com/download](https://ollama.com/download) and run the installer
+2. Pull the recommended model: `ollama pull qwen2.5-coder:7b`
+3. Add to `.planning/config.json`:
+
+   ```json
+   "local_llm": {
+     "enabled": true,
+     "model": "qwen2.5-coder:7b"
+   }
+   ```
+
+4. Verify connectivity: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js llm health` (DEPRECATED -- returns `{ deprecated: true }` as a no-op)
+
+### Field reference
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `local_llm.enabled` | boolean | `false` | Enable local LLM offloading; `false` = all calls use frontier |
+| `local_llm.provider` | string | `"ollama"` | Backend provider; only `"ollama"` is supported |
+| `local_llm.endpoint` | string | `"http://localhost:11434"` | Ollama API base URL |
+| `local_llm.model` | string | `"qwen2.5-coder:7b"` | Model tag to use for local inference |
+| `local_llm.timeout_ms` | integer | `3000` | Per-request timeout in milliseconds; >= 500 |
+| `local_llm.max_retries` | integer | `1` | Number of retry attempts on failure before falling back |
+| `local_llm.fallback` | string | `"frontier"` | What to use when local LLM fails: `"frontier"` or `"skip"` |
+| `local_llm.routing_strategy` | string | `"local_first"` | `"local_first"` sends fast tasks local; `"always_local"` routes everything |
+
+### features sub-table
+
+Controls which PBR tasks are eligible for local LLM offloading.
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `artifact_classification` | `true` | Classify artifact types (PLAN, SUMMARY, VERIFICATION) locally |
+| `task_validation` | `true` | Validate task scope and completeness locally |
+| `context_summarization` | `false` | Summarize context windows locally (higher token demand) |
+| `source_scoring` | `false` | Score source files by relevance locally |
+
+### advanced sub-table
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `confidence_threshold` | `0.9` | Minimum confidence (0–1) for local output to be accepted; below this, falls back to frontier |
+| `shadow_mode` | `false` | Run local LLM in parallel with frontier but discard local results — useful for tuning confidence thresholds without affecting output |
+| `max_input_tokens` | `2000` | Truncate inputs longer than this before sending to local model |
+| `keep_alive` | `"30m"` | How long Ollama keeps the model loaded between requests (Ollama format: `"5m"`, `"1h"`) |
+| `num_ctx` | `4096` | Context window size passed to Ollama; **must be 4096 on Windows** (see Windows gotchas) |
+| `disable_after_failures` | `3` | Automatically disable local LLM for the session after this many consecutive failures |
+
+### Hardware requirements
+
+| Tier | Hardware | Notes |
+|------|----------|-------|
+| Recommended | RTX 3060+ with 8 GB VRAM | Full GPU acceleration; qwen2.5-coder:7b loads entirely in VRAM |
+| Functional | GTX 1660+ with 6 GB VRAM | GPU acceleration with slight layer offload to RAM |
+| Marginal | CPU only, 32 GB RAM | Works but adds 5-20s latency per call; disable context-heavy features |
+
+For GPU acceleration, ensure NVIDIA drivers are 520+ and CUDA 11.8+ is installed. AMD GPU support is available via ROCm on Linux only.
+
+### Windows gotchas
+
+- **Smart App Control**: May block `ollama_llama_server.exe` on first run. Allow it via Security settings or disable Smart App Control.
+- **Windows Defender**: Add an exclusion for `%LOCALAPPDATA%\Programs\Ollama\ollama_llama_server.exe` to prevent Defender from scanning inference calls in real time.
+- **`num_ctx` must be 4096**: Higher values cause GPU memory fragmentation on Windows and result in OOM errors mid-session. Always set `advanced.num_ctx: 4096` in your config.
+- **Firewall**: Ollama listens on `localhost:11434` by default. If you see connection refused errors, check that Windows Firewall is not blocking loopback connections.
+
+### Viewing metrics (DEPRECATED)
+
+The local LLM feature was removed in v14.0. The `llm metrics` and `llm adjust-thresholds` subcommands are no-ops that return `{ deprecated: true }`. No metrics are collected.
+
+```bash
+# These commands return { deprecated: true } and perform no action:
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js llm metrics
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js llm adjust-thresholds
+```

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