@sienklogic/plan-build-run 2.1.0 → 2.1.1

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,32 @@ 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` | NO (WARNING if absent) | array | REQ-IDs from REQUIREMENTS.md 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: `[]` |
+
+### 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.
 
 ---
 
@@ -136,14 +163,20 @@ The Summary section is generated by the planner agent at plan creation time. It
        DISCORD_REDIRECT_URI=http://localhost:3000/auth/callback
   </action>
   <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
@@ -178,6 +211,33 @@ 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: Human Verify
 
 ```xml
@@ -265,9 +325,13 @@ Every task MUST have ALL 5. No exceptions.
 | `<name>` | What the task does | Imperative verb phrase. Short. |
 | `<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. |
+| `<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 5 standard elements
+> above are still required.
+
 ---
 
 ## Task ID Format

package/plugins/pbr/references/questioning.md

@@ -1,6 +1,41 @@
 # Deep Questioning Guide
 
-Techniques for understanding a user's project vision during `/pbr:begin`. The goal is to build a complete mental model of what needs to be built, not just a feature list.
+Techniques for understanding a user's project vision during `/pbr:new-project`. The goal is to build a complete mental model of what needs to be built, not just a feature list.
+
+> Skills are being migrated to these patterns. See Phase 5 for skill-level updates.
+
+---
+
+## Philosophy
+
+**You are a thinking partner, not an interviewer.**
+
+Project initialization is dream extraction, not requirements gathering. The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
+
+Don't interrogate. Collaborate. Don't follow a script. Follow the thread.
+
+By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:
+
+- **Research** needs: what domain to research, what the user already knows, what unknowns exist
+- **Requirements** needs: clear enough vision to scope v1 features
+- **Roadmap** needs: clear enough vision to decompose into phases, what "done" looks like
+- **plan** needs: specific requirements to break into tasks, context for implementation choices
+- **build** needs: success criteria to verify against, the "why" behind requirements
+
+A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
+
+---
+
+## Background Context Checklist
+
+Use this as a **background checklist**, not a conversation structure. Check these mentally as you go. If gaps remain, weave questions naturally into the conversation.
+
+- [ ] What they're building (concrete enough to explain to a stranger)
+- [ ] Why it needs to exist (the problem or desire driving it)
+- [ ] Who it's for (even if just themselves)
+- [ ] What "done" looks like (observable outcomes)
+
+Four things. When you have all four, you can offer to proceed. If they volunteer more, capture it.
 
 ---
 
@@ -91,44 +126,6 @@ This produces better answers than binary choices because users reveal their actu
 
 ---
 
-## Required Context Checklist
-
-By the end of questioning, you should have clear answers for ALL of these:
-
-### The Problem
-- [ ] What problem is being solved?
-- [ ] Who has this problem? (specific users/personas)
-- [ ] How are they solving it today? (current state)
-- [ ] Why is the current solution inadequate?
-
-### The Solution
-- [ ] What is being built? (concrete description)
-- [ ] What does "done" look like? (at least 3 success criteria)
-- [ ] What are the core features? (prioritized)
-- [ ] What is explicitly NOT being built? (scope boundaries)
-
-### Constraints
-- [ ] Technology choices already made (language, framework, hosting)
-- [ ] Budget constraints (money, time, resources)
-- [ ] Team constraints (size, skill level, availability)
-- [ ] Integration constraints (existing systems, APIs, databases)
-- [ ] Timeline expectations (deadlines, milestones)
-
-### Decisions Already Made
-- [ ] Architecture preferences or requirements
-- [ ] Deployment environment (cloud, self-hosted, serverless)
-- [ ] Authentication approach
-- [ ] Data storage approach
-- [ ] Third-party services to use
-
-### Edge Cases and Concerns
-- [ ] What keeps them up at night about this project?
-- [ ] What's the hardest part?
-- [ ] What might go wrong?
-- [ ] What are they unsure about?
-
----
-
 ## Progressive Depth Layers
 
 Structure the conversation as deepening layers. Each layer builds on the previous one. You do not need to complete every layer in every project, but the order matters — do not jump to Layer 3 before Layer 1 is solid.
@@ -138,24 +135,32 @@ Establish the broad outline. What is it, who is it for, what does it do?
 - Core purpose and user personas
 - Primary features and workflows
 - Technology preferences or constraints
+- What is being built (concrete deliverable)
+- What is NOT being built (scope boundaries)
+- Technology choices already made (language, framework, hosting)
 
 ### Layer 2: Feel — "How should users experience this?"
 Move from structure to experience. How does it feel to use?
 - UI expectations, interaction patterns, responsiveness
 - Tone, branding, visual direction
 - Performance expectations from the user's perspective
+- Timeline expectations and budget constraints
 
 ### Layer 3: Edges — "What happens when things go wrong?"
 Probe failure modes, edge cases, and the unexpected.
 - Error handling, empty states, data conflicts
 - Permission boundaries, rate limits, abuse scenarios
 - What the user has NOT thought about yet
+- What keeps them up at night about this project
+- What might go wrong, what's the hardest part
 
 ### Layer 4: System — "How does this fit into the bigger picture?"
 Zoom out to the surrounding ecosystem.
 - Integrations, data flows, deployment environment
 - Operational concerns — monitoring, backups, migrations
 - Future evolution and extensibility
+- Integration constraints (existing systems, APIs, databases)
+- Architecture preferences and deployment targets
 
 ---
 
@@ -199,16 +204,100 @@ See **[skills/shared/domain-probes.md](../shared/domain-probes.md)** for technol
 
 ---
 
+## Using AskUserQuestion
+
+Use AskUserQuestion to help users think by presenting concrete options to react to.
+
+### Concrete Interpretations
+
+Options should be specific and reactable, not abstract categories.
+
+**Bad options:**
+- "Simple", "Medium", "Complex"
+- "Technical", "Business", "Other"
+- Leading options that presume an answer
+
+**Good options:**
+- "Landing page with contact form", "Multi-page site with blog", "Full web app with auth and dashboard"
+- "Sub-second response", "Handles large datasets", "Quick to build"
+- Specific examples that reveal priorities
+
+**Example — vague answer:**
+User says "it should be fast"
+
+- header: "Fast"
+- question: "Fast how?"
+- options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]
+
+**Example — following a thread:**
+User mentions "frustrated with current tools"
+
+- header: "Frustration"
+- question: "What specifically frustrates you?"
+- options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]
+
+### Modifying Options
+
+Users can modify a presented option without selecting "Other":
+- Select by number and modify: "#1 but with X"
+- Reference and adjust: "#2 with pagination disabled"
+
+When a user modifies an option, accept the modification as their decision. Do not re-present options or ask them to pick from the original list.
+
+For AskUserQuestion structural rules (max 4 options, 12-char header, multiSelect), see `references/ui-brand.md`.
+
+---
+
+## Freeform Rule
+
+**When the user wants to explain freely, STOP using AskUserQuestion.**
+
+If a user selects "Other" or "Let me explain" and their response signals they want to describe something in their own words (e.g., "let me describe it", "I'll explain", "something else", or any open-ended reply that isn't choosing/modifying an existing option), you MUST:
+
+1. **Ask your follow-up as plain text** -- NOT via AskUserQuestion
+2. **Wait for them to type at the normal prompt**
+3. **Resume AskUserQuestion** only after processing their freeform response
+
+**Wrong:** User says "let me describe it" -> AskUserQuestion("What feature?", ["Feature A", "Feature B", "Describe in detail"])
+**Right:** User says "let me describe it" -> "Go ahead -- what are you thinking?"
+
+The freeform rule prevents AskUserQuestion from becoming an interrogation tool. When someone wants to talk, let them talk.
+
+---
+
+## Decision Gate
+
+When you have enough clarity to write the target document (PROJECT.md, CONTEXT.md, etc.), offer to proceed:
+
+```
+AskUserQuestion:
+  question: "I think I understand what you're after. Ready to proceed?"
+  header: "Ready?"
+  options:
+    - label: "Yes, proceed"    description: "Move forward with document creation"
+    - label: "Keep exploring"  description: "I want to share more or ask me more"
+```
+
+If "Keep exploring" -- ask what they want to add or identify gaps and probe naturally. Loop until "Yes, proceed" is selected.
+
+This gate is **mandatory** in all skills that transition from questioning to document creation (begin, discuss, explore).
+
+---
+
 ## Anti-Patterns
 
 1. **DO NOT** present a form and ask users to fill it in
-2. **DO NOT** ask all questions at once — have a conversation
-3. **DO NOT** assume you know what they want — ask
-4. **DO NOT** suggest technologies before understanding the problem
-5. **DO NOT** skip edge case exploration
-6. **DO NOT** accept vague answers — push for specifics
-7. **DO NOT** rush through questioning to get to planning
-8. **DO NOT** ignore concerns or hand-wave them away
-9. **DO NOT** lead the user toward a particular solution
-10. **DO NOT** forget to summarize and confirm understanding
-11. **DO NOT** ask what you already know — track what the user has stated and never re-ask it. If they said "I'm using React", do not later ask "Are you using a frontend framework?" If they said "PostgreSQL", do not ask "What database are you using?" Redundant questions waste exchanges and erode trust. Instead, build on what you know: "You mentioned React — are you using Next.js or plain CRA?"
+2. **DO NOT** walk through a checklist -- the background checklist is for your mental tracking, never for the user
+3. **DO NOT** ask all questions at once — have a conversation
+4. **DO NOT** assume you know what they want — ask
+5. **DO NOT** suggest technologies before understanding the problem
+6. **DO NOT** impose premature constraints before understanding what the user actually wants to build
+7. **DO NOT** skip edge case exploration
+8. **DO NOT** accept vague answers — push for specifics
+9. **DO NOT** rush through questioning to get to planning
+10. **DO NOT** ignore concerns or hand-wave them away
+11. **DO NOT** lead the user toward a particular solution
+12. **DO NOT** forget to summarize and confirm understanding
+13. **DO NOT** ask what you already know — track what the user has stated and never re-ask it. If they said "I'm using React", do not later ask "Are you using a frontend framework?" If they said "PostgreSQL", do not ask "What database are you using?" Redundant questions waste exchanges and erode trust. Instead, build on what you know: "You mentioned React — are you using Next.js or plain CRA?"
+14. **DO NOT** use corporate speak or jargon — "What are your success criteria?" and "Who are your stakeholders?" sound like a consultant, not a thinking partner
+15. **DO NOT** ask about the user's technical experience — it's irrelevant and condescending. You build what they describe regardless of their background.

package/plugins/pbr/references/reading-verification.md

@@ -95,20 +95,20 @@ You have several options:
 
 ### Option 1: Re-run the build (most common)
 ```
-/pbr:build <N>
+/pbr:execute-phase <N>
 ```
 The executor will detect what's already complete and only fix what's missing.
 
 ### Option 2: Create a gap-closure plan
 ```
-/pbr:plan <N> --gaps
+/pbr:plan-phase <N> --gaps
 ```
 This creates a focused plan that targets only the specific gaps found during verification.
 
 ### Option 3: Manual fix
 For small gaps (like a missing import), you can fix the code yourself and then re-run verification:
 ```
-/pbr:review <N>
+/pbr:verify-work <N>
 ```
 
 ### Option 4: Override (for false positives)

package/plugins/pbr/references/signal-files.md

@@ -0,0 +1,41 @@
+# Signal Files Reference
+
+Signal files are ephemeral files in `.planning/` that coordinate state between hook scripts
+and skills. They are scoped to either the current session or the current phase/plan.
+
+## Session-Scoped Files
+
+All 5 session signals are consolidated in `.planning/.session.json`. Scripts must read and write
+`.session.json` via `pbr-tools session get|set|clear` — never read the raw `.session.json` file directly.
+The `.session.json` schema is an object with the keys documented below.
+
+| JSON Key | Former File | Written By | Read By | Semantics |
+|----------|-------------|------------|---------|-----------|
+| `activeSkill` | `.active-skill` | Skills (Write tool) | check-skill-workflow, enforce-pbr-workflow, check-subagent-output, log-subagent, block-skill-self-read | Which skill is active. Written at skill start, cleared at skill end (session-cleanup). |
+| `compactCounter` | `.compact-counter` | suggest-compact.js | suggest-compact.js | Write count since last /compact. Resets on SessionStart. |
+| `sessionStart` | `.session-start` | progress-tracker.js | local-llm metrics | ISO timestamp of session start. Used for LLM metrics correlation. |
+| `activeOperation` | `.active-operation` | context-budget-check.js | context-budget-check.js | Current named operation for budget display. |
+| `activePlan` | `.active-plan` | context-budget-check.js | context-budget-check.js | Current plan ID for budget display. |
+
+**Atomic access**: Use `pbr-tools session get|set|clear` for safe reads/writes from hook scripts.
+
+**Lifecycle**: Written during SessionStart (progress-tracker), cleared during SessionEnd (session-cleanup).
+Stale sessions (> 60 min) are auto-cleaned by progress-tracker.js on next SessionStart.
+
+## One-Shot Files
+
+These files are NOT consolidated — they use write-once, delete-on-read semantics.
+
+| File | Written By | Read By | Semantics |
+|------|------------|---------|-----------|
+| `.planning/.auto-next` | auto-continue.js | auto-continue.js (Stop hook) | Next command to run after session stops. Deleted after read. |
+| `.planning/.auto-verify` | event-handler.js | event-handler.js (SubagentStop hook) | Trigger auto-verification after agent completes. Deleted after read. |
+
+## Phase-Scoped Files
+
+These files persist across sessions, scoped to a specific phase or plan.
+
+| File Pattern | Written By | Read By | Semantics |
+|-------------|------------|---------|-----------|
+| `.planning/phases/{id}/.checkpoint-manifest.json` | build skill | validate-task.js, session-cleanup.js | Checkpoint state for a plan in progress. Cleaned up after 24h. |
+| `.planning/phases/{id}/.PROGRESS-{taskId}` | executor agent | validate-task.js | Task progress marker for crash recovery. Orphaned files warn on SessionStart. |