@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/references/archive/tmux-setup.md

@@ -0,0 +1,288 @@
+# TMUX Setup for Claude Code (Windows 11 + WSL2)
+
+Complete guide to running Claude Code inside TMUX on Windows 11. Claude Code stays
+installed on Windows; TMUX in WSL2 wraps it via `cmd.exe /c claude`. Projects remain
+on Windows drives (e.g., `D:\Repos\`), accessed through WSL2's `/mnt/` mount.
+
+## Prerequisites
+
+- Windows 11 with WSL2 enabled (`wsl --install` if not already set up)
+- A WSL2 distro installed (Ubuntu recommended: `wsl --install -d Ubuntu`)
+- Claude Code installed on Windows (`npm install -g @anthropic-ai/claude-code`)
+- Windows Terminal (recommended, available from Microsoft Store)
+
+## Step 1: Install TMUX in WSL2
+
+```bash
+sudo apt update && sudo apt install -y tmux
+tmux -V  # Should print tmux 3.x+
+```
+
+## Step 2: Install gum (optional but recommended)
+
+gum provides polished interactive menus for `pbr-tmux`. Without it, `pbr-tmux` falls
+back to plain bash `select` menus -- fully functional, just less pretty.
+
+**Method A -- Charm apt repository (Ubuntu/Debian):**
+
+```bash
+sudo mkdir -p /etc/apt/keyrings
+curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
+echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" \
+  | sudo tee /etc/apt/sources.list.d/charm.list
+sudo apt update && sudo apt install gum
+```
+
+**Method B -- Direct binary download (any Linux distro):**
+
+```bash
+GUM_VERSION=$(curl -s https://api.github.com/repos/charmbracelet/gum/releases/latest | grep tag_name | cut -d'"' -f4 | tr -d v)
+curl -fsSL "https://github.com/charmbracelet/gum/releases/download/v${GUM_VERSION}/gum_${GUM_VERSION}_Linux_x86_64.tar.gz" \
+  | sudo tar xz -C /usr/local/bin gum
+```
+
+**Verify:** `gum --version`
+
+## Step 3: Install .tmux.conf
+
+Copy the PBR-optimized tmux configuration:
+
+```bash
+# From the plan-build-run repository root (WSL2 path):
+cp /mnt/d/Repos/plan-build-run/tools/pbr-tmux/tmux.conf ~/.tmux.conf
+```
+
+**CRITICAL:** The config sets `default-terminal "tmux-256color"`. Do NOT change this to
+`screen-256color` -- that causes Windows `.exe` processes (including `cmd.exe /c claude`)
+to hang indefinitely in WSL2 tmux panes.
+
+Key features provided by `.tmux.conf`:
+
+- Mouse support (click panes, scroll, resize)
+- 50,000-line scrollback history
+- Vi copy-mode with clipboard integration (xclip or clip.exe)
+- Vim-style pane navigation (`Ctrl-b h/j/k/l`)
+- Intuitive splits (`Ctrl-b |` horizontal, `Ctrl-b -` vertical)
+- PBR-aware status bar (shows current phase and status)
+
+## Step 4: Set up PBR status bar
+
+The status bar reads `.planning/STATE.md` every 10 seconds and displays the current
+phase and workflow status in the bottom-right corner.
+
+```bash
+mkdir -p ~/.tmux
+ln -sf /mnt/d/Repos/plan-build-run/tools/pbr-tmux/lib/pbr-state.sh ~/.tmux/pbr-status.sh
+```
+
+Point it at your project:
+
+```bash
+# Option A: Breadcrumb file (persists across sessions)
+echo "/mnt/d/Repos/your-project" > ~/.pbr-project-path
+
+# Option B: Environment variable (set in ~/.bashrc)
+export PBR_PROJECT_DIR="/mnt/d/Repos/your-project"
+```
+
+The status bar shows `P{phase}:{status}` when a project is active, or `no-pbr` when
+no `.planning/STATE.md` is found.
+
+## Step 5: Set up pbr-tmux
+
+`pbr-tmux` is the interactive CLI for common tmux operations in a PBR workflow.
+
+```bash
+# Option A: Symlink to PATH (recommended)
+sudo ln -sf /mnt/d/Repos/plan-build-run/tools/pbr-tmux/pbr-tmux /usr/local/bin/pbr-tmux
+
+# Option B: Add directory to PATH in ~/.bashrc
+echo 'export PATH="/mnt/d/Repos/plan-build-run/tools/pbr-tmux:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+Usage:
+
+- `pbr-tmux` -- Interactive menu (uses gum if available, bash select otherwise)
+- `pbr-tmux launch` -- Launch a Claude Code session in a new pane
+- `pbr-tmux cycle` -- Send `/clear` + `/pbr:resume-work` to the Claude pane
+- `pbr-tmux status` -- Show PBR project status
+- `pbr-tmux list` -- List active tmux sessions
+- `pbr-tmux --help` -- Full list of operations
+
+Non-interactive mode for scripting: `pbr-tmux cycle --non-interactive`
+
+## Step 6: Windows Terminal integration
+
+Add a dedicated "PBR TMUX" profile to Windows Terminal:
+
+1. Open Windows Terminal Settings (`Ctrl+,`) and click "Open JSON file"
+2. Add the contents of `tools/pbr-tmux/windows-terminal-profile.json` to `profiles.list[]`:
+
+```json
+{
+  "name": "PBR TMUX",
+  "commandline": "wsl.exe -d Ubuntu -- bash -lc 'tmux new-session -A -s pbr'",
+  "font": { "face": "JetBrainsMono Nerd Font", "size": 11 },
+  "colorScheme": "One Half Dark",
+  "padding": "4",
+  "scrollbarState": "hidden"
+}
+```
+
+**Notes:**
+
+- Change `Ubuntu` in the commandline to match your WSL2 distro (`wsl -l -v` to check)
+- Install JetBrainsMono Nerd Font from <https://www.nerdfonts.com/> for proper glyph
+  rendering in the status bar and gum menus
+- The `-A` flag in `tmux new-session -A -s pbr` attaches to an existing `pbr` session
+  if one is running, or creates a new one
+
+## Usage
+
+### Starting a session
+
+Click "PBR TMUX" in Windows Terminal, or from any WSL2 shell:
+
+```bash
+tmux new-session -A -s pbr
+```
+
+### Launching Claude Code
+
+```bash
+pbr-tmux launch
+# Or directly:
+cmd.exe /c claude
+```
+
+### Common workflows
+
+**Split-pane monitoring:** Use `Ctrl-b |` to split horizontally, run `pbr-tmux status`
+in the side pane while Claude works in the main pane.
+
+**Multiple sessions:** `pbr-tmux launch` in different windows for parallel Claude
+sessions. Use `pbr-tmux switch` to jump between them.
+
+**Auto-cycle (Phase 80):** `pbr-tmux cycle --non-interactive` sends `/clear` then
+`/pbr:resume-work` to the Claude pane for hands-free workflow continuation.
+
+### Automatic Session Cycling via auto-continue.js
+
+When running in autonomous mode with `features.auto_continue: true`, PBR automatically triggers session cycling based on `session_phase_limit` (default: 3 phases per session).
+
+**How it works:**
+1. `session-tracker.js` tracks completed phases in `.planning/.session-tracker`
+2. Counter resets to 0 at session start (via `progress-tracker.js`)
+3. Counter increments after each executor completion (via `event-handler.js`)
+4. When `auto-continue.js` detects the limit is reached AND `process.env.TMUX` is set:
+   - It spawns a detached process: `sleep 3 && tmux send-keys "/clear" Enter && sleep 1 && tmux send-keys "/pbr:resume-work" Enter`
+   - The current session pauses, then a fresh session starts automatically
+5. Outside TMUX, a banner displays manual instructions instead
+
+**Configure the limit:**
+
+```
+/pbr:settings session_phase_limit 5   # pause after 5 phases
+/pbr:settings session_phase_limit 0   # disable auto-pause
+```
+
+See `references/config-reference.md` for the full `session_phase_limit` specification.
+
+## Troubleshooting
+
+### Windows .exe hangs in tmux
+
+**Symptom:** `cmd.exe /c claude`, `explorer.exe`, or other Windows executables freeze.
+
+**Fix:** Check your terminal setting:
+
+```bash
+tmux show -g default-terminal
+# Must output: tmux-256color
+```
+
+If it shows `screen-256color`, update `~/.tmux.conf` and kill the tmux server:
+
+```bash
+tmux kill-server
+tmux  # Restart with new config
+```
+
+### Path issues
+
+Windows drives mount at `/mnt/{letter}/` in WSL2. If Claude cannot find your project,
+verify you are in the correct `/mnt/` path:
+
+```bash
+pwd               # Should show /mnt/d/Repos/your-project (not /home/user/...)
+ls .planning/     # Should show STATE.md if PBR is set up
+```
+
+### Clipboard
+
+Install `xclip` for full clipboard support (WSLg provides the X server on Windows 11):
+
+```bash
+sudo apt install xclip
+```
+
+Without xclip, tmux falls back to `clip.exe` which works for ASCII but may garble
+Unicode characters.
+
+### Font rendering
+
+Fonts are controlled by Windows Terminal, not tmux. If status bar icons or gum menus
+look broken, install a Nerd Font (JetBrainsMono Nerd Font recommended) and set it in
+the Windows Terminal profile.
+
+### Claude Code clipboard warnings
+
+Cosmetic warnings about clipboard access. Install `xclip` to suppress them. These do
+not affect Claude Code functionality.
+
+### gum not found
+
+`pbr-tmux` works without gum -- it falls back to bash `select` menus automatically.
+Install gum (Step 2) for the polished interactive experience.
+
+### tmux send-keys not working
+
+Verify basic send-keys functionality:
+
+```bash
+tmux send-keys -t 0 "echo hello" Enter
+```
+
+If Claude is mid-processing when you send keys, keystrokes queue in the terminal
+buffer. Add `sleep 0.5` between sequential `send-keys` commands for reliability.
+
+For the critical `cmd.exe /c claude` path, verify:
+
+```bash
+tmux new-session -d -s test "cmd.exe /c claude"
+sleep 3
+tmux send-keys -t test "/help" Enter
+```
+
+### Status bar shows "no-pbr"
+
+The status bar script cannot find `.planning/STATE.md`. Check:
+
+1. `~/.pbr-project-path` points to the correct WSL2 path (use `/mnt/` prefix)
+2. Or `PBR_PROJECT_DIR` environment variable is set
+3. The project has a `.planning/STATE.md` file
+
+## File Reference
+
+| File | Purpose |
+|------|---------|
+| `tools/pbr-tmux/tmux.conf` | TMUX configuration |
+| `tools/pbr-tmux/pbr-tmux` | Main CLI entry point |
+| `tools/pbr-tmux/operations.sh` | Operation implementations (start, launch, cycle, watch, multi) |
+| `tools/pbr-tmux/setup.sh` | One-shot installer for WSL2 |
+| `tools/pbr-tmux/layouts/dev.sh` | Dev layout (Claude + PBR watch + shell) |
+| `tools/pbr-tmux/lib/pbr-state.sh` | Status bar script (phase + context tier) |
+| `tools/pbr-tmux/lib/tmux-helpers.sh` | Shared tmux helper functions |
+| `tools/pbr-tmux/lib/gum-fallback.sh` | UI abstraction (gum/bash fallback) |
+| `tools/pbr-tmux/windows-terminal-profile.json` | Windows Terminal profile fragment |

package/plugins/pbr/references/archive/verification-matrix.md

@@ -0,0 +1,34 @@
+# Verification Matrix
+
+Which verification dimensions and gates run at each depth profile.
+
+## Plan-Checker Dimensions by Depth
+
+| Dimension | Quick | Standard | Comprehensive |
+|-----------|-------|----------|---------------|
+| D1: Requirement Coverage | Yes | Yes | Yes |
+| D2: Task Completeness | Yes | Yes | Yes |
+| D3: Dependency Correctness | Yes | Yes | Yes |
+| D4: Key Links Planned | Yes | Yes | Yes |
+| D5: Scope Sanity | Yes | Yes | Yes |
+| D6: Must-Haves Derivation | Yes | Yes | Yes |
+| D7: Context Compliance | Yes | Yes | Yes |
+| D8: Nyquist Compliance | No | Yes | Yes |
+| D9: Cross-Plan Data Contracts | No | Yes | Yes |
+| **Total dimensions** | **7** | **9** | **9** |
+
+## Verification Gates by Depth
+
+| Gate | Quick | Standard | Comprehensive |
+|------|-------|----------|---------------|
+| Plan-checking (pre-build) | Advisory | Blocking | Blocking |
+| Goal verification (post-build) | Advisory | Blocking | Blocking |
+| Inline verify (per-task) | Off | Off | On |
+| Requirements coverage | Advisory | Blocking | Blocking |
+
+## Behavioral Notes
+
+- **Quick**: Plan-checker runs 7 dimensions. Missing or failed `.plan-check.json` produces a warning, not a block. Goal verification runs but failures are advisory.
+- **Standard**: Full 9-dimension plan-check. `.plan-check.json` must exist and pass before executor spawn. Goal verification failures block phase completion.
+- **Comprehensive**: Same as standard plus inline_verify (planner self-validates before checker).
+- **--audit flag**: Forces full 9-dimension checking regardless of depth profile.

package/plugins/pbr/references/archive/verification-patterns.md

@@ -0,0 +1,277 @@
+# Goal-Backward Verification Patterns
+
+Reference patterns for deriving verification criteria from goals. Used by the planner to create `<verify>` and `<done>` elements, and by the verifier to check phase completion.
+
+---
+
+## The Four-Layer Check
+
+Every must-have is verified through up to four layers, checked in order:
+
+### Layer 1: Existence
+
+Does the artifact exist?
+
+```bash
+# File existence
+ls -la src/auth/discord.ts
+
+# Module export existence
+grep -q "export.*authenticateWithDiscord" src/auth/discord.ts
+
+# Database table existence
+npx prisma db execute --stdin <<< "SELECT 1 FROM users LIMIT 1"
+
+# Route existence
+curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/api/auth/login
+```
+
+### Layer 2: Substantiveness
+
+Is the artifact more than a stub?
+
+```bash
+# File has real content (not just exports)
+wc -l src/auth/discord.ts  # Should be > 10 lines for a real implementation
+
+# Function has a body (not just a signature)
+grep -A5 "authenticateWithDiscord" src/auth/discord.ts | grep -q "return"
+
+# Test file has actual test cases
+grep -c "it(" tests/auth.test.ts  # Should be > 0
+
+# API returns real data (not just 200 OK)
+curl -s http://localhost:3000/api/health | jq '.status' | grep -q "ok"
+```
+
+### Layer 3: Wiring
+
+Are components connected to each other?
+
+```bash
+# Module is imported where needed
+grep -q "from.*auth/discord" src/routes/auth.ts
+
+# Middleware is applied to routes
+grep -q "requireAuth" src/routes/protected.ts
+
+# Database is configured in app init
+grep -q "prisma" src/app.ts
+
+# Environment variables are referenced
+grep -q "DISCORD_CLIENT_ID" src/auth/discord.ts
+```
+
+### Layer 4: Functional
+
+Does the artifact actually work when executed?
+
+```bash
+# Tests pass
+npm test -- --testPathPattern auth
+pytest tests/test_auth.py -v
+
+# Build succeeds
+npm run build
+npx tsc --noEmit
+
+# API returns correct data
+curl -s http://localhost:3000/api/auth/login -X POST -d '{"code":"test"}' | jq '.token'
+
+# CLI produces expected output
+node src/cli.js --help | grep -q "Usage:"
+```
+
+**When to apply L4:** Only when automated verification commands exist (test suites, build scripts, API endpoints with test data). Skip for items requiring manual/visual testing. L4 is optional — artifacts passing L1-L3 without available automated tests are reported as `PASSED (L3 only)`.
+
+---
+
+## Verification by Feature Type
+
+### API Endpoint
+
+```
+Existence:   curl returns non-404 status
+Substance:   curl returns expected response shape (correct fields)
+Wiring:      endpoint calls the right service, middleware is applied
+Functional:  POST/GET with test data returns correct response, error cases handled
+```
+
+### Database Schema
+
+```
+Existence:   table/collection exists, can query without error
+Substance:   columns/fields match specification, constraints are applied
+Wiring:      application code references the schema, migrations run cleanly
+Functional:  CRUD operations work end-to-end, constraints reject invalid data
+```
+
+### Authentication
+
+```
+Existence:   auth routes exist, auth module exports functions
+Substance:   login flow returns token, invalid creds return error
+Wiring:      protected routes use auth middleware, tokens are validated
+Functional:  auth tests pass (valid token, expired token, missing token, malformed token)
+```
+
+### UI Component
+
+```
+Existence:   component file exists, exports default component
+Substance:   component renders expected elements (test or visual check)
+Wiring:      component is imported in parent, receives correct props, routes to it
+Functional:  component tests pass, build succeeds with component included
+```
+
+### Configuration
+
+```
+Existence:   config file exists, environment variables documented
+Substance:   config values are used (not dead code), defaults are sensible
+Wiring:      application reads config at startup, config changes take effect
+Functional:  app starts with config, missing config produces clear error message
+```
+
+---
+
+## Verify Command Patterns
+
+### TypeScript/JavaScript
+
+```bash
+# Type checking
+npx tsc --noEmit
+
+# Unit tests
+npm test
+npm test -- --grep "pattern"
+npx jest path/to/test
+
+# Linting
+npx eslint src/auth/
+
+# Build check
+npm run build
+```
+
+### Python
+
+```bash
+# Type checking
+mypy src/
+
+# Unit tests
+pytest tests/
+pytest tests/test_auth.py -v
+pytest -k "test_login"
+
+# Linting
+flake8 src/
+pylint src/auth/
+```
+
+### General
+
+```bash
+# File existence
+ls -la path/to/file
+
+# Content check
+grep -q "pattern" path/to/file
+
+# HTTP endpoint
+curl -s -o /dev/null -w "%{http_code}" http://localhost:PORT/path
+
+# Process running
+pgrep -f "process-name"
+
+# Port listening
+netstat -an | grep LISTEN | grep PORT
+```
+
+---
+
+## Done Condition Patterns
+
+### Good Done Conditions (Observable, Falsifiable)
+
+- "User can log in with Discord and see their dashboard"
+- "API returns paginated list of items with correct total count"
+- "Database migration creates users table with all required columns"
+- "Protected routes return 401 without valid JWT"
+- "Build completes without TypeScript errors"
+
+### Bad Done Conditions (Vague, Not Falsifiable)
+
+- "Authentication is implemented" (how do you test this?)
+- "Code is clean" (subjective)
+- "Database is set up" (what does "set up" mean?)
+- "Tests pass" (which tests? what do they test?)
+- "File was created" (created with what content?)
+
+### Transformation Rule
+
+```
+Bad:  "Authentication is implemented"
+Good: "User can complete Discord OAuth flow and receive a valid JWT"
+
+Bad:  "Database is set up"
+Good: "Users table exists with id, email, name columns and can accept INSERT"
+
+Bad:  "Tests pass"
+Good: "All 5 auth middleware tests pass: valid token, expired token,
+       missing token, malformed token, and correct user extraction"
+```
+
+---
+
+## Wiring Verification Patterns
+
+4 concrete patterns for verifying components are actually connected, not just present.
+
+### Pattern 1: Component to API
+1. Find the fetch/axios call in the component
+2. Verify the call is NOT commented out
+3. Verify the response is assigned to state (not discarded)
+4. Verify error handling exists (try/catch or .catch)
+
+### Pattern 2: API to Database
+1. Find the database query in the route handler
+2. Verify `await` is present (not fire-and-forget)
+3. Verify the result is returned in the response (not discarded)
+4. Verify error cases return appropriate HTTP status codes
+
+### Pattern 3: Form to Handler
+1. Find the form's onSubmit handler
+2. Verify it calls an API function (not just preventDefault)
+3. Verify form validation runs before the API call
+4. Verify success/error feedback is shown to the user
+
+### Pattern 4: State to Render
+1. Find state variables (useState, store, etc.)
+2. Verify they appear in JSX/template via .map(), interpolation, or conditional rendering
+3. Verify loading/error states are rendered (not just success state)
+4. Verify empty state is handled (not just "no data" crash)
+
+### Quick Verification Checklists
+
+**Component Checklist (8 items):**
+- [ ] Component file exists and exports correctly
+- [ ] Props/types are defined (not `any`)
+- [ ] API calls use actual endpoints (not hardcoded data)
+- [ ] Loading state renders something meaningful
+- [ ] Error state renders something meaningful
+- [ ] Empty state renders something meaningful
+- [ ] User interactions trigger actual handlers
+- [ ] Component is imported and rendered in parent
+
+**API Route Checklist (8 items):**
+- [ ] Route file exists and exports handler
+- [ ] Route is registered in router/app
+- [ ] Request validation exists (body, params, query)
+- [ ] Database query uses parameterized inputs
+- [ ] Success response includes expected data shape
+- [ ] Error response includes status code and message
+- [ ] Authentication/authorization check exists if needed
+- [ ] Response matches what the frontend expects

package/plugins/pbr/references/archive/worktree-sparse-checkout.md

@@ -0,0 +1,86 @@
+# Worktree Sparse Checkout Reference
+
+## Overview
+
+Agents with `isolation: worktree` in their frontmatter run in a temporary git worktree, giving them a clean working tree isolated from the main session. By default, the full repository is checked out in the worktree. For large repos, the `worktree.sparse_paths` config property limits what gets checked out, reducing disk usage and improving worktree creation speed.
+
+## Agents Using `isolation: worktree`
+
+| Agent | Purpose |
+|-------|---------|
+| verifier | Runs verification in an isolated worktree to avoid polluting the main working tree |
+
+## Configuration
+
+Add `worktree.sparse_paths` to `.planning/config.json`:
+
+```json
+{
+  "worktree": {
+    "sparse_paths": ["src/**", "tests/**", "package.json", ".planning/**"]
+  }
+}
+```
+
+- **Empty array** (default): Full checkout. The entire repo is materialized in the worktree.
+- **Non-empty array**: Only files matching the listed glob patterns are materialized. All other paths appear as missing in the worktree's working tree.
+- **Always include `.planning/**`** so agents can read state files (STATE.md, ROADMAP.md, plans, summaries).
+
+## How It Works
+
+When a worktree-isolated agent is spawned, the following sequence occurs:
+
+1. `git worktree add <path> HEAD` -- creates a new worktree linked to the current commit
+2. `cd <path> && git sparse-checkout set --no-cone <patterns>` -- restricts the working tree to matching paths
+3. The agent runs in the sparse worktree with only the specified files visible
+4. On completion, the worktree is cleaned up with `git worktree remove <path>`
+
+> **Note:** This config property is forward-looking. Currently, Claude Code creates full worktrees. The `sparse_paths` property will be consumed when Claude Code adds sparse checkout support to its worktree creation, or by a PBR hook that wraps worktree creation.
+
+## Recommended Patterns
+
+| Pattern | Purpose |
+|---------|---------|
+| `src/**` | Application source code |
+| `tests/**` | Test files |
+| `package.json` | Dependency manifest |
+| `*.config.*` | Config files at root |
+| `.planning/**` | PBR state and plans (always include) |
+
+### Example: Node.js Project
+
+```json
+{
+  "worktree": {
+    "sparse_paths": [
+      "src/**",
+      "tests/**",
+      "package.json",
+      "tsconfig.json",
+      "*.config.*",
+      ".planning/**"
+    ]
+  }
+}
+```
+
+### Example: Monorepo (Single Package)
+
+```json
+{
+  "worktree": {
+    "sparse_paths": [
+      "packages/my-app/**",
+      "package.json",
+      "pnpm-workspace.yaml",
+      ".planning/**"
+    ]
+  }
+}
+```
+
+## Limitations
+
+- **Git history is not reduced.** Sparse checkout only affects the working tree -- the full git history is still present in `.git`. For very large repos with large histories, shallow clones would also help but are not yet supported.
+- **No-cone mode.** The `--no-cone` flag is used for full glob support. Cone mode (directory-based) is faster but less flexible.
+- **Agent must stay within sparse paths.** If an agent tries to read or write a file outside the sparse set, the file will not exist in the worktree. The agent would need to be re-spawned with broader patterns.