@sienklogic/plan-build-run 2.3.0 → 2.4.0

package/plugins/copilot-pbr/references/checkpoints.md

@@ -0,0 +1,158 @@
+<!-- canonical: ../../pbr/references/checkpoints.md -->
+# Checkpoints Reference
+
+How Plan-Build-Run uses checkpoint tasks to pause execution and involve the human.
+
+---
+
+## What Are Checkpoints?
+
+Checkpoints are special task types that cause the executor agent to **stop execution** and return control to the orchestrator (or the human). They exist because some tasks require human judgment, manual action, or verification that cannot be automated.
+
+Checkpoints are defined in plan task XML via the `type` attribute. When the executor encounters a checkpoint task, it follows a specific protocol depending on the checkpoint type.
+
+---
+
+## Checkpoint Types
+
+Plan-Build-Run supports three checkpoint types:
+
+### checkpoint:human-verify
+
+**Purpose**: The executor has completed work, but a human needs to visually inspect or manually test the result before proceeding.
+
+**Executor behavior**:
+1. Execute the task's `<action>` steps normally
+2. Commit the changes
+3. **STOP execution**
+4. Return a structured `CHECKPOINT: HUMAN-VERIFY` response containing:
+   - What was done (summary of action taken)
+   - What to verify (from the task's `<done>` condition)
+   - How to verify (instructions derived from `<verify>`)
+   - Completed tasks table
+   - Remaining tasks list
+
+**Use when**: The result requires subjective judgment (UI looks correct, behavior feels right, output makes sense) that automated verification cannot cover.
+
+**Example scenario**: A template was created and needs visual review in the browser, or an API integration needs manual testing with real credentials.
+
+### checkpoint:decision
+
+**Purpose**: The plan reaches a point where a human decision is needed before the executor can continue. The task is NOT executed — execution pauses before the task starts.
+
+**Executor behavior**:
+1. **STOP before executing the task**
+2. Return a structured `CHECKPOINT: DECISION` response containing:
+   - The decision that needs to be made (from `<action>`)
+   - Available options
+   - Context to help the human decide
+   - Completed tasks table
+
+**Use when**: The plan has a fork point where different approaches are possible and the right choice depends on human preference, business context, or information the planner could not determine.
+
+**Example scenario**: Choosing between two authentication providers, deciding whether to use a specific third-party library or build in-house.
+
+### checkpoint:human-action
+
+**Purpose**: The task requires something the executor cannot do — a manual step that involves the human interacting with external systems, creating accounts, or performing physical actions.
+
+**Executor behavior**:
+1. **STOP before executing the task**
+2. Return a structured `CHECKPOINT: HUMAN-ACTION` response containing:
+   - What the human needs to do (from `<action>`)
+   - Step-by-step instructions
+   - Prompt to tell the executor when done
+   - Completed tasks table
+
+**Use when**: External setup is required — creating API keys, configuring DNS, setting up OAuth applications, or any action that requires credentials or permissions the agent does not have.
+
+**Example scenario**: The human needs to create a Discord application in the Developer Portal and paste the client ID and secret into `.env`.
+
+---
+
+## Checkpoint in Plan Format
+
+Checkpoints are declared in the task's `type` attribute in the plan XML:
+
+```xml
+<task id="02-01-T3" type="checkpoint:human-verify" tdd="false">
+  <name>Verify OAuth login flow in browser</name>
+  <files>...</files>
+  <action>...</action>
+  <verify>Open browser to localhost:3000/auth/login and complete the flow</verify>
+  <done>User can log in via Discord OAuth and see their profile</done>
+</task>
+```
+
+Valid checkpoint type values:
+- `checkpoint:human-verify`
+- `checkpoint:decision`
+- `checkpoint:human-action`
+
+Non-checkpoint task types use `type="auto"`.
+
+---
+
+## Autonomous vs Non-Autonomous Plans
+
+The plan frontmatter field `autonomous: true|false` indicates whether a plan contains checkpoint tasks:
+
+| Value | Meaning |
+|-------|---------|
+| `autonomous: true` | No checkpoint tasks. The executor can complete all tasks without human intervention. |
+| `autonomous: false` | Contains at least one checkpoint task. Execution will pause at some point. |
+
+The build orchestrator uses this field to determine execution strategy:
+- Autonomous plans can be executed in parallel with other autonomous plans in the same wave
+- Non-autonomous plans may block the wave while waiting for human input
+- The orchestrator tracks checkpoint state in `.checkpoint-manifest.json`
+
+---
+
+## Continuation Protocol
+
+After a checkpoint is resolved (human provides their answer, completes their action, or confirms verification), the orchestrator spawns a **fresh continuation executor** to resume from where the checkpoint paused.
+
+The continuation executor receives:
+1. The full plan content
+2. A table of completed tasks with their commit hashes
+3. The checkpoint resolution (what the human decided or confirmed)
+4. The task number to resume from
+5. The same project context as the original executor
+
+**Key rules for continuation**:
+- The continuation executor does NOT re-execute completed tasks
+- It reads the partial SUMMARY.md if one exists
+- It verifies prior commits exist via `git log`
+- It resumes from the next uncompleted task after the checkpoint
+
+---
+
+## Authentication Gate (Implicit Checkpoint)
+
+The executor also supports an implicit checkpoint for authentication failures. If the executor encounters an authentication error (missing API key, expired token, invalid credentials) during any task, it immediately stops and returns a `CHECKPOINT: AUTH-GATE` response.
+
+This is not declared in the plan — it triggers automatically when an auth error is detected. The response includes:
+- Which task was blocked
+- What credential is needed
+- Where to configure it
+- The actual error message
+
+---
+
+## Architectural Deviation (Implicit Checkpoint)
+
+Similarly, if the executor discovers that the plan's approach cannot work (API changed, framework limitation, dependency conflict), it stops with a `CHECKPOINT: ARCHITECTURAL-DEVIATION` response. This follows Deviation Rule 4 from the executor's deviation handling protocol.
+
+---
+
+## Best Practices for Planners
+
+When creating plans that include checkpoints:
+
+1. **Minimize checkpoint tasks** — each one pauses execution and requires human attention
+2. **Place checkpoints at natural boundaries** — after a feature is complete, not in the middle of wiring
+3. **Group manual actions** — combine related human actions into a single checkpoint rather than multiple stops
+4. **Provide clear instructions** — the `<action>` and `<verify>` elements should give the human everything they need
+5. **Consider autonomous alternatives** — if a task CAN be verified automatically, prefer `type="auto"` with a robust `<verify>` command
+6. **Set `autonomous: false`** in the plan frontmatter when any task is a checkpoint

package/plugins/copilot-pbr/references/common-bug-patterns.md

@@ -0,0 +1,14 @@
+<!-- canonical: ../../pbr/references/common-bug-patterns.md -->
+# Common Bug Patterns
+
+Quick reference for the debugger agent. Check these patterns early — they cover ~80% of bugs.
+
+| Category | Patterns to Check |
+|----------|------------------|
+| **Off-by-one** | Loop bounds (`<` vs `<=`), 0-based vs 1-based indexing, string slice boundaries |
+| **Null/undefined** | Missing optional chaining (`?.`), default params, DB query returning null, OOB array access |
+| **Async/timing** | Missing `await`, race conditions, stale closures, handlers registered before element exists |
+| **State management** | Direct mutation vs new object, update not triggering re-render, duplicated sources of truth, stale state in closures |
+| **Import/module** | Circular imports, default vs named export mismatch, wrong file (similar names), resolution path |
+| **Environment** | Missing/wrong env var, dev vs prod differences, case sensitivity (Windows vs Linux paths) |
+| **Data shape** | API response format changed, schema/model mismatch, type mismatch between layers, missing field |

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

@@ -0,0 +1,442 @@
+<!-- canonical: ../../pbr/references/config-reference.md -->
+# 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`.
+
+---
+
+## Top-Level Fields
+
+| Property | Type | Allowed Values | Default | Description |
+|----------|------|---------------|---------|-------------|
+| `version` | integer | `1`, `2` | `2` | Schema version; v1 configs are auto-migrated to v2 on load |
+| `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 |
+
+### context_strategy
+
+| Value | Behavior |
+|-------|----------|
+| `aggressive` | Proactive compaction warnings, strict context isolation, minimal file reads in main context |
+| `balanced` | Moderate context management with some inline reads |
+| `conservative` | Relaxed context management, more inline content allowed |
+
+### mode
+
+| Value | Behavior |
+|-------|----------|
+| `interactive` | Pauses at gates, asks for confirmation, waits for user decisions |
+| `autonomous` | Skips all gates, chains phases automatically, no user prompts |
+
+### depth
+
+| Value | Behavior |
+|-------|----------|
+| `quick` | Skips research, plan-checking, and verification; 2 mapper areas; 3 debug rounds max |
+| `standard` | Research + plan-checking + verification enabled; 4 mapper areas; 5 debug rounds max |
+| `comprehensive` | Everything from standard plus inline per-task verification; 10 debug rounds max |
+
+See [depth_profiles](#depth_profiles) for the exact feature overrides each depth level applies.
+
+---
+
+## features
+
+Boolean toggles that enable or disable specific workflow capabilities. All default to the value shown unless overridden by the active depth profile.
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `structured_planning` | `true` | Use phased planning with ROADMAP and plan files |
+| `goal_verification` | `true` | Run verifier agent after builds to check goals are met |
+| `integration_verification` | `true` | Run cross-phase integration checks |
+| `context_isolation` | `true` | Isolate heavy work into subagents to protect main context |
+| `atomic_commits` | `true` | One commit per task rather than batched commits |
+| `session_persistence` | `true` | Persist state across sessions via STATE.md |
+| `research_phase` | `true` | Run researcher agent before planning |
+| `plan_checking` | `true` | Run plan-checker agent to validate plans before execution |
+| `tdd_mode` | `false` | Red-Green-Refactor for all tasks (3 commits per task instead of 1) |
+| `status_line` | `true` | Show status line in session UI |
+| `auto_continue` | `false` | Write `.auto-next` signal on phase completion for chaining |
+| `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 |
+
+**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`).
+- `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.
+
+---
+
+## models
+
+Per-agent model selection. Valid values for all fields: `sonnet`, `opus`, `haiku`, `inherit`.
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `researcher` | `sonnet` | Model for the researcher agent |
+| `planner` | `inherit` | Model for the planner agent |
+| `executor` | `inherit` | Model for the executor agent |
+| `verifier` | `sonnet` | Model for the verifier agent |
+| `integration_checker` | `sonnet` | Model for the integration-checker agent |
+| `debugger` | `inherit` | Model for the debugger agent |
+| `mapper` | `sonnet` | Model for the codebase-mapper agent |
+| `synthesizer` | `haiku` | Model for the synthesizer agent (combines team outputs) |
+
+### models.complexity_map
+
+Maps task complexity to model tiers. Used when agents auto-select models based on task difficulty.
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `simple` | `haiku` | Model for simple tasks |
+| `medium` | `sonnet` | Model for medium-complexity tasks |
+| `complex` | `inherit` | Model for high-complexity tasks |
+
+---
+
+## parallelization
+
+Controls whether and how plans execute concurrently within a wave.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `enabled` | boolean | `true` | Enable parallel plan execution |
+| `plan_level` | boolean | `true` | Parallelize at plan level (multiple plans in same wave) |
+| `task_level` | boolean | `false` | Parallelize at task level within a plan (not currently used) |
+| `max_concurrent_agents` | integer | `3` | Maximum simultaneous executor subagents (1-10) |
+| `min_plans_for_parallel` | integer | `2` | Minimum plans in a wave to trigger parallel execution (min: 1) |
+| `use_teams` | boolean | `false` | Use Agent Teams for coordination (discussion only, never execution) |
+
+**Behavior notes:**
+- When `enabled: true` and a wave has >= `min_plans_for_parallel` plans, the build orchestrator spawns executors in parallel using `run_in_background: true`.
+- Git lock conflicts can occur with parallel execution. Executors retry with 2s waits (max 3 attempts). If conflicts persist, reduce `max_concurrent_agents`.
+
+---
+
+## teams
+
+Configures Agent Teams for multi-perspective planning and review discussions.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `planning_roles` | string[] | `["architect", "security-reviewer", "test-designer"]` | Roles used during team planning discussions |
+| `review_roles` | string[] | `["functional-reviewer", "security-auditor", "performance-analyst"]` | Roles used during team review discussions |
+| `synthesis_model` | string | `sonnet` | Model used for the synthesizer agent that combines team outputs |
+| `coordination` | string | `file-based` | How team members coordinate: `file-based` (parallel writes) or `sequential` |
+
+**Interaction with parallelization:** Teams require `parallelization.max_concurrent_agents` > 1 to be useful. Setting `max_concurrent_agents: 1` with teams configured is a validation error.
+
+---
+
+## planning
+
+Controls planning behavior and documentation.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `commit_docs` | boolean | `true` | Commit planning docs (SUMMARY, VERIFICATION) after builds |
+| `max_tasks_per_plan` | integer | `3` | Maximum tasks per plan; keeps plans focused and atomic (1-10) |
+| `search_gitignored` | boolean | `false` | Include gitignored files in codebase scanning |
+
+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`.
+
+---
+
+## git
+
+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 |
+| `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` |
+
+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.
+
+---
+
+## 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_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_transition` | `true` | Before transitioning to the next phase |
+| `issues_review` | `true` | Before proceeding when issues are detected |
+
+**Key interaction:** Gates are unreachable in `mode: autonomous`. Setting `mode: autonomous` with any gates enabled is a validation error.
+
+---
+
+## safety
+
+Safety controls for destructive or external operations.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `always_confirm_destructive` | boolean | `true` | Always ask before destructive git 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.
+
+---
+
+## hooks
+
+Controls behavior of hook scripts that fire during Claude Code lifecycle events.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `autoFormat` | boolean | `false` | Run auto-formatting after file writes |
+| `typeCheck` | boolean | `false` | Run type checking after file writes |
+| `detectConsoleLogs` | boolean | `false` | Warn when console.log statements are added |
+| `blockDocSprawl` | boolean | `false` | Block creation of excessive documentation files |
+| `compactThreshold` | integer | `50` | Context budget percentage at which to suggest compaction (10-200) |
+
+All hook checks are disabled by default and must be opted into via config.
+
+---
+
+## debug
+
+Controls debug workflow behavior.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `max_hypothesis_rounds` | integer | `5` | Maximum hypothesis-test cycles the debugger agent runs (1-20) |
+
+This value is overridden by the active depth profile if a `depth_profiles` entry sets `debug.max_hypothesis_rounds`.
+
+---
+
+## 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.
+
+**Built-in defaults:**
+
+| Setting | quick | standard | comprehensive |
+|---------|-------|----------|---------------|
+| `features.research_phase` | `false` | `true` | `true` |
+| `features.plan_checking` | `false` | `true` | `true` |
+| `features.goal_verification` | `false` | `true` | `true` |
+| `features.inline_verify` | `false` | `false` | `true` |
+| `scan.mapper_count` | `2` | `4` | `4` |
+| `scan.mapper_areas` | `["tech", "arch"]` | `["tech", "arch", "quality", "concerns"]` | `["tech", "arch", "quality", "concerns"]` |
+| `debug.max_hypothesis_rounds` | `3` | `5` | `10` |
+
+User overrides in `depth_profiles` merge on top of these defaults. For example, to keep standard depth but increase debug rounds:
+
+```json
+{
+  "depth": "standard",
+  "depth_profiles": {
+    "standard": {
+      "debug.max_hypothesis_rounds": 8
+    }
+  }
+}
+```
+
+---
+
+## spinner_tips
+
+Custom spinner tips shown during agent execution. Requires Claude Code 2.1.45+.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `tips` | string[] | `[]` | Array of custom tip strings to display in the spinner |
+| `exclude_defaults` | boolean | `false` | When true, only show custom tips (suppress default Claude Code tips) |
+
+---
+
+## status_line
+
+Controls the status line displayed in the session UI.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `sections` | string[] | `["phase", "plan", "status", "context"]` | Which sections to display; allowed values: `phase`, `plan`, `status`, `context` |
+| `brand_text` | string | -- | Custom brand text for the status line |
+| `max_status_length` | integer | -- | Maximum character length for the status section (10-200) |
+
+### status_line.context_bar
+
+Controls the visual context budget bar.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `width` | integer | -- | Width of the context bar in characters (1-50) |
+| `thresholds.green` | integer | -- | Percentage threshold for green indicator (0-100) |
+| `thresholds.yellow` | integer | -- | Percentage threshold for yellow indicator (0-100) |
+| `chars.filled` | string | -- | Character used for the filled portion of the bar |
+| `chars.empty` | string | -- | Character used for the empty portion of the bar |
+
+---
+
+## Common Configurations
+
+### Quick Solo Development
+
+Minimal overhead for small fixes or solo prototyping. Skips research, plan-checking, and verification. No gates, no branching.
+
+```json
+{
+  "version": 2,
+  "depth": "quick",
+  "mode": "interactive",
+  "features": {
+    "structured_planning": true,
+    "goal_verification": false,
+    "integration_verification": false,
+    "context_isolation": true,
+    "atomic_commits": true,
+    "research_phase": false,
+    "plan_checking": false
+  },
+  "gates": {
+    "confirm_project": false,
+    "confirm_roadmap": false,
+    "confirm_plan": false,
+    "confirm_execute": false,
+    "confirm_transition": false,
+    "issues_review": false
+  },
+  "git": {
+    "branching": "none",
+    "mode": "enabled"
+  }
+}
+```
+
+### Comprehensive Team Workflow
+
+Full verification, team discussions, parallel execution, and all gates enabled. Good for multi-phase projects with code review requirements.
+
+```json
+{
+  "version": 2,
+  "depth": "comprehensive",
+  "mode": "interactive",
+  "features": {
+    "structured_planning": true,
+    "goal_verification": true,
+    "integration_verification": true,
+    "context_isolation": true,
+    "atomic_commits": true,
+    "research_phase": true,
+    "plan_checking": true,
+    "tdd_mode": true,
+    "inline_verify": true,
+    "team_discussions": true
+  },
+  "parallelization": {
+    "enabled": true,
+    "plan_level": true,
+    "max_concurrent_agents": 3,
+    "use_teams": true
+  },
+  "teams": {
+    "planning_roles": ["architect", "security-reviewer", "test-designer"],
+    "review_roles": ["functional-reviewer", "security-auditor", "performance-analyst"],
+    "coordination": "file-based"
+  },
+  "gates": {
+    "confirm_project": true,
+    "confirm_roadmap": true,
+    "confirm_plan": true,
+    "confirm_execute": true,
+    "confirm_transition": true,
+    "issues_review": true
+  },
+  "git": {
+    "branching": "phase",
+    "mode": "enabled"
+  }
+}
+```
+
+### Autonomous CI/CD Mode
+
+Hands-free execution with no gates and automatic phase chaining. Suitable for CI pipelines or unattended runs.
+
+```json
+{
+  "version": 2,
+  "depth": "standard",
+  "mode": "autonomous",
+  "features": {
+    "structured_planning": true,
+    "goal_verification": true,
+    "integration_verification": true,
+    "context_isolation": true,
+    "atomic_commits": true,
+    "research_phase": true,
+    "plan_checking": true,
+    "auto_continue": true,
+    "auto_advance": true
+  },
+  "gates": {
+    "confirm_project": false,
+    "confirm_roadmap": false,
+    "confirm_plan": false,
+    "confirm_execute": false,
+    "confirm_transition": false,
+    "issues_review": false
+  },
+  "git": {
+    "branching": "phase",
+    "mode": "enabled"
+  },
+  "planning": {
+    "commit_docs": true
+  }
+}
+```
+
+---
+
+## 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 is not valid JSON"** -- Syntax error in the JSON file. Check for trailing commas, missing quotes, or unescaped characters.
+
+**"mode=autonomous with active gates: gates are unreachable in autonomous mode"** -- You set `mode: autonomous` but left one or more gates enabled. Autonomous mode never pauses for confirmation, so enabled gates are contradictory. Set all gates to `false` or switch back to `mode: interactive`.
+
+**"parallelization.max_concurrent_agents=1 with teams.coordination set: teams require concurrent agents to be useful"** -- Teams need multiple agents running in parallel. Either increase `max_concurrent_agents` above 1 or remove the `teams` configuration.
+
+### Validation Warnings
+
+**"features.auto_continue=true with mode=interactive"** -- `auto_continue` only fires in autonomous mode. It has no effect in interactive mode. Either switch to `mode: autonomous` or disable `auto_continue`.
+
+**"parallelization.enabled=false with plan_level=true"** -- `plan_level` is ignored when parallelization is disabled. Either enable parallelization or remove the `plan_level` setting.
+
+### Contradictory Configurations to Avoid
+
+| Configuration | Problem |
+|---------------|---------|
+| `mode: autonomous` + any gate `true` | Gates never fire in autonomous mode (validation error) |
+| `max_concurrent_agents: 1` + `teams.coordination` set | Teams cannot coordinate with only one agent (validation error) |
+| `auto_continue: true` + `mode: interactive` | auto_continue is ignored in interactive mode (warning) |
+| `parallelization.enabled: false` + `plan_level: true` | plan_level has no effect when parallelization is off (warning) |
+| `auto_advance: true` + `mode: interactive` | auto_advance requires autonomous mode to chain phases |
+| `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 |