fix(pm): address codex review findings on prompt robustness

- Add INCOMPLETE assessment status for when review sources fail/timeout
- Require evidence citations (plan_ref, spec_ref, evidence) in codex
  plan reviewer findings
- Require codex to verify file paths via read-only shell inspection
- Deduplicate by issue fingerprint not line proximity
- Calibrate gate semantics: only CRITICAL or 3+ IMPORTANT shift
  recommendation, MINOR/taste stays advisory
- Explicit source status tracking (ok/empty/failed/skipped)

Author: skylartaylor

pm/SKILL.md

@@ -994,11 +994,15 @@ which codex >/dev/null 2>&1 && echo "CODEX_AVAILABLE" || echo "CODEX_SKIP"
      - `[CURRENT_HEAD]` → output of `git rev-parse HEAD`
 
 4. Handle the synthesizer's Assessment:
-   - **CLEAN:** No findings. Proceed to Present & Publish with clean recommendation.
+   - **CLEAN:** No findings, both sources completed. Proceed to Present & Publish with clean recommendation.
    - **HAS_FIXES:** Dispatch a fix subagent (model: sonnet) with the Auto-fixable list.
      After fixes commit, proceed to Present & Publish with clean recommendation.
-   - **HAS_CONCERNS:** Carry the "Surface to User" list forward. Shift the recommendation
-     in Present & Publish away from "Publish" toward "Review the code first."
+   - **HAS_CONCERNS:** Carry the "Surface to User" list forward. Only shift the
+     recommendation away from "Publish" if CRITICAL items exist or there are 3+
+     IMPORTANT items. Otherwise include findings as advisory in the summary.
+   - **INCOMPLETE:** One or both review sources failed/timed out. Include whatever
+     findings are available and note in the summary that the review was partial.
+     Recommend the user review manually before publishing.
 
 **If `CODEX_SKIP`:**
 
@@ -1032,7 +1036,7 @@ Present the completed work to the user.
 - C) Changes needed — tell me what to adjust
 - D) Run /qa first (recommend if there's a testable URL you haven't checked)
 
-RECOMMENDATION: A if cross-model review returned CLEAN or HAS_FIXES (all fixed). B if cross-model review returned HAS_CONCERNS with unfixed items — the user should see the findings before publishing. D if the feature has a web-testable component and hasn't been tested in a browser yet.
+RECOMMENDATION: A if cross-model review returned CLEAN or HAS_FIXES (all fixed). B if cross-model review returned HAS_CONCERNS with CRITICAL items, 3+ IMPORTANT items, or INCOMPLETE — the user should see the findings before publishing. D if the feature has a web-testable component and hasn't been tested in a browser yet.
 
 **If the user picks A:** Run `/publish`. It handles versioning, CHANGELOG, test verification,
 PR creation, and everything else. Don't do it manually.

pm/SKILL.md.tmpl

@@ -647,11 +647,15 @@ which codex >/dev/null 2>&1 && echo "CODEX_AVAILABLE" || echo "CODEX_SKIP"
      - `[CURRENT_HEAD]` → output of `git rev-parse HEAD`
 
 4. Handle the synthesizer's Assessment:
-   - **CLEAN:** No findings. Proceed to Present & Publish with clean recommendation.
+   - **CLEAN:** No findings, both sources completed. Proceed to Present & Publish with clean recommendation.
    - **HAS_FIXES:** Dispatch a fix subagent (model: sonnet) with the Auto-fixable list.
      After fixes commit, proceed to Present & Publish with clean recommendation.
-   - **HAS_CONCERNS:** Carry the "Surface to User" list forward. Shift the recommendation
-     in Present & Publish away from "Publish" toward "Review the code first."
+   - **HAS_CONCERNS:** Carry the "Surface to User" list forward. Only shift the
+     recommendation away from "Publish" if CRITICAL items exist or there are 3+
+     IMPORTANT items. Otherwise include findings as advisory in the summary.
+   - **INCOMPLETE:** One or both review sources failed/timed out. Include whatever
+     findings are available and note in the summary that the review was partial.
+     Recommend the user review manually before publishing.
 
 **If `CODEX_SKIP`:**
 
@@ -685,7 +689,7 @@ Present the completed work to the user.
 - C) Changes needed — tell me what to adjust
 - D) Run /qa first (recommend if there's a testable URL you haven't checked)
 
-RECOMMENDATION: A if cross-model review returned CLEAN or HAS_FIXES (all fixed). B if cross-model review returned HAS_CONCERNS with unfixed items — the user should see the findings before publishing. D if the feature has a web-testable component and hasn't been tested in a browser yet.
+RECOMMENDATION: A if cross-model review returned CLEAN or HAS_FIXES (all fixed). B if cross-model review returned HAS_CONCERNS with CRITICAL items, 3+ IMPORTANT items, or INCOMPLETE — the user should see the findings before publishing. D if the feature has a web-testable component and hasn't been tested in a browser yet.
 
 **If the user picks A:** Run `/publish`. It handles versioning, CHANGELOG, test verification,
 PR creation, and everything else. Don't do it manually.

pm/codex-plan-reviewer-prompt.md

@@ -25,7 +25,12 @@ You are reviewing an implementation plan for a software feature.
 Read the plan at: [PLAN_FILE_PATH]
 Read the approved spec at: [SPEC_FILE_PATH]
 
-Review the plan against the spec and check:
+Review the plan against the spec. For each check, use read-only shell commands to
+verify claims in the plan (e.g., check that referenced file paths exist, inspect
+the repo structure). If you cannot verify a claim, say "not verified" rather than
+assuming it's correct.
+
+Check:
 
 1. **Completeness:** Are there TODOs, placeholders, missing steps, or vague hand-waves?
    Every task should be actionable without guessing.
@@ -34,8 +39,8 @@ Review the plan against the spec and check:
    scope creep (tasks that go beyond what the spec asks for)?
 
 3. **Feasibility:** Could an engineer follow this plan without getting stuck? Are file
-   paths real? Are dependencies between tasks correct? Would the batch ordering actually
-   work?
+   paths real (verify by listing them)? Are dependencies between tasks correct? Would
+   the batch ordering actually work?
 
 4. **Batch groupings:** Are risky/complex tasks isolated in solo batches? Are independent
    tasks correctly marked for parallel execution?
@@ -49,13 +54,20 @@ Tag each finding with a severity:
 - [P2] — Minor issue or suggestion. Won't block implementation but worth noting.
   Examples: could be more specific, batch grouping could be tighter, naming suggestion.
 
-Output format:
+Every finding MUST include evidence. Use this format:
 
 PLAN REVIEW:
 - [P1] [specific finding] — [why it matters]
+  plan_ref: [which task/step in the plan]
+  spec_ref: [which section of the spec, or "n/a"]
+  evidence: [what you saw when you checked — command output, file listing, or "not verified"]
+  suggested_change: [concrete fix]
+
 - [P2] [specific finding] — [suggestion]
+  plan_ref: [task/step]
+  evidence: [what you checked]
 
-If the plan looks solid, output:
+If the plan looks solid after all checks, output:
 PLAN REVIEW: No issues found.
 ```
 

pm/cross-model-reviewer-prompt.md

@@ -31,8 +31,20 @@ This is the output from OpenAI's Codex CLI reviewing the same diff:
 
 [CODEX_OUTPUT]
 
-(If this says "codex not available": skip all cross-model logic. Just pass through
-the Claude /review findings with all items marked [SINGLE SOURCE: review].)
+(If this says "codex not available" or is empty/error output: skip all cross-model logic.
+Just pass through the Claude /review findings with all items marked [SINGLE SOURCE: review].
+Set source_status for codex to "skipped" or "failed".)
+
+## Source Status
+
+Before synthesizing, classify each source's output:
+- **ok**: Source returned structured findings (even if "no issues found")
+- **empty**: Source returned but with no parseable findings
+- **failed**: Source timed out, errored, or returned garbage
+- **skipped**: Source was not run (e.g., codex not installed)
+
+You MUST note source status in your output. NEVER output Assessment: CLEAN unless
+both sources have status "ok" — if either source failed/skipped, use INCOMPLETE instead.
 
 ## Diff Context
 
@@ -44,9 +56,13 @@ need to verify a finding.
 
 ## Your Task
 
-1. **Deduplicate by location.** If both sources flag the same file:line (or clearly
-   the same issue within 5 lines), merge into one finding. Keep the more specific
-   description. Mark as [HIGH CONFIDENCE] — two independent models agree.
+1. **Deduplicate by issue fingerprint.** Two findings are duplicates if they describe
+   the same root cause and fix, even if they reference different line numbers (e.g.,
+   a caller and callee). Merge duplicates into one finding. Keep the more specific
+   description and the most precise location. Mark as [HIGH CONFIDENCE] — but only
+   if you verified the issue exists by checking the actual diff.
+
+   Two unrelated findings on nearby lines are NOT duplicates — don't merge by proximity alone.
 
 2. **Categorize each finding** using this taxonomy:
    - **auto-decidable** — Style, formatting, trivial fix, obvious bug with clear fix.
@@ -67,22 +83,39 @@ need to verify a finding.
    - IMPORTANT: Missing tests, performance issues, pattern violations
    - MINOR: Style, naming, documentation
 
-5. **Assess overall status:**
-   - CLEAN: No findings from either source
-   - HAS_FIXES: Only auto-fixable items found
-   - HAS_CONCERNS: Items that need user attention exist
+5. **Assess overall status.** Output EXACTLY ONE of these values on the Assessment line:
+   - CLEAN — No findings from either source AND both sources completed successfully (status: ok)
+   - HAS_FIXES — Only auto-fixable items found, no items requiring user attention
+   - HAS_CONCERNS — CRITICAL or IMPORTANT items that need user attention exist
+   - INCOMPLETE — One or both sources failed/skipped/empty. Pass through whatever
+     findings are available, but flag that the review is partial.
+
+## Gate Calibration
+
+Not every concern should block publishing:
+- CRITICAL (security, data loss, broken functionality) → always surface, shift away from publish
+- IMPORTANT → surface in summary, but don't shift recommendation unless there are 3+ items
+- MINOR and taste items → include in summary as advisory, never shift recommendation
 
 ## Output Format
 
+Output this exact structure. Do not add extra sections or commentary.
+
 ## Cross-Model Review Synthesis
 
+**Source Status:** review: [ok|empty|failed|skipped], codex: [ok|empty|failed|skipped]
+
 ### Auto-fixable
 - [file:line] [issue] — [specific fix] [HIGH CONFIDENCE|SINGLE SOURCE: review|SINGLE SOURCE: codex]
 
+(If none: "No auto-fixable items.")
+
 ### Surface to User
 - [SEVERITY] [file:line] [issue] — [recommendation] [HIGH CONFIDENCE|SINGLE SOURCE: review|SINGLE SOURCE: codex]
 
-### Assessment: CLEAN | HAS_FIXES | HAS_CONCERNS
+(If none: "No items requiring attention.")
+
+### Assessment: [exactly one of: CLEAN | HAS_FIXES | HAS_CONCERNS | INCOMPLETE]
 
 If Assessment is HAS_CONCERNS, add:
 ### Recommendation
@@ -93,11 +126,14 @@ If Assessment is HAS_CONCERNS, add:
 
 ## After synthesizer responds
 
-Parse the Assessment line:
+Parse the Assessment line (look for the word after "Assessment:"):
 
 - **CLEAN:** Proceed to Phase 6 with clean recommendation (Publish).
 - **HAS_FIXES:** Dispatch a fix subagent (model: sonnet) with the Auto-fixable list.
   After fixes commit, proceed to Phase 6 with clean recommendation.
-- **HAS_CONCERNS:** Carry the "Surface to User" list into Phase 6. Shift the
-  recommendation away from "Publish" toward "Review the code first." Include the
-  synthesizer's Recommendation line in the Phase 6 summary.
+- **HAS_CONCERNS:** Carry the "Surface to User" list into Phase 6. Only shift
+  the recommendation away from "Publish" if CRITICAL items exist or there are 3+
+  IMPORTANT items. Otherwise include findings as advisory in the summary.
+- **INCOMPLETE:** Proceed to Phase 6 but note in the summary that the review was
+  partial. Include whatever findings are available. Recommend the user do a manual
+  review before publishing.