@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/skills/validate-phase/SKILL.md

@@ -0,0 +1,362 @@
+---
+name: validate-phase
+description: "Post-build quality gate. Identifies test gaps and spawns nyquist-auditor to fill them."
+allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
+argument-hint: "<phase-number> [--auto]"
+---
+<!-- markdownlint-disable MD012 MD046 -->
+
+**STOP -- DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes tokens. Begin executing Step 1 immediately.**
+
+# /pbr:validate-phase -- Post-Build Validation Quality Gate
+
+**References:** `@references/ui-brand.md`
+
+You are the orchestrator for `/pbr:validate-phase`. This skill identifies validation gaps in a completed phase -- requirements without tests, tests that fail, or verify commands without automated coverage -- and spawns the nyquist-auditor agent to fill them. Your job is to collect gaps, present them, delegate test generation, and write VALIDATION.md.
+
+## Context Budget
+
+Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
+Reference: `skills/shared/agent-type-resolution.md` for agent type fallback when spawning Task() subagents.
+
+Additionally for this skill:
+
+- **Minimize** reading subagent output -- read only VALIDATION.md frontmatter for summaries after the auditor completes.
+- **Delegate** all test generation to the nyquist-auditor agent. Never write tests yourself.
+
+## Step 0 -- Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
++==============================================================+
+|  PLAN-BUILD-RUN > VALIDATING PHASE {N}                       |
++==============================================================+
+```
+
+Where `{N}` is the phase number from `$ARGUMENTS`. Then proceed to Step 1.
+
+## Multi-Session Sync
+
+Before any phase-modifying operations (writing VALIDATION.md, spawning agents), acquire a claim:
+
+```
+acquireClaim(phaseDir, sessionId)
+```
+
+If the claim fails (another session owns this phase), display: "Another session owns this phase. Use `/pbr:progress` to see active claims."
+
+On completion or error (including all exit paths), release the claim:
+
+```
+releaseClaim(phaseDir, sessionId)
+```
+
+## Prerequisites
+
+- `.planning/config.json` exists
+- Phase has been built: SUMMARY.md files exist in `.planning/phases/{NN}-{slug}/`
+
+---
+
+## Argument Parsing
+
+Parse `$ARGUMENTS` according to `skills/shared/phase-argument-parsing.md`.
+
+| Argument | Meaning |
+|----------|---------|
+| `3` | Validate phase 3 |
+| `3 --auto` | Validate phase 3, skip interactive gap confirmation |
+| (no number) | Use current phase from STATE.md |
+
+---
+
+## Orchestration Flow
+
+Execute these steps in order.
+
+---
+
+### Step 1: Parse and Validate (inline)
+
+1. Parse `$ARGUMENTS` for phase number and `--auto` flag
+   - If `--auto` is present: set `auto_mode = true`. Log: "Auto mode enabled -- skipping gap confirmation prompt"
+2. Read `.planning/config.json`
+   **CRITICAL (hook-enforced): Write .active-skill NOW.** Write the text "validate" to `.planning/.active-skill` using the Write tool.
+3. Resolve phase directory `.planning/phases/{NN}-{slug}/`
+4. Validate:
+   - Phase directory exists at `.planning/phases/{NN}-{slug}/`
+   - SUMMARY.md files exist (phase has been built)
+   - PLAN.md files exist (needed for requirement extraction)
+5. If no phase number given, read current phase from `.planning/STATE.md`
+
+**Validation errors:**
+
+If phase directory not found:
+
+```
++==============================================================+
+|  ERROR                                                       |
++==============================================================+
+
+Phase {N} not found in .planning/phases/. Run /pbr:status to see available phases.
+```
+
+If no SUMMARY.md files:
+
+```
++==============================================================+
+|  ERROR                                                       |
++==============================================================+
+
+Phase {N} hasn't been built yet.
+
+**To fix:** Run `/pbr:build {N}` first.
+```
+
+If no PLAN.md files:
+
+```
++==============================================================+
+|  ERROR                                                       |
++==============================================================+
+
+Phase {N} has no plans.
+
+**To fix:** Run `/pbr:plan-phase {N}` first.
+```
+
+---
+
+### Step 2: Collect Requirements and Tests (inline)
+
+1. Read all `PLAN-*.md` files in the phase directory:
+   - Extract `must_haves` from frontmatter (truths, artifacts, key_links)
+   - Extract `<verify>` commands from each `<task>` element
+2. Read all `SUMMARY-*.md` files in the phase directory:
+   - Extract `key_files` from frontmatter
+3. For each key_file: check if a corresponding test file exists using project test conventions:
+   - `*.test.js`, `*.test.ts` (Jest/Vitest)
+   - `test_*.py` (pytest)
+   - `*_test.go` (Go)
+   - `*.spec.js`, `*.spec.ts` (Mocha/Jasmine)
+4. For each `<verify>` command in plans: run it, record pass/fail
+5. Build gap list with entries:
+
+```
+{
+  task_id: "string",
+  requirement: "from must_have",
+  gap_type: "no_test_file | test_fails | no_automated_command",
+  impl_file: "path/to/file"
+}
+```
+
+---
+
+### Step 3: Present Gaps (inline)
+
+Display gap summary table:
+
+```
+Validation Gap Summary
+| Task ID | Requirement | Gap Type | Impl File |
+|---------|-------------|----------|-----------|
+| T1      | {req}       | {type}   | {file}    |
+```
+
+**If zero gaps:**
+
+1. Write VALIDATION.md with all-green status (see Step 5 format)
+2. Display: "All requirements have passing tests."
+3. Route to `/pbr:review {N}`
+4. Clean up and STOP
+
+**If gaps found and `--auto` flag set:**
+
+Skip confirmation, proceed directly to Step 4.
+
+**If gaps found without `--auto`:**
+
+Use AskUserQuestion:
+
+```
+question: "Found {N} validation gaps. Spawn nyquist-auditor to generate tests?"
+header: "Validation Gaps"
+options:
+  - label: "Yes"   description: "Generate tests for all gaps"
+  - label: "No"    description: "Skip test generation, save gap report only"
+```
+
+- If "Yes": proceed to Step 4
+- If "No": write VALIDATION.md with gaps (status yellow/red), display routing, clean up and STOP
+
+---
+
+### Step 4: Spawn Nyquist Auditor (delegated)
+
+Display: `Spawning nyquist-auditor... (est. 2-5 min)`
+
+Build spawn prompt with:
+
+- `<files_to_read>` block listing: all PLAN.md files, all SUMMARY.md files, implementation files from gaps
+- `<gaps>` XML block with the gap list from Step 2:
+
+```xml
+<gaps>
+  <gap task_id="{id}" gap_type="{type}" impl_file="{file}">
+    {requirement text}
+  </gap>
+  ...
+</gaps>
+```
+
+- Phase number and phase slug
+
+Spawn the agent:
+
+```
+Task({
+  subagent_type: "pbr:nyquist-auditor",
+  prompt: <auditor prompt with gaps and files_to_read>
+})
+```
+
+Parse agent return for completion marker:
+
+- `GAPS FILLED` -- all gaps resolved
+- `PARTIAL` -- some gaps remain
+- `ESCALATE` -- critical issues found
+
+---
+
+### Step 5: Write VALIDATION.md (inline)
+
+**CRITICAL: Write VALIDATION.md NOW. Do not skip this step.**
+
+**Template reference:** Read `${CLAUDE_PLUGIN_ROOT}/templates/VALIDATION.md.tmpl` for the standard validation format (test infrastructure, sampling rate, per-task verification map, Wave 0 requirements).
+
+Write `.planning/phases/{NN}-{slug}/VALIDATION.md` with this structure:
+
+**Frontmatter:**
+
+```yaml
+---
+phase: {NN}
+phase_slug: "{slug}"
+status: "green|yellow|red"
+gaps_total: {N}
+gaps_resolved: {M}
+gaps_escalated: {K}
+---
+```
+
+Status values:
+
+- `green` -- all gaps resolved or no gaps found
+- `yellow` -- some gaps resolved, some remain
+- `red` -- escalations exist or critical gaps unresolved
+
+**Body:**
+
+```markdown
+## Requirement-to-Test Mapping
+
+| Task ID | Requirement | Test File | Command | Status |
+|---------|-------------|-----------|---------|--------|
+| T1      | {req}       | {file}    | {cmd}   | PASS   |
+| T2      | {req}       | -         | -       | GAP    |
+
+## Escalated Gaps
+
+{If any escalated gaps, list them here with details}
+
+{If none: "No escalated gaps."}
+```
+
+---
+
+### Step 6: Route Next (inline)
+
+**If status is green or yellow (all gaps resolved or partially resolved):**
+
+```
++==============================================================+
+|  VALIDATION COMPLETE                                         |
++==============================================================+
+
+Phase {N} validation: {status}
+Gaps found: {total} | Resolved: {resolved} | Remaining: {remaining}
+
+NEXT UP:
+  /pbr:review {N}          -- run verification checks
+  /pbr:validate-phase {N}  -- re-validate (if yellow)
+```
+
+**If status is red (escalations exist):**
+
+```
++==============================================================+
+|  VALIDATION: ESCALATIONS                                     |
++==============================================================+
+
+Phase {N} validation: RED
+Gaps found: {total} | Resolved: {resolved} | Escalated: {escalated}
+
+NEXT UP:
+  /pbr:build {N} --gaps-only  -- fix implementation bugs
+  /pbr:validate-phase {N}     -- re-validate after fixes
+```
+
+---
+
+## Cleanup
+
+Delete `.planning/.active-skill` if it exists. This must happen on all paths (success, partial, and failure) before reporting results.
+
+Release any multi-session claim acquired in the sync step.
+
+---
+
+## Error Handling
+
+### Nyquist-auditor agent fails
+
+If the Task() spawn fails, display:
+
+```
++==============================================================+
+|  ERROR                                                       |
++==============================================================+
+
+Nyquist-auditor failed to complete.
+
+**To fix:** Review gaps manually or retry with `/pbr:validate-phase {N}`.
+```
+
+Write VALIDATION.md with current gap status (status: red). Clean up and STOP.
+
+### No must-haves to check
+
+If plans have empty must_haves:
+
+- Warn: "Plans don't have defined must-haves. Validation will be based on key_files only."
+- Use SUMMARY.md key_files as the basis for gap detection
+
+---
+
+## Files Created/Modified by /pbr:validate-phase
+
+| File | Purpose | When |
+|------|---------|------|
+| `.planning/phases/{NN}-{slug}/VALIDATION.md` | Validation report with test mapping | Step 5 |
+| `.planning/.active-skill` | Session lock | Step 1 (created), Cleanup (deleted) |
+
+---
+
+## Notes
+
+- The nyquist-auditor agent handles ALL test generation -- never write tests in the orchestrator
+- Re-running `/pbr:validate-phase` after fixes triggers fresh gap detection
+- VALIDATION.md is persistent and serves as the ground truth for test coverage gaps
+- Gap detection checks: test file existence, test execution results, automated verify commands

package/plugins/pbr/templates/CONTEXT.md.tmpl

@@ -1,38 +1,59 @@
 # CONTEXT.md Template
 
 > Referenced by: begin skill (Step 9c), discuss skill, plan skill
-> Created during /pbr:begin. Updated by /pbr:discuss and /pbr:plan --assumptions.
+> Created during /pbr:new-project. Updated by /pbr:discuss-phase and /pbr:plan-phase --assumptions.
 
 ## Structure
 
 ```markdown
-# Project Context
+# Phase Context
 
-## Locked Decisions
+**Created by:** {skill}
+**Date:** {date}
 
-{Technology choices, architecture decisions, and constraints that are NON-NEGOTIABLE.
- These MUST be honored by every plan and executor — no exceptions.}
+## Decision Summary
 
-| Decision | Rationale | Locked By |
-|----------|-----------|-----------|
-| {e.g., "Use TypeScript"} | {User preference, team skill} | User |
-| {e.g., "PostgreSQL via Supabase"} | {Existing infrastructure} | User |
+<!-- Compact digest for agent prompt injection. ~300 tokens max. -->
 
-## User Constraints
+<domain>
+{Problem domain context -- what this phase is about, key terminology, system boundaries}
+</domain>
 
-{Budget, timeline, skill level, hosting, team size — factors that shape planning}
+<decisions>
+{Locked decisions from discuss. NON-NEGOTIABLE during planning.}
 
-- {e.g., "Solo developer, no team"}
-- {e.g., "Deploy to Hetzner VPS"}
-- {e.g., "Must work offline"}
+- [ ] **{Decision title}** -- {Description}
+  - Scope: {RH-IDs}
+  - Quality: {acceptance criteria}
+  - Integration: {how it connects to other components}
+</decisions>
 
-## Deferred Ideas
+<canonical_refs>
+{Specs, ADRs, design docs, research files with FULL paths. Downstream agents MUST read these.}
 
-{Features explicitly moved to v2 or out-of-scope. Plans MUST NOT include these.}
+- .planning/research/{file}.md -- {description}
+- {other paths}
+</canonical_refs>
 
-| Idea | Reason Deferred |
-|------|----------------|
-| {feature} | {reason} |
+<specifics>
+{User references, preferences, and "I want it like X" moments captured during discussion.
+ These are NOT decisions -- they're directional hints for the planner.}
+
+- **{Reference}** -- {Context from user}
+</specifics>
+
+<code_context>
+{Reusable assets, established patterns, and integration points relevant to this phase.
+ Planner should leverage these rather than creating from scratch.}
+
+- **{Pattern/Asset}** -- {Location and how to reuse}
+</code_context>
+
+<deferred>
+{Ideas explicitly excluded from this phase. Plans MUST NOT include these.}
+
+- **{Idea}** -- {Reason deferred}
+</deferred>
 
 ## Claude's Discretion Areas
 
@@ -46,7 +67,11 @@
 
 ## Rules
 
-- Locked decisions are immutable once set — only the user can change them
+- Locked decisions are immutable once set -- only the user can change them
 - Deferred ideas must NEVER appear in plans
 - Discretion areas are documented when the planner exercises choice
 - Phase-level CONTEXT.md files (in phase directories) override project-level for that phase
+- Backward compatibility: existing CONTEXT.md files using markdown headers (## Decisions, ## Deferred Ideas) remain valid
+- The `<specifics>` section captures user references and "I want it like X" moments -- directional hints, not locked decisions
+- The `<code_context>` section captures reusable assets and established patterns -- planner should leverage these rather than reinventing
+- XML sections in order: domain, decisions, canonical_refs, specifics, code_context, deferred

package/plugins/pbr/templates/DISCOVERY.md.tmpl

@@ -0,0 +1,29 @@
+# Discovery: {topic}
+
+> Lightweight library/option decision for phase {phase_id}.
+> For deep research, use RESEARCH.md instead.
+
+## Question
+{What needs to be decided? e.g., "Which testing library for React components?"}
+
+## Options Evaluated
+
+| Option | Pros | Cons | Recommendation |
+|--------|------|------|----------------|
+| {option 1} | {pros} | {cons} | {recommended/acceptable/rejected} |
+
+## Decision
+**Chosen**: {option}
+**Rationale**: {why}
+
+## Don't Hand-Roll
+
+{Problems that look simple but have existing solutions. Prevents agents from reimplementing solved problems.}
+
+- **{Problem}** - Use {existing solution} instead of building from scratch
+- **{Problem}** - Use {library/pattern} -- it handles edge cases you'll miss
+
+## Source Priority
+1. Context7 MCP (library docs)
+2. Official documentation
+3. Web search

package/plugins/pbr/templates/DISCUSSION-LOG.md.tmpl

@@ -0,0 +1,49 @@
+<!-- Source: skills/discuss/SKILL.md | Purpose: Audit trail of discuss-phase Q&A -- NOT consumed by agents -->
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md -- this log preserves the alternatives considered.
+
+# Phase {N}: {Name} -- Discussion Log
+
+**Date:** {ISO date}
+**Phase:** {phase_id}
+**Areas discussed:** {comma-separated list}
+
+---
+
+## {Area 1 Name}
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| {Option 1} | {Brief description} | |
+| {Option 2} | {Brief description} | {checkmark} |
+| {Option 3} | {Brief description} | |
+
+**User's choice:** {Selected option or verbatim free-text response}
+**Notes:** {Any clarifications or rationale provided during discussion}
+
+---
+
+## {Area 2 Name}
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| {Option 1} | {Brief description} | |
+
+**User's choice:** {choice}
+**Notes:** {notes}
+
+---
+
+## Claude's Discretion
+
+{Areas delegated to Claude's judgment -- list what was deferred and why}
+
+## Deferred Ideas
+
+{Ideas mentioned but not in scope for this phase}
+
+---
+
+*Phase: {phase_id}*
+*Discussion log generated by /pbr:discuss*

package/plugins/pbr/templates/HANDOFF.json.tmpl

@@ -0,0 +1,30 @@
+{
+  "_description": "Structured pause state for session recovery. Written by /pbr:pause, read by /pbr:resume.",
+  "status": "{paused | interrupted | waiting}",
+  "created_at": "{ISO timestamp}",
+  "phase": {
+    "number": "{N}",
+    "slug": "{slug}",
+    "name": "{name}"
+  },
+  "plan": {
+    "number": "{N}",
+    "wave": "{N}",
+    "task_current": "{N}",
+    "tasks_total": "{N}"
+  },
+  "next_action": "{description of what to do next}",
+  "blockers": [
+    "{description of what's blocking progress}"
+  ],
+  "human_actions_pending": [
+    "{action the user needs to take before resuming}"
+  ],
+  "completed_tasks": [
+    "{task descriptions already done in current plan}"
+  ],
+  "uncommitted_files": [
+    "{file paths with uncommitted changes}"
+  ],
+  "context_notes": "{mental context -- what was being thought about, key decisions in-flight}"
+}

package/plugins/pbr/templates/INTEGRATION-REPORT.md.tmpl

@@ -111,7 +111,22 @@ Phase 03 (Core)  ──provides──→ Phase 04 (Frontend)
 ### Flow 2: {Flow Name} - {STATUS}
 ...
 
-## 5. Integration Issues Summary
+## 5. Data-Flow Propagation
+
+### Cross-Boundary Data Flows
+
+| Data Field | Source | Intermediate Steps | Destination | Status |
+|------------|--------|-------------------|-------------|--------|
+| {field name} | {origin, e.g., hook stdin `data.session_id`} | {module1:L12 → module2:L45} | {dest, e.g., metrics.jsonl `session_id`} | PROPAGATED |
+| {field name} | {origin} | {module1:L12 → module2:L45} | {dest} | DATA_DROPPED |
+
+### Data-Flow Issues
+
+| Field | Dropped At | Available In Scope | Passed Instead | Fix |
+|-------|-----------|-------------------|----------------|-----|
+| {field} | {file:line} | `data.session_id` | `undefined` | Pass `data.session_id` |
+
+## 6. Integration Issues Summary
 
 ### Critical Issues (system cannot function)
 
@@ -130,7 +145,7 @@ Phase 03 (Core)  ──provides──→ Phase 04 (Frontend)
 1. **{Issue}**: {description}
    - Fix: {recommended action}
 
-## 6. Integration Score
+## 7. Integration Score
 
 | Category | Items Checked | Passed | Failed | Score |
 |----------|--------------|--------|--------|-------|
@@ -138,6 +153,7 @@ Phase 03 (Core)  ──provides──→ Phase 04 (Frontend)
 | API coverage | {n} | {n} | {n} | {%} |
 | Auth protection | {n} | {n} | {n} | {%} |
 | E2E flows | {n} | {n} | {n} | {%} |
+| Data-flow propagation | {n} | {n} | {n} | {%} |
 | **Overall** | {n} | {n} | {n} | **{%}** |
 
 ## Recommendations

package/plugins/pbr/templates/MILESTONE-AUDIT.md.tmpl

@@ -0,0 +1,44 @@
+---
+version: "{version}"
+status: "{passed | gaps_found}"
+audited_at: "{ISO timestamp}"
+scores:
+  requirements: "{satisfied}/{total}"
+  phases: "{verified}/{total}"
+  integration: "{passed}/{total}"
+  flows: "{passed}/{total}"
+gaps:
+  - requirement: "{REQ-ID}"
+    phase: "{phase number}"
+    severity: "{critical | non-critical}"
+    description: "{what's missing}"
+tech_debt:
+  - phase: "{phase number}"
+    item: "{description}"
+    severity: "{low | medium | high}"
+---
+# Milestone Audit: {version}
+
+> Audited: {date}
+> Status: **{STATUS}**
+
+## Scores
+
+| Dimension | Score | Status |
+|-----------|-------|--------|
+| Requirements | {N}/{M} | {PASS/FAIL} |
+| Phases | {N}/{M} | {PASS/FAIL} |
+| Integration | {N}/{M} | {PASS/FAIL} |
+| Flows | {N}/{M} | {PASS/FAIL} |
+
+## Gaps
+
+{gap details or "No gaps found."}
+
+## Tech Debt
+
+{tech debt items or "No tech debt identified."}
+
+## Recommendations
+
+{actionable recommendations based on audit findings}