@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plugins/pbr/references/pbr-tools-cli.md

@@ -1,4 +1,4 @@
-# pbr-tools.js CLI Reference
+# pbr-tools.cjs CLI Reference
 
 Command-line interface for structured JSON operations on `.planning/` state.
 Skills and agents call this via Bash to avoid token-expensive text parsing.
@@ -32,7 +32,7 @@ node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load
     "status": "building",
     "progress_percent": 45,
     "last_activity": "2025-01-15",
-    "last_command": "/pbr:build",
+    "last_command": "/pbr:execute-phase",
     "blockers": []
   },
   "roadmap": {               // Parsed ROADMAP.md
@@ -230,6 +230,21 @@ node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js roadmap update-plans 1 2 5
 
 **Output:** `{ "success": true, "old_plans": "1/5", "new_plans": "2/5" }`
 
+### Roadmap Format Notes
+
+**Phase sections** in ROADMAP.md include these fields (parsed by the dashboard and plan skill):
+- `**Goal:**` — phase objective
+- `**Requirements:**` — mapped REQ-IDs (e.g., `REQ-F-001, REQ-F-002`)
+- `**Success Criteria:**` — verifiable conditions for phase completion
+- `**Provides:**` — exported capabilities (bulleted list)
+- `**Depends on:**` — prerequisite phases
+- `**Implements:**` — REQ-IDs implemented
+
+**Milestone collapse format** (created by `/pbr:milestone complete`):
+- **New format:** `<details><summary>## Milestone: {name} ({version}) — SHIPPED {date}</summary>` wrapping phase table and archive link
+- **Legacy format:** `## Milestone: {name} ({version}) -- COMPLETED` (still recognized for backward compat)
+- **Milestone index:** `## Milestones` section near top of ROADMAP.md with version/name/status/date table
+
 ---
 
 ## History Commands
@@ -283,3 +298,118 @@ node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js event error hook-failure '{"scri
 **Output:** `{ "logged": true, "category": "build", "event": "plan-complete" }`
 
 If the JSON-details argument is not valid JSON, it's stored as `{ "raw": "<the string>" }`.
+
+---
+
+## Compound Init Commands
+
+Compound commands that compose multiple data sources into a single JSON response.
+Replace multi-step context loading in skills with a single CLI call.
+
+### `init execute-phase <phase>`
+
+Everything an executor needs to start building a phase.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init execute-phase 3
+```
+
+**Output:**
+```json
+{
+  "executor_model": "sonnet",
+  "verifier_model": "sonnet",
+  "config": { "depth": "standard", "mode": "interactive", "parallelization": {}, "planning": {}, "gates": {}, "features": {} },
+  "phase": { "num": "3", "dir": "03-auth", "name": "auth", "goal": "...", "has_context": false, "status": "planned", "plan_count": 2, "completed": 0 },
+  "plans": [{ "file": "PLAN-01.md", "plan_id": "01", "wave": 1, "autonomous": true, "has_summary": false, "must_haves_count": 4, "depends_on": [] }],
+  "waves": { "wave_1": ["01", "02"] },
+  "branch_name": "main",
+  "git_clean": true
+}
+```
+
+### `init plan-phase <phase>`
+
+Everything a planner needs to start phase planning.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init plan-phase 3
+```
+
+**Output:** `researcher_model`, `planner_model`, `checker_model`, `config` (depth profile, features, planning settings), `phase` (num, dir, goal, depends_on), `existing_artifacts`, `workflow` flags.
+
+### `init quick <description>`
+
+Everything the quick skill needs: next task number, slug, directory path.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init quick "add search feature"
+```
+
+**Output:** `next_task_number`, `slug`, `dir`, `dir_name`, `timestamp`, `config` subset.
+
+### `init verify-work <phase>`
+
+Everything a verifier needs to start verification.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init verify-work 3
+```
+
+**Output:** `verifier_model`, `phase` info, `has_verification`, `prior_attempts`, `prior_status`, `summaries`.
+
+### `init resume`
+
+Detect interrupted state and suggest continuation.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init resume
+```
+
+**Output:** `state`, `auto_next`, `continue_here`, `active_skill`, `current_phase`, `progress`.
+
+### `init progress`
+
+All phases with status and completion data.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init progress
+```
+
+**Output:** `current_phase`, `phase_count`, `status`, `phases` array, `total_plans`, `completed_plans`, `percentage`.
+
+---
+
+## State Mutation Extensions
+
+### `state patch <JSON>`
+
+Multi-field atomic STATE.md update. Updates all fields in a single pass.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state patch '{"status":"executing","last_activity":"now"}'
+```
+
+**Valid fields:** `current_phase`, `status`, `plans_complete`, `last_activity`, `progress_percent`, `phase_slug`, `last_command`, `blockers`
+
+**Output:** `{ "success": true, "updated": ["status", "last_activity"] }`
+
+### `state advance-plan`
+
+Increment current plan number in STATE.md and update progress percentage.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state advance-plan
+```
+
+**Output:** `{ "success": true, "previous_plan": 1, "current_plan": 2, "total_plans": 5, "progress_percent": 40 }`
+
+### `state record-metric [--duration Nm] [--plans-completed N]`
+
+Record session/execution metrics. Appends to HISTORY.md and updates last_activity.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state record-metric --duration 15m --plans-completed 3
+```
+
+**Output:** `{ "success": true, "duration_minutes": 15, "plans_completed": 3 }`

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
@@ -172,6 +200,43 @@ Two plans CONFLICT if their `files_modified` lists overlap. Conflicting plans:
 
 ---
 
+## @file: Output Pattern (Large Payloads)
+
+When a `pbr-tools` CLI command produces output exceeding 50,000 characters, the tool writes
+the JSON payload to a temporary file instead of emitting it inline. It then prints a single
+line of the form:
+
+```
+@file:/tmp/pbr-1234567890.json
+```
+
+This prevents stdout overflow in environments with limited buffer sizes (hooks, Task() runners).
+
+### Verify Step Pattern
+
+If a plan's `<verify>` step calls `pbr-tools` and inspects the output, guard against the
+`@file:` case:
+
+```bash
+OUT=$(node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load)
+if echo "$OUT" | grep -q '^@file:'; then
+  OUT=$(cat "${OUT#@file:}")
+fi
+echo "$OUT" | grep '"status"'
+```
+
+### Agent Prompt Handling
+
+When an agent receives `@file:` output from a spawned tool call, it must read the referenced
+file to obtain the actual JSON payload. The `@file:` prefix is a signal — not a path fragment
+to be appended to another command.
+
+Plan actions that spawn `pbr-tools` subcommands should instruct the agent:
+
+> If the output starts with `@file:`, read the file at that path to get the full JSON response.
+
+---
+
 ## Context Fidelity Checklist
 
 Before writing plan files, verify context compliance:

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

@@ -43,9 +43,12 @@ provides:
   - "requireAuth() middleware"
 consumes:
   - "Database connection (from plan 01-01)"
-requirement_ids:
-  - "P02-G1"
-  - "P02-G2"
+implements:
+  - "REQ-F-001"
+  - "REQ-F-002"
+closes_issues:
+  - 42
+  - 57
 ---
 ```
 
@@ -68,8 +71,34 @@ requirement_ids:
 | `must_haves.key_links` | YES | array | Connections between components. Append `: grep command` for verification. |
 | `provides` | NO | array | What this plan exports for other plans to consume (classes, endpoints, modules) |
 | `consumes` | NO | array | What this plan needs from prior plans. Format: `"Thing (from plan XX-YY)"` |
-| `requirement_ids` | NO | array | Requirement IDs from REQUIREMENTS.md or ROADMAP.md goal IDs that this plan addresses. Enables bidirectional traceability between plans and requirements/goals. |
+| `implements` | YES (WARNING if absent) | array | REQ-IDs from REQUIREMENTS.md or ROADMAP this plan addresses. Primary traceability field. |
+| `requirement_ids` | NO | array | DEPRECATED — use `implements:` instead. Kept for backward compat. |
 | `dependency_fingerprints` | NO | object | Hashes of dependency phase SUMMARY.md files at plan-creation time. Used to detect stale plans. |
+| `data_contracts` | NO | array | Cross-boundary parameter mappings for calls where arguments originate from external boundaries. Format: `"param: source (context) [fallback]"` |
+| `closes_issues` | NO | number[] | GitHub issue numbers to close when this plan's final commit lands. Default: `[]` |
+
+> **Note:** The `implements` field is mandatory for new plans. The plan-checker validates that listed IDs trace to ROADMAP phase items. Existing plans without `implements` receive a WARNING (not a blocker) during the transition period.
+
+### Data Contracts
+
+When a task's `<action>` includes calls across module boundaries where arguments come from external sources (hook stdin, env vars, API params, config files), document the parameter-to-source mapping in `data_contracts` frontmatter and in the `<action>` step itself.
+
+Example frontmatter:
+
+```yaml
+data_contracts:
+  - "sessionId: data.session_id (hook stdin) [undefined in CLI context]"
+  - "config: configLoad(planningDir) (disk) [resolveConfig(undefined)]"
+```
+
+Example in `<action>`:
+
+```
+3. Call classifyArtifact(llmConfig, planningDir, content, fileType, data.session_id)
+   Data contract: sessionId ← data.session_id from hook stdin (undefined in CLI context)
+```
+
+**When to apply:** Any call where caller and callee are in different modules AND at least one argument originates from an external boundary. Internal helper calls within the same module do not need contracts.
 
 ---
 
@@ -109,6 +138,9 @@ The Summary section is generated by the planner agent at plan creation time. It
 ```xml
 <task id="02-01-T1" type="auto" complexity="medium">
   <name>Create Discord OAuth client module</name>
+  <read_first>
+    src/auth/types.ts
+  </read_first>
   <files>
     src/auth/discord.ts
     src/auth/types.ts
@@ -135,20 +167,35 @@ The Summary section is generated by the planner agent at plan creation time. It
        DISCORD_CLIENT_SECRET=
        DISCORD_REDIRECT_URI=http://localhost:3000/auth/callback
   </action>
+  <acceptance_criteria>
+    grep -q "authenticateWithDiscord" src/auth/discord.ts
+    grep -q "DiscordUser" src/auth/types.ts
+    test -f src/auth/discord.ts
+  </acceptance_criteria>
   <verify>
-    npx tsc --noEmit
-    ls src/auth/discord.ts
-    ls src/auth/types.ts
+    <automated>
+      npx tsc --noEmit
+      ls src/auth/discord.ts
+      ls src/auth/types.ts
+    </automated>
   </verify>
   <done>Discord OAuth client module exists and compiles without errors</done>
 </task>
 ```
 
+> **Verify block forms**: The `<automated>` wrapper (Option A) is preferred — it enables machine-parsing
+> for `auto_checkpoints` mode. Plain-text verify commands without the wrapper (Option B) remain valid
+> for backward compatibility. Both forms are supported by the executor.
+
 ### TDD Task
 
 ```xml
 <task id="02-01-T2" type="auto" tdd="true" complexity="medium">
   <name>Implement auth middleware with TDD</name>
+  <read_first>
+    src/auth/discord.ts
+    src/auth/types.ts
+  </read_first>
   <files>
     src/middleware/auth.ts
     tests/middleware/auth.test.ts
@@ -171,6 +218,11 @@ The Summary section is generated by the planner agent at plan creation time. It
     REFACTOR:
     3. Extract token verification into `verifyToken()` helper
   </action>
+  <acceptance_criteria>
+    grep -q "requireAuth" src/middleware/auth.ts
+    grep -q "rejects request without token" tests/middleware/auth.test.ts
+    test -f src/middleware/auth.ts
+  </acceptance_criteria>
   <verify>
     npm test -- --grep "auth middleware"
   </verify>
@@ -178,6 +230,66 @@ The Summary section is generated by the planner agent at plan creation time. It
 </task>
 ```
 
+### Feature Task (TDD Variant)
+
+Feature tasks add a `<feature>` element for structured TDD planning. The element contains two required children:
+
+- **`<behavior>`** — the observable outcome from the user's perspective. Maps directly to a `must_haves.truths` entry.
+- **`<implementation>`** — the technical approach at a high level (which files, patterns, or algorithms to use).
+
+Prose structure (illustrative — not a live task block to avoid validator false-positives):
+
+```
+task id="02-01-T3" type="auto" tdd="true" complexity="medium"
+  name: Implement rate limiter for OAuth endpoint
+  files: src/middleware/rate-limit.ts / tests/middleware/rate-limit.test.ts
+  feature:
+    behavior: OAuth endpoint rejects more than 5 requests per minute per IP with HTTP 429
+    implementation: Token-bucket algorithm; Redis-backed counter with TTL; express-rate-limit wrapper
+  action:
+    RED: Write failing tests for 429 response at >5 req/min
+    GREEN: Implement token-bucket middleware using Redis
+    REFACTOR: Extract counter logic to RateLimitStore class
+  verify:
+    automated: npm test -- --grep "rate limiter"
+  done: Rate limiter rejects excessive OAuth requests with 429
+```
+
+The `<feature>` element is optional — standard TDD tasks without it are still valid. Use `<feature>` when the planner wants to record the behavior/implementation split explicitly for traceability.
+
+## Checkpoint System
+
+Plans use 3 checkpoint types for human-in-the-loop interaction. Most plans have zero checkpoints — only use them when the plan explicitly requires human input.
+
+| Type | Frequency | Purpose | Executor Action |
+|------|-----------|---------|-----------------|
+| `checkpoint:human-verify` | ~90% of checkpoints | User verifies output | Show what was built, ask "looks good?" |
+| `checkpoint:decision` | ~9% of checkpoints | User chooses between options | Present options with context, wait for selection |
+| `checkpoint:human-action` | ~1% of checkpoints | User does something outside Claude | Explain what's needed, wait for confirmation |
+
+### Structured Checkpoint Return Format
+
+When an executor encounters a checkpoint task, it MUST return a completion marker with structured data:
+
+```text
+## CHECKPOINT: {TYPE}
+
+<checkpoint>
+  <type>{human-verify|decision|human-action}</type>
+  <task_id>{plan_id}-T{N}</task_id>
+  <description>{what this checkpoint is about}</description>
+  <what_built>{for human-verify: summary of what was built}</what_built>
+  <verify_steps>{for human-verify: numbered steps to verify}</verify_steps>
+  <options>{for decision: lettered options with descriptions}</options>
+  <required_action>{for human-action: what the user needs to do}</required_action>
+  <resume_signal>{what response means "proceed"}</resume_signal>
+</checkpoint>
+```
+
+Not all fields apply to all types. Use only the relevant fields for the checkpoint type.
+
+---
+
 ### Checkpoint: Human Verify
 
 ```xml
@@ -256,18 +368,57 @@ The Summary section is generated by the planner agent at plan creation time. It
 
 ---
 
-## The 5 Mandatory Elements
+## The 7 Mandatory Elements
 
-Every task MUST have ALL 5. No exceptions.
+Every task MUST have ALL 7. No exceptions.
 
 | Element | Purpose | Rules |
 |---------|---------|-------|
 | `<name>` | What the task does | Imperative verb phrase. Short. |
+| `<read_first>` | Files to read before editing | One path per line. Specific paths, no globs. Prevents blind edits. |
 | `<files>` | Files touched | One per line. Actual file paths. |
 | `<action>` | How to do it | Numbered steps. Specific. Code snippets for complex work. |
-| `<verify>` | How to check | Executable shell commands. Or checkpoint format. |
+| `<acceptance_criteria>` | Grep-verifiable conditions | One condition per line. Shell commands returning 0/non-0. Concrete, not subjective. |
+| `<verify>` | How to check | Executable shell commands (plain-text or wrapped in `<automated>`). Or checkpoint format. |
 | `<done>` | How to know it worked | Observable user/system behavior. Maps to a must-have. |
 
+> **Optional `<feature>` element**: Feature tasks (TDD variant) may add a `<feature>` element with
+> `<behavior>` and `<implementation>` children for structured TDD planning. The 7 standard elements
+> above are still required.
+
+---
+
+## read_first Field
+
+**Purpose:** Prevents the "blind edit" anti-pattern where the executor modifies files it hasn't read.
+
+**Content:** Actual file paths (one per line). The executor must Read each listed file before editing any files in the task. No globs or wildcards allowed — paths must be specific.
+
+**Plan-checker validates:**
+
+- Field exists and is non-empty for every task
+- Paths are specific (no `*` wildcards)
+
+**Planner generates:** Based on `files_modified` (existing files that will be edited) and known dependencies (types, interfaces, configs imported by the modified files).
+
+---
+
+## acceptance_criteria Field
+
+**Purpose:** Built-in verification lighter than spawning a separate verifier agent. Catches structural problems immediately after task completion.
+
+**Content:** Shell commands that return 0 on success, non-zero on failure. Common patterns:
+
+- `grep -q "functionName" path/to/file.ts` — verify a function exists
+- `test -f path/to/file.ts` — verify a file exists
+- `node -e "require('./path/to/module')"` — verify a module loads
+
+**Rules:**
+
+- Must be concrete and grep-verifiable. No subjective conditions like "code is clean".
+- Each criterion is a single shell command returning 0 (pass) or non-zero (fail).
+- The executor runs these after completing each task. If any fail, deviation rules apply.
+
 ---
 
 ## Task ID Format

package/plugins/pbr/references/pretooluse-jsonl-behavior.md

@@ -0,0 +1,58 @@
+---
+description: Documents why PreToolUse hook decisions appear in PBR hook logs but not Claude Code session JSONL
+---
+
+# PreToolUse JSONL Behavior
+
+## Behavior
+
+PreToolUse hooks log decisions to PBR's hook logs but **NOT** to Claude Code's session JSONL.
+
+- **PBR hook logs**: `.planning/logs/hooks-YYYY-MM-DD.jsonl` — contains all PreToolUse decisions (allow, block, warn)
+- **Session JSONL**: `~/.claude/projects/{path}/*.jsonl` — does NOT contain PreToolUse hook decisions
+
+## Why
+
+Claude Code session JSONL records conversations, tool calls, and tool results. PreToolUse hooks are middleware that runs *before* the tool executes:
+
+- If the hook **allows** the tool: the tool runs and its result appears in session JSONL normally
+- If the hook **blocks** the tool: the tool never executes, so there is no tool result to record
+
+In either case, the hook's own decision is not surfaced as a separate entry in session JSONL. This is by-design behavior in Claude Code's hook architecture.
+
+## Where to Find PreToolUse Logs
+
+Filter PBR hook logs for PreToolUse events:
+
+```bash
+grep '"event":"PreToolUse"' .planning/logs/hooks-$(date +%Y-%m-%d).jsonl
+```
+
+Each entry includes:
+
+- `hook`: the hook script name (e.g., `validate-task`)
+- `event`: `PreToolUse`
+- `decision`: `allow`, `block`, or `warn`
+- `source`: the originating hook script
+- `details`: tool name, input parameters, block reason (if blocked)
+
+## Hook Scripts That Log PreToolUse Events
+
+| Script | Purpose |
+|--------|---------|
+| `validate-commit.js` | Validates commit message format |
+| `validate-task.js` | Gates executor/planner/verifier spawns |
+| `check-dangerous-commands.js` | Blocks destructive shell commands |
+| `check-doc-sprawl.js` | Blocks excessive documentation creation |
+| `check-skill-workflow.js` | Enforces skill workflow ordering |
+| `check-summary-gate.js` | Validates SUMMARY.md before state updates |
+| `pre-bash-dispatch.js` | Dispatch for Bash PreToolUse checks |
+| `pre-write-dispatch.js` | Dispatch for Write/Edit PreToolUse checks |
+| `block-skill-self-read.js` | Prevents skills from reading their own SKILL.md |
+| `enforce-pbr-workflow.js` | Advisory PBR workflow compliance |
+| `intercept-plan-mode.js` | Intercepts plan mode entry |
+| `validate-skill-args.js` | Validates skill argument format |
+
+## Audit Implications
+
+The `/pbr:audit` agent must check PBR hook logs (`.planning/logs/hooks-*.jsonl`), not session JSONL, for PreToolUse evidence. Session JSONL cannot confirm whether PreToolUse hooks fired or what decisions they made.