@sienklogic/plan-build-run 2.37.0 → 2.38.1

package/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to Plan-Build-Run will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.38.1](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.38.0...plan-build-run-v2.38.1) (2026-02-27)
+
+
+### Documentation
+
+* **quick-018:** add TDD decision heuristic to plan-authoring reference ([b6744ab](https://github.com/SienkLogic/plan-build-run/commit/b6744abd33befddb0650f584fe8f8f3c6ebdf77f))
+
+## [2.38.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.37.0...plan-build-run-v2.38.0) (2026-02-27)
+
+
+### Features
+
+* **quick-016:** add L4 verification, failure markers, roadmap dual format, requirement coverage ([1260623](https://github.com/SienkLogic/plan-build-run/commit/1260623f483ae0e62a22b7637bfd3400da7883df))
+* **quick-016:** enhance agent success criteria and behavioral anchors from GSD gap analysis ([a3ac95a](https://github.com/SienkLogic/plan-build-run/commit/a3ac95a7cb0cfc6a44905bdbba1b2e354aabb7ea))
+* **quick-017:** add migrate subcommand to pbr-tools.js dispatcher ([8b4737a](https://github.com/SienkLogic/plan-build-run/commit/8b4737aa11eca1eea46a259805bd128ff3bee2e4))
+* **quick-017:** GREEN - implement migrate.js and wire CURRENT_SCHEMA_VERSION into config.js ([84beb51](https://github.com/SienkLogic/plan-build-run/commit/84beb51b77af7e4ee6db59e868df291f114e621e))
+* **scripts:** add CRITICAL tier to context-bridge ([4f46411](https://github.com/SienkLogic/plan-build-run/commit/4f464114b1401de3c6bb22c3fb2baff56ce3502f))
+* **skills:** add /pbr:test skill with command across all plugins ([a38d6e3](https://github.com/SienkLogic/plan-build-run/commit/a38d6e3f8fc3eda17a5810b38bd17fddaccb730a))
+* **skills:** add save-defaults, load-defaults, and --repair flag ([a56d1c9](https://github.com/SienkLogic/plan-build-run/commit/a56d1c9468c7212b802b18d71b7fe951b924d1c0))
+* **tools:** add todo.js library with tests ([2ba058b](https://github.com/SienkLogic/plan-build-run/commit/2ba058bb2f143333a920ef8dd14b09021d7abe11))
+
+
+### Bug Fixes
+
+* **tests:** force-add fixture todo files ignored by .gitignore ([1b89f11](https://github.com/SienkLogic/plan-build-run/commit/1b89f1178b3980b9e167d8d137e300b0f2aa9e7d))
+* **tools:** clean up .bak files in atomicWrite + add agent body sync tests ([af1aba2](https://github.com/SienkLogic/plan-build-run/commit/af1aba29ed80e46ec0e901974f6c851151274579))
+
 ## [2.37.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.36.0...plan-build-run-v2.37.0) (2026-02-27)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.37.0",
+  "version": "2.38.1",
   "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
   "keywords": [
     "claude-code",

package/plugins/copilot-pbr/agents/audit.agent.md

@@ -223,3 +223,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/copilot-pbr/agents/codebase-mapper.agent.md

@@ -126,6 +126,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/copilot-pbr/agents/debugger.agent.md

@@ -28,6 +28,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/copilot-pbr/agents/dev-sync.agent.md

@@ -112,3 +112,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/copilot-pbr/agents/executor.agent.md

@@ -368,6 +368,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/copilot-pbr/agents/integration-checker.agent.md

@@ -148,6 +148,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
@@ -159,11 +160,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>
@@ -176,3 +178,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/copilot-pbr/agents/planner.agent.md

@@ -42,6 +42,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 `${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
@@ -50,6 +61,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}
@@ -58,7 +75,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.
 
 ---
 
@@ -234,8 +251,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>
 
@@ -249,6 +272,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
 
 ---
 
@@ -306,6 +330,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/copilot-pbr/agents/researcher.agent.md

@@ -237,7 +237,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/copilot-pbr/agents/verifier.agent.md

@@ -98,16 +98,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)
 
@@ -135,13 +149,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.
@@ -258,7 +274,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
@@ -273,6 +289,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/copilot-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/copilot-pbr/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.37.0",
+  "version": "2.38.1",
   "description": "Plan-Build-Run — Structured development workflow for GitHub Copilot CLI. Solves context rot through disciplined agent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

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

@@ -158,6 +158,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

package/plugins/copilot-pbr/references/verification-patterns.md

@@ -4,9 +4,9 @@ Reference patterns for deriving verification criteria from goals. Used by the pl
 
 ---
 
-## The Three-Layer Check
+## The Four-Layer Check
 
-Every must-have is verified through three layers, checked in order:
+Every must-have is verified through up to four layers, checked in order:
 
 ### Layer 1: Existence
 
@@ -62,6 +62,28 @@ grep -q "prisma" src/app.ts
 grep -q "DISCORD_CLIENT_ID" src/auth/discord.ts
 ```
 
+### Layer 4: Functional
+
+Does the artifact actually work when executed?
+
+```bash
+# Tests pass
+npm test -- --testPathPattern auth
+pytest tests/test_auth.py -v
+
+# Build succeeds
+npm run build
+npx tsc --noEmit
+
+# API returns correct data
+curl -s http://localhost:3000/api/auth/login -X POST -d '{"code":"test"}' | jq '.token'
+
+# CLI produces expected output
+node src/cli.js --help | grep -q "Usage:"
+```
+
+**When to apply L4:** Only when automated verification commands exist (test suites, build scripts, API endpoints with test data). Skip for items requiring manual/visual testing. L4 is optional — artifacts passing L1-L3 without available automated tests are reported as `PASSED (L3 only)`.
+
 ---
 
 ## Verification by Feature Type
@@ -69,41 +91,46 @@ grep -q "DISCORD_CLIENT_ID" src/auth/discord.ts
 ### API Endpoint
 
 ```
-Existence:  curl returns non-404 status
-Substance:  curl returns expected response shape (correct fields)
-Wiring:     endpoint calls the right service, middleware is applied
+Existence:   curl returns non-404 status
+Substance:   curl returns expected response shape (correct fields)
+Wiring:      endpoint calls the right service, middleware is applied
+Functional:  POST/GET with test data returns correct response, error cases handled
 ```
 
 ### Database Schema
 
 ```
-Existence:  table/collection exists, can query without error
-Substance:  columns/fields match specification, constraints are applied
-Wiring:     application code references the schema, migrations run cleanly
+Existence:   table/collection exists, can query without error
+Substance:   columns/fields match specification, constraints are applied
+Wiring:      application code references the schema, migrations run cleanly
+Functional:  CRUD operations work end-to-end, constraints reject invalid data
 ```
 
 ### Authentication
 
 ```
-Existence:  auth routes exist, auth module exports functions
-Substance:  login flow returns token, invalid creds return error
-Wiring:     protected routes use auth middleware, tokens are validated
+Existence:   auth routes exist, auth module exports functions
+Substance:   login flow returns token, invalid creds return error
+Wiring:      protected routes use auth middleware, tokens are validated
+Functional:  auth tests pass (valid token, expired token, missing token, malformed token)
 ```
 
 ### UI Component
 
 ```
-Existence:  component file exists, exports default component
-Substance:  component renders expected elements (test or visual check)
-Wiring:     component is imported in parent, receives correct props, routes to it
+Existence:   component file exists, exports default component
+Substance:   component renders expected elements (test or visual check)
+Wiring:      component is imported in parent, receives correct props, routes to it
+Functional:  component tests pass, build succeeds with component included
 ```
 
 ### Configuration
 
 ```
-Existence:  config file exists, environment variables documented
-Substance:  config values are used (not dead code), defaults are sensible
-Wiring:     application reads config at startup, config changes take effect
+Existence:   config file exists, environment variables documented
+Substance:   config values are used (not dead code), defaults are sensible
+Wiring:      application reads config at startup, config changes take effect
+Functional:  app starts with config, missing config produces clear error message
 ```
 
 ---

package/plugins/copilot-pbr/skills/config/SKILL.md

@@ -112,10 +112,11 @@ Use AskUserQuestion:
     - label: "Depth"          description: "quick/standard/comprehensive"
     - label: "Model profile"  description: "quality/balanced/budget/adaptive"
     - label: "Features"       description: "Toggle workflow features, gates, status line"
-    - label: "Git settings"   description: "branching strategy, commit mode"
+    - label: "Git settings"      description: "branching strategy, commit mode"
+    - label: "Save as defaults"  description: "Save current config as user-level defaults for new projects"
   multiSelect: false
 
-Note: The original 7 categories are condensed to 4. "Models" (per-agent) is accessible through "Model profile" with a follow-up option. "Gates", "Parallelization", and "Status Line" are grouped under "Features".
+Note: The original 7 categories are condensed to 5. "Models" (per-agent) is accessible through "Model profile" with a follow-up option. "Gates", "Parallelization", and "Status Line" are grouped under "Features". "Save as defaults" exports to ~/.claude/pbr-defaults.json.
 
 **Follow-up based on selection:**
 
@@ -178,6 +179,15 @@ Use AskUserQuestion:
     - label: "Disabled"    description: "No git integration"
   multiSelect: false
 
+If user selects "Save as defaults":
+Save current project config as user-level defaults for future projects:
+
+```bash
+node "${PLUGIN_ROOT}/scripts/pbr-tools.js" config save-defaults
+```
+
+Display: "Saved your preferences to ~/.claude/pbr-defaults.json. New projects created with /pbr:setup will use these as starting values."
+
 If user types something else (freeform): interpret as a direct setting command and handle via Step 2 argument parsing logic.
 
 ### 4. Apply Changes

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

@@ -17,10 +17,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 +190,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 +204,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 +223,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/copilot-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/copilot-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/copilot-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.