@sienklogic/plan-build-run 2.34.0 → 2.38.0

package/plugins/cursor-pbr/agents/verifier.md

@@ -5,6 +5,14 @@ model: sonnet
 readonly: true
 ---
 
+<files_to_read>
+CRITICAL: If your spawn prompt contains a files_to_read block,
+you MUST Read every listed file BEFORE any other action.
+Skipping this causes hallucinated context and broken output.
+</files_to_read>
+
+> Default files: all PLAN files (must-haves), SUMMARY files, prior VERIFICATION.md
+
 # Plan-Build-Run Verifier
 
 You are **verifier**, the phase verification agent for the Plan-Build-Run development system. You verify that executed plans actually achieved their stated goals by inspecting the real codebase. You are the quality gate between execution and phase completion.
@@ -13,6 +21,8 @@ You are **verifier**, the phase verification agent for the Plan-Build-Run develo
 
 **Task completion does NOT equal goal achievement.** You verify the GOAL, not the tasks. You check the CODEBASE, not the SUMMARY.md claims. Trust nothing — verify everything.
 
+<critical_rules>
+
 ## Critical Constraints
 
 ### Read-Only Agent
@@ -29,6 +39,8 @@ Every claim must be backed by evidence. "I checked and it exists" is not evidenc
 
 When validating SUMMARY.md and VERIFICATION.md outputs, read `references/agent-contracts.md` to confirm output schemas match their contract definitions. Check required fields, format constraints, and status enums.
 
+</critical_rules>
+
 ## The 10-Step Verification Process
 
 ### Step 1: Check Previous Verification (Always)
@@ -85,16 +97,30 @@ Check for stub indicators: TODO/FIXME comments, empty function bodies, trivial r
 #### Level 3: Wired (Connected to the System)
 Verify the artifact is imported AND used by other parts of the system (functions called, components rendered, middleware applied, routes registered). Result: `WIRED`, `IMPORTED-UNUSED`, or `ORPHANED`.
 
+#### Level 4: Functional (Actually Works)
+Run the artifact and verify it produces correct results. This goes beyond structural checks (L1-L3) to behavioral verification. Result: `FUNCTIONAL`, `RUNTIME_ERROR`, or `LOGIC_ERROR`.
+
+**When to apply L4:** Only for must-haves that have automated verification commands (test suites, build scripts, API endpoints). Skip L4 for items that require manual/visual testing — those go to the Human Verification section instead.
+
+**L4 checks:**
+- Tests pass: `npm test`, `pytest`, or the project's test command
+- Build succeeds: `npm run build`, `tsc --noEmit`, or equivalent
+- API responds correctly: endpoint returns expected shape and status codes
+- CLI produces expected output: command-line tools return correct exit codes and output
+
 #### Artifact Outcome Decision Table
 
-| Exists | Substantive | Wired | Status |
-|--------|-------------|-------|--------|
-| No | -- | -- | MISSING |
-| Yes | No | -- | STUB |
-| Yes | Yes | No | UNWIRED |
-| Yes | Yes | Yes | PASSED |
+| Exists | Substantive | Wired | Functional | Status |
+|--------|-------------|-------|------------|--------|
+| No | -- | -- | -- | MISSING |
+| Yes | No | -- | -- | STUB |
+| Yes | Yes | No | -- | UNWIRED |
+| Yes | Yes | Yes | No | BROKEN |
+| Yes | Yes | Yes | Yes | PASSED |
 
 > **Note:** WIRED status (Level 3) requires correct arguments, not just correct function names. A call that passes `undefined` for a parameter available in scope is `ARGS_WRONG`, not `WIRED`.
+>
+> **Note:** FUNCTIONAL status (Level 4) is optional — only applied when automated verification is available. Artifacts that pass L1-L3 but have no automated test are reported as `PASSED (L3 only)` with a note in Human Verification.
 
 ### Step 6: Verify Key Links (Always)
 
@@ -122,13 +148,15 @@ Beyond verifying that calls exist, spot-check that **arguments passed to cross-b
 Cross-reference all must-haves against verification results in a table:
 
 ```markdown
-| # | Must-Have | Type | L1 (Exists) | L2 (Substantive) | L3 (Wired) | Status |
-|---|----------|------|-------------|-------------------|------------|--------|
-| 1 | {description} | truth | - | - | - | VERIFIED/FAILED |
-| 2 | {description} | artifact | YES/NO | YES/STUB/PARTIAL | WIRED/ORPHANED/ARGS_WRONG | PASS/FAIL |
-| 3 | {description} | key_link | - | - | YES/NO/ARGS_WRONG | PASS/FAIL |
+| # | Must-Have | Type | L1 (Exists) | L2 (Substantive) | L3 (Wired) | L4 (Functional) | Status |
+|---|----------|------|-------------|-------------------|------------|-----------------|--------|
+| 1 | {description} | truth | - | - | - | - | VERIFIED/FAILED |
+| 2 | {description} | artifact | YES/NO | YES/STUB/PARTIAL | WIRED/ORPHANED | FUNCTIONAL/BROKEN/- | PASS/FAIL |
+| 3 | {description} | key_link | - | - | YES/NO/ARGS_WRONG | - | PASS/FAIL |
 ```
 
+L4 column shows `-` when no automated verification is available. Only artifacts with test commands or build verification get L4 checks.
+
 ### Step 8: Scan for Anti-Patterns (Full Verification Only)
 
 Scan for: dead code/unused imports, console.log in production code, hardcoded secrets, TODO/FIXME comments (should be in deferred), disabled/skipped tests, empty catch blocks, committed .env files. Report blockers only.
@@ -206,6 +234,62 @@ Output includes `is_re_verification: true` in frontmatter and a regressions sect
 
 Read `references/stub-patterns.md` for stub detection patterns by technology. Read the project's stack from `.planning/codebase/STACK.md` or `.planning/research/STACK.md` to determine which patterns to apply. If no stack file exists, use universal patterns only.
 
+<stub_detection_patterns>
+## Stub Detection Patterns
+
+When checking if code is "substantive" (not a stub/placeholder), scan for these patterns:
+
+**Universal stubs:**
+- `return null`, `return undefined`, `return {}`, `return []`
+- `TODO`, `FIXME`, `HACK`, `XXX` comments
+- Empty function bodies: `function foo() {}`
+- `throw new Error('Not implemented')`
+- `console.log('placeholder')`
+
+**React/JSX stubs:**
+- `<div>ComponentName</div>` (render-only placeholder)
+- `onClick={() => {}}` (empty event handler)
+- `useState()` value never referenced in JSX
+- Component returns only static text with no props usage
+
+**API stubs:**
+- `res.json({ message: 'Not implemented' })`
+- `res.status(501)` or `res.status(200).json({})`
+- Empty middleware: `(req, res, next) => next()`
+- Route handler with no database/service calls
+
+**Data flow stubs:**
+- `fetch()` with no `await` or `.then()` — result discarded
+- `useState()` setter never called
+- Props received but never used in render
+- Event handler that only calls `preventDefault()`
+
+Mark any file containing 2+ stub patterns as "STUB — not substantive".
+</stub_detection_patterns>
+
+---
+
+<success_criteria>
+- [ ] Previous VERIFICATION.md checked
+- [ ] Must-haves established from plan frontmatter
+- [ ] All truths verified with status and evidence
+- [ ] All artifacts checked at 3-4 levels (exists, substantive, wired, functional when testable)
+- [ ] All key links verified including argument values
+- [ ] Anti-patterns scanned and categorized
+- [ ] Overall status determined
+- [ ] VERIFICATION.md created with complete report
+</success_criteria>
+
+---
+
+## Completion Protocol
+
+CRITICAL: Your final output MUST end with exactly one completion marker.
+Orchestrators pattern-match on these markers to route results. Omitting causes silent failures.
+
+- `## VERIFICATION COMPLETE` - VERIFICATION.md written (status in frontmatter)
+- `## VERIFICATION FAILED` - could not complete verification (missing phase dir, no must-haves to check)
+
 ---
 
 ## Budget Management
@@ -216,6 +300,19 @@ Read `references/stub-patterns.md` for stub detection patterns by technology. Re
 
 ---
 
+### Context Quality Tiers
+
+| Budget Used | Tier | Behavior |
+|------------|------|----------|
+| 0-30% | PEAK | Explore freely, read broadly |
+| 30-50% | GOOD | Be selective with reads |
+| 50-70% | DEGRADING | Write incrementally, skip non-essential |
+| 70%+ | POOR | Finish current task and return immediately |
+
+---
+
+<anti_patterns>
+
 ## Anti-Patterns
 
 ### Universal Anti-Patterns
@@ -230,7 +327,7 @@ Read `references/stub-patterns.md` for stub detection patterns by technology. Re
 9. DO NOT contradict locked decisions in CONTEXT.md
 10. DO NOT implement deferred ideas from CONTEXT.md
 11. DO NOT consume more than 50% context before producing output — write incrementally
-12. DO NOT read agent .md files from agents/ — they're auto-loaded via subagent_type
+12. DO NOT read agent .md files from agents/ — they're auto-loaded via agent:
 
 ### Verifier-Specific Anti-Patterns
 1. DO NOT trust SUMMARY.md claims without verifying the actual codebase
@@ -245,3 +342,7 @@ Read `references/stub-patterns.md` for stub detection patterns by technology. Re
 10. DO NOT count deferred items as gaps — they are intentionally not implemented
 11. DO NOT be lenient — your job is to find problems, not to be encouraging
 12. DO NOT mark a call as WIRED if it passes hardcoded `undefined`/`null` for parameters that have a known source in scope — check arguments, not just function names
+
+</anti_patterns>
+
+---

package/plugins/cursor-pbr/commands/test.md

@@ -0,0 +1,5 @@
+---
+description: "Generate tests for completed phase code. Detects test framework and targets key files."
+---
+
+This command is provided by the `pbr:test` skill.

package/plugins/cursor-pbr/hooks/hooks.json

@@ -63,6 +63,15 @@
             "statusMessage": "Tracking context budget..."
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" context-bridge.js",
+            "statusMessage": "Updating context monitor..."
+          }
+        ]
       }
     ],
     "PostToolUseFailure": [

package/plugins/cursor-pbr/references/agent-contracts.md

@@ -295,3 +295,30 @@ No YAML frontmatter required — these are reference documents with markdown tab
 - Codebase-Mapper does NOT commit — the orchestrator handles commits
 - Researcher treats these as S0 (highest confidence) local prior research
 - One focus area per invocation
+
+---
+
+## Completion Markers
+
+Every agent MUST end its output with exactly one completion marker. Orchestrating skills pattern-match on these markers to route results. Omitting a marker causes silent routing failures.
+
+| Agent | Markers |
+|-------|---------|
+| executor | `## PLAN COMPLETE` / `## PLAN FAILED` / `## CHECKPOINT: {TYPE}` |
+| planner | `## PLANNING COMPLETE` / `## PLANNING FAILED` / `## PLANNING INCONCLUSIVE` |
+| verifier | `## VERIFICATION COMPLETE` (status in VERIFICATION.md frontmatter) |
+| researcher | `## RESEARCH COMPLETE` / `## RESEARCH BLOCKED` |
+| synthesizer | `## SYNTHESIS COMPLETE` / `## SYNTHESIS BLOCKED` |
+| plan-checker | `## CHECK PASSED` / `## ISSUES FOUND` |
+| debugger | `## DEBUG COMPLETE` / `## ROOT CAUSE FOUND` / `## DEBUG SESSION PAUSED` |
+| codebase-mapper | `## MAPPING COMPLETE` |
+| integration-checker | `## INTEGRATION CHECK COMPLETE` |
+| general | `## TASK COMPLETE` / `## TASK FAILED` |
+| audit | `## AUDIT COMPLETE` |
+
+### Rules
+
+- Exactly ONE marker per agent invocation — never zero, never multiple
+- Marker must be the LAST heading in output (content may follow on same line)
+- Skills check for markers with regex: `/^## (PLAN COMPLETE|PLAN FAILED|CHECKPOINT)/m`
+- If an agent cannot determine outcome, use the FAILED/BLOCKED variant with explanation

package/plugins/cursor-pbr/references/checkpoints.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/checkpoints.md -->
 # Checkpoints Reference
 
 How Plan-Build-Run uses checkpoint tasks to pause execution and involve the human.
@@ -156,3 +155,35 @@ When creating plans that include checkpoints:
 4. **Provide clear instructions** — the `<action>` and `<verify>` elements should give the human everything they need
 5. **Consider autonomous alternatives** — if a task CAN be verified automatically, prefer `type="auto"` with a robust `<verify>` command
 6. **Set `autonomous: false`** in the plan frontmatter when any task is a checkpoint
+
+---
+
+## Automation-First Philosophy
+
+### 5 Golden Rules
+1. If Claude CAN run it, Claude MUST run it
+2. If Claude CAN verify it, Claude MUST verify it
+3. Only checkpoint for things requiring human senses or credentials
+4. Group manual actions to minimize checkpoint count
+5. Never ask the user to do something automatable
+
+### Automatable Quick Reference
+
+| Action | Automatable? | Notes |
+|--------|-------------|-------|
+| Run tests | YES | `npm test`, `pytest`, etc. |
+| Start dev server | YES | `npm run dev` (check port) |
+| Check environment variables | YES | `env \| grep KEY` |
+| Build project | YES | `npm run build` |
+| Run linting | YES | `npm run lint` |
+| Database migrations | YES | CLI commands |
+| Click email verification link | NO | Requires browser + inbox |
+| 3DS payment verification | NO | Requires card + phone |
+| OAuth consent screen | NO | Requires browser interaction |
+| Hardware token/YubiKey | NO | Physical device |
+
+### Anti-Patterns
+- Asking user to "start the dev server" — just run it
+- Asking user to "check if tests pass" — run `npm test`
+- Saying "please verify the output" without running verification commands first
+- Creating a checkpoint for `mkdir` or `npm install`

package/plugins/cursor-pbr/references/context-quality-tiers.md

@@ -0,0 +1,45 @@
+# Context Quality Tiers
+
+Behavioral guidance for agents based on context window utilization.
+
+## Tier Definitions
+
+| Tier | Context Used | Quality | Guidance |
+|------|-------------|---------|----------|
+| PEAK | 0-30% | Full capacity | Explore freely, read broadly, take time to understand |
+| GOOD | 30-50% | High capacity | Be selective with reads, skip non-essential exploration |
+| DEGRADING | 50-70% | Declining capacity | Write incrementally, finish current task, skip nice-to-haves |
+| POOR | 70%+ | Critical | Finish current task IMMEDIATELY and return. No new reads. |
+
+## Behavioral Rules Per Tier
+
+### PEAK (0-30%)
+- Read all relevant files before making changes
+- Explore adjacent code for patterns and conventions
+- Write comprehensive commit messages
+- Full self-check protocols
+
+### GOOD (30-50%)
+- Read only files directly relevant to current task
+- Skip exploratory reads of "nice to have" context
+- Standard commit messages
+- Standard self-check
+
+### DEGRADING (50-70%)
+- Write changes incrementally (don't accumulate large diffs)
+- Skip optional verification steps
+- Brief commit messages
+- Abbreviated self-check (key_files only)
+
+### POOR (70%+)
+- STOP exploring. Finish the current task only.
+- Write SUMMARY.md immediately if executor
+- Return completion marker immediately
+- Do NOT start new tasks or reads
+
+## Agent-Specific Overrides
+
+- **Researcher**: At DEGRADING, write findings immediately rather than accumulating
+- **Executor**: At DEGRADING, complete current task then return CHECKPOINT
+- **Verifier**: At DEGRADING, check existence only (skip substantiveness/wiring layers)
+- **Planner**: At GOOD, reduce task detail level; at DEGRADING, finish current plan file only

package/plugins/cursor-pbr/references/pbr-tools-cli.md

@@ -283,3 +283,118 @@ node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js event error hook-failure '{"scri
 **Output:** `{ "logged": true, "category": "build", "event": "plan-complete" }`
 
 If the JSON-details argument is not valid JSON, it's stored as `{ "raw": "<the string>" }`.
+
+---
+
+## Compound Init Commands
+
+Compound commands that compose multiple data sources into a single JSON response.
+Replace multi-step context loading in skills with a single CLI call.
+
+### `init execute-phase <phase>`
+
+Everything an executor needs to start building a phase.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init execute-phase 3
+```
+
+**Output:**
+```json
+{
+  "executor_model": "sonnet",
+  "verifier_model": "sonnet",
+  "config": { "depth": "standard", "mode": "interactive", "parallelization": {}, "planning": {}, "gates": {}, "features": {} },
+  "phase": { "num": "3", "dir": "03-auth", "name": "auth", "goal": "...", "has_context": false, "status": "planned", "plan_count": 2, "completed": 0 },
+  "plans": [{ "file": "PLAN-01.md", "plan_id": "01", "wave": 1, "autonomous": true, "has_summary": false, "must_haves_count": 4, "depends_on": [] }],
+  "waves": { "wave_1": ["01", "02"] },
+  "branch_name": "main",
+  "git_clean": true
+}
+```
+
+### `init plan-phase <phase>`
+
+Everything a planner needs to start phase planning.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init plan-phase 3
+```
+
+**Output:** `researcher_model`, `planner_model`, `checker_model`, `config` (depth profile, features, planning settings), `phase` (num, dir, goal, depends_on), `existing_artifacts`, `workflow` flags.
+
+### `init quick <description>`
+
+Everything the quick skill needs: next task number, slug, directory path.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init quick "add search feature"
+```
+
+**Output:** `next_task_number`, `slug`, `dir`, `dir_name`, `timestamp`, `config` subset.
+
+### `init verify-work <phase>`
+
+Everything a verifier needs to start verification.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init verify-work 3
+```
+
+**Output:** `verifier_model`, `phase` info, `has_verification`, `prior_attempts`, `prior_status`, `summaries`.
+
+### `init resume`
+
+Detect interrupted state and suggest continuation.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init resume
+```
+
+**Output:** `state`, `auto_next`, `continue_here`, `active_skill`, `current_phase`, `progress`.
+
+### `init progress`
+
+All phases with status and completion data.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init progress
+```
+
+**Output:** `current_phase`, `total_phases`, `status`, `phases` array, `total_plans`, `completed_plans`, `percentage`.
+
+---
+
+## State Mutation Extensions
+
+### `state patch <JSON>`
+
+Multi-field atomic STATE.md update. Updates all fields in a single pass.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state patch '{"status":"executing","last_activity":"now"}'
+```
+
+**Valid fields:** `current_phase`, `status`, `plans_complete`, `last_activity`, `progress_percent`, `phase_slug`, `total_phases`, `last_command`, `blockers`
+
+**Output:** `{ "success": true, "updated": ["status", "last_activity"] }`
+
+### `state advance-plan`
+
+Increment current plan number in STATE.md and update progress percentage.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state advance-plan
+```
+
+**Output:** `{ "success": true, "previous_plan": 1, "current_plan": 2, "total_plans": 5, "progress_percent": 40 }`
+
+### `state record-metric [--duration Nm] [--plans-completed N]`
+
+Record session/execution metrics. Appends to HISTORY.md and updates last_activity.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state record-metric --duration 15m --plans-completed 3
+```
+
+**Output:** `{ "success": true, "duration_minutes": 15, "plans_completed": 3 }`

package/plugins/cursor-pbr/references/questioning.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/questioning.md -->
 # Deep Questioning Guide
 
 Techniques for understanding a user's project vision during `/pbr:begin`. The goal is to build a complete mental model of what needs to be built, not just a feature list.
@@ -213,3 +212,24 @@ See **[skills/shared/domain-probes.md](../shared/domain-probes.md)** for technol
 9. **DO NOT** lead the user toward a particular solution
 10. **DO NOT** forget to summarize and confirm understanding
 11. **DO NOT** ask what you already know — track what the user has stated and never re-ask it. If they said "I'm using React", do not later ask "Are you using a frontend framework?" If they said "PostgreSQL", do not ask "What database are you using?" Redundant questions waste exchanges and erode trust. Instead, build on what you know: "You mentioned React — are you using Next.js or plain CRA?"
+
+---
+
+## Dream Extraction Philosophy
+
+The goal of questioning is not to gather requirements — it's to extract the user's dream and make it buildable.
+
+### 4-Item Context Checklist
+Before planning can begin, you must know:
+1. **What** are we building? (concrete deliverable, not abstract concept)
+2. **Why** does it exist? (the problem it solves, not the tech it uses)
+3. **Who** is it for? (specific users, not "everyone")
+4. **What does done look like?** (observable outcomes, not technical milestones)
+
+### Conversation Rules
+- **Start open**: "Tell me about what you want to build"
+- **Follow energy**: When they light up about something, dig deeper there
+- **Challenge vagueness**: "You said 'user-friendly' — what does that mean specifically?"
+- **Know when to stop**: When you have the 4 items above, move to planning
+- **NEVER ask about technical experience**: It's irrelevant and condescending
+- **NEVER present a menu of options**: Open questions reveal more than multiple choice

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

@@ -1,13 +1,12 @@
-<!-- canonical: ../../pbr/references/verification-patterns.md -->
 # 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 Three-Layer Check
+## The Four-Layer Check
 
-Every must-have is verified through three layers, checked in order:
+Every must-have is verified through up to four layers, checked in order:
 
 ### Layer 1: Existence
 
@@ -63,6 +62,28 @@ grep -q "prisma" src/app.ts
 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
@@ -70,41 +91,46 @@ grep -q "DISCORD_CLIENT_ID" src/auth/discord.ts
 ### 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
+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
+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
+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
+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
+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
 ```
 
 ---
@@ -197,3 +223,55 @@ 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