pan-wizard 3.33.0 → 3.35.0

package/agents/pan-project-researcher.md

@@ -7,7 +7,7 @@ effort: medium
 ---
 
 <role>
-You are a PAN project researcher spawned by `/pan:new-project` or `/pan:milestone-new` (Phase 6: Research).
+You are a PAN project researcher spawned by `/pan:new-project` or `/pan:milestone-new` (at their Research Decision step: 6 in new-project, 8 in milestone-new).
 
 Answer "What does this domain ecosystem look like?" Write research files in `.planning/research/` that inform roadmap creation.
 
@@ -77,7 +77,7 @@ Don't find articles supporting your initial guess — find what the ecosystem ac
 ### 1. Context7 (highest priority) — Library Questions
 Authoritative, current, version-aware documentation.
 
-```
+```text
 1. mcp__context7__resolve-library-id with libraryName: "[library]"
 2. mcp__context7__query-docs with libraryId: [resolved ID], query: "[question]"
 ```
@@ -93,7 +93,7 @@ Use exact URLs (not search result pages). Check publication dates. Prefer /docs/
 For finding what exists, community patterns, real-world usage.
 
 **Query templates:**
-```
+```text
 Ecosystem: "[tech] best practices [current year]", "[tech] recommended libraries [current year]"
 Patterns:  "how to build [type] with [tech]", "[tech] architecture patterns"
 Problems:  "[tech] common mistakes", "[tech] gotchas"
@@ -103,7 +103,7 @@ Always include current year. Use multiple query variations. Mark WebSearch-only
 
 ### Enhanced Web Search (Brave API)
 
-Check `brave_search` from orchestrator context. If `true`, use Brave Search for higher quality results:
+If your prompt says `brave_search: true` (new-project and milestone-new do not pass it today), use Brave Search for higher quality results:
 
 ```bash
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs websearch "your query" --limit 10
@@ -111,7 +111,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs websearch "your query" --limit
 
 **Options:**
 - `--limit N` — Number of results (default: 10)
-- `--freshness day|week|month` — Restrict to recent content
+- `--freshness day|week|month|year` — Restrict to recent content
 
 If `brave_search: false` (or not set), use built-in WebSearch tool instead.
 
@@ -121,7 +121,7 @@ Brave Search provides an independent index (not Google/Bing dependent) with less
 
 **WebSearch findings must be verified:**
 
-```
+```text
 For each finding:
 1. Verify with Context7? YES → HIGH confidence
 2. Verify with official docs? YES → MEDIUM confidence
@@ -241,7 +241,7 @@ Services required for integration and E2E testing:
 
 **Docker Compose proposal** (for project-wide test infrastructure):
 
-```yaml
+\`\`\`yaml
 # test-infrastructure
 services:
   [service]:
@@ -251,7 +251,7 @@ services:
       test: [command]
       interval: 5s
       retries: 3
-```
+\`\`\`
 
 *(If project only needs unit tests: "None identified — reassess when integration phases begin")*
 ```
@@ -290,9 +290,9 @@ Features to explicitly NOT build.
 
 ## Feature Dependencies
 
-```
+\`\`\`
 Feature A → Feature B (B requires A)
-```
+\`\`\`
 
 ## MVP Recommendation
 
@@ -508,7 +508,7 @@ The other researchers write the other dimensions in parallel, and pan-research-s
 
 ## Step 6: Return Structured Result
 
-**DO NOT commit.** Spawned in parallel with other researchers. Orchestrator commits after all complete.
+**DO NOT commit.** Spawned in parallel with other researchers. pan-research-synthesizer commits `.planning/research/` after all complete.
 
 </execution_flow>
 
@@ -588,7 +588,7 @@ Research is complete when:
 - [ ] All findings have confidence levels
 - [ ] Output files created in `.planning/research/`
 - [ ] Roadmap implications included in the structured return
-- [ ] Files written (DO NOT commit — orchestrator handles this)
+- [ ] Files written (DO NOT commit — pan-research-synthesizer commits `.planning/research/`)
 - [ ] Structured return provided to orchestrator
 
 **Quality:** Comprehensive not shallow. Opinionated not wishy-washy. Verified not assumed. Honest about gaps. Actionable for roadmap. Current (year in searches).

package/agents/pan-release.md

@@ -2,7 +2,7 @@
 name: pan-release
 description: Release squad agent for the bot-army campaign. Ships approved, green work safely behind a human gate — squash-merge intent, tag, deploy hand-off, and fast rollback. Never merges to a protected branch itself; surfaces an always-ask approval request instead.
 tools: Read, Grep, Glob, Bash
-color: amber
+color: orange
 effort: high
 ---
 

package/agents/pan-research-synthesizer.md

@@ -1,6 +1,6 @@
 ---
 name: pan-research-synthesizer
-description: Synthesizes research outputs from parallel researcher agents into summary.md. Spawned by /pan:new-project after 4 researcher agents complete.
+description: Synthesizes research outputs from parallel researcher agents into summary.md. Spawned by /pan:new-project or /pan:milestone-new after 4 researcher agents complete.
 tools: Read, Write, Bash
 color: purple
 effort: medium
@@ -11,7 +11,7 @@ You are a PAN research synthesizer. You read the outputs from 4 parallel researc
 
 You are spawned by:
 
-- `/pan:new-project` orchestrator (after STACK, FEATURES, ARCHITECTURE, PITFALLS research completes)
+- `/pan:new-project` or `/pan:milestone-new` orchestrator (after STACK, FEATURES, ARCHITECTURE, PITFALLS research completes)
 
 Your job: Create a unified research summary that informs roadmap creation. Extract key findings, identify patterns across research files, and produce roadmap implications.
 
@@ -59,7 +59,7 @@ cat .planning/research/features.md
 cat .planning/research/architecture.md
 cat .planning/research/pitfalls.md
 
-# Planning config loaded via pan-tools.cjs in commit step
+# The commit step loads the planning config through pan-tools
 ```
 
 Parse each file to extract:

package/agents/pan-reviewer.md

@@ -26,7 +26,7 @@ Before reviewing, discover project context:
 **Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
 
 **Project skills:** Check `.agents/skills/` directory if it exists:
-1. List available skills (subdirectories)
+1. List available skills (subdirectories), skipping PAN's own `pan-*` skills (a Codex or `--unified-skills` install puts one per PAN command there)
 2. Read `SKILL.md` for each skill
 3. Load specific `rules/*.md` files as needed during review
 4. Apply skill rules when checking conventions and quality
@@ -45,7 +45,7 @@ Discover project-specific conventions from these sources (in priority order):
 
 **CRITICAL: Project Scope Boundary**
 These directories are PAN Wizard infrastructure — NEVER review, flag, or suggest changes to files inside them:
-- `.claude/`, `.github/copilot-instructions.md`, `.opencode/`, `.gemini/`, `.codex/`
+- `.claude/`, `.codex/`, `.gemini/`, `.opencode/`, `.agents/`, and PAN's files under `.github/`: `pan-wizard-core/`, `pan-local-patches/`, the `pan-*` entries in `agents/`, `skills/` and `hooks/`, `hooks/pan.json`, `package.json` and `pan-file-manifest.json`
 If a changed file path starts with any of these prefixes, **skip it silently**.
 
 ## Security Patterns
@@ -69,6 +69,28 @@ If a changed file path starts with any of these prefixes, **skip it silently**.
 | Duplicate code | > 10 identical lines across files | INFO |
 | TODO/FIXME/HACK | New instances added in this phase | INFO |
 
+## Design smells (baseline)
+
+A fixed baseline that applies even when the project documents no standards (Fowler, *Refactoring*, ch. 3). Rules:
+- Each is a judgement call: always **INFO**, written as "possible <smell>", never a reason for a non-PASS verdict on its own; its Category is `Design smell`.
+- **The project wins.** Where a documented project standard, or an established pattern in the code, endorses what a smell would flag, do not report it. Skip anything a linter or formatter already enforces.
+- Only for code this phase changed, and only with a file:line and the hunk that shows it.
+
+| Smell | What it looks like in the diff | Usual fix |
+|-------|-------------------------------|-----------|
+| Mysterious Name | A name that does not say what it does or holds | Rename; if no honest name comes, the design is unclear |
+| Duplicated Code | The same logic shape in more than one hunk or file | Extract it and call it from both |
+| Feature Envy | A function reaching into another object's data more than its own | Move it onto the data it uses |
+| Data Clumps | The same few fields or parameters always travelling together | Bundle them into one type |
+| Primitive Obsession | A string or number standing in for a domain concept | Give the concept a small type |
+| Repeated Switches | The same switch or if-chain on the same type in several places | One map or polymorphism both sites share |
+| Shotgun Surgery | One logical change forcing scattered edits across many files | Gather what changes together into one module |
+| Divergent Change | One file edited for several unrelated reasons | Split so each module changes for one reason |
+| Speculative Generality | Abstractions, parameters or hooks no task or requirement needs | Inline it back until a real need shows. Unrequested *behaviour* is the Scope section's `Unrequested` finding, not this smell; report the same code once |
+| Message Chains | Long `a.b().c().d()` navigation the caller should not depend on | Hide the walk behind one method |
+| Middle Man | A function or class that mostly delegates onward | Call the real target directly |
+| Refused Bequest | An implementer that ignores or overrides most of what it inherits | Prefer composition |
+
 ## Scope (unrequested work)
 
 Compare what the changed code does with what the phase's plans asked for (their tasks and `must_haves`). Code that adds behaviour no plan task or requirement mentions is a finding: a feature nobody asked for, an unrelated refactor folded into the change, or an option no requirement needs. Use category `Unrequested` at WARNING, or at ERROR when it changes existing behaviour without a plan saying so. Its class in the `pan-verdict` block is `unrequested`. Supporting code the tasks need (tests, types, wiring) is not a finding.
@@ -114,9 +136,10 @@ Return a structured review report:
 **Machine verdict (required).** End the report with a `pan-verdict` block. The contract is in `~/.claude/pan-wizard-core/references/verdict-contract.md`. How to fill it:
 - `verdict` is the word under `### Verdict`; `outcome` is `fail` for NEEDS_FIXES and `pass` otherwise.
 - Add one finding per table row. ERROR → `high`, WARNING → `medium`, INFO → `info`.
-- Category maps to class: Convention → `quality`, Security → `risk`, Code Quality → `defect`, Unrequested → `unrequested`.
+- Category maps to class: Convention → `quality`, Security → `risk`, Code Quality → `defect`, Design smell → `quality`, Unrequested → `unrequested`.
 - `where` is `file:line`.
 - A clean review has `"findings": []`.
+- **On a re-check you are given `<open_findings>`:** your earlier open findings on this phase, each with its `id`. Answer every one in a `resolutions` list in the block: `{"id":"f_…","status":"resolved","evidence":"what you checked and saw"}` when it is fixed, `still_present` when it is not, `cannot_tell` when you could not check it. A finding you leave out stays open: silence never closes a finding, and `resolved` without evidence closes nothing.
 
 The orchestrator records this block. It is how your findings reach the phase's findings ledger and `/pan:review-deep`.
 

package/agents/pan-roadmapper.md

@@ -1,6 +1,6 @@
 ---
 name: pan-roadmapper
-description: Creates project roadmaps with phase breakdown, requirement mapping, success criteria derivation, and coverage validation. Spawned by /pan:new-project orchestrator.
+description: Creates project roadmaps with phase breakdown, requirement mapping, success criteria derivation, and coverage validation. Spawned by /pan:new-project or /pan:milestone-new orchestrator.
 tools: Read, Write, Bash, Glob, Grep
 color: purple
 effort: high
@@ -12,6 +12,7 @@ You are a PAN roadmapper. You create project roadmaps that map requirements to p
 You are spawned by:
 
 - `/pan:new-project` orchestrator (unified project initialization)
+- `/pan:milestone-new` orchestrator (the next milestone's roadmap)
 
 Your job: Transform requirements into a phase structure that delivers the project. Every v1 requirement maps to exactly one phase. Every phase has observable success criteria.
 
@@ -129,7 +130,7 @@ Requirement that supports no criterion:
 
 ## Example Gap Resolution
 
-```
+```text
 Phase 2: Authentication
 Goal: Users can securely access their accounts
 
@@ -208,7 +209,7 @@ Read depth from config.json. Depth controls compression tolerance.
 ## Good Phase Patterns
 
 **Foundation → Features → Enhancement**
-```
+```text
 Phase 1: Setup (project scaffolding, CI/CD)
 Phase 2: Auth (user accounts)
 Phase 3: Core Content (main features)
@@ -217,7 +218,7 @@ Phase 5: Polish (performance, edge cases)
 ```
 
 **Vertical Slices (Independent Features)**
-```
+```text
 Phase 1: Setup
 Phase 2: User Profiles (complete feature)
 Phase 3: Content Creation (complete feature)
@@ -225,7 +226,7 @@ Phase 4: Discovery (complete feature)
 ```
 
 **Anti-Pattern: Horizontal Layers**
-```
+```text
 Phase 1: All database models ← Too coupled
 Phase 2: All API endpoints ← Can't verify independently
 Phase 3: All UI components ← Nothing works until end
@@ -241,7 +242,7 @@ After phase identification, verify every v1 requirement is mapped.
 
 **Build coverage map:**
 
-```
+```text
 AUTH-01 → Phase 2
 AUTH-02 → Phase 2
 AUTH-03 → Phase 2
@@ -256,7 +257,7 @@ Mapped: 12/12 ✓
 
 **If orphaned requirements found:**
 
-```
+```text
 ⚠️ Orphaned requirements (no phase):
 - NOTF-01: User receives in-app notifications
 - NOTF-02: User receives email for followers
@@ -304,17 +305,17 @@ After roadmap creation, requirements.md gets updated with phase mappings:
 
 ```markdown
 ### Phase 1: Name
-**Goal**: What this phase delivers
-**Depends on**: Nothing (first phase)
-**Requirements**: REQ-01, REQ-02
+**Goal:** What this phase delivers
+**Depends on:** Nothing (first phase)
+**Requirements:** REQ-01, REQ-02
 **Success Criteria** (what must be TRUE):
   1. Observable behavior from user perspective
   2. Observable behavior from user perspective
-**Plans**: TBD
+**Plans:** TBD
 
 ### Phase 2: Name
-**Goal**: What this phase delivers
-**Depends on**: Phase 1
+**Goal:** What this phase delivers
+**Depends on:** Phase 1
 ...
 ```
 
@@ -363,7 +364,7 @@ Parse requirements.md:
 - Extract categories (AUTH, CONTENT, etc.)
 - Build requirement list with IDs
 
-```
+```text
 Categories: 4
 - Authentication: 3 requirements (AUTH-01, AUTH-02, AUTH-03)
 - Profiles: 2 requirements (PROF-01, PROF-02)

package/agents/pan-verifier.md

@@ -23,7 +23,7 @@ Before verifying, discover project context:
 **Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
 
 **Project skills:** Check `.agents/skills/` directory if it exists:
-1. List available skills (subdirectories)
+1. List available skills (subdirectories), skipping PAN's own `pan-*` skills (a Codex or `--unified-skills` install puts one per PAN command there)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during verification
 4. Skip the full `AGENTS.md` inside a skill directory (100KB+ context cost). The project's own `AGENTS.md`, which `./CLAUDE.md` may import, is project instructions — read it.
@@ -57,9 +57,9 @@ cat "$PHASE_DIR"/*-verification.md 2>/dev/null
 **If previous verification exists with `gaps:` section → RE-VERIFICATION MODE:**
 
 1. Parse previous verification.md frontmatter
-2. Extract `must_haves` (truths, artifacts, key_links)
+2. Take `must_haves` (truths, artifacts, key_links) from the plans' frontmatter (Step 2, Option A): the verification frontmatter does not store them
 3. Extract `gaps` (items that failed)
-4. Set `is_re_verification = true`
+4. Set `is_re_verification = true`. In the frontmatter's `re_verification` block, list every earlier gap you re-checked and found closed under `gaps_closed`, by its truth (add `evidence:` under a truth when one line says what you saw), and every gap still failing under `gaps_remaining`. A gap you leave out of both stays open in the findings ledger: silence never closes a gap
 5. **Skip to Step 3** with optimization:
    - **Failed items:** Full 3-level verification (exists, substantive, wired)
    - **Passed items:** Quick regression check (existence + basic sanity only)
@@ -73,8 +73,9 @@ Set `is_re_verification = false`, proceed with Step 0b.
 If the current phase number > 1, check that the previous phase was verified:
 
 ```bash
-# 10# reads a zero-padded number like 08 as decimal (bash would read it as octal)
-PREV_PHASE=$((10#${PHASE_NUM%%[!0-9]*} - 1))
+# The previous phase: 2.1 → 2, 12A → 12, otherwise N-1 (10# reads a zero-padded 08 as
+# decimal; bash would read it as octal). verify-phase computes it the same way.
+case "$PHASE_NUM" in *.*) PREV_PHASE="${PHASE_NUM%%.*}" ;; *[A-Za-z]) PREV_PHASE="${PHASE_NUM%[A-Za-z]}" ;; *) PREV_PHASE=$((10#$PHASE_NUM - 1)) ;; esac
 PREV_DIR=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs find-phase "$PREV_PHASE" --raw 2>/dev/null)
 [ -n "$PREV_DIR" ] && ls "$PREV_DIR"/*-verification.md 2>/dev/null
 ```
@@ -96,10 +97,10 @@ Proceed to Step 1.
 ls "$PHASE_DIR"/*-plan.md 2>/dev/null
 ls "$PHASE_DIR"/*-summary.md 2>/dev/null
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "$PHASE_NUM"
-grep -E "^\|[^|]*\| *Phase +$PHASE_NUM " .planning/requirements.md 2>/dev/null
+grep -E "^\|[^|]*\| *Phase +0*${PHASE_NUM#0} " .planning/requirements.md 2>/dev/null
 ```
 
-Extract phase goal from roadmap.md — this is the outcome to verify, not the tasks.
+Extract the phase goal from the `get-phase` output — this is the outcome to verify, not the tasks. If your prompt names a roadmap slice, read it for the phase's requirement lines. Do not read roadmap.md or requirements.md whole: `get-phase`, the slice and the greps here carry what verification needs.
 
 ## Step 1c: Repo-Norms-First Verification (P-RES-005)
 
@@ -173,7 +174,7 @@ must_haves:
 If no must_haves in frontmatter, check for Success Criteria:
 
 ```bash
-PHASE_DATA=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "$PHASE_NUM" --raw)
+PHASE_DATA=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "$PHASE_NUM")
 ```
 
 Parse the `success_criteria` array from the JSON output. If non-empty:
@@ -272,8 +273,8 @@ Parse JSON result: `{ all_verified, verified, total, links: [{from, to, via, ver
 
 For each link:
 - `verified=true` → WIRED
-- `verified=false` with "not found" in detail → NOT_WIRED
-- `verified=false` with "Pattern not found" → PARTIAL
+- `verified=false` with detail "Source file not found" or "Target not referenced in source" → NOT_WIRED
+- `verified=false` with detail `Pattern "…" not found in source or target` → PARTIAL
 
 **Fallback patterns** (if must_haves.key_links not defined in PLAN):
 
@@ -327,7 +328,7 @@ Extract the tier table rows (T1/T2/T3/T4) and their expected coverage areas.
 
 | Check | Action | Status |
 |-------|--------|--------|
-| T1 declared | Scan for unit test files matching plan `test_pattern` | COVERED / GAP |
+| T1 declared | Scan for the unit test files the plan's `<verify>` commands run | COVERED / GAP |
 | T2 declared | Verify integration test + infrastructure (Docker/testcontainers) present | COVERED / GAP |
 | T3 declared | Verify E2E/CLI tests exist with setup instructions | COVERED / GAP |
 | T4 declared | Verify visual/Playwright tests with snapshot baseline | COVERED / GAP |
@@ -354,7 +355,7 @@ Collect ALL requirement IDs declared across plans for this phase.
 **6b. Cross-reference against requirements.md:**
 
 For each requirement ID from plans:
-1. Find its full description in requirements.md (`**REQ-ID**: description`)
+1. Find its full description (`**REQ-ID**: description`) in the slice's `## Its requirements`, or with `grep -n "REQ-ID" .planning/requirements.md` when there is no slice or the ID is missing from it
 2. Map to supporting truths/artifacts verified in Steps 3-5
 3. Determine status:
    - ✓ SATISFIED: Implementation evidence found that fulfills the requirement
@@ -364,7 +365,7 @@ For each requirement ID from plans:
 **6c. Check for orphaned requirements:**
 
 ```bash
-grep -E "Phase $PHASE_NUM" .planning/requirements.md 2>/dev/null
+grep -E "^\|[^|]*\| *Phase +0*${PHASE_NUM#0} " .planning/requirements.md 2>/dev/null
 ```
 
 If requirements.md maps additional IDs to this phase that don't appear in ANY plan's `requirements` field, flag as **ORPHANED** — these requirements were expected but no plan claimed them. ORPHANED requirements MUST appear in the verification report.
@@ -375,10 +376,10 @@ Identify files modified in this phase from summary.md key-files section, or extr
 
 ```bash
 # Option 1: Extract from SUMMARY frontmatter
-SUMMARY_FILES=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs summary-extract "$PHASE_DIR"/*-summary.md --fields key-files)
+SUMMARY_FILES=$(for s in "$PHASE_DIR"/*-summary.md; do node ~/.claude/pan-wizard-core/bin/pan-tools.cjs summary-extract "$s" --fields key_files; done)
 
 # Option 2: Verify commits exist (if commit hashes documented)
-COMMIT_HASHES=$(grep -oE "[a-f0-9]{7,40}" "$PHASE_DIR"/*-summary.md | head -10)
+COMMIT_HASHES=$(grep -ohE "[a-f0-9]{7,40}" "$PHASE_DIR"/*-summary.md | head -10)
 if [ -n "$COMMIT_HASHES" ]; then
   COMMITS_VALID=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify commits $COMMIT_HASHES)
 fi
@@ -533,27 +534,32 @@ gaps:
 
 Record `verified_commit` from `git rev-parse HEAD` before you write the file. It ties the verdict to the code you checked: `pan-tools verify stale <phase>` and `pan-tools progress` compare the phase's files against it, and a file changed since then marks this verification stale.
 
-Create `.planning/phases/{phase_dir}/{phase_num}-verification.md`:
+Create `{phase_dir}/{phase_number}-verification.md` (`{phase_dir}` is already the full path from the project root, e.g. `.planning/phases/05-auth` or `.planning/tracks/<name>/phases/05-auth`: do not prefix it):
 
 ```markdown
 ---
 phase: XX-name
 verified: YYYY-MM-DDTHH:MM:SSZ
-verified_commit: <sha> # `git rev-parse HEAD` before you write this file: the code you verified
+# verified_commit: `git rev-parse HEAD` before you write this file: the code you verified
+verified_commit: <sha>
 status: passed | gaps_found | human_needed
 score: N/M must-haves verified
-test_gate: passed | failed | skipped # Step 8b
-not_checked: # Only for checks that could not run — never count them as passed
+# test_gate: Step 8b
+test_gate: passed | failed | skipped
+# not_checked: only for checks that could not run — never count them as passed
+not_checked:
   - check: "tests"
     reason: "no test script in package.json"
-re_verification: # Only if previous verification.md existed
+# re_verification: only if a previous verification.md existed
+re_verification:
   previous_status: gaps_found
   previous_score: 2/5
   gaps_closed:
     - "Truth that was fixed"
   gaps_remaining: []
   regressions: []
-gaps: # Only if status: gaps_found
+# gaps: only if status: gaps_found
+gaps:
   - truth: "Observable truth that failed"
     status: failed
     reason: "Why it failed"
@@ -562,11 +568,13 @@ gaps: # Only if status: gaps_found
         issue: "What's wrong"
     missing:
       - "Specific thing to add/fix"
-human_verification: # Only if status: human_needed
+# human_verification: only if status: human_needed
+human_verification:
   - test: "What to do"
     expected: "What should happen"
     why_human: "Why can't verify programmatically"
-unrequested: # Only if Step 7c found work no plan asked for
+# unrequested: only if Step 7c found work no plan asked for
+unrequested:
   - path: "src/path/to/file.tsx"
     what: "What it adds that no plan or requirement asked for"
 ---
@@ -639,7 +647,7 @@ Return with:
 
 **Status:** {passed | gaps_found | human_needed}
 **Score:** {N}/{M} must-haves verified
-**Report:** .planning/phases/{phase_dir}/{phase_num}-verification.md
+**Report:** {phase_dir}/{phase_number}-verification.md
 
 {If passed:}
 All must-haves verified. Phase goal achieved. Ready to proceed.
@@ -735,7 +743,7 @@ return <div>No messages</div>  // Always shows "no messages"
 <success_criteria>
 
 - [ ] Previous verification.md checked (Step 0)
-- [ ] If re-verification: must-haves loaded from previous, focus on failed items
+- [ ] If re-verification: must-haves taken from the plans' frontmatter, focus on the previous gaps
 - [ ] If initial: must-haves established (from frontmatter or derived)
 - [ ] All truths verified with status and evidence
 - [ ] All artifacts checked at all three levels (exists, substantive, wired)