@sienklogic/plan-build-run 2.18.1 → 2.19.1

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/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

@@ -1,6 +1,6 @@
 # Reading Verification Reports
 
-A user-friendly guide to understanding verification results. For agent-facing patterns, see `verification-patterns.md`.
+A user-friendly guide to understanding verification results.
 
 ---
 
@@ -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)