@sienklogic/plan-build-run 2.21.1 → 2.21.2

package/plugins/copilot-pbr/references/agent-contracts.md

@@ -1,297 +0,0 @@
-# Agent Contracts
-
-Input/output schemas for agent-to-agent handoffs in Plan-Build-Run.
-
-Each contract defines: the file exchanged, required frontmatter fields, body structure, and special handling notes. Agents MUST produce output matching these schemas — consumers depend on them.
-
----
-
-## Contract: Researcher -> Synthesizer
-
-**File**: `.planning/research/{topic-slug}.md` (project) or `.planning/phases/{NN}-{slug}/RESEARCH.md` (phase)
-**Direction**: Researcher writes, Synthesizer reads 2-4 of these
-
-### Required Frontmatter
-
-```yaml
----
-confidence: high|medium|low
-sources_checked: N        # integer count of sources consulted
-coverage: "complete|partial|minimal"
----
-```
-
-### Required Body Sections
-
-- `## Key Findings` — each finding tagged with source level (`[S1]`..`[S6]`) and confidence
-- `## Gaps` — areas not covered and why
-- `## Sources` — source list with what each provided
-
-### Special Handling
-
-- Every factual claim must have a source attribution tag
-- Version-sensitive info (API signatures, config syntax) must come from S1-S3 sources
-- `[SPECULATIVE]` tag marks unverified reasoning — synthesizer must not upgrade confidence
-
----
-
-## Contract: Synthesizer -> Planner
-
-**File**: `.planning/research/SUMMARY.md` (or specified path)
-**Direction**: Synthesizer writes, Planner reads
-
-### Required Frontmatter
-
-```yaml
----
-confidence: high|medium|low
-sources: N                # integer count of input documents
-conflicts: N              # integer count of contradictions found
----
-```
-
-### Required Body Sections
-
-- `## Resolved Decisions` — table with Topic, Decision, Confidence, Sources columns
-- `## Open Questions` — items marked `[NEEDS DECISION]` for planner to handle
-- `## Deferred Ideas` — items out of scope
-
-### Special Handling
-
-- `[NEEDS DECISION]` flags: planner creates `checkpoint:decision` tasks OR decides within discretion scope
-- Confidence levels never upgraded beyond what input documents support
-- Contradictions always documented, never silently dropped
-
----
-
-## Contract: Planner -> Executor
-
-**File**: `.planning/phases/{NN}-{slug}/PLAN-{NN}.md`
-**Direction**: Planner writes, Executor reads and executes sequentially
-
-### Required Frontmatter
-
-```yaml
----
-phase: "{phase-slug}"
-plan: "{NN-MM}"
-wave: N
-depends_on: []
-files_modified: ["{path}"]
-must_haves:
-  truths: ["{observable condition}"]
-  artifacts: ["{file: description}"]
-  key_links: ["{connection description}"]
-provides: ["{exported item}"]
-consumes: ["{required item}"]
-requirement_ids: []
----
-```
-
-### Required Body: XML Tasks (each task needs all 5 elements)
-
-```xml
-<task id="{plan}-T{n}" type="{type}" tdd="{bool}" complexity="{simple|medium|complex}">
-<name>{imperative verb phrase}</name>
-<files>{file paths, one per line}</files>
-<action>{numbered steps}</action>
-<verify>{executable shell command}</verify>
-<done>{observable outcome}</done>
-</task>
-```
-
-### Special Handling
-
-- Task types: `auto`, `tdd`, `checkpoint:human-verify`, `checkpoint:decision`, `checkpoint:human-action`
-- Complexity drives model selection: simple=haiku, medium=sonnet, complex=inherit
-- Executor stages ONLY files listed in `<files>` per task
-- Plans end with a `## Summary` section (plan ID, task list, key files, must-haves, provides/consumes)
-
----
-
-## Contract: Planner -> Plan-Checker
-
-**File**: Same `PLAN-{NN}.md` files (read-only)
-**Direction**: Planner writes, Plan-Checker reads and returns text assessment
-**Returns**: Inline text report (no file output)
-
-### Expected Input
-
-Plan-Checker reads plan frontmatter + XML tasks and evaluates across 10 dimensions (D1-D10). Optionally receives CONTEXT.md path.
-
-### Output Format
-
-```
-VERIFICATION PASSED | ISSUES FOUND
-Plans: N | Tasks: N | Blockers: N | Warnings: N | Info: N
-
-## Blockers
-- [{plan_id}] D{N} {severity}: {description} -> Fix: {hint}
-```
-
-### Special Handling
-
-- Blockers must be fixed before execution; warnings are advisory
-- Plan-Checker never modifies plans — only reports issues
-- Planner enters Revision Mode to address feedback
-
----
-
-## Contract: Executor -> Verifier
-
-**File**: `.planning/phases/{NN}-{slug}/SUMMARY-{plan_id}.md`
-**Direction**: Executor writes after completing plan tasks, Verifier reads
-
-### Required Frontmatter
-
-```yaml
----
-plan: "{plan_id}"
-status: complete|partial|checkpoint
-commits: ["{sha1}", "{sha2}"]
-provides: ["{exported item}"]
-must_haves:
-  - "{must-have description}: DONE|PARTIAL|SKIPPED"
----
-```
-
-### Required Body Sections
-
-- `## Task Results` — table with Task, Status, Notes columns
-- `## Deviations` — list of deviations from plan, or "None"
-
-### Special Handling
-
-- Verifier does NOT trust SUMMARY.md claims — verifies against actual codebase
-- Verifier checks must-haves from PLAN.md frontmatter, not SUMMARY.md self-reports
-- One SUMMARY per plan execution; status reflects final state
-
----
-
-## Contract: Verifier -> Planner (Gap Closure)
-
-**File**: `.planning/phases/{NN}-{slug}/VERIFICATION.md`
-**Direction**: Verifier writes, Planner reads to create gap-closure plans
-
-### Required Frontmatter
-
-```yaml
----
-status: passed|gaps_found|human_needed
-attempt: N
-must_haves_total: N
-must_haves_passed: M
-gaps: ["gap description"]
-overrides: []
----
-```
-
-### Required Body Sections
-
-- `## Must-Have Verification` — table with #, Must-Have, Status, Evidence columns
-- `## Gaps` — per-gap detail with Evidence and Suggested fix
-
-### Special Handling
-
-- `gaps_found` triggers Planner Gap Closure Mode — planner creates targeted fix plans
-- `overrides` list: must-haves marked as override by user, counted as passed
-- Re-verification increments `attempt` counter; checks regressions on previously-passed items
-- Verifier has Write access ONLY for VERIFICATION.md — cannot fix source code
-
----
-
-## Contract: Integration-Checker -> Planner
-
-**File**: `.planning/phases/{NN}-{slug}/INTEGRATION-REPORT.md`
-**Direction**: Integration-Checker writes, Planner reads for cross-phase fixes
-
-### Required Frontmatter
-
-```yaml
----
-status: passed|issues_found
-checks_total: N
-checks_passed: M
-critical_issues: K
----
-```
-
-### Required Body Sections
-
-- `## Integration Checks` — table with Check, Status, Evidence columns
-- `## E2E Flows` — table with Flow, Status, Broken Link columns
-- `## Critical Issues` — detailed issue descriptions
-
-### Special Handling
-
-- Checks ACROSS phases (unlike Verifier which checks single phase)
-- 5 check categories: Export/Import Wiring, API Route Coverage, Auth Protection, E2E Flows, Cross-Phase Dependencies
-- Integration-Checker has Write access ONLY for INTEGRATION-REPORT.md — cannot fix source code
-
----
-
-## Contract: Debugger (Self-Contained)
-
-**File**: `.planning/debug/{slug}.md`
-**Direction**: Debugger creates, updates, and resolves within a single session
-
-### Required Frontmatter
-
-```yaml
----
-slug: "{slug}"
-status: "gathering|investigating|fixing|verifying|resolved"
-created: "{ISO-8601}"
-updated: "{ISO-8601}"
-mode: "find_and_fix|find_root_cause_only"
----
-```
-
-### Required Body Sections
-
-- `## Current Focus` — Hypothesis, Test, Expecting, Disconfirm, Next action
-- `## Symptoms` — IMMUTABLE after gathering phase
-- `## Hypotheses` — Active (unchecked) and Eliminated (checked, append-only)
-- `## Evidence Log` — append-only timestamped entries
-- `## Resolution` — root cause, mechanism, fix, commit hash (when resolved)
-
-### Special Handling
-
-- Status transitions: `gathering -> investigating -> fixing -> verifying -> resolved`
-- Symptoms and Evidence Log are append-only / immutable — prevents mutation bias
-- Fix commits use format: `fix({scope}): {description}` with root cause in body
-- May emit checkpoints (`HUMAN-VERIFY`, `HUMAN-ACTION`, `DECISION`) for user input
-
----
-
-## Contract: Codebase-Mapper (Self-Contained)
-
-**Files**: `.planning/codebase/{STACK,ARCHITECTURE,CONVENTIONS,CONCERNS}.md` (varies by focus)
-**Direction**: Codebase-Mapper writes, consumed by Researcher (as S0 local prior) and Planner
-
-### Focus Areas and Outputs
-
-| Focus | Output Files |
-|-------|-------------|
-| `tech` | STACK.md, INTEGRATIONS.md |
-| `arch` | ARCHITECTURE.md, STRUCTURE.md |
-| `quality` | CONVENTIONS.md, TESTING.md |
-| `concerns` | CONCERNS.md |
-
-### Fallback Frontmatter (per file)
-
-No YAML frontmatter required — these are reference documents with markdown tables.
-
-### Required Body Structure (minimum per file)
-
-- **STACK.md**: `## Tech Stack` table (Category, Technology, Version, Config File) + `## Package Manager`
-- **ARCHITECTURE.md**: `## Architecture Overview` (pattern name) + `## Key Components` table + `## Data Flow`
-- **CONVENTIONS.md**: `## Code Conventions` table (Convention, Pattern, Example File) + `## Naming Patterns`
-- **CONCERNS.md**: `## Concerns` table (Severity, Area, Description, File) + `## Security Considerations`
-
-### Special Handling
-
-- Every claim must reference actual file paths — no vague references
-- Codebase-Mapper does NOT commit — the orchestrator handles commits
-- Researcher treats these as S0 (highest confidence) local prior research
-- One focus area per invocation

package/plugins/copilot-pbr/references/agent-interactions.md

@@ -1,135 +0,0 @@
-<!-- canonical: ../../pbr/references/agent-interactions.md -->
-# Agent Interaction Map
-
-This document shows how Plan-Build-Run agents communicate through files on disk. Agents never message each other directly -- they read and write shared files in `.planning/`.
-
-## Interaction Graph
-
-```
-                    User / Orchestrator
-                     |           ^
-                     v           |
-              +--------------+   |
-              |  researcher  |---+---> planner
-              +--------------+         |    ^
-                     |                 v    |
-              +--------------+   +--------------+
-              | synthesizer  |   | plan-checker |
-              +--------------+   +--------------+
-                                       |
-                                       v
-                                 +-----------+
-                                 |  executor  |
-                                 +-----------+
-                                       |
-                                       v
-                                 +-----------+
-                                 |  verifier  |----> planner (gap closure)
-                                 +-----------+
-                                       |
-                                       v
-                              +--------------------+
-                              | integration-checker|
-                              +--------------------+
-```
-
-## Per-Agent Interaction Details
-
-### researcher
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | User/Orchestrator | Research topics, CONTEXT.md constraints, phase goals |
-| Produces for | planner | Research documents with technology details and recommendations |
-| Produces for | synthesizer | Research documents to be combined |
-| Produces for | User | Direct reading for decision-making |
-
-### synthesizer
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | researcher | Research documents to synthesize |
-| Receives from | Orchestrator | Paths to research documents, synthesis request |
-| Produces for | planner | SUMMARY.md as consolidated research input for planning |
-| Produces for | User | High-level project/phase research overview |
-
-### planner
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | researcher | Research documents with technology details and recommendations |
-| Receives from | plan-checker | Issue reports requiring plan revision |
-| Receives from | verifier | VERIFICATION.md reports requiring gap closure plans |
-| Receives from | User/Orchestrator | Phase goals, CONTEXT.md, planning requests |
-| Produces for | plan-checker | Plan files for quality verification |
-| Produces for | executor | Plan files for execution |
-| Produces for | verifier | Must-have definitions for verification (embedded in plan frontmatter) |
-
-### plan-checker
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator/User | Plan files to check, phase context |
-| Receives from | planner | Newly created or revised plan files |
-| Produces for | planner | Issue reports for revision |
-| Produces for | Orchestrator/User | Pass/fail decision on plan quality |
-
-### executor
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator | Plan files to execute, continuation instructions |
-| Receives from | planner | The plans themselves (indirectly, via files) |
-| Produces for | verifier | SUMMARY.md for verification, committed code for inspection |
-| Produces for | Orchestrator | Checkpoint responses, completion status |
-| Produces for | planner | Deferred ideas (in SUMMARY.md) for future planning |
-
-### verifier
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator | Phase to verify, timing trigger |
-| Receives from | executor | Completed work (via codebase and SUMMARY.md) |
-| Receives from | Previous VERIFICATION.md | Gaps to re-check (in re-verification mode) |
-| Produces for | planner | Gap list for gap-closure planning (via VERIFICATION.md) |
-| Produces for | Orchestrator | Phase status (passed/gaps_found/human_needed) |
-| Produces for | User | Human verification items with specific test instructions |
-
-### integration-checker
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator | Phases to check, trigger event (milestone/review) |
-| Receives from | verifier | Phase-level verification reports (for context on per-phase status) |
-| Produces for | planner | Integration gap list for cross-phase fix plans |
-| Produces for | Orchestrator | Integration status for milestone decisions |
-| Produces for | User | Integration health overview and security issues |
-
-### debugger
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator/User | Bug reports, symptoms, reproduction steps |
-| Receives from | executor | Errors encountered during execution (via checkpoint responses) |
-| Receives from | verifier | Issues discovered during verification |
-| Produces for | Orchestrator/User | Root cause analysis, fix commits, checkpoint requests |
-| Produces for | planner | Findings requiring architectural changes |
-| Produces for | executor | Simple fix instructions for executor to apply |
-
-### codebase-mapper
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator/User | Focus area to analyze, project path |
-| Receives from | researcher | May be invoked alongside researcher for new projects |
-| Produces for | planner | STACK.md, ARCHITECTURE.md, STRUCTURE.md for informed planning |
-| Produces for | executor | CONVENTIONS.md for code style, TESTING.md for test patterns |
-| Produces for | verifier | All documents as reference for what "correct" looks like |
-| Produces for | User | Direct reading for project understanding |
-
-### general
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator/User | Ad-hoc task instructions |
-| Produces for | Orchestrator/User | Task output (files, formatting, config changes) |

package/plugins/copilot-pbr/references/agent-teams.md

@@ -1,55 +0,0 @@
-<!-- canonical: ../../pbr/references/agent-teams.md -->
-# Agent Teams Reference
-
-Agent Teams enable parallel specialist perspectives for critical phases. Teams are off by default.
-
-## Activation
-
-- **Global**: Set `parallelization.use_teams: true` in `.planning/config.json`
-- **Per-invocation**: Use `--teams` flag on `/pbr:plan`, `/pbr:review`, or `/pbr:build --team`
-- Per-invocation flag takes precedence over global config
-
-## Planning Teams
-
-When `/pbr:plan <N> --teams` is invoked, three specialist agents run in parallel:
-
-| Role | Agent | Focus | Output File |
-|------|-------|-------|-------------|
-| Architect | planner | Structure, dependencies, wave ordering, file boundaries | `.planning/phases/{NN}/team/architect-PLAN.md` |
-| Security Reviewer | planner | Auth, input validation, secrets handling, permission checks | `.planning/phases/{NN}/team/security-PLAN.md` |
-| Test Designer | planner | Test strategy, coverage targets, edge cases, TDD candidates | `.planning/phases/{NN}/team/test-PLAN.md` |
-
-All three use the `planner` agent with different prompts. The orchestrator includes the role and focus in the Task() spawn prompt.
-
-After all three complete, the synthesizer agent reads all team outputs and produces the final unified PLAN.md files.
-
-## Review Teams
-
-When `/pbr:review <N>` runs with teams enabled, three review agents run in parallel:
-
-| Role | Agent | Focus | Output File |
-|------|-------|-------|-------------|
-| Functional Reviewer | verifier | Must-haves met, code correctness, completeness | `.planning/phases/{NN}/team/functional-VERIFY.md` |
-| Security Auditor | verifier | Vulnerabilities, auth bypass, injection, secrets exposure | `.planning/phases/{NN}/team/security-VERIFY.md` |
-| Performance Analyst | verifier | N+1 queries, memory leaks, bundle size, unnecessary re-renders | `.planning/phases/{NN}/team/performance-VERIFY.md` |
-
-All three use the `verifier` agent with different prompts. The synthesizer combines them into a unified VERIFICATION.md.
-
-## File-Based Coordination
-
-Team members write to separate files in a `team/` subdirectory. This avoids file conflicts:
-```
-.planning/phases/{NN}-{slug}/
-  team/
-    architect-PLAN.md
-    security-PLAN.md
-    test-PLAN.md
-```
-
-The synthesizer reads all files in `team/` and produces the final artifact. The `team/` directory is kept for audit purposes but is not read by subsequent skills.
-
-## When to Use Teams
-
-- **Recommended**: Security-critical phases, architectural phases, public API design
-- **Not recommended**: Simple refactors, documentation, configuration changes
-- **Cost consideration**: Teams triple the agent spawns. Use only when the additional perspectives justify the cost.

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

@@ -1,158 +0,0 @@
-<!-- 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

@@ -1,14 +0,0 @@
-<!-- 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 |