@sienklogic/plan-build-run 2.37.0 → 2.38.1

package/plugins/cursor-pbr/skills/health/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: health
 description: "Check planning directory integrity. Find and fix corrupted state."
+argument-hint: "[--repair]"
 ---
 
 ## Step 0 — Immediate Output
@@ -17,10 +18,16 @@ Then proceed to Step 1.
 
 # /pbr:health — Planning Directory Diagnostics
 
-You are running the **health** skill. Your job is to validate the integrity of the `.planning/` directory, report problems, and suggest targeted fixes. You never auto-repair anything.
+You are running the **health** skill. Your job is to validate the integrity of the `.planning/` directory, report problems, and suggest targeted fixes.
 
 This skill runs **inline**. It is read-only by default, but offers an optional **auto-fix** flow for common corruption patterns (see the Auto-Fix section below).
 
+## Argument Parsing
+
+Check if the user passed `--repair`:
+- `--repair`: Skip the AskUserQuestion prompt in the Auto-Fix section and automatically apply ALL fixes (equivalent to selecting "Fix all"). Still create backups before any destructive operations.
+- No flag: Use the interactive AskUserQuestion flow as described below (default behavior).
+
 ---
 
 ## How Checks Work
@@ -184,7 +191,11 @@ cp .planning/STATE.md .planning/backups/STATE-$(date +%Y%m%dT%H%M%S).md
 
 This ensures the user can recover the original STATE.md if the fix produces incorrect results.
 
-1. Count the auto-fixable issues and present:
+1. Count the auto-fixable issues.
+
+   **If `--repair` flag was passed**: Skip the question and go directly to "Fix all" (step 2). Display: "Auto-repair mode: applying {N} fixes..."
+
+   **Otherwise**: Present the choice:
 
    Use AskUserQuestion:
      question: "Found {N} auto-fixable issues. How should we handle them?"
@@ -194,7 +205,7 @@ This ensures the user can recover the original STATE.md if the fix produces inco
        - label: "Review each"   description: "Show each fix and confirm individually"
        - label: "Skip"          description: "Do nothing — just report"
 
-2. If "Fix all": Apply all fixes in order, then display a summary:
+2. If "Fix all" (or `--repair`): Apply all fixes in order, then display a summary:
    ```
    Auto-fix results:
    - Fixed: {description of fix 1}
@@ -213,8 +224,6 @@ This ensures the user can recover the original STATE.md if the fix produces inco
 
 4. If "Skip": Do nothing, continue to the rest of the output.
 
-**Note:** When auto-fix is active, the health skill is no longer strictly read-only. The `allowed-tools` frontmatter must include `Write` and `AskUserQuestion` for auto-fix to work. Update the frontmatter accordingly.
-
 ---
 
 ## Bonus: Recent Decisions

package/plugins/cursor-pbr/skills/setup/SKILL.md

@@ -71,7 +71,15 @@ mkdir -p .planning/phases .planning/todos/pending .planning/todos/done .planning
 
 **CRITICAL: Write .planning/config.json NOW. Do NOT skip this step.**
 
-Create `.planning/config.json` with defaults:
+Before writing config.json, check for user-level defaults:
+
+```bash
+node "${PLUGIN_ROOT}/scripts/pbr-tools.js" config load-defaults
+```
+
+If user defaults exist (the output has keys like `mode`, `features`, etc.), inform the user: "Found your saved preferences from ~/.claude/pbr-defaults.json. These will be merged into your project config (project-specific settings take precedence)." Then deep-merge user defaults into the config below before writing.
+
+Create `.planning/config.json` with defaults (merged with user defaults if they exist):
 ```json
 {
   "version": 2,

package/plugins/cursor-pbr/skills/shared/context-budget.md

@@ -17,6 +17,16 @@ Every skill that spawns agents or reads significant content must follow these ru
 4. **Delegate** heavy work to agents — the orchestrator routes, it doesn't execute
 5. **Before spawning agents**: If you've already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider running `/pbr:pause` to checkpoint progress." Suggest pause proactively rather than waiting for compaction.
 
+## Context Degradation Awareness
+
+Quality degrades gradually before panic thresholds fire. Watch for these early warning signs:
+
+- **Silent partial completion** — agent claims task is done but implementation is incomplete. Self-check catches file existence but not semantic completeness. Always verify agent output meets the plan's must_haves, not just that files exist.
+- **Increasing vagueness** — agent starts using phrases like "appropriate handling" or "standard patterns" instead of specific code. This indicates context pressure even before budget warnings fire.
+- **Skipped steps** — agent omits protocol steps it would normally follow. If an agent's success criteria has 8 items but it only reports 5, suspect context pressure.
+
+When delegating to agents, the orchestrator cannot verify semantic correctness of agent output — only structural completeness. This is a fundamental limitation. Mitigate with must_haves.truths and spot-check verification.
+
 ## Customization
 
 Skills should add skill-specific rules below the reference line. Common skill-specific additions:

package/plugins/cursor-pbr/skills/shared/universal-anti-patterns.md

@@ -36,3 +36,9 @@ These rules prevent context rot -- quality degradation as the context window fil
 14. **Do not** suggest multiple next actions without clear priority -- one primary suggestion, alternatives listed secondary.
 15. **Do not** use `git add .` or `git add -A` -- stage specific files only.
 16. **Do not** include sensitive information (API keys, passwords, tokens) in planning documents or commits.
+
+## Error Recovery Rules (apply to every skill)
+
+17. **Git lock detection**: Before any git operation, if it fails with "Unable to create lock file", check for stale `.git/index.lock` and advise the user to remove it (do not remove automatically — another process may hold it legitimately).
+18. **Config fallback awareness**: `configLoad()` returns `null` silently on invalid JSON. If your skill depends on config values, check for null and warn the user: "config.json is invalid or missing — running with defaults. Run `/pbr:health` to diagnose."
+19. **Partial state recovery**: If STATE.md references a phase directory that doesn't exist, do not proceed silently. Warn the user and suggest `/pbr:health` to diagnose the mismatch.

package/plugins/cursor-pbr/skills/test/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: test
+description: "Generate tests for completed phase code. Detects test framework and targets key files."
+argument-hint: "<phase-number>"
+---
+
+**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by the plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.**
+
+# /pbr:test — Post-Phase Test Generation
+
+You are the orchestrator for `/pbr:test`. This skill generates tests for code that was built WITHOUT TDD mode. It targets key files from completed phases and creates meaningful test coverage.
+
+## Context Budget
+
+Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
+
+Additionally for this skill:
+- **Delegate** all test writing to executor agents — never write test code in the main context
+- Read only SUMMARY.md frontmatter for `key_files` lists — do not read full summaries
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► GENERATING TESTS FOR PHASE {N}             ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Where `{N}` is the phase number from `$ARGUMENTS`. Then proceed to Step 1.
+
+## Prerequisites
+
+- `.planning/config.json` exists
+- Phase has been built: SUMMARY.md files exist in `.planning/phases/{NN}-{slug}/`
+- Phase should NOT already have TDD coverage (check if `features.tdd_mode` is false in config — if TDD mode is enabled, warn user that tests should already exist and ask to proceed anyway)
+
+---
+
+## Argument Parsing
+
+Parse `$ARGUMENTS` according to `skills/shared/phase-argument-parsing.md`.
+
+| Argument | Meaning |
+|----------|---------|
+| `3` | Generate tests for phase 3 |
+| (no number) | Use current phase from STATE.md |
+
+---
+
+## Step 1 — Gather Context
+
+**CRITICAL: Run init command to load project state efficiently.**
+
+```bash
+node "${PLUGIN_ROOT}/scripts/pbr-tools.js" init execute-phase {phase_number}
+```
+
+This returns STATE.md snapshot, phase plans, ROADMAP excerpt, and config — all in one call.
+
+## Step 2 — Detect Test Framework
+
+Scan the project root for test framework indicators:
+
+1. Check `package.json` for `jest`, `vitest`, `mocha`, `ava` in devDependencies
+2. Check for `pytest.ini`, `pyproject.toml` (with `[tool.pytest]`), `setup.cfg` (with `[tool:pytest]`)
+3. Check for `jest.config.*`, `vitest.config.*`, `.mocharc.*`
+4. Check for existing test directories: `tests/`, `test/`, `__tests__/`, `spec/`
+5. Check for existing test file patterns: `*.test.*`, `*.spec.*`, `test_*.py`
+
+If no test framework is detected, ask the user:
+
+Use AskUserQuestion:
+  question: "No test framework detected. Which should I use?"
+  header: "Framework"
+  options:
+    - label: "Jest"      description: "JavaScript/TypeScript testing (most common)"
+    - label: "Vitest"    description: "Vite-native testing (faster, ESM-friendly)"
+    - label: "pytest"    description: "Python testing framework"
+  multiSelect: false
+
+## Step 3 — Collect Target Files
+
+Read SUMMARY.md frontmatter from each plan in the phase to extract `key_files`:
+
+```bash
+node "${PLUGIN_ROOT}/scripts/pbr-tools.js" frontmatter .planning/phases/{NN}-{slug}/SUMMARY.md
+```
+
+Collect all `key_files` across all plans in the phase. Filter to only source files (exclude config, docs, assets). Group by:
+- **High priority**: Files with business logic, API endpoints, data models
+- **Medium priority**: Utility functions, helpers, middleware
+- **Low priority**: Config, types-only files, constants
+
+Present the file list to the user:
+
+Use AskUserQuestion:
+  question: "Found {N} source files from phase {P}. Generate tests for which?"
+  header: "Scope"
+  options:
+    - label: "High priority only"  description: "{X} files — business logic, APIs, models"
+    - label: "High + Medium"       description: "{Y} files — adds utilities and helpers"
+    - label: "All files"           description: "{Z} files — comprehensive coverage"
+  multiSelect: false
+
+## Step 4 — Generate Test Plans
+
+For each target file, create a lightweight test plan (NOT a full PBR PLAN.md — just a task list):
+
+```
+File: src/auth/login.js
+Tests to generate:
+  - Happy path: valid credentials return token
+  - Error: invalid password returns 401
+  - Error: missing email returns 400
+  - Edge: expired session handling
+Framework: jest
+Output: tests/auth/login.test.js
+```
+
+## Step 5 — Spawn Executor Agents
+
+**CRITICAL: Delegate ALL test writing to agents. Do NOT write test code in the main context.**
+
+For each target file (or batch of related files), spawn an executor agent:
+
+```
+Spawn agent_type: "pbr:executor"
+
+Task: Generate tests for the following file(s):
+
+<files_to_test>
+{file_path}: {brief description from SUMMARY}
+</files_to_test>
+
+<test_framework>
+{detected framework name and version}
+Existing test directory: {path}
+Test file naming: {pattern, e.g., *.test.js}
+</test_framework>
+
+<test_plan>
+{test plan from Step 4}
+</test_plan>
+
+Instructions:
+1. Read each source file to understand the implementation
+2. Write test files following the project's existing test patterns
+3. Each test file should cover: happy path, error cases, edge cases
+4. Use the project's existing mocking patterns if any exist
+5. Run the tests to verify they pass: {test command}
+6. Commit with format: test({phase}-tests): add tests for {file}
+```
+
+Spawn up to `parallelization.max_concurrent_agents` agents in parallel for independent files.
+
+## Step 6 — Verify and Report
+
+After all agents complete, check results:
+
+1. Glob for new test files created in this session
+2. Run the test suite to verify all new tests pass:
+   ```bash
+   {test_command}
+   ```
+3. Count: files tested, tests written, tests passing
+
+Display completion:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► TESTS GENERATED ✓                          ║
+╚══════════════════════════════════════════════════════════════╝
+
+Phase {N}: {X} test files created, {Y} tests passing
+
+Files tested:
+  - src/auth/login.js → tests/auth/login.test.js (8 tests)
+  - src/api/users.js → tests/api/users.test.js (12 tests)
+
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Run coverage check** to see how much is covered
+
+`npm test -- --coverage`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+
+**Also available:**
+- `/pbr:review {N}` — verify the full phase
+- `/pbr:continue` — execute next logical step
+
+
+```
+
+---
+
+## Anti-Patterns
+
+1. **DO NOT** write test code in the main orchestrator context — always delegate to executor agents
+2. **DO NOT** generate tests for files not listed in SUMMARY.md key_files — stay scoped to the phase
+3. **DO NOT** skip running the tests — always verify they pass before reporting success
+4. **DO NOT** generate trivial tests (testing getters/setters, testing constants) — focus on behavior
+5. **DO NOT** read full source files in the orchestrator — let the executor agents read them

package/plugins/pbr/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.37.0",
+  "version": "2.38.1",
   "description": "Plan-Build-Run — Structured development workflow for Claude Code. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/pbr/agents/audit.md

@@ -228,3 +228,4 @@ CRITICAL: Your final output MUST end with exactly one completion marker.
 Orchestrators pattern-match on these markers to route results. Omitting causes silent failures.
 
 - `## AUDIT COMPLETE` - audit report written to .planning/audits/
+- `## AUDIT FAILED` - could not complete audit (no session logs found, unreadable JSONL)

package/plugins/pbr/agents/codebase-mapper.md

@@ -131,6 +131,7 @@ CRITICAL: Your final output MUST end with exactly one completion marker.
 Orchestrators pattern-match on these markers to route results. Omitting causes silent failures.
 
 - `## MAPPING COMPLETE` - analysis document written to output path
+- `## MAPPING FAILED` - could not complete analysis (empty project, inaccessible files)
 
 ---
 

package/plugins/pbr/agents/debugger.md

@@ -34,6 +34,9 @@ You are **debugger**, the systematic debugging agent. Investigate bugs using the
 - [ ] Evidence log maintained (append-only)
 - [ ] Scientific method followed (hypothesis, test, observe)
 - [ ] Fix committed with root cause in body (if fix mode)
+- [ ] Fix verification: original issue no longer reproduces
+- [ ] Fix verification: regression tests pass (existing tests still green)
+- [ ] Fix verification: no environment-specific assumptions introduced
 - [ ] Debug file updated with current status
 - [ ] Completion marker returned
 </success_criteria>

package/plugins/pbr/agents/dev-sync.md

@@ -118,3 +118,26 @@ Copied verbatim (no transformations needed).
 6. DO NOT leave `argument-hint` in Copilot skills
 7. DO NOT consume more than 50% context before producing output
 8. DO NOT spawn sub-agents — this agent performs only file read/write operations
+
+---
+
+<success_criteria>
+- [ ] Source file(s) read from plugins/pbr/
+- [ ] File type determined (skill, agent, reference, shared, template)
+- [ ] Transformations applied per rules table
+- [ ] Cursor derivative written with correct format (no allowed-tools, ${PLUGIN_ROOT})
+- [ ] Copilot derivative written with correct format (.agent.md extension, no model/memory)
+- [ ] Derivative-specific content preserved (not overwritten)
+- [ ] Sync report returned with files modified and transformations applied
+- [ ] Completion marker returned
+</success_criteria>
+
+---
+
+## Completion Protocol
+
+CRITICAL: Your final output MUST end with exactly one completion marker.
+Orchestrators pattern-match on these markers to route results. Omitting causes silent failures.
+
+- `## SYNC COMPLETE` - all derivatives updated
+- `## SYNC FAILED` - could not complete sync, reason provided

package/plugins/pbr/agents/executor.md

@@ -374,6 +374,7 @@ Record timestamps at start and end using `node -e "console.log(new Date().toISOS
 - [ ] All tasks executed (or checkpoint state returned)
 - [ ] Each task committed individually with proper format
 - [ ] All deviations documented in SUMMARY.md
+- [ ] All requirement_ids from PLAN frontmatter copied to SUMMARY requirements-completed
 - [ ] SUMMARY.md created with substantive content (not placeholder)
 - [ ] Self-check performed: all key_files exist on disk
 - [ ] Self-check performed: all commits present in git log

package/plugins/pbr/agents/integration-checker.md

@@ -153,6 +153,7 @@ See `references/integration-patterns.md` for grep/search patterns by framework.
 
 ### Agent-Specific
 - Never attempt to fix issues — you REPORT them
+- ALWAYS include specific file paths and line numbers in every finding — never say "the config module" without a path
 - Imports are not usage — verify symbols are actually called
 - "File exists" is not "component is integrated"
 - Auth middleware existing somewhere does not mean routes are protected
@@ -164,11 +165,12 @@ See `references/integration-patterns.md` for grep/search patterns by framework.
 ---
 
 <success_criteria>
-- [ ] All 5 check categories evaluated
-- [ ] Cross-phase dependencies verified
-- [ ] E2E flows traced end-to-end
+- [ ] All check categories evaluated (export/import, API routes, auth, E2E flows, cross-phase deps, data-flow)
+- [ ] Cross-phase dependencies verified (provides/consumes chains satisfied)
+- [ ] E2E flows traced end-to-end with specific file paths as evidence
 - [ ] Export/import wiring confirmed
-- [ ] Critical issues documented with evidence
+- [ ] Requirements integration map: every requirement traced to implementation with wiring status
+- [ ] Critical issues documented with evidence (file paths, line numbers)
 - [ ] INTEGRATION-REPORT.md written
 - [ ] Completion marker returned
 </success_criteria>
@@ -181,3 +183,4 @@ CRITICAL: Your final output MUST end with exactly one completion marker.
 Orchestrators pattern-match on these markers to route results. Omitting causes silent failures.
 
 - `## INTEGRATION CHECK COMPLETE` - report written with pass/fail status
+- `## INTEGRATION CHECK FAILED` - could not complete checks (missing artifacts, no phases to check)

package/plugins/pbr/agents/planner.md

@@ -47,6 +47,17 @@ Invoked with plan-checker feedback containing issues. Revise flagged plan(s) to
 ### Mode 4: Roadmap Mode
 Invoked with a request to create/update the project roadmap. Produce `.planning/ROADMAP.md` using the template at `${CLAUDE_PLUGIN_ROOT}/templates/ROADMAP.md.tmpl`.
 
+#### Requirement Coverage Validation
+
+Before writing ROADMAP.md, cross-reference REQUIREMENTS.md (or the goals from the begin output) against the planned phases. Every requirement MUST appear in at least one phase's goal or provides list. If any requirement is unassigned, either add it to an existing phase or create a new phase. Report coverage: `{covered}/{total} requirements mapped to phases`.
+
+#### Dual Format: Checklist + Detail
+
+ROADMAP.md MUST contain TWO representations of the phase structure:
+
+1. **Quick-scan checklist** (at the top, after milestone header) — one line per phase with status
+2. **Detailed phase descriptions** — full goal, discovery, provides, depends-on per phase
+
 #### Fallback Format: ROADMAP.md (if template unreadable)
 
 ```markdown
@@ -55,6 +66,12 @@ Invoked with a request to create/update the project roadmap. Produce `.planning/
 ## Milestone: {project} v1.0
 **Goal:** {one-line milestone goal}
 **Phases:** 1 - {N}
+**Requirement coverage:** {covered}/{total} requirements mapped
+
+### Phase Checklist
+- [ ] Phase 01: {name} — {one-line goal summary}
+- [ ] Phase 02: {name} — {one-line goal summary}
+- [ ] Phase 03: {name} — {one-line goal summary}
 
 ### Phase 01: {name}
 **Goal:** {goal}
@@ -63,7 +80,7 @@ Invoked with a request to create/update the project roadmap. Produce `.planning/
 **Depends on:** {list}
 ```
 
-**Milestone grouping:** All phases in the initial roadmap MUST be wrapped in a `## Milestone: {project name} v1.0` section. This section includes `**Goal:**` and `**Phases:** 1 - {N}`, followed by the `### Phase NN:` details. For comprehensive-depth projects (8+ phases), consider splitting into multiple milestones if there are natural delivery boundaries (e.g., "Core Platform" phases 1-5, "Advanced Features" phases 6-10). Each milestone section follows the format defined in the roadmap template.
+**Milestone grouping:** All phases in the initial roadmap MUST be wrapped in a `## Milestone: {project name} v1.0` section. This section includes `**Goal:**`, `**Phases:** 1 - {N}`, and `**Requirement coverage:**`, followed by the Phase Checklist and `### Phase NN:` details. For comprehensive-depth projects (8+ phases), consider splitting into multiple milestones if there are natural delivery boundaries (e.g., "Core Platform" phases 1-5, "Advanced Features" phases 6-10). Each milestone section follows the format defined in the roadmap template.
 
 ---
 
@@ -239,8 +256,14 @@ When receiving checker feedback:
 - [ ] Tasks grouped into plans by wave
 - [ ] PLAN files exist with XML task structure
 - [ ] Each plan: frontmatter complete (depends_on, files_modified, must_haves)
+- [ ] Each plan: requirement_ids field populated (MUST NOT be empty)
 - [ ] Each task: all 5 elements (name, files, action, verify, done)
 - [ ] Wave structure maximizes parallelism
+- [ ] Every REQ-ID from ROADMAP/REQUIREMENTS appears in at least one plan
+- [ ] Gap closure mode (if VERIFICATION.md exists): gaps clustered, tasks derived from gap.missing
+- [ ] Revision mode (if re-planning): flagged issues addressed, no new issues introduced, waves still valid
+- [ ] Context fidelity: locked decisions from CONTEXT.md all have corresponding tasks
+- [ ] PLAN files written via Write tool (NEVER Bash heredoc)
 - [ ] PLAN files committed to git
 </success_criteria>
 
@@ -254,6 +277,7 @@ Orchestrators pattern-match on these markers to route results. Omitting causes s
 - `## PLANNING COMPLETE` - all plan files written and self-checked
 - `## PLANNING FAILED` - cannot produce valid plans from available context
 - `## PLANNING INCONCLUSIVE` - need more research or user decisions
+- `## CHECKPOINT REACHED` - blocked on human decision, checkpoint details provided
 
 ---
 
@@ -311,6 +335,8 @@ One-line task descriptions in `<name>`. File paths in `<files>`, not explanation
 10. DO NOT assume research is done — check discovery level
 11. DO NOT leave done conditions vague — they must be observable
 12. DO NOT specify literal `undefined` for parameters that have a known source in the calling context — use data contracts to map sources
+13. DO NOT use Bash heredoc for file creation — ALWAYS use the Write tool
+14. DO NOT leave requirement_ids empty in PLAN frontmatter — every plan must trace to requirements
 
 </anti_patterns>
 

package/plugins/pbr/agents/researcher.md

@@ -245,7 +245,10 @@ Additionally for this agent:
 - [ ] Source hierarchy followed (S1-S6 ordering)
 - [ ] All findings tagged with source level and confidence
 - [ ] Version-sensitive info sourced from S1-S3 only
-- [ ] Gaps documented with reasons
+- [ ] Negative claims verified (absence of feature confirmed, not just unmentioned)
+- [ ] Multiple sources cross-referenced for key decisions
+- [ ] Publication dates checked — no stale guidance presented as current
+- [ ] Gaps documented with reasons and "What might I have missed?" reflection
 - [ ] Research output file written with required sections
 - [ ] Completion marker returned
 </success_criteria>

package/plugins/pbr/agents/verifier.md

@@ -104,16 +104,30 @@ Check for stub indicators: TODO/FIXME comments, empty function bodies, trivial r
 #### Level 3: Wired (Connected to the System)
 Verify the artifact is imported AND used by other parts of the system (functions called, components rendered, middleware applied, routes registered). Result: `WIRED`, `IMPORTED-UNUSED`, or `ORPHANED`.
 
+#### Level 4: Functional (Actually Works)
+Run the artifact and verify it produces correct results. This goes beyond structural checks (L1-L3) to behavioral verification. Result: `FUNCTIONAL`, `RUNTIME_ERROR`, or `LOGIC_ERROR`.
+
+**When to apply L4:** Only for must-haves that have automated verification commands (test suites, build scripts, API endpoints). Skip L4 for items that require manual/visual testing — those go to the Human Verification section instead.
+
+**L4 checks:**
+- Tests pass: `npm test`, `pytest`, or the project's test command
+- Build succeeds: `npm run build`, `tsc --noEmit`, or equivalent
+- API responds correctly: endpoint returns expected shape and status codes
+- CLI produces expected output: command-line tools return correct exit codes and output
+
 #### Artifact Outcome Decision Table
 
-| Exists | Substantive | Wired | Status |
-|--------|-------------|-------|--------|
-| No | -- | -- | MISSING |
-| Yes | No | -- | STUB |
-| Yes | Yes | No | UNWIRED |
-| Yes | Yes | Yes | PASSED |
+| Exists | Substantive | Wired | Functional | Status |
+|--------|-------------|-------|------------|--------|
+| No | -- | -- | -- | MISSING |
+| Yes | No | -- | -- | STUB |
+| Yes | Yes | No | -- | UNWIRED |
+| Yes | Yes | Yes | No | BROKEN |
+| Yes | Yes | Yes | Yes | PASSED |
 
 > **Note:** WIRED status (Level 3) requires correct arguments, not just correct function names. A call that passes `undefined` for a parameter available in scope is `ARGS_WRONG`, not `WIRED`.
+>
+> **Note:** FUNCTIONAL status (Level 4) is optional — only applied when automated verification is available. Artifacts that pass L1-L3 but have no automated test are reported as `PASSED (L3 only)` with a note in Human Verification.
 
 ### Step 6: Verify Key Links (Always)
 
@@ -141,13 +155,15 @@ Beyond verifying that calls exist, spot-check that **arguments passed to cross-b
 Cross-reference all must-haves against verification results in a table:
 
 ```markdown
-| # | Must-Have | Type | L1 (Exists) | L2 (Substantive) | L3 (Wired) | Status |
-|---|----------|------|-------------|-------------------|------------|--------|
-| 1 | {description} | truth | - | - | - | VERIFIED/FAILED |
-| 2 | {description} | artifact | YES/NO | YES/STUB/PARTIAL | WIRED/ORPHANED/ARGS_WRONG | PASS/FAIL |
-| 3 | {description} | key_link | - | - | YES/NO/ARGS_WRONG | PASS/FAIL |
+| # | Must-Have | Type | L1 (Exists) | L2 (Substantive) | L3 (Wired) | L4 (Functional) | Status |
+|---|----------|------|-------------|-------------------|------------|-----------------|--------|
+| 1 | {description} | truth | - | - | - | - | VERIFIED/FAILED |
+| 2 | {description} | artifact | YES/NO | YES/STUB/PARTIAL | WIRED/ORPHANED | FUNCTIONAL/BROKEN/- | PASS/FAIL |
+| 3 | {description} | key_link | - | - | YES/NO/ARGS_WRONG | - | PASS/FAIL |
 ```
 
+L4 column shows `-` when no automated verification is available. Only artifacts with test commands or build verification get L4 checks.
+
 ### Step 8: Scan for Anti-Patterns (Full Verification Only)
 
 Scan for: dead code/unused imports, console.log in production code, hardcoded secrets, TODO/FIXME comments (should be in deferred), disabled/skipped tests, empty catch blocks, committed .env files. Report blockers only.
@@ -264,7 +280,7 @@ Mark any file containing 2+ stub patterns as "STUB — not substantive".
 - [ ] Previous VERIFICATION.md checked
 - [ ] Must-haves established from plan frontmatter
 - [ ] All truths verified with status and evidence
-- [ ] All artifacts checked at 3 levels (exists, substantive, wired)
+- [ ] All artifacts checked at 3-4 levels (exists, substantive, wired, functional when testable)
 - [ ] All key links verified including argument values
 - [ ] Anti-patterns scanned and categorized
 - [ ] Overall status determined
@@ -279,6 +295,7 @@ CRITICAL: Your final output MUST end with exactly one completion marker.
 Orchestrators pattern-match on these markers to route results. Omitting causes silent failures.
 
 - `## VERIFICATION COMPLETE` - VERIFICATION.md written (status in frontmatter)
+- `## VERIFICATION FAILED` - could not complete verification (missing phase dir, no must-haves to check)
 
 ---
 

package/plugins/pbr/commands/test.md

@@ -0,0 +1,5 @@
+---
+description: "Generate tests for completed phase code. Detects test framework and targets key files."
+---
+
+This command is provided by the `pbr:test` skill.

package/plugins/pbr/references/plan-authoring.md

@@ -157,6 +157,34 @@ When a plan requires research before execution, set the `discovery` field in pla
 
 ---
 
+## TDD Decision Heuristic
+
+When assigning `tdd="true"` or `tdd="false"` on a task, apply this test:
+
+> **Can you write `expect(fn(input)).toBe(output)` before writing `fn`?**
+> Yes → `tdd="true"`. No → `tdd="false"`.
+
+### When TDD Adds Value
+
+- Pure functions and data transformations
+- Business logic with defined inputs/outputs
+- API response parsing and validation
+- State machines and workflow transitions
+- Utility functions and helpers
+
+### When to Skip TDD
+
+- UI rendering and layout (test after)
+- Configuration and environment setup
+- Glue code wiring modules together
+- Simple CRUD with no business logic
+- File system operations and I/O plumbing
+- One-off scripts and migrations
+
+When the global config `features.tdd_mode: true` is set, all tasks default to TDD. The planner should still set `tdd="false"` on tasks matching the skip list above — the global flag is a project preference, not a mandate for every task.
+
+---
+
 ## Dependency Graph Rules
 
 ### File Conflict Detection