@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plan-build-run/skills/undo/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: undo
+description: "Revert recent PBR-generated commits by phase/plan, safely using git revert."
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+argument-hint: "[--last N] [--phase NN] [--plan NN-MM] [--range HASH..HASH]"
+---
+
+**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Begin executing Step 0 immediately.**
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► UNDO                                       ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+# /pbr:undo — Safe Commit Reversal
+
+You are running the **undo** skill. Your job is to help the user safely revert recent PBR-generated commits using `git revert` (history-preserving), not `git reset` (destructive).
+
+This skill runs **inline** (no Task delegation).
+
+---
+
+## Step 1 — Gather PBR Commits
+
+Run:
+
+```bash
+git log --oneline --no-merges -50
+```
+
+Filter lines matching the PBR commit pattern:
+`^[0-9a-f]+ (feat|fix|refactor|test|docs|chore|wip|revert)(\([a-zA-Z0-9._-]+\))?:`
+
+If no PBR commits found, display:
+
+```
+No PBR commits found in the last 50 commits.
+```
+
+Then exit.
+
+**Parse $ARGUMENTS for flags**:
+- `--last N`: limit to N most recent PBR commits (default 20)
+- `--phase NN`: filter to commits for a specific phase number (e.g. `--phase 55`)
+- `--plan NN-MM`: filter to commits for a specific plan (e.g. `--plan 55-02`)
+- `--range HASH..HASH`: preselect a hash range for revert — if provided, skip to Step 5 with that range pre-filled
+
+**Phase manifest mode (`--phase NN`):**
+
+When `--phase NN` is specified, first check for a `.phase-manifest.json` in the phase directory:
+
+1. Resolve the phase directory: `.planning/phases/{NN}-*/`
+2. Check for `.phase-manifest.json` in that directory
+3. If manifest exists: use `manifest.commits` as the commit list (skip git log scan)
+4. If manifest missing (phases completed before manifest support): fall back to git log scan and filter by scope pattern
+
+Phase manifests are written by `completePhase()`. Older phases may not have manifests.
+
+Apply filters to the collected PBR commits before proceeding.
+
+---
+
+## Step 2 — Group Commits by Scope
+
+Parse the scope from each commit message (e.g., `55-02`, `quick-003`, `planning`). If no scope is present, use `(no scope)`.
+
+Present grouped output:
+
+```
+Recent PBR commits (grouped by scope):
+
+[undo]
+  abc1234  feat(undo): add undo skill
+  def5678  chore(undo): register undo command
+
+[quick-003]
+  ghi9012  fix(quick-003): fix hook path resolution
+
+[planning]
+  jkl3456  docs(planning): update roadmap phase 55
+```
+
+For descriptive scopes, show just the scope label. For phase-plan scopes (NN-MM pattern, from older commits), add a "Phase NN, Plan MM" annotation.
+
+---
+
+## Step 3 — Prompt for Selection
+
+Use AskUserQuestion with the **select-action** pattern:
+
+- **question**: "Which commit(s) do you want to undo? Select a scope to revert all commits in that scope, or choose a custom option."
+- **header**: "Select commits to undo"
+- **options**: (dynamic — top 8 scope labels from grouped list, each formatted as `[{scope}] {N} commit(s)`, plus "Enter custom hash or range" and "Cancel")
+- **multiSelect**: false
+
+If user selects a scope label: collect all commits with that scope as the revert set.
+If user selects "Enter custom hash or range": use AskUserQuestion (freeform) to ask:
+  - "Enter a commit hash or range (e.g. abc1234 or abc..def):"
+  - Parse the response as a hash or HASH1..HASH2 range
+If user selects "Cancel": print "Undo cancelled." and exit.
+
+---
+
+## Step 3.5 — Pre-Revert Safety Gates (for `--phase NN` mode)
+
+When reverting an entire phase (`--phase NN`), run these 3 safety checks before proceeding to confirmation:
+
+**Gate 1: Downstream dependency check**
+Parse `.planning/ROADMAP.md` to find phases that list the target phase in their "Depends on" field. If any dependent phase has been started (has PLAN files or SUMMARY files), block with:
+```
+Phase {M} ({name}) depends on phase {N} and has already begun. Undo would break downstream work.
+To proceed anyway, use --force.
+```
+
+**Gate 2: Commit preview**
+Display all commits that will be reverted as a numbered list:
+```
+Commits to revert ({count}):
+  1. abc1234  feat(auth): implement discord oauth
+  2. def5678  fix(auth): handle null profile
+  3. ghi9012  docs(planning): add phase 3 summaries
+```
+
+**Gate 3: Explicit confirmation**
+Use AskUserQuestion with the **yes-no** pattern:
+- **question**: "Revert {count} commits from phase {N}? This uses git revert (history-preserving)."
+- **options**: ["Proceed with revert", "Cancel"]
+
+If user selects "Cancel": print "Undo cancelled." and exit.
+
+For non-phase mode (single commits, custom ranges), skip Gate 1 and proceed to Step 4.
+
+---
+
+## Step 4 — Confirm Selection
+
+Display the commits that will be reverted:
+
+```
+The following commits will be reverted (using git revert, NOT git reset):
+
+  abc1234  feat(undo): add undo skill
+  def5678  chore(undo): register undo command
+
+This creates new revert commits — your history is preserved.
+```
+
+Use AskUserQuestion with the **yes-no** pattern:
+- **question**: "Proceed with reverting these commits?"
+- **options**: ["Proceed with revert", "Cancel"]
+
+If user selects "Cancel": print "Undo cancelled." and exit.
+
+---
+
+## Step 5 — Execute git revert
+
+For each commit hash in **reverse chronological order** (newest first):
+
+```bash
+git revert --no-commit {hash}
+```
+
+After all reverts are staged, determine the commit message:
+- Extract scope from the first commit being reverted (e.g., `undo`, `auth`, `executor`)
+- If reverting a **single commit**: `revert({scope}): undo {original description}`
+- If reverting **multiple commits**: `revert({scope}): undo {N} commits from {scope}`
+
+Commit with:
+
+```bash
+git commit -m "revert({scope}): undo {description}"
+```
+
+**Conflict handling**: If `git revert --no-commit` exits non-zero or produces conflict markers:
+1. Run `git revert --abort` to clean up
+2. Display:
+   ```
+   Revert failed due to merge conflicts. Manual resolution required.
+   Run: git revert {hashes} and resolve conflicts.
+   ```
+3. Exit without committing.
+
+---
+
+## Step 6 — Report Result
+
+Display completion banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► UNDO COMPLETE                              ║
+╚══════════════════════════════════════════════════════════════╝
+
+Reverted: {N} commit(s) from scope {scope}
+New revert commit: {hash} — revert({scope}): undo {description}
+
+/pbr:progress — check current state
+```
+
+---
+
+## Anti-Patterns
+
+1. **DO NOT** use `git reset` — always use `git revert` to preserve history
+2. **DO NOT** revert commits from other users without confirmation
+3. **DO NOT** revert merge commits without warning the user about potential complexity
+4. **DO NOT** skip the confirmation step (Step 4)
+5. **DO NOT** commit if `git revert` reports conflicts — abort and report instead

package/plan-build-run/templates/CLAUDE.md

@@ -0,0 +1,7 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+*No recent activity*
+</claude-mem-context>

package/plan-build-run/templates/DEBUG.md

@@ -0,0 +1,164 @@
+# Debug Template
+
+Template for `.planning/debug/[slug].md` — active debug session tracking.
+
+---
+
+## File Template
+
+```markdown
+---
+status: gathering | investigating | fixing | verifying | awaiting_human_verify | resolved
+trigger: "[verbatim user input]"
+created: [ISO timestamp]
+updated: [ISO timestamp]
+---
+
+## Current Focus
+<!-- OVERWRITE on each update - always reflects NOW -->
+
+hypothesis: [current theory being tested]
+test: [how testing it]
+expecting: [what result means if true/false]
+next_action: [immediate next step]
+
+## Symptoms
+<!-- Written during gathering, then immutable -->
+
+expected: [what should happen]
+actual: [what actually happens]
+errors: [error messages if any]
+reproduction: [how to trigger]
+started: [when it broke / always broken]
+
+## Eliminated
+<!-- APPEND only - prevents re-investigating after /clear -->
+
+- hypothesis: [theory that was wrong]
+  evidence: [what disproved it]
+  timestamp: [when eliminated]
+
+## Evidence
+<!-- APPEND only - facts discovered during investigation -->
+
+- timestamp: [when found]
+  checked: [what was examined]
+  found: [what was observed]
+  implication: [what this means]
+
+## Resolution
+<!-- OVERWRITE as understanding evolves -->
+
+root_cause: [empty until found]
+fix: [empty until applied]
+verification: [empty until verified]
+files_changed: []
+```
+
+---
+
+<section_rules>
+
+**Frontmatter (status, trigger, timestamps):**
+- `status`: OVERWRITE - reflects current phase
+- `trigger`: IMMUTABLE - verbatim user input, never changes
+- `created`: IMMUTABLE - set once
+- `updated`: OVERWRITE - update on every change
+
+**Current Focus:**
+- OVERWRITE entirely on each update
+- Always reflects what Claude is doing RIGHT NOW
+- If Claude reads this after /clear, it knows exactly where to resume
+- Fields: hypothesis, test, expecting, next_action
+
+**Symptoms:**
+- Written during initial gathering phase
+- IMMUTABLE after gathering complete
+- Reference point for what we're trying to fix
+- Fields: expected, actual, errors, reproduction, started
+
+**Eliminated:**
+- APPEND only - never remove entries
+- Prevents re-investigating dead ends after context reset
+- Each entry: hypothesis, evidence that disproved it, timestamp
+- Critical for efficiency across /clear boundaries
+
+**Evidence:**
+- APPEND only - never remove entries
+- Facts discovered during investigation
+- Each entry: timestamp, what checked, what found, implication
+- Builds the case for root cause
+
+**Resolution:**
+- OVERWRITE as understanding evolves
+- May update multiple times as fixes are tried
+- Final state shows confirmed root cause and verified fix
+- Fields: root_cause, fix, verification, files_changed
+
+</section_rules>
+
+<lifecycle>
+
+**Creation:** Immediately when /pbr:debug is called
+- Create file with trigger from user input
+- Set status to "gathering"
+- Current Focus: next_action = "gather symptoms"
+- Symptoms: empty, to be filled
+
+**During symptom gathering:**
+- Update Symptoms section as user answers questions
+- Update Current Focus with each question
+- When complete: status → "investigating"
+
+**During investigation:**
+- OVERWRITE Current Focus with each hypothesis
+- APPEND to Evidence with each finding
+- APPEND to Eliminated when hypothesis disproved
+- Update timestamp in frontmatter
+
+**During fixing:**
+- status → "fixing"
+- Update Resolution.root_cause when confirmed
+- Update Resolution.fix when applied
+- Update Resolution.files_changed
+
+**During verification:**
+- status → "verifying"
+- Update Resolution.verification with results
+- If verification fails: status → "investigating", try again
+
+**After self-verification passes:**
+- status -> "awaiting_human_verify"
+- Request explicit user confirmation in a checkpoint
+- Do NOT move file to resolved yet
+
+**On resolution:**
+- status → "resolved"
+- Move file to .planning/debug/resolved/ (only after user confirms fix)
+
+</lifecycle>
+
+<resume_behavior>
+
+When Claude reads this file after /clear:
+
+1. Parse frontmatter → know status
+2. Read Current Focus → know exactly what was happening
+3. Read Eliminated → know what NOT to retry
+4. Read Evidence → know what's been learned
+5. Continue from next_action
+
+The file IS the debugging brain. Claude should be able to resume perfectly from any interruption point.
+
+</resume_behavior>
+
+<size_constraint>
+
+Keep debug files focused:
+- Evidence entries: 1-2 lines each, just the facts
+- Eliminated: brief - hypothesis + why it failed
+- No narrative prose - structured data only
+
+If evidence grows very large (10+ entries), consider whether you're going in circles. Check Eliminated to ensure you're not re-treading.
+
+</size_constraint>

package/plan-build-run/templates/UAT.md

@@ -0,0 +1,247 @@
+# UAT Template
+
+Template for `.planning/phases/XX-name/{phase_num}-UAT.md` — persistent UAT session tracking.
+
+---
+
+## File Template
+
+```markdown
+---
+status: testing | complete | diagnosed
+phase: XX-name
+source: [list of SUMMARY.md files tested]
+started: [ISO timestamp]
+updated: [ISO timestamp]
+---
+
+## Current Test
+<!-- OVERWRITE each test - shows where we are -->
+
+number: [N]
+name: [test name]
+expected: |
+  [what user should observe]
+awaiting: user response
+
+## Tests
+
+### 1. [Test Name]
+expected: [observable behavior - what user should see]
+result: [pending]
+
+### 2. [Test Name]
+expected: [observable behavior]
+result: pass
+
+### 3. [Test Name]
+expected: [observable behavior]
+result: issue
+reported: "[verbatim user response]"
+severity: major
+
+### 4. [Test Name]
+expected: [observable behavior]
+result: skipped
+reason: [why skipped]
+
+...
+
+## Summary
+
+total: [N]
+passed: [N]
+issues: [N]
+pending: [N]
+skipped: [N]
+
+## Gaps
+
+<!-- YAML format for plan-phase --gaps consumption -->
+- truth: "[expected behavior from test]"
+  status: failed
+  reason: "User reported: [verbatim response]"
+  severity: blocker | major | minor | cosmetic
+  test: [N]
+  root_cause: ""     # Filled by diagnosis
+  artifacts: []      # Filled by diagnosis
+  missing: []        # Filled by diagnosis
+  debug_session: ""  # Filled by diagnosis
+```
+
+---
+
+<section_rules>
+
+**Frontmatter:**
+- `status`: OVERWRITE - "testing" or "complete"
+- `phase`: IMMUTABLE - set on creation
+- `source`: IMMUTABLE - SUMMARY files being tested
+- `started`: IMMUTABLE - set on creation
+- `updated`: OVERWRITE - update on every change
+
+**Current Test:**
+- OVERWRITE entirely on each test transition
+- Shows which test is active and what's awaited
+- On completion: "[testing complete]"
+
+**Tests:**
+- Each test: OVERWRITE result field when user responds
+- `result` values: [pending], pass, issue, skipped
+- If issue: add `reported` (verbatim) and `severity` (inferred)
+- If skipped: add `reason` if provided
+
+**Summary:**
+- OVERWRITE counts after each response
+- Tracks: total, passed, issues, pending, skipped
+
+**Gaps:**
+- APPEND only when issue found (YAML format)
+- After diagnosis: fill `root_cause`, `artifacts`, `missing`, `debug_session`
+- This section feeds directly into /pbr:plan-phase --gaps
+
+</section_rules>
+
+<diagnosis_lifecycle>
+
+**After testing complete (status: complete), if gaps exist:**
+
+1. User runs diagnosis (from verify-work offer or manually)
+2. diagnose-issues workflow spawns parallel debug agents
+3. Each agent investigates one gap, returns root cause
+4. UAT.md Gaps section updated with diagnosis:
+   - Each gap gets `root_cause`, `artifacts`, `missing`, `debug_session` filled
+5. status → "diagnosed"
+6. Ready for /pbr:plan-phase --gaps with root causes
+
+**After diagnosis:**
+```yaml
+## Gaps
+
+- truth: "Comment appears immediately after submission"
+  status: failed
+  reason: "User reported: works but doesn't show until I refresh the page"
+  severity: major
+  test: 2
+  root_cause: "useEffect in CommentList.tsx missing commentCount dependency"
+  artifacts:
+    - path: "src/components/CommentList.tsx"
+      issue: "useEffect missing dependency"
+  missing:
+    - "Add commentCount to useEffect dependency array"
+  debug_session: ".planning/debug/comment-not-refreshing.md"
+```
+
+</diagnosis_lifecycle>
+
+<lifecycle>
+
+**Creation:** When /pbr:verify-work starts new session
+- Extract tests from SUMMARY.md files
+- Set status to "testing"
+- Current Test points to test 1
+- All tests have result: [pending]
+
+**During testing:**
+- Present test from Current Test section
+- User responds with pass confirmation or issue description
+- Update test result (pass/issue/skipped)
+- Update Summary counts
+- If issue: append to Gaps section (YAML format), infer severity
+- Move Current Test to next pending test
+
+**On completion:**
+- status → "complete"
+- Current Test → "[testing complete]"
+- Commit file
+- Present summary with next steps
+
+**Resume after /clear:**
+1. Read frontmatter → know phase and status
+2. Read Current Test → know where we are
+3. Find first [pending] result → continue from there
+4. Summary shows progress so far
+
+</lifecycle>
+
+<severity_guide>
+
+Severity is INFERRED from user's natural language, never asked.
+
+| User describes | Infer |
+|----------------|-------|
+| Crash, error, exception, fails completely, unusable | blocker |
+| Doesn't work, nothing happens, wrong behavior, missing | major |
+| Works but..., slow, weird, minor, small issue | minor |
+| Color, font, spacing, alignment, visual, looks off | cosmetic |
+
+Default: **major** (safe default, user can clarify if wrong)
+
+</severity_guide>
+
+<good_example>
+```markdown
+---
+status: diagnosed
+phase: 04-comments
+source: 04-01-SUMMARY.md, 04-02-SUMMARY.md
+started: 2025-01-15T10:30:00Z
+updated: 2025-01-15T10:45:00Z
+---
+
+## Current Test
+
+[testing complete]
+
+## Tests
+
+### 1. View Comments on Post
+expected: Comments section expands, shows count and comment list
+result: pass
+
+### 2. Create Top-Level Comment
+expected: Submit comment via rich text editor, appears in list with author info
+result: issue
+reported: "works but doesn't show until I refresh the page"
+severity: major
+
+### 3. Reply to a Comment
+expected: Click Reply, inline composer appears, submit shows nested reply
+result: pass
+
+### 4. Visual Nesting
+expected: 3+ level thread shows indentation, left borders, caps at reasonable depth
+result: pass
+
+### 5. Delete Own Comment
+expected: Click delete on own comment, removed or shows [deleted] if has replies
+result: pass
+
+### 6. Comment Count
+expected: Post shows accurate count, increments when adding comment
+result: pass
+
+## Summary
+
+total: 6
+passed: 5
+issues: 1
+pending: 0
+skipped: 0
+
+## Gaps
+
+- truth: "Comment appears immediately after submission in list"
+  status: failed
+  reason: "User reported: works but doesn't show until I refresh the page"
+  severity: major
+  test: 2
+  root_cause: "useEffect in CommentList.tsx missing commentCount dependency"
+  artifacts:
+    - path: "src/components/CommentList.tsx"
+      issue: "useEffect missing dependency"
+  missing:
+    - "Add commentCount to useEffect dependency array"
+  debug_session: ".planning/debug/comment-not-refreshing.md"
+```
+</good_example>

package/plan-build-run/templates/VALIDATION.md

@@ -0,0 +1,76 @@
+---
+phase: {N}
+slug: {phase-slug}
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: {date}
+---
+
+# Phase {N} — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | {pytest 7.x / jest 29.x / vitest / go test / other} |
+| **Config file** | {path or "none — Wave 0 installs"} |
+| **Quick run command** | `{quick command}` |
+| **Full suite command** | `{full command}` |
+| **Estimated runtime** | ~{N} seconds |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run `{quick run command}`
+- **After every plan wave:** Run `{full suite command}`
+- **Before `/pbr:verify-work`:** Full suite must be green
+- **Max feedback latency:** {N} seconds
+
+---
+
+## Per-Task Verification Map
+
+| Task ID | Plan | Wave | Requirement | Test Type | Automated Command | File Exists | Status |
+|---------|------|------|-------------|-----------|-------------------|-------------|--------|
+| {N}-01-01 | 01 | 1 | REQ-{XX} | unit | `{command}` | ✅ / ❌ W0 | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+---
+
+## Wave 0 Requirements
+
+- [ ] `{tests/test_file.py}` — stubs for REQ-{XX}
+- [ ] `{tests/conftest.py}` — shared fixtures
+- [ ] `{framework install}` — if no framework detected
+
+*If none: "Existing infrastructure covers all phase requirements."*
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| {behavior} | REQ-{XX} | {reason} | {steps} |
+
+*If none: "All phase behaviors have automated verification."*
+
+---
+
+## Validation Sign-Off
+
+- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
+- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
+- [ ] Wave 0 covers all MISSING references
+- [ ] No watch-mode flags
+- [ ] Feedback latency < {N}s
+- [ ] `nyquist_compliant: true` set in frontmatter
+
+**Approval:** {pending / approved YYYY-MM-DD}