@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plan-build-run/workflows/verify-work.md

@@ -0,0 +1,465 @@
+<purpose>
+Validate built features through conversational testing with persistent state. Creates UAT.md that tracks test progress, survives /clear, and feeds gaps into /pbr:plan-phase --gaps.
+
+User tests, Claude records. One test at a time. Plain text responses.
+</purpose>
+
+<philosophy>
+**Show expected, ask if reality matches.**
+
+Claude presents what SHOULD happen. User confirms or describes what's different.
+- "yes" / "y" / "next" / empty → pass
+- Anything else → logged as issue, severity inferred
+
+No Pass/Fail buttons. No severity questions. Just: "Here's what should happen. Does it?"
+</philosophy>
+
+<template>
+@~/.claude/plan-build-run/templates/UAT.md
+</template>
+
+<process>
+
+<step name="initialize" priority="first">
+If $ARGUMENTS contains a phase number, load context:
+
+```bash
+INIT=$(node ~/.claude/plan-build-run/scripts/pbr-tools.cjs init verify-work "${PHASE_ARG}")
+```
+
+Parse JSON for: `planner_model`, `checker_model`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `has_verification`.
+</step>
+
+<step name="check_active_session">
+**First: Check for active UAT sessions**
+
+```bash
+find .planning/phases -name "*-UAT.md" -type f 2>/dev/null | head -5
+```
+
+**If active sessions exist AND no $ARGUMENTS provided:**
+
+Read each file's frontmatter (status, phase) and Current Test section.
+
+Display inline:
+
+```
+## Active UAT Sessions
+
+| # | Phase | Status | Current Test | Progress |
+|---|-------|--------|--------------|----------|
+| 1 | 04-comments | testing | 3. Reply to Comment | 2/6 |
+| 2 | 05-auth | testing | 1. Login Form | 0/4 |
+
+Reply with a number to resume, or provide a phase number to start new.
+```
+
+Wait for user response.
+
+- If user replies with number (1, 2) → Load that file, go to `resume_from_file`
+- If user replies with phase number → Treat as new session, go to `create_uat_file`
+
+**If active sessions exist AND $ARGUMENTS provided:**
+
+Check if session exists for that phase. If yes, offer to resume or restart.
+If no, continue to `create_uat_file`.
+
+**If no active sessions AND no $ARGUMENTS:**
+
+```
+No active UAT sessions.
+
+Provide a phase number to start testing (e.g., /pbr:verify-work 4)
+```
+
+**If no active sessions AND $ARGUMENTS provided:**
+
+Continue to `create_uat_file`.
+</step>
+
+<step name="find_summaries">
+**Find what to test:**
+
+Use `phase_dir` from init (or run init if not already done).
+
+```bash
+ls "$phase_dir"/*-SUMMARY.md 2>/dev/null
+```
+
+Read each SUMMARY.md to extract testable deliverables.
+</step>
+
+<step name="extract_tests">
+**Extract testable deliverables from SUMMARY.md:**
+
+Parse for:
+1. **Accomplishments** - Features/functionality added
+2. **User-facing changes** - UI, workflows, interactions
+
+Focus on USER-OBSERVABLE outcomes, not implementation details.
+
+For each deliverable, create a test:
+- name: Brief test name
+- expected: What the user should see/experience (specific, observable)
+
+Examples:
+- Accomplishment: "Added comment threading with infinite nesting"
+  → Test: "Reply to a Comment"
+  → Expected: "Clicking Reply opens inline composer below comment. Submitting shows reply nested under parent with visual indentation."
+
+Skip internal/non-observable items (refactors, type changes, etc.).
+</step>
+
+<step name="create_uat_file">
+**Create UAT file with all tests:**
+
+```bash
+mkdir -p "$PHASE_DIR"
+```
+
+Build test list from extracted deliverables.
+
+Create file:
+
+```markdown
+---
+status: testing
+phase: XX-name
+source: [list of SUMMARY.md files]
+started: [ISO timestamp]
+updated: [ISO timestamp]
+---
+
+## Current Test
+<!-- OVERWRITE each test - shows where we are -->
+
+number: 1
+name: [first test name]
+expected: |
+  [what user should observe]
+awaiting: user response
+
+## Tests
+
+### 1. [Test Name]
+expected: [observable behavior]
+result: [pending]
+
+### 2. [Test Name]
+expected: [observable behavior]
+result: [pending]
+
+...
+
+## Summary
+
+total: [N]
+passed: 0
+issues: 0
+pending: [N]
+skipped: 0
+
+## Gaps
+
+[none yet]
+```
+
+Write to `.planning/phases/XX-name/{phase}-UAT.md`
+
+Proceed to `present_test`.
+</step>
+
+<step name="present_test">
+**Present current test to user:**
+
+Read Current Test section from UAT file.
+
+Display using checkpoint box format:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  CHECKPOINT: Verification Required                           ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Test {number}: {name}**
+
+{expected}
+
+──────────────────────────────────────────────────────────────
+→ Type "pass" or describe what's wrong
+──────────────────────────────────────────────────────────────
+```
+
+Wait for user response (plain text, no AskUserQuestion).
+</step>
+
+<step name="process_response">
+**Process user response and update file:**
+
+**If response indicates pass:**
+- Empty response, "yes", "y", "ok", "pass", "next", "approved", "✓"
+
+Update Tests section:
+```
+### {N}. {name}
+expected: {expected}
+result: pass
+```
+
+**If response indicates skip:**
+- "skip", "can't test", "n/a"
+
+Update Tests section:
+```
+### {N}. {name}
+expected: {expected}
+result: skipped
+reason: [user's reason if provided]
+```
+
+**If response is anything else:**
+- Treat as issue description
+
+Infer severity from description:
+- Contains: crash, error, exception, fails, broken, unusable → blocker
+- Contains: doesn't work, wrong, missing, can't → major
+- Contains: slow, weird, off, minor, small → minor
+- Contains: color, font, spacing, alignment, visual → cosmetic
+- Default if unclear: major
+
+Update Tests section:
+```
+### {N}. {name}
+expected: {expected}
+result: issue
+reported: "{verbatim user response}"
+severity: {inferred}
+```
+
+Append to Gaps section (structured YAML for plan-phase --gaps):
+```yaml
+- truth: "{expected behavior from test}"
+  status: failed
+  reason: "User reported: {verbatim user response}"
+  severity: {inferred}
+  test: {N}
+  artifacts: []  # Filled by diagnosis
+  missing: []    # Filled by diagnosis
+```
+
+**After any response:**
+
+Update Summary counts.
+Update frontmatter.updated timestamp.
+
+If more tests remain → Update Current Test, go to `present_test`
+If no more tests → Go to `complete_session`
+</step>
+
+<step name="resume_from_file">
+**Resume testing from UAT file:**
+
+Read the full UAT file.
+
+Find first test with `result: [pending]`.
+
+Announce:
+```
+Resuming: Phase {phase} UAT
+Progress: {passed + issues + skipped}/{total}
+Issues found so far: {issues count}
+
+Continuing from Test {N}...
+```
+
+Update Current Test section with the pending test.
+Proceed to `present_test`.
+</step>
+
+<step name="complete_session">
+**Complete testing and commit:**
+
+Update frontmatter:
+- status: complete
+- updated: [now]
+
+Clear Current Test section:
+```
+## Current Test
+
+[testing complete]
+```
+
+Commit the UAT file:
+```bash
+node ~/.claude/plan-build-run/scripts/pbr-tools.cjs commit "test({phase}): complete UAT - {passed} passed, {issues} issues" --files ".planning/phases/XX-name/{phase}-UAT.md"
+```
+
+Present summary:
+```
+## UAT Complete: Phase {phase}
+
+| Result | Count |
+|--------|-------|
+| Passed | {N}   |
+| Issues | {N}   |
+| Skipped| {N}   |
+
+[If issues > 0:]
+### Issues Found
+
+[List from Issues section]
+```
+
+**If issues > 0:** Proceed to `diagnose_issues`
+
+**If issues == 0:**
+```
+All tests passed. Ready to continue.
+
+- `/pbr:plan-phase {next}` — Plan next phase
+- `/pbr:execute-phase {next}` — Execute next phase
+```
+</step>
+
+<step name="diagnose_issues">
+**Diagnose root causes before planning fixes:**
+
+```
+---
+
+{N} issues found. Diagnosing root causes...
+
+Spawning parallel debug agents to investigate each issue.
+```
+
+- Load diagnose-issues workflow
+- Follow @~/.claude/plan-build-run/workflows/diagnose-issues.md
+- Spawn parallel debug agents for each issue
+- Collect root causes
+- Update UAT.md with root causes (set frontmatter status to `diagnosed`)
+- Proceed to `present_gap_closure_next`
+
+Diagnosis runs automatically - no user prompt. Parallel agents investigate simultaneously, so overhead is minimal and fixes are more accurate.
+</step>
+
+<step name="present_gap_closure_next">
+**Defer gap planning to a fresh context window.**
+
+Do NOT spawn planners or checkers inline — by this point in the session, context is heavily used from UAT testing and diagnosis. Gap planning needs fresh context for quality results.
+
+Commit the diagnosed UAT file:
+
+```bash
+node ~/.claude/plan-build-run/scripts/pbr-tools.cjs commit "test({phase}): diagnose UAT gaps - {issues} issues found" --files ".planning/phases/XX-name/{phase}-UAT.md"
+```
+
+Present:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PBR ► GAPS DIAGNOSED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase {X}: {Name}** — {N} issue(s) diagnosed
+
+| # | Issue | Severity | Root Cause |
+|---|-------|----------|------------|
+| 1 | {truth 1} | {severity} | {root_cause} |
+| 2 | {truth 2} | {severity} | {root_cause} |
+
+Diagnoses saved to: {phase}-UAT.md
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Plan fixes** — create gap closure plans from diagnoses
+
+`/pbr:plan-phase {phase} --gaps`
+
+<sub>`/clear` first → fresh context window for quality planning</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/pbr:execute-phase {phase} --gaps-only` — if fix plans already exist
+- Re-run `/pbr:verify-work {phase}` — test additional scenarios
+
+───────────────────────────────────────────────────────────────
+```
+
+**STOP HERE.** Do not spawn planners or checkers. The user will `/clear` and run `/pbr:plan-phase --gaps` in a fresh context where the planner gets full context budget for quality gap closure plans.
+</step>
+
+</process>
+
+<update_rules>
+**Batched writes for efficiency:**
+
+Keep results in memory. Write to file only when:
+1. **Issue found** — Preserve the problem immediately
+2. **Session complete** — Final write before commit
+3. **Checkpoint** — Every 5 passed tests (safety net)
+
+| Section | Rule | When Written |
+|---------|------|--------------|
+| Frontmatter.status | OVERWRITE | Start, complete |
+| Frontmatter.updated | OVERWRITE | On any file write |
+| Current Test | OVERWRITE | On any file write |
+| Tests.{N}.result | OVERWRITE | On any file write |
+| Summary | OVERWRITE | On any file write |
+| Gaps | APPEND | When issue found |
+
+On context reset: File shows last checkpoint. Resume from there.
+</update_rules>
+
+<severity_inference>
+**Infer severity from user's natural language:**
+
+| User says | Infer |
+|-----------|-------|
+| "crashes", "error", "exception", "fails completely" | blocker |
+| "doesn't work", "nothing happens", "wrong behavior" | major |
+| "works but...", "slow", "weird", "minor issue" | minor |
+| "color", "spacing", "alignment", "looks off" | cosmetic |
+
+Default to **major** if unclear. User can correct if needed.
+
+**Never ask "how severe is this?"** - just infer and move on.
+</severity_inference>
+
+<integration_health>
+## Integration Health Score
+
+After UAT testing completes, calculate integration health to quantify system quality:
+
+```bash
+SCORE=$(node ~/.claude/plan-build-run/scripts/pbr-tools.cjs integration-score --raw)
+```
+
+The integration score uses the **5-state export model** (CONNECTED, IMPORTED_NOT_USED, ORPHANED, MISMATCHED, MISSING_EXPORT) to classify every export and calculates per-category scores for:
+- **Exports** -- percentage of exports in CONNECTED state
+- **API Coverage** -- percentage of routes with active consumers
+- **Auth Protection** -- percentage of sensitive routes with auth checks
+- **E2E Flows** -- percentage of user flows completing end-to-end
+
+Include the score in the UAT completion summary when a VERIFICATION.md exists.
+
+For CRUD entity verification, use the 10-step template:
+@~/.claude/plan-build-run/templates/crud-flow-verification.md
+</integration_health>
+
+<success_criteria>
+- [ ] UAT file created with all tests from SUMMARY.md
+- [ ] Tests presented one at a time with expected behavior
+- [ ] User responses processed as pass/issue/skip
+- [ ] Severity inferred from description (never asked)
+- [ ] Batched writes: on issue, every 5 passes, or completion
+- [ ] Committed on completion
+- [ ] If issues: parallel debug agents diagnose root causes
+- [ ] If issues: UAT.md committed with diagnoses (status: diagnosed)
+- [ ] If issues: user directed to `/pbr:plan-phase --gaps` in fresh context
+- [ ] Integration health score calculated when VERIFICATION.md available
+- [ ] Ready for next step when complete
+</success_criteria>

package/plugins/pbr/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.11.0",
+  "version": "2.12.1",
   "description": "Plan-Build-Run — Structured development workflow for Claude Code. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/pbr/CLAUDE.md

@@ -0,0 +1,19 @@
+# PBR Plugin Instructions
+
+This file is loaded by Claude Code for all PBR plugin interactions. Rules here apply globally to every skill and agent.
+
+## Universal Anti-Patterns
+
+All skills and agents MUST follow the anti-patterns defined in `skills/shared/universal-anti-patterns.md`. These rules apply globally to every PBR workflow and are organized into the following categories:
+
+- **Context Budget Rules** (1-5): Prevent context rot by never reading agent definitions, never inlining large files into Task() prompts, scaling read depth with context window size, delegating heavy work to subagents, and proactively warning about context budget.
+- **File Reading Rules** (6-9): Control SUMMARY.md read depth by context window, restrict cross-phase plan reads, forbid log file reads, and prefer frontmatter over full reads.
+- **Task/Subagent Rules** (10-11): Never invoke Skill() inside Task(), always use `subagent_type: "pbr:{agent}"` instead of generic agent types.
+- **Questioning Anti-Patterns** (20-22): No checklist walking, no corporate speak, no premature constraints.
+- **State Consolidation Anti-Patterns** (23-25): No writes to deprecated CONTEXT.md or HISTORY.md, correct mode value is "autonomous" not "auto".
+- **Behavioral Rules** (11-16): Respect locked decisions, confirm before creating artifacts, stay in scope, give clear priority, stage specific files, use CLI for STATE.md writes.
+- **Error Recovery Rules** (17-19): Git lock detection, config fallback awareness, partial state recovery.
+
+Note: Individual skills do not need to reference this fragment directly — it is loaded globally via this CLAUDE.md file which is injected into every plugin interaction.
+
+The canonical source is `skills/shared/universal-anti-patterns.md`. Refer to it for the full rule definitions and details.

package/plugins/pbr/UI-CONSISTENCY-GAPS.md

@@ -30,7 +30,7 @@ Tracks remaining gaps found after initial UI consistency pass.
 
 | # | Skill | Issue | Status |
 |---|-------|-------|--------|
-| 3.1 | build | References ui-formatting.md templates but never shows banner inline | DONE |
+| 3.1 | build | References ui-brand.md templates but never shows banner inline | DONE |
 | 3.2 | discuss | No completion banner at all | DONE |
 | 3.3 | debug | No banner for resolved case | DONE |
 | 3.4 | todo | Plain `✓` lines, no branded banner | DONE |