@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/{cursor-pbr/references → pbr/references/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.
@@ -27,7 +26,8 @@ Condensed from the 3,100-line `docs/DEVELOPMENT-GUIDE.md`. When in doubt, these
 12. **Never** read full subagent output — read frontmatter only (first 10-20 lines).
 13. Read STATE.md and config.json fully. Read ROADMAP.md by section. Read PLAN.md/SUMMARY.md/VERIFICATION.md frontmatter only.
 14. Use the `limit` parameter on Read to restrict line counts.
-15. Proactively suggest `/pbr:pause` when context gets heavy — before compaction, not after.
+15. Proactively suggest `/pbr:pause-work` when context gets heavy — before compaction, not after.
+15b. **After compaction or context recovery**, always read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
 
 ---
 
@@ -74,7 +74,7 @@ Condensed from the 3,100-line `docs/DEVELOPMENT-GUIDE.md`. When in doubt, these
 39. Mark each step as `(inline)` or `(delegate)` — inline for light work, delegate for analysis.
 40. Reference templates and references by filename — never inline them.
 41. Gate checks: read config toggle → display summary → ask user → proceed/abort/revise.
-42. Use branded UI elements from `references/ui-formatting.md`.
+42. Use branded UI elements from `references/ui-brand.md`.
 
 ---
 
@@ -105,7 +105,7 @@ Condensed from the 3,100-line `docs/DEVELOPMENT-GUIDE.md`. When in doubt, these
 
 56. Format: `{type}({scope}): {description}`.
 57. Valid types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `wip`.
-58. Valid scopes: `{NN}-{MM}` (phase-plan), `quick-{NNN}`, `planning`, or any lowercase word.
+58. Valid scopes: a short descriptive word for what changed (e.g., `auth`, `executor`, `config`), `quick-{NNN}`, `planning`, or `{NN}-{MM}` (phase-plan, legacy).
 59. **Never** use `git add .` or `git add -A` — stage specific files only.
 60. Blocked files: `.env` (not `.env.example`), `*.key`, `*.pem`, `*.pfx`, `*.p12`, `*credential*`, `*secret*` (unless in `tests/` or `*.example`).
 61. TDD tasks: exactly 3 commits — RED (test), GREEN (feat), REFACTOR.

package/plugins/pbr/references/archive/verification-patterns.md

@@ -0,0 +1,277 @@
+# Goal-Backward Verification Patterns
+
+Reference patterns for deriving verification criteria from goals. Used by the planner to create `<verify>` and `<done>` elements, and by the verifier to check phase completion.
+
+---
+
+## The Four-Layer Check
+
+Every must-have is verified through up to four layers, checked in order:
+
+### Layer 1: Existence
+
+Does the artifact exist?
+
+```bash
+# File existence
+ls -la src/auth/discord.ts
+
+# Module export existence
+grep -q "export.*authenticateWithDiscord" src/auth/discord.ts
+
+# Database table existence
+npx prisma db execute --stdin <<< "SELECT 1 FROM users LIMIT 1"
+
+# Route existence
+curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/api/auth/login
+```
+
+### Layer 2: Substantiveness
+
+Is the artifact more than a stub?
+
+```bash
+# File has real content (not just exports)
+wc -l src/auth/discord.ts  # Should be > 10 lines for a real implementation
+
+# Function has a body (not just a signature)
+grep -A5 "authenticateWithDiscord" src/auth/discord.ts | grep -q "return"
+
+# Test file has actual test cases
+grep -c "it(" tests/auth.test.ts  # Should be > 0
+
+# API returns real data (not just 200 OK)
+curl -s http://localhost:3000/api/health | jq '.status' | grep -q "ok"
+```
+
+### Layer 3: Wiring
+
+Are components connected to each other?
+
+```bash
+# Module is imported where needed
+grep -q "from.*auth/discord" src/routes/auth.ts
+
+# Middleware is applied to routes
+grep -q "requireAuth" src/routes/protected.ts
+
+# Database is configured in app init
+grep -q "prisma" src/app.ts
+
+# Environment variables are referenced
+grep -q "DISCORD_CLIENT_ID" src/auth/discord.ts
+```
+
+### Layer 4: Functional
+
+Does the artifact actually work when executed?
+
+```bash
+# Tests pass
+npm test -- --testPathPattern auth
+pytest tests/test_auth.py -v
+
+# Build succeeds
+npm run build
+npx tsc --noEmit
+
+# API returns correct data
+curl -s http://localhost:3000/api/auth/login -X POST -d '{"code":"test"}' | jq '.token'
+
+# CLI produces expected output
+node src/cli.js --help | grep -q "Usage:"
+```
+
+**When to apply L4:** Only when automated verification commands exist (test suites, build scripts, API endpoints with test data). Skip for items requiring manual/visual testing. L4 is optional — artifacts passing L1-L3 without available automated tests are reported as `PASSED (L3 only)`.
+
+---
+
+## Verification by Feature Type
+
+### API Endpoint
+
+```
+Existence:   curl returns non-404 status
+Substance:   curl returns expected response shape (correct fields)
+Wiring:      endpoint calls the right service, middleware is applied
+Functional:  POST/GET with test data returns correct response, error cases handled
+```
+
+### Database Schema
+
+```
+Existence:   table/collection exists, can query without error
+Substance:   columns/fields match specification, constraints are applied
+Wiring:      application code references the schema, migrations run cleanly
+Functional:  CRUD operations work end-to-end, constraints reject invalid data
+```
+
+### Authentication
+
+```
+Existence:   auth routes exist, auth module exports functions
+Substance:   login flow returns token, invalid creds return error
+Wiring:      protected routes use auth middleware, tokens are validated
+Functional:  auth tests pass (valid token, expired token, missing token, malformed token)
+```
+
+### UI Component
+
+```
+Existence:   component file exists, exports default component
+Substance:   component renders expected elements (test or visual check)
+Wiring:      component is imported in parent, receives correct props, routes to it
+Functional:  component tests pass, build succeeds with component included
+```
+
+### Configuration
+
+```
+Existence:   config file exists, environment variables documented
+Substance:   config values are used (not dead code), defaults are sensible
+Wiring:      application reads config at startup, config changes take effect
+Functional:  app starts with config, missing config produces clear error message
+```
+
+---
+
+## Verify Command Patterns
+
+### TypeScript/JavaScript
+
+```bash
+# Type checking
+npx tsc --noEmit
+
+# Unit tests
+npm test
+npm test -- --grep "pattern"
+npx jest path/to/test
+
+# Linting
+npx eslint src/auth/
+
+# Build check
+npm run build
+```
+
+### Python
+
+```bash
+# Type checking
+mypy src/
+
+# Unit tests
+pytest tests/
+pytest tests/test_auth.py -v
+pytest -k "test_login"
+
+# Linting
+flake8 src/
+pylint src/auth/
+```
+
+### General
+
+```bash
+# File existence
+ls -la path/to/file
+
+# Content check
+grep -q "pattern" path/to/file
+
+# HTTP endpoint
+curl -s -o /dev/null -w "%{http_code}" http://localhost:PORT/path
+
+# Process running
+pgrep -f "process-name"
+
+# Port listening
+netstat -an | grep LISTEN | grep PORT
+```
+
+---
+
+## Done Condition Patterns
+
+### Good Done Conditions (Observable, Falsifiable)
+
+- "User can log in with Discord and see their dashboard"
+- "API returns paginated list of items with correct total count"
+- "Database migration creates users table with all required columns"
+- "Protected routes return 401 without valid JWT"
+- "Build completes without TypeScript errors"
+
+### Bad Done Conditions (Vague, Not Falsifiable)
+
+- "Authentication is implemented" (how do you test this?)
+- "Code is clean" (subjective)
+- "Database is set up" (what does "set up" mean?)
+- "Tests pass" (which tests? what do they test?)
+- "File was created" (created with what content?)
+
+### Transformation Rule
+
+```
+Bad:  "Authentication is implemented"
+Good: "User can complete Discord OAuth flow and receive a valid JWT"
+
+Bad:  "Database is set up"
+Good: "Users table exists with id, email, name columns and can accept INSERT"
+
+Bad:  "Tests pass"
+Good: "All 5 auth middleware tests pass: valid token, expired token,
+       missing token, malformed token, and correct user extraction"
+```
+
+---
+
+## Wiring Verification Patterns
+
+4 concrete patterns for verifying components are actually connected, not just present.
+
+### Pattern 1: Component to API
+1. Find the fetch/axios call in the component
+2. Verify the call is NOT commented out
+3. Verify the response is assigned to state (not discarded)
+4. Verify error handling exists (try/catch or .catch)
+
+### Pattern 2: API to Database
+1. Find the database query in the route handler
+2. Verify `await` is present (not fire-and-forget)
+3. Verify the result is returned in the response (not discarded)
+4. Verify error cases return appropriate HTTP status codes
+
+### Pattern 3: Form to Handler
+1. Find the form's onSubmit handler
+2. Verify it calls an API function (not just preventDefault)
+3. Verify form validation runs before the API call
+4. Verify success/error feedback is shown to the user
+
+### Pattern 4: State to Render
+1. Find state variables (useState, store, etc.)
+2. Verify they appear in JSX/template via .map(), interpolation, or conditional rendering
+3. Verify loading/error states are rendered (not just success state)
+4. Verify empty state is handled (not just "no data" crash)
+
+### Quick Verification Checklists
+
+**Component Checklist (8 items):**
+- [ ] Component file exists and exports correctly
+- [ ] Props/types are defined (not `any`)
+- [ ] API calls use actual endpoints (not hardcoded data)
+- [ ] Loading state renders something meaningful
+- [ ] Error state renders something meaningful
+- [ ] Empty state renders something meaningful
+- [ ] User interactions trigger actual handlers
+- [ ] Component is imported and rendered in parent
+
+**API Route Checklist (8 items):**
+- [ ] Route file exists and exports handler
+- [ ] Route is registered in router/app
+- [ ] Request validation exists (body, params, query)
+- [ ] Database query uses parameterized inputs
+- [ ] Success response includes expected data shape
+- [ ] Error response includes status code and message
+- [ ] Authentication/authorization check exists if needed
+- [ ] Response matches what the frontend expects

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,9 @@ 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. |
 
 ### context_strategy
 
@@ -38,6 +41,28 @@ 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`.
+
 ---
 
 ## features
@@ -62,10 +87,11 @@ Boolean toggles that enable or disable specific workflow capabilities. All defau
 | `inline_verify` | `false` | Per-task verification after each executor commit; adds ~10-20s latency per plan |
 
 **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.
 
 ---
 
@@ -150,26 +176,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 +225,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 +257,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 +298,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/tmux-setup.md` for TMUX environment setup.
+
+---
+
 ## spinner_tips
 
 Custom spinner tips shown during agent execution. Requires Claude Code 2.1.45+.
@@ -407,13 +472,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`
 
-**"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 +520,92 @@ 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
+
+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 /path/to/plugins/pbr/scripts/pbr-tools.js llm health`
+
+### 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
+
+After enabling local LLM, PBR logs per-call metrics to `.planning/logs/local-llm-metrics.jsonl`. Use the built-in subcommands to inspect them:
+
+```bash
+# Show session summary (calls routed, latency, token savings)
+node plugins/pbr/scripts/pbr-tools.js llm metrics
+
+# Suggest routing threshold adjustments based on recent accuracy
+node plugins/pbr/scripts/pbr-tools.js llm adjust-thresholds
+```
+
+Metrics include: routing decision, model used, latency ms, confidence score, whether the frontier fallback was triggered, and estimated tokens saved.