@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plan-build-run/references/verification-patterns.md

@@ -0,0 +1,612 @@
+# Verification Patterns
+
+How to verify different types of artifacts are real implementations, not stubs or placeholders.
+
+<core_principle>
+**Existence ≠ Implementation**
+
+A file existing does not mean the feature works. Verification must check:
+1. **Exists** - File is present at expected path
+2. **Substantive** - Content is real implementation, not placeholder
+3. **Wired** - Connected to the rest of the system
+4. **Functional** - Actually works when invoked
+
+Levels 1-3 can be checked programmatically. Level 4 often requires human verification.
+</core_principle>
+
+<stub_detection>
+
+## Universal Stub Patterns
+
+These patterns indicate placeholder code regardless of file type:
+
+**Comment-based stubs:**
+```bash
+# Grep patterns for stub comments
+grep -E "(TODO|FIXME|XXX|HACK|PLACEHOLDER)" "$file"
+grep -E "implement|add later|coming soon|will be" "$file" -i
+grep -E "// \.\.\.|/\* \.\.\. \*/|# \.\.\." "$file"
+```
+
+**Placeholder text in output:**
+```bash
+# UI placeholder patterns
+grep -E "placeholder|lorem ipsum|coming soon|under construction" "$file" -i
+grep -E "sample|example|test data|dummy" "$file" -i
+grep -E "\[.*\]|<.*>|\{.*\}" "$file"  # Template brackets left in
+```
+
+**Empty or trivial implementations:**
+```bash
+# Functions that do nothing
+grep -E "return null|return undefined|return \{\}|return \[\]" "$file"
+grep -E "pass$|\.\.\.|\bnothing\b" "$file"
+grep -E "console\.(log|warn|error).*only" "$file"  # Log-only functions
+```
+
+**Hardcoded values where dynamic expected:**
+```bash
+# Hardcoded IDs, counts, or content
+grep -E "id.*=.*['\"].*['\"]" "$file"  # Hardcoded string IDs
+grep -E "count.*=.*\d+|length.*=.*\d+" "$file"  # Hardcoded counts
+grep -E "\\\$\d+\.\d{2}|\d+ items" "$file"  # Hardcoded display values
+```
+
+</stub_detection>
+
+<react_components>
+
+## React/Next.js Components
+
+**Existence check:**
+```bash
+# File exists and exports component
+[ -f "$component_path" ] && grep -E "export (default |)function|export const.*=.*\(" "$component_path"
+```
+
+**Substantive check:**
+```bash
+# Returns actual JSX, not placeholder
+grep -E "return.*<" "$component_path" | grep -v "return.*null" | grep -v "placeholder" -i
+
+# Has meaningful content (not just wrapper div)
+grep -E "<[A-Z][a-zA-Z]+|className=|onClick=|onChange=" "$component_path"
+
+# Uses props or state (not static)
+grep -E "props\.|useState|useEffect|useContext|\{.*\}" "$component_path"
+```
+
+**Stub patterns specific to React:**
+```javascript
+// RED FLAGS - These are stubs:
+return <div>Component</div>
+return <div>Placeholder</div>
+return <div>{/* TODO */}</div>
+return <p>Coming soon</p>
+return null
+return <></>
+
+// Also stubs - empty handlers:
+onClick={() => {}}
+onChange={() => console.log('clicked')}
+onSubmit={(e) => e.preventDefault()}  // Only prevents default, does nothing
+```
+
+**Wiring check:**
+```bash
+# Component imports what it needs
+grep -E "^import.*from" "$component_path"
+
+# Props are actually used (not just received)
+# Look for destructuring or props.X usage
+grep -E "\{ .* \}.*props|\bprops\.[a-zA-Z]+" "$component_path"
+
+# API calls exist (for data-fetching components)
+grep -E "fetch\(|axios\.|useSWR|useQuery|getServerSideProps|getStaticProps" "$component_path"
+```
+
+**Functional verification (human required):**
+- Does the component render visible content?
+- Do interactive elements respond to clicks?
+- Does data load and display?
+- Do error states show appropriately?
+
+</react_components>
+
+<api_routes>
+
+## API Routes (Next.js App Router / Express / etc.)
+
+**Existence check:**
+```bash
+# Route file exists
+[ -f "$route_path" ]
+
+# Exports HTTP method handlers (Next.js App Router)
+grep -E "export (async )?(function|const) (GET|POST|PUT|PATCH|DELETE)" "$route_path"
+
+# Or Express-style handlers
+grep -E "\.(get|post|put|patch|delete)\(" "$route_path"
+```
+
+**Substantive check:**
+```bash
+# Has actual logic, not just return statement
+wc -l "$route_path"  # More than 10-15 lines suggests real implementation
+
+# Interacts with data source
+grep -E "prisma\.|db\.|mongoose\.|sql|query|find|create|update|delete" "$route_path" -i
+
+# Has error handling
+grep -E "try|catch|throw|error|Error" "$route_path"
+
+# Returns meaningful response
+grep -E "Response\.json|res\.json|res\.send|return.*\{" "$route_path" | grep -v "message.*not implemented" -i
+```
+
+**Stub patterns specific to API routes:**
+```typescript
+// RED FLAGS - These are stubs:
+export async function POST() {
+  return Response.json({ message: "Not implemented" })
+}
+
+export async function GET() {
+  return Response.json([])  // Empty array with no DB query
+}
+
+export async function PUT() {
+  return new Response()  // Empty response
+}
+
+// Console log only:
+export async function POST(req) {
+  console.log(await req.json())
+  return Response.json({ ok: true })
+}
+```
+
+**Wiring check:**
+```bash
+# Imports database/service clients
+grep -E "^import.*prisma|^import.*db|^import.*client" "$route_path"
+
+# Actually uses request body (for POST/PUT)
+grep -E "req\.json\(\)|req\.body|request\.json\(\)" "$route_path"
+
+# Validates input (not just trusting request)
+grep -E "schema\.parse|validate|zod|yup|joi" "$route_path"
+```
+
+**Functional verification (human or automated):**
+- Does GET return real data from database?
+- Does POST actually create a record?
+- Does error response have correct status code?
+- Are auth checks actually enforced?
+
+</api_routes>
+
+<database_schema>
+
+## Database Schema (Prisma / Drizzle / SQL)
+
+**Existence check:**
+```bash
+# Schema file exists
+[ -f "prisma/schema.prisma" ] || [ -f "drizzle/schema.ts" ] || [ -f "src/db/schema.sql" ]
+
+# Model/table is defined
+grep -E "^model $model_name|CREATE TABLE $table_name|export const $table_name" "$schema_path"
+```
+
+**Substantive check:**
+```bash
+# Has expected fields (not just id)
+grep -A 20 "model $model_name" "$schema_path" | grep -E "^\s+\w+\s+\w+"
+
+# Has relationships if expected
+grep -E "@relation|REFERENCES|FOREIGN KEY" "$schema_path"
+
+# Has appropriate field types (not all String)
+grep -A 20 "model $model_name" "$schema_path" | grep -E "Int|DateTime|Boolean|Float|Decimal|Json"
+```
+
+**Stub patterns specific to schemas:**
+```prisma
+// RED FLAGS - These are stubs:
+model User {
+  id String @id
+  // TODO: add fields
+}
+
+model Message {
+  id        String @id
+  content   String  // Only one real field
+}
+
+// Missing critical fields:
+model Order {
+  id     String @id
+  // No: userId, items, total, status, createdAt
+}
+```
+
+**Wiring check:**
+```bash
+# Migrations exist and are applied
+ls prisma/migrations/ 2>/dev/null | wc -l  # Should be > 0
+npx prisma migrate status 2>/dev/null | grep -v "pending"
+
+# Client is generated
+[ -d "node_modules/.prisma/client" ]
+```
+
+**Functional verification:**
+```bash
+# Can query the table (automated)
+npx prisma db execute --stdin <<< "SELECT COUNT(*) FROM $table_name"
+```
+
+</database_schema>
+
+<hooks_utilities>
+
+## Custom Hooks and Utilities
+
+**Existence check:**
+```bash
+# File exists and exports function
+[ -f "$hook_path" ] && grep -E "export (default )?(function|const)" "$hook_path"
+```
+
+**Substantive check:**
+```bash
+# Hook uses React hooks (for custom hooks)
+grep -E "useState|useEffect|useCallback|useMemo|useRef|useContext" "$hook_path"
+
+# Has meaningful return value
+grep -E "return \{|return \[" "$hook_path"
+
+# More than trivial length
+[ $(wc -l < "$hook_path") -gt 10 ]
+```
+
+**Stub patterns specific to hooks:**
+```typescript
+// RED FLAGS - These are stubs:
+export function useAuth() {
+  return { user: null, login: () => {}, logout: () => {} }
+}
+
+export function useCart() {
+  const [items, setItems] = useState([])
+  return { items, addItem: () => console.log('add'), removeItem: () => {} }
+}
+
+// Hardcoded return:
+export function useUser() {
+  return { name: "Test User", email: "test@example.com" }
+}
+```
+
+**Wiring check:**
+```bash
+# Hook is actually imported somewhere
+grep -r "import.*$hook_name" src/ --include="*.tsx" --include="*.ts" | grep -v "$hook_path"
+
+# Hook is actually called
+grep -r "$hook_name()" src/ --include="*.tsx" --include="*.ts" | grep -v "$hook_path"
+```
+
+</hooks_utilities>
+
+<environment_config>
+
+## Environment Variables and Configuration
+
+**Existence check:**
+```bash
+# .env file exists
+[ -f ".env" ] || [ -f ".env.local" ]
+
+# Required variable is defined
+grep -E "^$VAR_NAME=" .env .env.local 2>/dev/null
+```
+
+**Substantive check:**
+```bash
+# Variable has actual value (not placeholder)
+grep -E "^$VAR_NAME=.+" .env .env.local 2>/dev/null | grep -v "your-.*-here|xxx|placeholder|TODO" -i
+
+# Value looks valid for type:
+# - URLs should start with http
+# - Keys should be long enough
+# - Booleans should be true/false
+```
+
+**Stub patterns specific to env:**
+```bash
+# RED FLAGS - These are stubs:
+DATABASE_URL=your-database-url-here
+STRIPE_SECRET_KEY=sk_test_xxx
+API_KEY=placeholder
+NEXT_PUBLIC_API_URL=http://localhost:3000  # Still pointing to localhost in prod
+```
+
+**Wiring check:**
+```bash
+# Variable is actually used in code
+grep -r "process\.env\.$VAR_NAME|env\.$VAR_NAME" src/ --include="*.ts" --include="*.tsx"
+
+# Variable is in validation schema (if using zod/etc for env)
+grep -E "$VAR_NAME" src/env.ts src/env.mjs 2>/dev/null
+```
+
+</environment_config>
+
+<wiring_verification>
+
+## Wiring Verification Patterns
+
+Wiring verification checks that components actually communicate. This is where most stubs hide.
+
+### Pattern: Component → API
+
+**Check:** Does the component actually call the API?
+
+```bash
+# Find the fetch/axios call
+grep -E "fetch\(['\"].*$api_path|axios\.(get|post).*$api_path" "$component_path"
+
+# Verify it's not commented out
+grep -E "fetch\(|axios\." "$component_path" | grep -v "^.*//.*fetch"
+
+# Check the response is used
+grep -E "await.*fetch|\.then\(|setData|setState" "$component_path"
+```
+
+**Red flags:**
+```typescript
+// Fetch exists but response ignored:
+fetch('/api/messages')  // No await, no .then, no assignment
+
+// Fetch in comment:
+// fetch('/api/messages').then(r => r.json()).then(setMessages)
+
+// Fetch to wrong endpoint:
+fetch('/api/message')  // Typo - should be /api/messages
+```
+
+### Pattern: API → Database
+
+**Check:** Does the API route actually query the database?
+
+```bash
+# Find the database call
+grep -E "prisma\.$model|db\.query|Model\.find" "$route_path"
+
+# Verify it's awaited
+grep -E "await.*prisma|await.*db\." "$route_path"
+
+# Check result is returned
+grep -E "return.*json.*data|res\.json.*result" "$route_path"
+```
+
+**Red flags:**
+```typescript
+// Query exists but result not returned:
+await prisma.message.findMany()
+return Response.json({ ok: true })  // Returns static, not query result
+
+// Query not awaited:
+const messages = prisma.message.findMany()  // Missing await
+return Response.json(messages)  // Returns Promise, not data
+```
+
+### Pattern: Form → Handler
+
+**Check:** Does the form submission actually do something?
+
+```bash
+# Find onSubmit handler
+grep -E "onSubmit=\{|handleSubmit" "$component_path"
+
+# Check handler has content
+grep -A 10 "onSubmit.*=" "$component_path" | grep -E "fetch|axios|mutate|dispatch"
+
+# Verify not just preventDefault
+grep -A 5 "onSubmit" "$component_path" | grep -v "only.*preventDefault" -i
+```
+
+**Red flags:**
+```typescript
+// Handler only prevents default:
+onSubmit={(e) => e.preventDefault()}
+
+// Handler only logs:
+const handleSubmit = (data) => {
+  console.log(data)
+}
+
+// Handler is empty:
+onSubmit={() => {}}
+```
+
+### Pattern: State → Render
+
+**Check:** Does the component render state, not hardcoded content?
+
+```bash
+# Find state usage in JSX
+grep -E "\{.*messages.*\}|\{.*data.*\}|\{.*items.*\}" "$component_path"
+
+# Check map/render of state
+grep -E "\.map\(|\.filter\(|\.reduce\(" "$component_path"
+
+# Verify dynamic content
+grep -E "\{[a-zA-Z_]+\." "$component_path"  # Variable interpolation
+```
+
+**Red flags:**
+```tsx
+// Hardcoded instead of state:
+return <div>
+  <p>Message 1</p>
+  <p>Message 2</p>
+</div>
+
+// State exists but not rendered:
+const [messages, setMessages] = useState([])
+return <div>No messages</div>  // Always shows "no messages"
+
+// Wrong state rendered:
+const [messages, setMessages] = useState([])
+return <div>{otherData.map(...)}</div>  // Uses different data
+```
+
+</wiring_verification>
+
+<verification_checklist>
+
+## Quick Verification Checklist
+
+For each artifact type, run through this checklist:
+
+### Component Checklist
+- [ ] File exists at expected path
+- [ ] Exports a function/const component
+- [ ] Returns JSX (not null/empty)
+- [ ] No placeholder text in render
+- [ ] Uses props or state (not static)
+- [ ] Event handlers have real implementations
+- [ ] Imports resolve correctly
+- [ ] Used somewhere in the app
+
+### API Route Checklist
+- [ ] File exists at expected path
+- [ ] Exports HTTP method handlers
+- [ ] Handlers have more than 5 lines
+- [ ] Queries database or service
+- [ ] Returns meaningful response (not empty/placeholder)
+- [ ] Has error handling
+- [ ] Validates input
+- [ ] Called from frontend
+
+### Schema Checklist
+- [ ] Model/table defined
+- [ ] Has all expected fields
+- [ ] Fields have appropriate types
+- [ ] Relationships defined if needed
+- [ ] Migrations exist and applied
+- [ ] Client generated
+
+### Hook/Utility Checklist
+- [ ] File exists at expected path
+- [ ] Exports function
+- [ ] Has meaningful implementation (not empty returns)
+- [ ] Used somewhere in the app
+- [ ] Return values consumed
+
+### Wiring Checklist
+- [ ] Component → API: fetch/axios call exists and uses response
+- [ ] API → Database: query exists and result returned
+- [ ] Form → Handler: onSubmit calls API/mutation
+- [ ] State → Render: state variables appear in JSX
+
+</verification_checklist>
+
+<automated_verification_script>
+
+## Automated Verification Approach
+
+For the verification subagent, use this pattern:
+
+```bash
+# 1. Check existence
+check_exists() {
+  [ -f "$1" ] && echo "EXISTS: $1" || echo "MISSING: $1"
+}
+
+# 2. Check for stub patterns
+check_stubs() {
+  local file="$1"
+  local stubs=$(grep -c -E "TODO|FIXME|placeholder|not implemented" "$file" 2>/dev/null || echo 0)
+  [ "$stubs" -gt 0 ] && echo "STUB_PATTERNS: $stubs in $file"
+}
+
+# 3. Check wiring (component calls API)
+check_wiring() {
+  local component="$1"
+  local api_path="$2"
+  grep -q "$api_path" "$component" && echo "WIRED: $component → $api_path" || echo "NOT_WIRED: $component → $api_path"
+}
+
+# 4. Check substantive (more than N lines, has expected patterns)
+check_substantive() {
+  local file="$1"
+  local min_lines="$2"
+  local pattern="$3"
+  local lines=$(wc -l < "$file" 2>/dev/null || echo 0)
+  local has_pattern=$(grep -c -E "$pattern" "$file" 2>/dev/null || echo 0)
+  [ "$lines" -ge "$min_lines" ] && [ "$has_pattern" -gt 0 ] && echo "SUBSTANTIVE: $file" || echo "THIN: $file ($lines lines, $has_pattern matches)"
+}
+```
+
+Run these checks against each must-have artifact. Aggregate results into VERIFICATION.md.
+
+</automated_verification_script>
+
+<human_verification_triggers>
+
+## When to Require Human Verification
+
+Some things can't be verified programmatically. Flag these for human testing:
+
+**Always human:**
+- Visual appearance (does it look right?)
+- User flow completion (can you actually do the thing?)
+- Real-time behavior (WebSocket, SSE)
+- External service integration (Stripe, email sending)
+- Error message clarity (is the message helpful?)
+- Performance feel (does it feel fast?)
+
+**Human if uncertain:**
+- Complex wiring that grep can't trace
+- Dynamic behavior depending on state
+- Edge cases and error states
+- Mobile responsiveness
+- Accessibility
+
+**Format for human verification request:**
+```markdown
+## Human Verification Required
+
+### 1. Chat message sending
+**Test:** Type a message and click Send
+**Expected:** Message appears in list, input clears
+**Check:** Does message persist after refresh?
+
+### 2. Error handling
+**Test:** Disconnect network, try to send
+**Expected:** Error message appears, message not lost
+**Check:** Can retry after reconnect?
+```
+
+</human_verification_triggers>
+
+<checkpoint_automation_reference>
+
+## Pre-Checkpoint Automation
+
+For automation-first checkpoint patterns, server lifecycle management, CLI installation handling, and error recovery protocols, see:
+
+**@~/.claude/plan-build-run/references/checkpoints.md** → `<automation_reference>` section
+
+Key principles:
+- Claude sets up verification environment BEFORE presenting checkpoints
+- Users never run CLI commands (visit URLs only)
+- Server lifecycle: start before checkpoint, handle port conflicts, keep running for duration
+- CLI installation: auto-install where safe, checkpoint for user choice otherwise
+- Error handling: fix broken environment before checkpoint, never present checkpoint with failed setup
+
+</checkpoint_automation_reference>

package/plan-build-run/references/wave-execution.md

@@ -0,0 +1,52 @@
+# Wave Execution Model
+
+Plans within a phase are grouped into **waves** for execution ordering. Plans in the same wave are independent and can run in parallel; plans in later waves depend on earlier ones.
+
+## Wave Assignment Rules
+
+| Rule | Description |
+|------|-------------|
+| Wave 1 | Plans with `depends_on: []` — no prerequisites |
+| Wave N+1 | Plans that depend on any Wave N plan |
+| No self-wave deps | A plan cannot depend on another plan in the same wave |
+| No circular deps | Dependency graph must be a DAG |
+
+## Parallelization
+
+The build skill spawns multiple executor `Task()` calls for same-wave plans when `config.parallelization` allows it. Default: sequential (one executor at a time). When parallel:
+
+- Each executor operates on its own files (enforced by `files_modified` non-overlap within a wave)
+- Git commits are serialized — only one executor commits at a time via lock file
+- If a lock conflict occurs, retry up to 3 times with 2s delay
+
+## Git Lock Handling
+
+Parallel executors share one git index. The build skill uses a lock file (`.planning/.git-commit-lock`) to serialize commit operations:
+
+1. Executor completes task, stages files
+2. Acquires lock (atomic `fs.writeFileSync` with `wx` flag)
+3. Commits
+4. Releases lock (deletes file)
+
+If lock acquisition fails, wait 2s and retry (max 3 attempts).
+
+## Checkpoint Manifests
+
+Between waves, the build skill writes a checkpoint manifest via:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/pbr-tools.cjs checkpoint init {phase-slug} --plans "{plan-ids}"
+```
+
+The manifest tracks: which plans completed, their commit SHAs, provides/consumes resolution, and session affinity. The next wave reads this to verify prerequisites are met.
+
+## Failure Handling
+
+| Scenario | Action |
+|----------|--------|
+| One plan in wave fails | Other same-wave plans continue; dependent waves are blocked |
+| All plans in wave fail | Phase marked `partial`; build skill reports to user |
+| Checkpoint task blocks | Wave pauses; user action required before continuing |
+| Executor hits context limit | Progress file written; `continue` skill resumes from last task |
+
+Partial wave completion is recorded in STATE.md. The build skill can re-run failed plans without re-executing successful ones.