@sienklogic/plan-build-run 2.21.0 → 2.21.2

package/plugins/pbr/references/few-shot-examples/check-plan-format.md

@@ -0,0 +1,172 @@
+---
+component: check-plan-format
+version: 1
+last_calibrated: 2026-03-24
+---
+
+# check-plan-format Few-Shot Examples
+
+These examples document structural patterns for reference and calibration. The hook uses JavaScript validation, not LLM judgment.
+
+## Positive Examples
+
+### Example 1: Well-formed PLAN.md with all required frontmatter and task elements
+
+**Input:** Write to `.planning/phases/42-auth-refactor/PLAN-01.md`
+
+**Content:**
+
+```yaml
+---
+phase: "42-auth-refactor"
+plan: "42-01"
+type: "feature"
+wave: 1
+depends_on: []
+files_modified:
+  - "src/auth/middleware.js"
+  - "src/auth/session.js"
+autonomous: true
+must_haves:
+  truths:
+    - "Session tokens are encrypted at rest"
+  artifacts:
+    - "src/auth/middleware.js: >50 lines"
+  key_links:
+    - "middleware.js imported by server.js"
+implements:
+  - "REQ-AUTH-01"
+---
+```
+
+```xml
+<task id="42-01-T1" type="auto" tdd="false" complexity="simple">
+<name>Implement encrypted session storage</name>
+<read_first>
+src/auth/session.js
+</read_first>
+<files>
+src/auth/middleware.js
+src/auth/session.js
+</files>
+<action>
+1. Add AES-256-GCM encryption to session.save()
+2. Add decryption to session.load()
+</action>
+<acceptance_criteria>
+grep -n "createCipheriv" src/auth/session.js
+</acceptance_criteria>
+<verify>
+node -e "require('./src/auth/session').save({test:1}); console.log('OK')"
+</verify>
+<done>Session tokens encrypted at rest using AES-256-GCM.</done>
+</task>
+```
+
+**Hook result:** No errors, no warnings. All 7 required frontmatter fields present (`phase`, `plan`, `wave`, `type`, `depends_on`, `files_modified`, `autonomous`). `must_haves` has all 3 sub-fields (`truths`, `artifacts`, `key_links`). `implements` present. Task has all 7 required elements (`name`, `read_first`, `files`, `action`, `acceptance_criteria`, `verify`, `done`).
+
+### Example 2: Well-formed SUMMARY.md with required fields and Self-Check section
+
+**Input:** Write to `.planning/phases/42-auth-refactor/SUMMARY-01.md`
+
+**Content:**
+
+```yaml
+---
+phase: "42-auth-refactor"
+plan: "42-01"
+status: "complete"
+provides:
+  - "Encrypted session storage"
+requires: []
+key_files:
+  - "src/auth/middleware.js: AES-256-GCM encryption middleware"
+  - "src/auth/session.js: session save/load with encryption"
+deferred:
+  - "Session key rotation (out of scope for this plan)"
+duration: 12
+requirements-completed:
+  - "REQ-AUTH-01"
+---
+```
+
+```markdown
+## Self-Check: PASSED
+
+- [x] middleware.js encrypts session data (verified: grep shows createCipheriv)
+- [x] session.js decrypts on load (verified: test script exits 0)
+- [x] No plaintext tokens in storage
+```
+
+**Hook result:** No errors. All required fields present (`phase`, `plan`, `status`, `provides`, `requires`, `key_files`). `deferred` field present (avoids warning). `duration` and `requirements-completed` present (avoids advisory warnings).
+
+## Negative Examples
+
+### Example 1: PLAN.md missing must_haves and task missing verify element
+
+**Input:** Write to `.planning/phases/42-auth-refactor/PLAN-01.md`
+
+**Content:**
+
+```yaml
+---
+phase: "42-auth-refactor"
+plan: "42-01"
+type: "feature"
+wave: 1
+depends_on: []
+files_modified:
+  - "src/auth/middleware.js"
+autonomous: true
+implements: []
+---
+```
+
+```xml
+<task id="42-01-T1" type="auto" tdd="false" complexity="simple">
+<name>Implement encrypted session storage</name>
+<read_first>
+src/auth/session.js
+</read_first>
+<files>
+src/auth/middleware.js
+</files>
+<action>
+1. Add encryption to session storage
+</action>
+<acceptance_criteria>
+grep -n "encrypt" src/auth/session.js
+</acceptance_criteria>
+<done>Session encryption added.</done>
+</task>
+```
+
+**Hook result:** 2 errors:
+
+- `Frontmatter missing "must_haves" field (truths/artifacts/key_links required)` -- format-validators.js `validatePlan()` checks for `must_haves:` in frontmatter. Without it, there is nothing for the verifier to check against.
+- `Task 1: missing <verify> element` -- Every task must include a `<verify>` command that the executor runs post-implementation. Without it, the self-check step has no verification command to run.
+
+### Example 2: SUMMARY.md missing requires and key_files fields
+
+**Input:** Write to `.planning/phases/42-auth-refactor/SUMMARY-01.md`
+
+**Content:**
+
+```yaml
+---
+phase: "42-auth-refactor"
+plan: "42-01"
+status: "complete"
+provides:
+  - "Encrypted session storage"
+---
+```
+
+**Hook result:** 2 blocking errors:
+
+- `Frontmatter missing "requires" field` -- Even if there are no dependencies, `requires: []` must be explicitly stated. The build skill uses this field to check inter-plan dependencies.
+- `Frontmatter missing "key_files" field` -- Even if empty, `key_files: []` must be present. The dashboard and status skill read this field to show what was produced.
+
+Additionally, 1 warning:
+
+- `Frontmatter missing "deferred" field` -- The `deferred` field forces the executor to consciously record any scope creep. Omitting it means out-of-scope work may go untracked.

package/plugins/pbr/references/few-shot-examples/check-subagent-output.md

@@ -0,0 +1,118 @@
+---
+component: check-subagent-output
+version: 1
+last_calibrated: 2026-03-24
+---
+
+# check-subagent-output Few-Shot Examples
+
+These examples document output sufficiency patterns. The hook checks file existence and structure, not content quality.
+
+## Positive Examples
+
+### Example 1: Executor produces SUMMARY.md with required fields and completion marker
+
+**Scenario:** Build skill spawns `pbr:executor` for plan 42-01. Executor writes SUMMARY-01.md and returns completion marker.
+
+**SUMMARY-01.md on disk:**
+
+```yaml
+---
+phase: "42-auth-refactor"
+plan: "42-01"
+status: "complete"
+provides:
+  - "Encrypted session storage"
+requires: []
+key_files:
+  - "src/auth/middleware.js: AES-256-GCM encryption"
+deferred: []
+---
+```
+
+```markdown
+## Self-Check: PASSED
+
+- [x] middleware.js has createCipheriv call
+- [x] Tests pass with `npm test`
+```
+
+**Task tool_output contains:** `## PLAN COMPLETE`
+
+**Hook result:** Verified. The hook finds SUMMARY-01.md in the phase directory (mtime within last 15 minutes), confirms the file exists, and sees the completion marker in `tool_output`. No warnings emitted. The build skill can route to the next step (verification or next plan).
+
+### Example 2: Verifier produces VERIFICATION.md with status and per-criterion evidence
+
+**Scenario:** Review skill spawns `pbr:verifier` for phase 42. Verifier writes VERIFICATION.md.
+
+**VERIFICATION.md on disk:**
+
+```yaml
+---
+phase: "42-auth-refactor"
+status: "passed"
+must_haves_checked: 3
+must_haves_passed: 3
+must_haves_total: 3
+---
+```
+
+```markdown
+## Must-Have Verification
+
+### Truth 1: Session tokens are encrypted at rest
+**L1 (Existence):** grep shows `createCipheriv` in middleware.js line 23.
+**L2 (Substantive):** AES-256-GCM with 32-byte key, IV generation per write.
+**L3 (Wired):** middleware.js required by server.js line 8, session.save() calls encrypt().
+**Status: PASSED**
+
+### Artifact 1: src/auth/middleware.js: >50 lines
+**L1 (Existence):** File exists, 87 lines.
+**L2 (Substantive):** 3 exported functions, no TODO/FIXME stubs.
+**L3 (Wired):** Imported by server.js and tested in middleware.test.js.
+**Status: PASSED**
+
+### Key Link 1: middleware.js imported by server.js
+**Evidence:** `grep -n "require.*middleware" src/server.js` shows line 8.
+**Status: PASSED**
+```
+
+**Hook result:** Verified. The hook finds VERIFICATION.md in the phase directory. No warnings emitted. The `status: "passed"` frontmatter field and per-criterion evidence rows confirm the verifier did substantive work.
+
+## Negative Examples
+
+### Example 1: Executor completes but no SUMMARY.md exists on disk
+
+**Scenario:** Build skill spawns `pbr:executor` for plan 42-01. The executor hits a tool error mid-run (e.g., a Bash command timeout) and returns without writing SUMMARY.md.
+
+**Phase directory contents:** `PLAN-01.md` only. No `SUMMARY-01.md` or `SUMMARY.md`.
+
+**Task tool_output contains:** (error trace or partial output, no completion marker)
+
+**Hook result:** Warning emitted via `additionalContext`:
+
+```
+[WARN] Agent pbr:executor completed but no SUMMARY-{plan_id}.md (or SUMMARY.md) was found.
+Likely causes: (1) agent hit an error mid-run, (2) wrong working directory.
+To fix: re-run the parent skill -- the executor gate will block until the output is present.
+Check the Task() output above for error details.
+```
+
+**Why this matters:** Without SUMMARY.md, the build skill has no artifact to pass to the verifier. The warning tells the orchestrator to re-run rather than proceeding to verification with missing data.
+
+### Example 2: Executor produces SUMMARY.md but no completion marker in tool_output
+
+**Scenario:** Build skill spawns `pbr:executor` for plan 42-01. The executor writes SUMMARY-01.md to disk but its final output text does not include `## PLAN COMPLETE`, `## PLAN FAILED`, or `## CHECKPOINT:`.
+
+**SUMMARY-01.md on disk:** Exists with valid frontmatter.
+
+**Task tool_output contains:** `"All tasks completed successfully."` (no structured marker)
+
+**Hook result:** Skill-specific warning emitted:
+
+```
+Executor did not return a completion marker (expected ## PLAN COMPLETE, ## PLAN FAILED, or ## CHECKPOINT:).
+Build skill may not route correctly.
+```
+
+**Why this matters:** The build skill pattern-matches on completion markers to decide the next action: advance to verification (`PLAN COMPLETE`), handle failure (`PLAN FAILED`), or checkpoint (`CHECKPOINT:`). Without a marker, the build skill cannot route and may stall or take the wrong branch. The SUMMARY.md file exists, so the generic "missing output" warning does not fire -- only this marker-specific warning catches the problem.

package/plugins/pbr/references/few-shot-examples/integration-checker.md

@@ -0,0 +1,70 @@
+---
+component: integration-checker
+version: 1
+last_calibrated: 2026-03-24
+---
+
+# Integration-Checker Few-Shot Examples
+
+## Positive Examples
+
+### Example 1: Cross-phase export/import case mismatch detected
+
+**Input:** Phase 5 SUMMARY.md declares `provides: ["AuthService class in src/services/auth.js"]`. Phase 6 code imports `const { authService } = require('./services/auth')`.
+
+**Output:**
+
+> **Check: Export/Import Wiring**
+> Status: MISMATCHED
+> Evidence: Phase 5 exports `AuthService` (PascalCase class, `src/services/auth.js` line 45: `module.exports = { AuthService }`). Phase 6 imports `authService` (camelCase, `src/routes/api.js` line 3: `const { authService } = require('./services/auth')`). Destructuring will yield `undefined` because the export key is `AuthService`, not `authService`.
+> Recommendation: Change Phase 6 import to `const { AuthService } = require('./services/auth')` or add a camelCase alias in Phase 5 exports.
+
+**Why this is good:** The checker traced the exact export and import statements with file paths and line numbers. It identified the root cause (JavaScript destructuring is case-sensitive) and explained the runtime consequence (`undefined`). The recommendation is specific and gives two options.
+
+### Example 2: Missing database migration for new column
+
+**Input:** Phase 8 adds `user_preferences` column reference in `src/models/user.js` (line 23: `this.preferences = row.user_preferences`). No migration file exists in `migrations/` directory.
+
+**Output:**
+
+> **Check: Cross-Phase Dependency Satisfaction**
+> Status: ERROR
+> Evidence: `src/models/user.js` line 23 reads `row.user_preferences` but no migration file in `migrations/` creates this column. `ls migrations/` shows latest migration is `20260320_add_sessions_table.js`. Grep for `user_preferences` across all migrations returns 0 matches.
+> Impact: Runtime `SELECT` queries will return `undefined` for `row.user_preferences` on any existing database. New deployments will fail if the ORM enforces column existence.
+> Recommendation: Create migration `20260324_add_user_preferences_column.js` adding `user_preferences TEXT` to the users table.
+
+**Why this is good:** The checker went beyond code structure to check data layer dependencies. It verified the column does not exist in any migration file using grep, identified the runtime impact, and provided a specific migration file recommendation with naming convention that matches the existing pattern.
+
+## Negative Examples
+
+### Example 1: No cross-phase boundary checks performed
+
+**Input:** 4 completed phases with SUMMARY.md provides/requires declared. Phase 3 requires `configLoad` from Phase 2.
+
+**Output:**
+
+> ## Integration Checks
+>
+> | Check | Status | Evidence |
+> |-------|--------|----------|
+> | Export/Import Wiring | PASSED | All phases have provides/requires declared |
+> | API Route Coverage | N/A | No API routes |
+> | Auth Protection | N/A | No auth |
+> | E2E Flows | N/A | No user flows |
+>
+> Status: passed, checks_total: 4, checks_passed: 4
+
+**Why this is bad:** The checker reported "PASSED" for Export/Import Wiring by only verifying that SUMMARY.md frontmatter fields exist -- it never checked whether the actual code matches the declarations. Having `provides: ["configLoad"]` in a SUMMARY.md does not mean `configLoad` is actually exported or that Phase 3 actually imports it. No grep commands, no file reads, no line numbers.
+
+### Example 2: False positive from incomplete scope analysis
+
+**Input:** Phase 4 exports `logHook()` from `plugins/pbr/scripts/hook-logger.js`. Checker reports it as ORPHANED because no standard `import` or `require` references it in Phase 5-7 source files.
+
+**Output:**
+
+> **Check: Export/Import Wiring**
+> Status: ORPHANED (WARNING)
+> Evidence: `logHook` exported from `plugins/pbr/scripts/hook-logger.js` line 12. Grep for `require.*hook-logger` in phases 5-7 files returns 0 matches. Export appears unused.
+> Recommendation: Remove unused export or add consumer.
+
+**Why this is bad:** The checker only searched phases 5-7 source files but `logHook` is consumed by hook scripts loaded dynamically via `hooks.json` -- not through standard `require()` imports in application code. Hook scripts use `const { logHook } = require('./hook-logger')` but live in `plugins/pbr/scripts/`, which the checker excluded from its search scope. A thorough integration check would search ALL files that could consume the export, including hook scripts and config-referenced modules.

package/plugins/pbr/references/few-shot-examples/nyquist-auditor.md

@@ -0,0 +1,83 @@
+---
+component: nyquist-auditor
+version: 1
+last_calibrated: 2026-03-24
+---
+
+# Nyquist-Auditor Few-Shot Examples
+
+## Positive Examples
+
+### Example 1: Unvalidated code path identified with specific line range and fix
+
+**Input:** Gap: Task T2 requires "post-write-dispatch.js validates STATE.md writes" but no test covers the STATE.md branch.
+
+**Output:**
+
+> **Gap: T2 -- STATE.md write validation**
+> **Analysis:** Read `plugins/pbr/scripts/post-write-dispatch.js` lines 45-78. The `checkSync` function handles ROADMAP.md (line 52) and PLAN.md (line 61) but returns `null` for STATE.md writes (line 71: `if (file.includes('STATE.md')) return null`). This means STATE.md writes bypass all validation in the dispatch chain.
+> **Test created:** `tests/post-write-dispatch-state.test.js`
+> ```javascript
+> test('STATE.md writes trigger checkStateWrite validation', () => {
+>   const result = dispatch({ file_path: '.planning/STATE.md', content: '---\nstatus: building\n---' });
+>   expect(result).not.toBeNull();
+>   expect(result.additionalContext).toContain('STATE.md');
+> });
+> ```
+> **Run:** `npx jest tests/post-write-dispatch-state.test.js` -- FAILED (expected: not null, received: null)
+> **Classification:** IMPLEMENTATION BUG -- The dispatch function intentionally returns null for STATE.md, meaning no validation occurs. Escalating to executor.
+> **Status:** ESCALATED -- implementation gap, not test gap
+
+**Why this is good:** The auditor read the actual implementation, identified the specific line where the gap exists (line 71), wrote a behavioral test that verifies the observable requirement (STATE.md writes get validated), ran the test, and correctly classified the failure as an implementation bug rather than trying to fix the source code. The escalation includes all context needed for the executor to fix it.
+
+### Example 2: Hook ordering race condition identified with evidence
+
+**Input:** Gap: Task T3 requires "context tier is current when suggest-compact.js runs"
+
+**Output:**
+
+> **Gap: T3 -- Context tier freshness for suggest-compact**
+> **Analysis:** Both `context-bridge.js` and `suggest-compact.js` are registered as PostToolUse handlers for Write|Edit events in `hooks.json`. `context-bridge.js` updates `.context-budget.json` with the current tier. `suggest-compact.js` reads `.context-budget.json` to decide whether to suggest compaction.
+> **Evidence:** `hooks.json` lines 23-24 register both on the same event. Execution order is not guaranteed (documented in `references/archive/hook-ordering.md` line 8: "execution order is not guaranteed for same-event hooks").
+> **Test created:** `tests/hook-ordering-context.test.js`
+> ```javascript
+> test('context-bridge writes tier before suggest-compact reads it', async () => {
+>   // Simulate: suggest-compact reads stale tier
+>   fs.writeFileSync(budgetPath, JSON.stringify({ tier: 'PEAK', chars_read: 0 }));
+>   await runHook('suggest-compact', { tool: 'Write', chars: 180000 });
+>   const budget = JSON.parse(fs.readFileSync(budgetPath));
+>   expect(budget.tier).not.toBe('PEAK'); // Should have been updated by context-bridge first
+> });
+> ```
+> **Run:** `npx jest tests/hook-ordering-context.test.js` -- PASSED (context-bridge runs first in practice due to hooks.json array order)
+> **Note:** Test passes currently but relies on implicit array ordering, not a guaranteed contract. Documented as fragile.
+> **Status:** green (with fragility note)
+
+**Why this is good:** The auditor identified a real architectural concern (race condition between two hooks on the same event), cited the documentation that confirms ordering is not guaranteed, wrote a test that verifies the current behavior, and honestly noted the fragility even though the test passes. This gives the team actionable information about a latent risk.
+
+## Negative Examples
+
+### Example 1: Partial coverage claimed after checking only 3 of 28 hook scripts
+
+**Input:** Gaps list contains 8 items across different hook scripts. Auditor checks 3.
+
+**Output:**
+
+> **Validation Summary**
+> All hooks look correct. Checked context-bridge.js, suggest-compact.js, and validate-commit.js. No issues found.
+> Resolved: 8/8, Escalated: 0/8
+
+**Why this is bad:** The auditor claimed 8/8 gaps resolved but only examined 3 hook scripts. The other 5 gaps (covering post-bash-triage.js, check-plan-format.js, auto-continue.js, track-context-budget.js, and pre-write-dispatch.js) were never read or tested. Marking untested gaps as resolved violates the core rule: "Never mark untested tests as passing." Each gap must have its own test execution evidence.
+
+### Example 2: Theoretical performance concern without measurement
+
+**Input:** Gap: Task T1 requires "hook-logger.js handles high-frequency events without blocking"
+
+**Output:**
+
+> **Gap: T1 -- hook-logger performance**
+> **Analysis:** `hook-logger.js` uses synchronous `fs.appendFileSync` for every log entry (line 34). This could be slow under high-frequency hook events because synchronous I/O blocks the Node.js event loop.
+> **Recommendation:** Switch to `fs.appendFile` (async) or batch writes.
+> **Status:** ESCALATED -- potential performance issue
+
+**Why this is bad:** The auditor flagged a theoretical concern ("could be slow") without any measurement. No benchmark test was written, no timing data was collected, no evidence of actual performance degradation was provided. The gap requires verification of "handles high-frequency events without blocking" -- the correct approach is to write a test that fires 100+ log calls and measures elapsed time, then compare against a threshold. Speculation about synchronous I/O is not evidence.

package/plugins/pbr/references/few-shot-examples/plan-checker.md

@@ -0,0 +1,73 @@
+---
+component: plan-checker
+version: 1
+last_calibrated: 2026-03-24
+---
+
+# Plan-Checker Few-Shot Examples
+
+## Positive Examples
+
+### Example 1: BLOCKER flagged for vague task action missing file and function names
+
+**Input:** Plan task with action: "Implement the authentication feature for the API routes."
+
+**Output:**
+
+> ```yaml
+> issues:
+>   - dimension: D2
+>     severity: BLOCKER
+>     finding: "Task T1 action says 'implement the authentication feature' without naming target files, functions to create, or middleware to apply. Executor cannot determine what to build."
+>     affected_field: "<action>"
+>     suggested_fix: "Specify: create authMiddleware in src/middleware/auth.js, apply to routes in src/routes/api.js lines 12-45, verify with integration test"
+> ```
+
+**Why this is good:** The checker cited the specific dimension (D2: Task Completeness), quoted the problematic text, explained why it is a blocker (executor cannot determine what to build), and gave a concrete fix with file paths and function names. The finding is actionable -- the planner knows exactly what to add.
+
+### Example 2: BLOCKER for same-wave file conflict between two plans
+
+**Input:** Two plans in wave 1 -- Plan 01 modifies `plugins/pbr/scripts/post-write-dispatch.js`, Plan 02 also modifies `plugins/pbr/scripts/post-write-dispatch.js`. No `depends_on` declared.
+
+**Output:**
+
+> ```yaml
+> issues:
+>   - dimension: D3
+>     severity: BLOCKER
+>     finding: "Plans 01 and 02 both modify plugins/pbr/scripts/post-write-dispatch.js in wave 1 with no depends_on relationship. Concurrent execution will cause merge conflicts or lost changes."
+>     affected_field: "files_modified"
+>     suggested_fix: "Either move Plan 02 to wave 2 with depends_on: ['01'] or consolidate the file changes into a single plan"
+> ```
+
+**Why this is good:** The checker identified a real structural problem -- two plans modifying the same file in the same wave without a dependency relationship. It cited D3 (Dependency Correctness), named both plans, the conflicting file, and provided two alternative fixes.
+
+## Negative Examples
+
+### Example 1: All dimensions pass when verify commands are missing
+
+**Input:** Plan with 3 tasks. Task T2 has `<verify></verify>` (empty). Task T3 has `<verify>echo "done"</verify>` (trivial, cannot distinguish pass from fail).
+
+**Output:**
+
+> ## CHECK PASSED
+> Plans: 1 | Tasks: 3 | Dimensions: 10 | Issues: 0
+
+**Why this is bad:** The checker missed two violations. D6 (Must-Haves Derivation) requires verify commands to be runnable and test actual output -- an empty verify block is a BLOCKER. D8 (Nyquist Compliance) requires verify to distinguish pass from fail -- `echo "done"` always returns 0 regardless of implementation state. Both should have been flagged.
+
+### Example 2: False positive INFO for a correctly-sized plan
+
+**Input:** Plan with 3 tasks, 6 unique files, 1 dependency. All within limits.
+
+**Output:**
+
+> ```yaml
+> issues:
+>   - dimension: D5
+>     severity: INFO
+>     finding: "Plan has 3 tasks -- consider splitting into smaller plans for faster iteration"
+>     affected_field: "task count"
+>     suggested_fix: "Split tasks into separate plans"
+> ```
+
+**Why this is bad:** The checker flagged a non-issue. D5 (Scope Sanity) allows 2-3 tasks per plan -- 3 tasks is within limits. The checker applied a personal preference ("smaller is better") rather than the documented threshold. This wastes planner time on false positives and erodes trust in the checker's judgment. A correct check would produce no issue for this plan.

package/plugins/pbr/references/few-shot-examples/ui-checker.md

@@ -0,0 +1,71 @@
+---
+component: ui-checker
+version: 1
+last_calibrated: 2026-03-24
+---
+
+# UI-Checker Few-Shot Examples
+
+## Positive Examples
+
+### Example 1: Interactive flow bug found through actual button click testing
+
+**Input:** UI-SPEC.md requires "Refresh button updates phase data without full page reload." Dashboard running at localhost:3141.
+
+**Output:**
+
+> **Dimension: Experience**
+> Score: 2 (Partial)
+> Evidence: Navigated to `localhost:3141` via `mcp__claude-in-chrome__navigate`. Clicked "Refresh" button in the phase list header using `mcp__claude-in-chrome__computer` (coordinates: 845, 62). Page performed a full browser reload (URL bar showed loading indicator, all components re-mounted). Verified via `mcp__claude-in-chrome__read_page` -- the entire DOM tree was replaced, not just the phase data section.
+> Code reference: `dashboard/src/components/PhaseList.jsx` line 34: `onClick={() => window.location.reload()}` -- uses `window.location.reload()` instead of calling the data fetch function.
+> Spec violation: UI-SPEC.md section 4.2 states "Refresh must use targeted API call to update data in-place without unmounting components."
+> Suggestion: Replace `window.location.reload()` with `fetchPhaseData()` call (already defined at line 18 in the same component).
+
+**Why this is good:** The checker actually interacted with the running application, observed the behavior (full page reload vs targeted update), traced the cause to a specific line of code, and cited the exact spec section being violated. The fix is concrete -- replace one function call with another that already exists in the same file.
+
+### Example 2: Accessibility gap with specific affected components listed
+
+**Input:** UI-SPEC.md requires "All form inputs must have associated labels or aria-label attributes." Dashboard settings page at localhost:3141/settings.
+
+**Output:**
+
+> **Dimension: Experience**
+> Score: 2 (Partial)
+> Evidence: Used `mcp__claude-in-chrome__read_page` on `/settings`. Found 4 form inputs missing `aria-label` or associated `<label>` elements:
+> 1. `dashboard/src/components/Settings.jsx` line 45: `<input type="text" placeholder="Port number" />` -- no aria-label, no htmlFor label
+> 2. `dashboard/src/components/Settings.jsx` line 52: `<input type="text" placeholder="Planning directory" />` -- same issue
+> 3. `dashboard/src/components/Settings.jsx` line 67: `<select>` for depth profile -- no aria-label
+> 4. `dashboard/src/components/ConfigEditor.jsx` line 23: `<textarea>` for JSON config -- no aria-label
+> Verified with `mcp__claude-in-chrome__get_page_text` -- screen reader would announce these as unlabeled inputs.
+> Spec violation: UI-SPEC.md section 6.1 accessibility requirements.
+> Suggestion: Add `aria-label` attributes: `aria-label="Server port"`, `aria-label="Planning directory path"`, `aria-label="Depth profile selector"`, `aria-label="Configuration JSON editor"`.
+
+**Why this is good:** The checker enumerated every affected component with file paths and line numbers, checked both HTML attributes and the rendered DOM, cited the specific spec section, and provided concrete aria-label values for each input rather than a generic "add labels" recommendation.
+
+## Negative Examples
+
+### Example 1: Landing page only checked with no interactive flow testing
+
+**Input:** UI-SPEC.md covers 6 pages with interactive forms, navigation, and data visualizations. Dashboard running at localhost:3141.
+
+**Output:**
+
+> **Overall Score: 3.5/4.0**
+> All dimensions scored 3 or above. The dashboard looks clean and professional. Navigation bar is present. Color scheme matches the spec. Typography is consistent.
+> Visual verification: Yes (viewed landing page)
+> Recommendation: Minor spacing adjustments on the sidebar.
+
+**Why this is bad:** The checker only viewed the landing page and scored 3.5 based on first impressions. No navigation to settings, phase detail, or milestone pages was performed. No button clicks, no form interactions, no responsive breakpoint checks. The spec covers 6 pages but only 1 was checked. "Looks clean and professional" is subjective assessment, not evidence-based scoring against spec criteria.
+
+### Example 2: Passing score for a feature that returns 404
+
+**Input:** UI-SPEC.md requires a "/milestones" page showing archived milestone data. Checker verifies route exists in router config.
+
+**Output:**
+
+> **Dimension: Experience**
+> Score: 3 (Compliant)
+> Evidence: `dashboard/src/App.jsx` line 28 contains `<Route path="/milestones" element={<MilestonePage />} />`. Route is correctly registered in the React Router configuration.
+> All navigation spec requirements met.
+
+**Why this is bad:** The checker verified the route exists in code but never navigated to `/milestones` to confirm it actually renders. If `MilestonePage` component throws an error, imports a missing module, or the page shows "No data" because the API endpoint is not connected, the route registration means nothing. The checker should have navigated to the URL and verified the page renders the expected content. A 404 or error page with a valid route config is still a broken feature.