@sienklogic/plan-build-run 2.11.0 → 2.12.1

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.cjs` 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/hook-ordering.md

@@ -0,0 +1,89 @@
+# Hook Ordering Reference
+
+Claude Code does **not** guarantee execution order between separate hook entries
+registered on the same event matcher. This document records the ordering
+expectations and safety invariants that PBR hooks rely on.
+
+## PostToolUse Write|Edit Hooks
+
+Two independent hook entries fire on every `Write` or `Edit` tool use:
+
+| Hook Script | Purpose |
+|-------------|---------|
+| `post-write-dispatch.js` | Validates plan format, roadmap sync, state sync |
+| `post-write-quality.js` | Auto-format, type-check, detect console.log |
+
+These hooks may execute in **any order** or even concurrently. They are safe
+because they write to **different files** and do not share mutable state:
+
+- `post-write-dispatch` writes to `STATE.md`, `ROADMAP.md`, and logs.
+- `post-write-quality` only returns `additionalContext` warnings; it does not
+  write files.
+
+## PreToolUse Hooks
+
+PreToolUse hooks match on distinct tool types, so ordering between them is
+irrelevant:
+
+| Hook Script | Tool Matcher |
+|-------------|-------------|
+| `pre-write-dispatch.js` | `Write`, `Edit` |
+| `pre-bash-dispatch.js` | `Bash` |
+
+Within each dispatch script, sub-checks run sequentially and results are
+collected independently (no early returns).
+
+## Design Rules
+
+1. **No shared mutable state.** Hooks on the same event must not read/write the
+   same in-memory variable or the same file without coordination. Use
+   append-only patterns (e.g., `hook-logger.js` with `fs.open('a')`) for any
+   file that multiple hooks touch.
+
+2. **Idempotency.** Every hook must produce the same result if called twice with
+   the same input. This guards against Claude Code retrying a hook or firing it
+   redundantly.
+
+3. **Independent error handling.** Each hook wraps its logic in try-catch. One
+   hook crashing must not prevent others from running. Dispatch scripts
+   (`post-write-dispatch.js`) run all sub-checks and merge results.
+
+4. **Dirty flag protection.** `check-state-sync.js` uses mtime comparison to
+   detect external edits to `STATE.md` and `ROADMAP.md`. If another process
+   (or the user) modifies these files between hook invocations, the sync hook
+   skips the overwrite and logs a `skip-dirty` entry.
+
+## Known Safe Pairs
+
+These hook combinations fire on the same event and have been verified to not
+conflict:
+
+| Event | Hook A | Hook B | Why Safe |
+|-------|--------|--------|----------|
+| PostToolUse Write | `post-write-dispatch` | `post-write-quality` | Write different files |
+| PostToolUse Write | `post-write-dispatch` | `suggest-compact` | One writes state, other returns context |
+| PostToolUse Read | `track-context-budget` | (sole hook) | No conflict |
+| PostToolUse Task | `check-subagent-output` | (sole hook) | No conflict |
+
+## Adding New Hooks
+
+When registering a new hook on an existing event:
+
+1. Check this table for conflicts with existing hooks on the same event.
+2. Ensure your hook does not write to files that another hook on the same event
+   also writes.
+3. If you must share a file, use append-only writes (`fs.open` with `'a'` flag).
+4. Add your hook to the "Known Safe Pairs" table above.
+
+## PreToolUse and Session JSONL Logging
+
+**[Todo 016] Investigation result: by design.**
+
+Claude Code's session JSONL (at `~/.claude/projects/*/`) records tool calls, not hook decisions.
+
+- When a PreToolUse hook **allows** (exit 0): the tool runs and a `tool_use` + `tool_result` pair appears in session JSONL. The hook decision itself is NOT separately logged in session JSONL — visible only in `.planning/logs/hooks-*.jsonl`.
+- When a PreToolUse hook **blocks** (exit 2): the tool never runs, so no `tool_use` entry appears in session JSONL. The block IS recorded in `.planning/logs/hooks-*.jsonl`.
+
+**Implication for audit analysis:** The `/pbr:audit` behavioral compliance dimensions that rely on session JSONL will not see PreToolUse hook decisions. Use `.planning/logs/hooks-*.jsonl` directly for hook enforcement evidence. The BC-04 dimension (block-skill-self-read enforcement) should be verified from the hooks log, not session JSONL.
+
+**No code change required.** This is consistent with Claude Code's architecture.

package/plugins/pbr/references/limitations.md

@@ -0,0 +1,106 @@
+# Accepted Limitations
+
+Known constraints in PBR's hook and CLI architecture. Each section explains
+the limitation, why it exists, and the recommended workaround.
+
+---
+
+## PostToolUse Hooks Are Warn-Only
+
+**Limitation**: PostToolUse hooks fire AFTER the tool has already executed. They
+can return `{ additionalContext: "..." }` to surface warnings, but they CANNOT
+block or undo the tool call.
+
+**Contrast with PreToolUse**: PreToolUse hooks fire BEFORE execution and can
+return `{ decision: "block", reason: "..." }` to prevent the action entirely.
+
+**Why it matters**: Validation that lives in a PostToolUse hook (e.g.,
+`check-plan-format.js` warning about malformed frontmatter) is advisory. The
+malformed file is already written to disk by the time the warning appears.
+
+**What to do instead**:
+
+- For critical enforcement (phase boundary, dangerous commands, format gates),
+  use **PreToolUse** hooks that block before execution.
+- Use PostToolUse only for telemetry, context injection, and soft advisories
+  where the cost of a bad write is recoverable.
+- Example: `check-phase-boundary.js` runs as PreToolUse to block cross-phase
+  writes. `post-write-quality.js` runs as PostToolUse because a missed
+  formatting warning is not destructive.
+
+---
+
+## CLI Commands in Prompts Are Best-Effort
+
+**Limitation**: When skill or agent prompts instruct the LLM to run CLI
+commands (e.g., `node pbr-tools.cjs state advance-plan`), the LLM may skip
+them under cognitive load. Prompt instructions are suggestions, not guarantees.
+
+**Why it matters**: State updates, progress tracking, and roadmap syncing that
+rely on agents calling CLI commands will be missed when the agent's context is
+saturated or it encounters deviations.
+
+**What to do instead**:
+
+- For critical state updates, use **hooks that fire automatically**. For
+  example, `check-state-sync.js` auto-syncs STATE.md on ROADMAP.md writes
+  without any agent cooperation.
+- Reserve CLI commands in prompts for actions where skipping is tolerable or
+  where hook-level enforcement is impractical.
+- Design principle: "Push intelligence into CODE (hooks/scripts), not PROMPTS
+  (markdown)."
+
+---
+
+## Hook Execution Order Is Not Guaranteed
+
+**Limitation**: When multiple hooks register on the same Claude Code event
+(e.g., two PostToolUse hooks on `Write`), their execution order is undefined.
+They may run sequentially in any order, or concurrently.
+
+**Why it matters**: If Hook A writes a file that Hook B reads, the result
+depends on which runs first -- producing nondeterministic behavior.
+
+**What to do instead**:
+
+- Design hooks to be **independent**: no hook should depend on another hook
+  having already run on the same event.
+- Hooks on the same event must not write to the same file. Use append-only
+  patterns (`fs.open` with `'a'` flag) for shared log files.
+- Each hook must be **idempotent** -- calling it twice with the same input
+  produces the same result.
+- See `references/hook-ordering.md` for the Known Safe Pairs table and
+  conflict-checking procedure when adding new hooks.
+
+---
+
+## Session State Flows via stdin, Not Shared Memory
+
+**Limitation**: Each hook invocation receives session context (`session_id`,
+`tool_name`, tool input) as a JSON blob on stdin. There is no persistent
+in-process state between hook calls -- every invocation is a fresh Node.js
+process.
+
+**Why it matters**: Hooks cannot accumulate state across calls without writing
+to disk. Any cross-call coordination requires file I/O (e.g., `.active-skill`
+files, mtime comparisons).
+
+**What to do instead**:
+
+- Accept the per-invocation cost of stdin parsing. It is fast (< 1ms) and
+  reliable.
+- For state that must persist across hook calls, use well-defined files with
+  clear ownership (one writer, many readers).
+- For session-scoped state, use the `session_id` from stdin to namespace files
+  (e.g., `.active-skill-{session_id}`).
+
+---
+
+## Summary Table
+
+| Limitation | Risk | Mitigation |
+|-----------|------|------------|
+| PostToolUse warn-only | Bad writes not blocked | Use PreToolUse for critical checks |
+| CLI in prompts skipped | State updates missed | Use auto-firing hooks instead |
+| Hook order undefined | Race conditions | Design hooks to be independent |
+| stdin-only session state | No cross-call memory | Use namespaced files for persistence |

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