@sienklogic/plan-build-run 2.21.0 → 2.21.2

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

@@ -0,0 +1,109 @@
+---
+component: verifier
+version: 2
+last_calibrated: 2026-03-25
+calibration_source: "153 verification entries, 89% pass rate, 3 gap categories"
+---
+
+# Verifier Few-Shot Examples
+
+## Positive Examples
+
+### Example 1: Thorough multi-level artifact verification with real gap discovery
+
+**Input:** Must-have artifact: `plugins/pbr/scripts/context-bridge.js: >50 lines`
+
+**Output:**
+
+> **L1 (Existence):** EXISTS -- `plugins/pbr/scripts/context-bridge.js` found, 187 lines.
+> **L2 (Substantive):** SUBSTANTIVE -- No TODO/FIXME markers, 4 exported functions (`updateContextTier`, `getContextBudget`, `injectContextWarning`, `resetTierState`), non-trivial logic with config reads and threshold calculations.
+> **L3 (Wired):** WIRED -- Imported by `plugins/pbr/hooks/hooks.json` as PostToolUse handler (line 47). Called by `post-write-dispatch.js` at line 23 via `require('./context-bridge')`. Arguments verified: receives `(toolName, data, planningDir)` matching the function signature.
+> **Status: PASSED**
+
+**Why this is good:** The verifier checked all three levels independently with specific evidence at each level -- file path, line count, exported symbols, import location, and argument verification. It did not stop at "file exists" but traced wiring through to actual usage with correct arguments.
+
+### Example 2: Correct FAILED classification with grep evidence
+
+**Input:** Must-have truth: `validate-commit.js rejects commits missing scope parentheses`
+
+**Output:**
+
+> **Method:** Ran `grep -n "scope" plugins/pbr/scripts/validate-commit.js` to locate scope validation logic.
+> **Evidence:** Lines 34-41 show regex `/^(feat|fix|refactor|test|docs|chore|wip)\(/` which requires opening paren after type. However, no test for MISSING closing paren exists -- the regex accepts `feat(: description` (missing scope content and closing paren).
+> **Ran:** `echo "feat(: test" | node plugins/pbr/scripts/validate-commit.js` -- exit code 0 (accepted).
+> **Status: FAILED** -- Commit messages with empty scope `feat(: desc)` are accepted. The truth "rejects commits missing scope parentheses" does not hold for empty-scope edge case.
+
+**Why this is good:** The verifier did not trust the code's intent -- it ran an actual test with an edge case input and reported the specific failure. Evidence includes the regex, the test command, the exit code, and why the truth does not hold.
+
+### Example 3: Catching missing wiring (calibration-derived gap pattern)
+
+**Input:** Must-have key_link: `check-subagent-output.js imports and calls feedback-loop.js extractFeedback()`
+
+**Output:**
+
+> **Method:** Ran `grep -n "feedback-loop\|extractFeedback" plugins/pbr/scripts/check-subagent-output.js`.
+> **Evidence:** Zero matches. The file `feedback-loop.js` exists (172 lines, substantive), and `tests/feedback-loop.test.js` passes (229 lines). But `check-subagent-output.js` never imports or calls it.
+> **Cross-check:** `grep -rn "require.*feedback-loop" plugins/pbr/scripts/` returns zero results across all scripts.
+> **Status: FAILED** -- The artifact exists and is tested, but is completely orphaned. The key_link "imports and calls" does not hold. This is a **missing wiring** gap.
+
+**Why this is good:** The verifier caught a common calibration pattern: code that exists, is tested, but is never actually wired into the system. L1 and L2 pass, but L3 (wiring) fails. This pattern accounts for 37% of all gaps found in calibration corpus.
+
+### Example 4: Catching missing config schema entries (calibration-derived gap pattern)
+
+**Input:** Must-have truth: `Config toggles features.architecture_graph and features.architecture_guard exist with defaults`
+
+**Output:**
+
+> **Method:** Ran `grep "architecture_graph\|architecture_guard" plugins/pbr/scripts/config-schema.json`.
+> **Evidence:** Zero matches in schema. However, `grep "architecture" plugins/pbr/scripts/lib/config.js` shows both flags in CONFIG_DEFAULTS (lines 426, 428).
+> **Gap:** Defaults exist in code but schema validation doesn't know about them. `configValidate()` would strip these fields on load, making the defaults unreachable.
+> **Status: FAILED** -- Config flags work in code but are invisible to schema validation. This is a **missing wiring** gap between config layers.
+
+**Why this is good:** The verifier checked multiple config layers (schema vs defaults vs code) rather than just one. Config wiring requires schema + defaults + code to agree — checking only one layer misses layer-mismatch bugs.
+
+### Example 5: Distinguishing planning gaps from execution failures
+
+**Input:** Must-have truth: `All MSYS regex patterns consolidated into shared module`
+
+**Output:**
+
+> **Method:** Ran `grep -rn "\/\[a-zA-Z\]\/" plugins/pbr/scripts/` to find inline MSYS regex.
+> **Evidence:** 2 matches in `commands/misc.js` (lines 26, 487). These were NOT in the original plan scope — Phase 148 extracted code into misc.js AFTER Phase 149's plan was written.
+> **Assessment:** The executor correctly completed all planned tasks. The gap is a **planning ordering issue**, not an execution failure.
+> **Status: PASS_WITH_NOTES** -- Executor did what was planned. Unconsolidated regex noted as follow-up, not as a failure of this phase.
+
+**Why this is good:** The verifier distinguished between what was planned vs what exists now. Code that changed AFTER plan creation is a planning gap, not an executor failure. This prevents false FAIL verdicts on correctly-executed work.
+
+## Calibration-Derived Gap Patterns
+
+Based on analysis of 153 verification entries (80% pass rate, 8 gaps):
+
+| Pattern | Count | % of Gaps | What to Check |
+|---------|-------|-----------|---------------|
+| Missing wiring | 3 | 37% | File exists + tested but never imported/called by consumer |
+| Missing tests | 2 | 25% | Feature works but test file excluded from CI or never runs |
+| Other | 3 | 38% | Config layer mismatches, planning ordering issues, schema gaps |
+
+## Negative Examples
+
+### Example 1: Blanket pass with no per-criterion evidence
+
+**Input:** Must-haves: 5 truths, 3 artifacts, 2 key_links from plan frontmatter.
+
+**Output:**
+
+> All must-haves have been verified. The implementation matches the plan requirements. Files exist and are properly connected. Status: PASSED.
+> must_haves_checked: 10, must_haves_passed: 10
+
+**Why this is bad:** No individual must-have is listed or checked. No file paths, no line numbers, no grep output, no level-by-level breakdown. The verifier restated the must-haves as passing without showing any evidence. This would miss stubs, orphaned exports, and broken wiring.
+
+### Example 2: File existence check without substance or wiring verification
+
+**Input:** Must-have artifact: `plugins/pbr/scripts/audit-checks/index.js: >100 lines`
+
+**Output:**
+
+> **L1 (Existence):** EXISTS -- File found at `plugins/pbr/scripts/audit-checks/index.js`, 142 lines.
+> **Status: PASSED**
+
+**Why this is bad:** The verifier stopped at Level 1. The file has 142 lines but could contain `// TODO: implement all checks` with stub functions returning empty objects. Level 2 (substantive) and Level 3 (wired) were skipped entirely. A file that exists but is never imported or contains only placeholder code should not pass.

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

@@ -7,23 +7,42 @@ Plan-Build-Run's commit conventions, commit points, branching strategy, and hook
 ## Commit Message Format
 
 ```
-{type}({phase}-{plan}): {description}
+{type}({scope}): {description}
 ```
 
 ### Components
 
 | Part | Description | Example |
 |------|-------------|---------|
-| `{type}` | Conventional commit type | `feat`, `fix`, `test` |
-| `{phase}` | Phase number (zero-padded) | `02` |
-| `{plan}` | Plan number | `01` |
-| `{description}` | Imperative, lowercase description | `implement discord oauth client` |
-
-The format is configurable via `config.json` at `git.commit_format`. The default is `{type}({phase}-{plan}): {description}`.
+| `{type}` | Conventional commit type | `feat`, `fix`, `chore` |
+| `{scope}` | Component name for the area of change | `hooks`, `skills`, `agents` |
+| `{description}` | Imperative, lowercase description | `add drift detection to state sync` |
+
+The format is configurable via `config.json` at `git.commit_format`. The default is `{type}({scope}): {description}`.
+
+### Component Scopes
+
+Use these scopes to indicate which part of PBR the change affects. git-cliff uses these to group changelog entries by component.
+
+| Scope | What It Covers | Example |
+|-------|---------------|---------|
+| `hooks` | Hook scripts in `hooks/` and `plugins/pbr/scripts/` | `feat(hooks): add drift detection to state sync` |
+| `skills` | SKILL.md files and skill logic | `feat(skills): add velocity metrics to status` |
+| `agents` | Agent definitions in `agents/` | `fix(agents): scale executor budget for 1M context` |
+| `cli` | `pbr-tools.js` and `bin/lib/` modules | `feat(cli): implement stateRederive command` |
+| `dashboard` | Dashboard UI and server | `fix(dashboard): handle missing phases in chart` |
+| `templates` | `.tmpl` template files | `feat(templates): add XML sections to CONTEXT.md` |
+| `plugin` | Plugin manifests, CLAUDE.md, commands | `chore(plugin): bump version to 2.9.0` |
+| `config` | Config schema, validation, defaults | `feat(config): add node_repair_budget setting` |
+| `ci` | GitHub Actions, lint, coverage | `fix(ci): lower branch coverage threshold` |
+| `tests` | Test files and fixtures | `test(tests): add resolve-root macOS symlink test` |
+| `refs` | Reference docs in `references/` | `docs(refs): document hook ordering expectations` |
+| `commands` | Command registration files | `feat(commands): add autonomous command` |
 
 ### Full Example
+
 ```
-feat(02-01): implement discord oauth client
+feat(hooks): implement stateRederive with drift detection
 ```
 
 ---
@@ -32,26 +51,60 @@ feat(02-01): implement discord oauth client
 
 | Type | When to Use | Example |
 |------|------------|---------|
-| `feat` | New feature or functionality | `feat(02-01): implement discord oauth client` |
-| `fix` | Bug fix (including during execution) | `fix(02-01): handle null user profile from discord api` |
-| `refactor` | Code restructuring, no behavior change | `refactor(02-01): extract token validation into helper` |
-| `test` | Adding or modifying tests | `test(02-01): add failing tests for discord oauth flow` |
-| `docs` | Documentation changes | `docs(03-02): add api endpoint documentation` |
-| `chore` | Build config, dependencies, tooling | `chore(01-01): configure typescript and eslint` |
-| `style` | Formatting, whitespace (no logic change) | `style(02-01): fix import ordering` |
+| `feat` | New feature or functionality | `feat(skills): add velocity metrics to status` |
+| `fix` | Bug fix (including during execution) | `fix(hooks): resolve MSYS path bridging on Windows` |
+| `refactor` | Code restructuring, no behavior change | `refactor(cli): extract state mutations to lib/state.cjs` |
+| `test` | Adding or modifying tests | `test(hooks): add resolve-root tests for walk-up discovery` |
+| `docs` | Documentation changes | `docs(refs): document hook ordering expectations` |
+| `chore` | Build config, dependencies, tooling | `chore(plugin): bump version to 2.9.0` |
+| `wip` | Work in progress (use sparingly) | `wip(skills): partial checkpoint routing` |
+| `revert` | Reverting a previous commit | `revert(hooks): revert auto-continue signal file change` |
+| `perf` | Performance improvement | `perf(cli): cache resolveProjectRoot result` |
+| `ci` | CI/CD changes | `ci(ci): add markdownlint job to test workflow` |
+| `build` | Build system changes | `build(plugin): update hooks.json paths` |
+
+---
+
+## Commit Type Discipline
+
+| Type | Use For | Appears in Changelog |
+|------|---------|---------------------|
+| `feat` | User-visible features ONLY (new commands, new config options, changed behavior users notice) | YES |
+| `fix` | Bug fixes users would notice | YES |
+| `refactor` | Internal restructuring, TDD GREEN commits, code cleanup | No |
+| `test` | Test additions including TDD RED commits | No |
+| `docs` | Documentation (hidden — mostly planning artifacts) | No |
+| `chore` | Build config, deps, tooling, internal scaffolding | No |
+| `wip` | Work in progress (use sparingly) | No |
+| `revert` | Reverting a previous commit | YES |
+
+**TDD commits**: RED phase → `test({scope}): RED - ...`, GREEN phase → `refactor({scope}): GREEN - ...`, REFACTOR phase → `refactor({scope}): REFACTOR - ...`
 
 ---
 
-## Special Commit Scopes
+## Special Commit Patterns
 
-Beyond the standard `{phase}-{plan}` scope, Plan-Build-Run recognizes these additional patterns:
+Beyond component scopes, Plan-Build-Run recognizes these additional patterns:
 
 | Pattern | When Used | Example |
 |---------|-----------|---------|
 | `{type}(quick-{NNN})` | Quick-task commits via `/pbr:quick` | `feat(quick-001): add health endpoint` |
 | `docs(planning)` | Planning document commits | `docs(planning): add phase 3 plans` |
-| `wip: {desc}` or `wip({area}): {desc}` | Work-in-progress (use sparingly) | `wip(auth): partial oauth implementation` |
-| Merge commits | Git merge operations | `Merge branch 'plan-build-run/phase-02-auth'` |
+| `wip: {desc}` or `wip({area}): {desc}` | Work-in-progress (use sparingly) | `wip(skills): partial checkpoint routing` |
+| Merge commits | Git merge operations | `Merge branch 'feature/auth-rework'` |
+
+---
+
+## Session Affinity Metadata
+
+When a session ID is available, append a `[session:{short_id}]` suffix to the commit description. The `short_id` is the first 8 characters of the session_id. This enables conflict tracing across concurrent sessions.
+
+Example:
+```
+feat(auth): implement discord oauth client [session:a1b2c3d4]
+```
+
+When no session ID is available (e.g., manual commits), omit the suffix.
 
 ---
 
@@ -60,7 +113,7 @@ Beyond the standard `{phase}-{plan}` scope, Plan-Build-Run recognizes these addi
 For commits that need explanation, add a body after a blank line:
 
 ```
-feat(02-01): implement discord oauth client
+feat(02-01): implement discord oauth client [session:a1b2c3d4]
 
 - Uses discord-oauth2 library for token exchange
 - Stores tokens in httpOnly cookies for security
@@ -84,9 +137,9 @@ Each successfully completed plan task gets exactly one atomic commit. No more, n
 TDD tasks (`tdd="true"`) produce exactly 3 commits following Red-Green-Refactor:
 
 ```
-test(02-01): RED - add failing tests for auth middleware
-feat(02-01): GREEN - implement auth middleware to pass tests
-refactor(02-01): REFACTOR - extract token verification helper
+test(auth): RED - add failing tests for auth middleware
+refactor(auth): GREEN - implement auth middleware to pass tests
+refactor(auth): REFACTOR - extract token verification helper
 ```
 
 ### Commit Preconditions
@@ -125,15 +178,15 @@ When an executor applies a deviation rule during a task, the deviation is includ
 ```bash
 # Standard task
 git add src/auth/discord.ts src/auth/types.ts
-git commit -m "feat(02-01): implement Discord OAuth client with token exchange"
+git commit -m "feat(auth): implement Discord OAuth client with token exchange"
 
 # Task that also installed a dependency (Rule 2)
 git add src/auth/discord.ts src/auth/types.ts package.json package-lock.json
-git commit -m "feat(02-01): implement Discord OAuth client with token exchange"
+git commit -m "feat(auth): implement Discord OAuth client with token exchange"
 
 # TDD RED
 git add tests/auth/discord.test.ts
-git commit -m "test(02-01): add failing tests for Discord OAuth flow"
+git commit -m "test(auth): add failing tests for Discord OAuth flow"
 ```
 
 ---
@@ -174,6 +227,36 @@ Branch name templates are configured in `config.json`:
 - `git.phase_branch_template`: Default `plan-build-run/phase-{phase}-{slug}`
 - `git.milestone_branch_template`: Default `plan-build-run/{milestone}-{slug}`
 
+### PR Creation
+
+When `git.auto_pr: true` and `git.branching` is `phase` or `milestone`, the build skill creates a GitHub PR after verification passes:
+
+1. Push the phase branch to the remote
+2. Create a PR via `gh pr create` with structured title and body
+3. PR title follows the commit convention: `feat(phase-{N}): {phase slug}`
+4. PR body includes phase goal, key files changed, and must-have verification results
+
+When `git.auto_pr: false` (default), the build skill offers the user a choice after verification:
+- Create PR now
+- Skip PR creation
+- Push branch only (create PR later)
+
+PR creation requires `gh` CLI authenticated with repo write access.
+
+### CI Integration
+
+When `ci.gate_enabled: true`, the build skill checks GitHub Actions status after each wave completes:
+
+1. Run: `gh run list --branch $(git branch --show-current) --limit 1 --json status,conclusion,url`
+2. If `status == completed` and `conclusion == success`: proceed to next wave
+3. If `status == in_progress`: wait up to `ci.wait_timeout_seconds`, re-check
+4. If `conclusion != success` or timeout: surface warning with run URL and offer:
+   - **Wait**: continue polling
+   - **Continue anyway**: proceed despite CI failure (logged as deviation)
+   - **Abort**: stop the build
+
+CI gate requires `gh` CLI and GitHub Actions configured on the repository. The gate only activates when there are commits pushed to a remote branch (branching must be enabled).
+
 ### Git Mode
 
 The `git.mode` field controls whether git integration is active:
@@ -207,7 +290,7 @@ Plan-Build-Run uses Claude Code hooks (defined in `hooks/hooks.json`) to enforce
 
 The commit validation hook (`PreToolUse` on Bash commands) enforces the commit format:
 - Checks that `git commit -m "..."` messages match the pattern: `{type}({scope}): {description}`
-- Valid types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `wip`
+- Valid types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `wip`, `revert`
 - Allows merge commits (starting with "Merge")
 - Allows quick-task, planning, and WIP scope patterns
 - Blocks commits with sensitive file patterns (`.env`, `.key`, `.pem`, credentials) unless they match safe patterns (`.example`, `.template`, `.sample`, test directories)

package/plugins/pbr/references/git-planning-commit.md

@@ -0,0 +1,35 @@
+# Git Planning Commit
+
+Use git directly for `.planning/` file commits. Check `commit_docs` in config and `.gitignore` before committing. If `commit_docs: false` in config or `.planning/` is gitignored, skip committing planning files.
+
+## Commit via git
+
+```bash
+# Check if .planning/ is gitignored first
+git check-ignore -q .planning/ && echo "SKIP: .planning/ is gitignored" || git add .planning/STATE.md .planning/ROADMAP.md && git commit -m "docs({scope}): {description}"
+```
+
+## Amend previous commit
+
+To fold `.planning/` file changes into the previous commit:
+
+```bash
+git add .planning/codebase/*.md && git commit --amend --no-edit
+```
+
+## Commit Message Patterns
+
+| Command | Scope | Example |
+|---------|-------|---------|
+| plan-phase | phase | `docs(phase-03): create authentication plans` |
+| execute-phase | phase | `docs(phase-03): complete authentication phase` |
+| new-milestone | milestone | `docs: start milestone v1.1` |
+| remove-phase | chore | `chore: remove phase 17 (dashboard)` |
+| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` |
+| add-phase | phase | `docs: add phase 07 (settings page)` |
+
+## When to Skip
+
+- `commit_docs: false` in config
+- `.planning/` is gitignored
+- No changes to commit (check with `git status --porcelain .planning/`)

package/plugins/pbr/references/model-profile-resolution.md

@@ -0,0 +1,34 @@
+# Model Profile Resolution
+
+Resolve model profile once at the start of orchestration, then use it for all Task spawns.
+
+## Resolution Pattern
+
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+Default: `balanced` if not set or config missing.
+
+## Lookup Table
+
+@${CLAUDE_PLUGIN_ROOT}/references/model-profiles.md
+
+Look up the agent in the table for the resolved profile. Pass the model parameter to Task calls:
+
+```
+Task(
+  prompt="...",
+  subagent_type="pbr-planner",
+  model="{resolved_model}"  # "inherit", "sonnet", or "haiku"
+)
+```
+
+**Note:** Opus-tier agents resolve to `"inherit"` (not `"opus"`). This causes the agent to use the parent session's model, avoiding conflicts with organization policies that may block specific opus versions.
+
+## Usage
+
+1. Resolve once at orchestration start
+2. Store the profile value
+3. Look up each agent's model from the table when spawning
+4. Pass model parameter to each Task call (values: `"inherit"`, `"sonnet"`, `"haiku"`)

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

@@ -4,9 +4,29 @@ How Plan-Build-Run maps agents to models and how to configure model selection.
 
 ---
 
+## Session Model (Orchestrator)
+
+The orchestrator is your main Claude Code session -- it reads skills, manages state, and routes work to agents. Its model is whatever you selected in Claude Code (not controlled by PBR's `config.json`).
+
+**Cost impact:** The orchestrator accounts for roughly 40% of total session cost. Agents set to `inherit` (planner, executor, debugger, general in the `balanced` profile) also use this model. Switching your session from Opus to Sonnet reduces cost for both the orchestrator and all `inherit` agents.
+
+**Recommendations:**
+
+| Goal | Session Model | Config Adjustment |
+|------|---------------|-------------------|
+| Maximum quality | Opus | None needed -- `inherit` agents get Opus |
+| Balanced cost/quality | Sonnet | None needed -- `inherit` agents get Sonnet, which handles most tasks well |
+| Cheap orchestration, Opus agents | Sonnet | Set `planner: "opus"`, `executor: "opus"`, `debugger: "opus"` to override inherit |
+
+Sonnet 4.6 handles orchestration tasks (state reading, routing decisions, context assembly) effectively. Reserve Opus for agents doing complex reasoning, architecture, or novel code generation.
+
+---
+
 ## Agent-to-Model Mapping
 
-Each Plan-Build-Run agent has a default model specified in its agent definition frontmatter (`model:` field). These defaults are overridden by the `models` section of `config.json`.
+Each Plan-Build-Run agent's model is controlled by `config.json models.*`. When no config entry exists for an agent, the agent inherits the session model.
+
+The `model:` frontmatter field has been removed from PBR agent definitions — `config.json` is now the sole source of truth for agent model assignment.
 
 ### Default Agent Models
 
@@ -22,14 +42,16 @@ Each Plan-Build-Run agent has a default model specified in its agent definition
 | `codebase-mapper` | `sonnet` | Codebase analysis requires thorough reasoning |
 | `synthesizer` | `haiku` | Synthesis is mechanical combination; speed over depth |
 | `general` | `inherit` | Lightweight utility; inherits session model |
+| `audit` | `inherit` | Session log analysis inherits session model |
+| `dev-sync` | `inherit` | Cross-plugin sync is mechanical; inherits session model |
 
-The `inherit` value means the agent uses whatever model the parent session is running (typically the user's configured Claude model).
+The `inherit` value means the agent uses whatever model the parent session is running (typically the user's configured Claude model). Defaults listed above are the effective values from the `balanced` profile in `config.json`.
 
 ---
 
 ## Model Profile Presets
 
-The `/pbr:config model-profile {preset}` command sets all agent models at once using a preset:
+The `/pbr:settings model-profile {preset}` command sets all agent models at once using a preset:
 
 | Profile | Researcher | Planner | Executor | Verifier | Int-Checker | Debugger | Mapper | Synthesizer |
 |---------|-----------|---------|----------|----------|-------------|----------|--------|-------------|
@@ -45,17 +67,56 @@ The `/pbr:config model-profile {preset}` command sets all agent models at once u
 - **budget**: All agents use haiku. Fastest and cheapest, but reduced quality for complex reasoning tasks. Suitable for well-defined, mechanical work.
 - **adaptive**: Front-loads intelligence in research and planning (where decisions matter most), uses lighter models for mechanical execution and verification. Good cost-quality tradeoff.
 
+### context_window_tokens per Profile
+
+| Profile | context_window_tokens |
+|---------|----------------------|
+| `quality` | `1000000` |
+| `balanced` | `200000` |
+| `budget` | `200000` |
+| `adaptive` | `200000` |
+
+The `quality` profile targets Claude models with 1M context windows (e.g., Claude Opus with extended context). All other profiles default to 200000, matching Claude Sonnet and Haiku context windows. Adjust manually via `/pbr:settings` or by editing `config.json` if your model has a different context window size.
+
+### 1M Context Feature Defaults per Profile
+
+When using `/pbr:settings model-profile {preset}`, these feature defaults are also applied:
+
+| Feature | quality | balanced | budget | adaptive |
+|---------|---------|----------|--------|----------|
+| `workflow.inline_execution` | `true` | `false` | `false` | `false` |
+| `features.inline_verify` | `true` | `false` | `false` | `false` |
+| `features.extended_context` | `true` | `false` | `false` | `false` |
+| `workflow.phase_boundary_clear` | `"recommend"` | `"off"` | `"off"` | `"off"` |
+| `workflow.autonomous` | `false` | `false` | `false` | `false` |
+| `workflow.speculative_planning` | `false` | `false` | `false` | `false` |
+| `workflow.phase_replay` | `false` | `false` | `false` | `false` |
+| `planning.multi_phase` | `false` | `false` | `false` | `false` |
+| `intel.enabled` | `false` | `false` | `false` | `false` |
+| `intel.auto_update` | `false` | `false` | `false` | `false` |
+| `intel.inject_on_start` | `false` | `false` | `false` | `false` |
+| `context_ledger.enabled` | `true` | `false` | `false` | `false` |
+| `context_ledger.stale_after_minutes` | `60` | `60` | `60` | `60` |
+| `learnings.enabled` | `true` | `false` | `false` | `false` |
+| `learnings.read_depth` | `5` | `3` | `3` | `3` |
+| `context_budget.threshold_curve` | `"adaptive"` | `"linear"` | `"linear"` | `"linear"` |
+| `verification.confidence_gate` | `false` | `false` | `false` | `false` |
+| `verification.confidence_threshold` | `1.0` | `1.0` | `1.0` | `1.0` |
+| `gates.checkpoint_auto_resolve` | `"none"` | `"none"` | `"none"` | `"none"` |
+
+**Quality profile rationale:** Enables safe 1M-native features (learnings, inline execution, adaptive thresholds, context ledger, phase boundary recommendations). Keeps experimental features disabled (intel, autonomous, speculative planning, confidence gate, multi-phase planning) -- these require explicit opt-in via `/pbr:settings` or config.json.
+
 ---
 
 ## Configuring Models
 
 ### Per-Agent Configuration
 
-Set an individual agent's model via `/pbr:config`:
+Set an individual agent's model via `/pbr:settings`:
 
 ```
-/pbr:config model executor sonnet
-/pbr:config model verifier opus
+/pbr:settings model executor sonnet
+/pbr:settings model verifier opus
 ```
 
 Or edit `config.json` directly:
@@ -88,6 +149,28 @@ Note: Claude Code 2.1.45+ supports Sonnet 4.6. Model values are abstract names
 
 ---
 
+## Custom Profiles
+
+The `model_profiles` key in `config.json` lets you define named profiles beyond the four built-in presets. Each profile is a partial map of agent names to model strings — omitted agents fall back to the active profile defaults.
+
+```json
+{
+  "model_profiles": {
+    "my-profile": {
+      "executor": "opus",
+      "planner": "opus",
+      "synthesizer": "sonnet"
+    }
+  }
+}
+```
+
+Activate a custom profile with `/pbr:settings model-profile my-profile`. The profile merges with the `balanced` preset: any agent not listed in your custom profile uses its `balanced` default.
+
+Partial profiles are allowed — you can override just the agents you care about. This is useful for temporarily upgrading a single agent without specifying the rest.
+
+---
+
 ## Model Selection in Skill Orchestration
 
 Skills that spawn subagents use the `model` parameter in `Task()` calls. Some skills hardcode a lighter model for specific tasks:
@@ -96,4 +179,4 @@ Skills that spawn subagents use the `model` parameter in `Task()` calls. Some sk
 - **Build skill**: Spawns codebase mapper updates with `model: "haiku"` for incremental map refreshes
 - **Plan skill**: Uses the configured `planner` model for main planning work
 
-The `subagent_type` parameter automatically loads the agent definition, and the model from `config.json` takes precedence over the agent's default `model:` frontmatter field.
+The `subagent_type` parameter automatically loads the agent definition, and the model from `config.json` takes precedence over any agent-level model setting.

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

@@ -14,7 +14,7 @@ Plan-Build-Run uses adaptive model selection to balance cost and capability.
 |-----------|-------|-----------|
 | simple | haiku | Fast, cheap — sufficient for mechanical changes |
 | medium | sonnet | Good balance for standard feature work |
-| complex | inherit | Uses session model — typically Opus for critical work |
+| complex | inherit | Uses session model — see `model-profiles.md` Session Model section for cost implications |
 
 ## Override Mechanisms
 

package/plugins/pbr/references/node-repair.md

@@ -0,0 +1,48 @@
+# Node Repair System
+
+When a task fails during execution, the executor follows this repair taxonomy:
+
+## RETRY (Attempt 1)
+
+**Trigger**: Task verification fails (test error, lint error, missing artifact).
+**Action**: Re-attempt with adjustment based on the error.
+**Budget**: 1 retry per task (2 total attempts before escalating).
+**What changes**: Fix the specific error, don't restructure.
+
+## DECOMPOSE (Attempt 2)
+
+**Trigger**: Retry failed. Task may be too complex.
+**Action**: Split the task into 2-3 sub-tasks and execute them sequentially.
+**Budget**: Sub-tasks get 1 attempt each (no recursion).
+**What changes**: Break down, don't change approach.
+
+## PRUNE (Skip with justification)
+
+**Trigger**: Decomposed sub-tasks also fail. Task is not critical-path.
+**Action**: Skip the task, document in SUMMARY.md deviations (Rule 3).
+**Condition**: Only if task is NOT in must_haves. Must-have tasks cannot be pruned.
+**What changes**: Remove from execution, add to deferred.
+
+## ESCALATE (Ask user)
+
+**Trigger**: Must-have task failed after retry+decompose, OR task requires decisions outside plan scope.
+**Action**: Stop execution. Present the failure with context. Ask user for direction.
+**What changes**: Nothing -- user decides next step.
+
+## Budget Summary
+
+- 2 attempts per task (original + 1 retry)
+- 1 decompose pass (2-3 sub-tasks, 1 attempt each)
+- Then PRUNE or ESCALATE
+- Total max attempts before giving up: ~5 per original task
+
+## Executor Integration
+
+The executor reads this reference before execution. For each task:
+
+1. Execute task
+2. Verify task (run tests, check artifacts)
+3. If verification fails -> RETRY
+4. If retry fails -> DECOMPOSE
+5. If sub-tasks fail -> PRUNE (if not must-have) or ESCALATE (if must-have)
+6. Record repair actions in SUMMARY.md deviations