Needs Attention: surface PRs via the universal pr gate; delete gateless builder-derived fallbacks

[waleedkadous]

Problem

Needs Attention has accreted a builder-state-derived model that is fragile and wrong. It surfaces builder rows (not just PRs), keeps merged PRs showing, and hides ready PRs — three faces of one root cause: bugfix attention is derived from porch terminal/builder state (derivePrReady's bugfix && phase==='verified' fallback, the pr_ready_for_human field, and the defensive builder-emit branch in NeedsAttentionList.buildItems) instead of from the PR.

Key finding: the universal signal already exists

Every PR-producing protocol already has a pr gate — bugfix, air (on the pr phase), spir, aspir, pir (on the review phase). The pr gate going pending (set by porch after the PR phase / CMAP completes) is the uniform "PR ready for human, after CMAP" signal across all protocols. No new marker/abstraction is needed.

The entire mess traces to one deviation: a gateless bugfix variant (observed on an external adopter, codev 3.1.4, 4-phase investigate/fix/verify/pr with no pr gate). With no pr gate, the dashboard fell back to the fragile bugfix && verified derivation + builder-emit. The gated path never broke (it self-heals through rollback by re-requesting the pr gate).

Desired behavior

Needs Attention = (A) open PRs whose linked builder has a pending pr gate, surfaced as PR rows ∪ (B) genuine pre-PR/post-merge human gate rows (spec-approval, plan-approval, dev-approval, verify-approval). Never a builder standing in for a PR.

Direction (spec to flesh this out)

1. Surface open PRs whose builder's pr gate is pending (the universal post-CMAP signal). Emit PR rows only — find the open PR; if not found (cache miss), do not emit a builder row.
2. Delete the bugfix && phase==='verified' fallback in derivePrReady and the builder-emit branch in NeedsAttentionList.buildItems. These exist only to cope with the gateless case.
3. Keep the gate-row path for spec/plan/dev/verify-approval, and the unaffiliated/human-PR reviewDecision === REVIEW_REQUIRED fallback.
4. A protocol must carry a pr gate for its PR to surface (the universal contract). Gateless PR-producing variants won't surface PR rows by design — adopters use the pr-gated protocol.
5. EXPERIMENT/MAINTAIN don't follow the CMAP-PR pattern (they have experiment-complete/maintain-complete gates) — they surface via those completion gates, not PR rows. State this explicitly.

Relationships

• [Bugfix #901] Skip stale post-merge prReady rows in NeedsAttentionList #902 (recentlyMergedIssueIds): becomes far less load-bearing once merged PRs drop via open-only + no builder-emit; the spec should assess whether it's still needed or removable.
• Terminal state 'verified' over-promises: split back into 'complete' (phases done) vs 'verified' (verify-approval passed) #919 (verified→complete rename): its Needs-Attention parts (req 8 pr_ready re-derivation, derivePrReady rework) become unnecessary under this model. The terminal-state rename stands on its own as honesty work; reconcile/descope Terminal state 'verified' over-promises: split back into 'complete' (phases done) vs 'verified' (verify-approval passed) #919 accordingly.
• External adopter (shannon): separately align its bugfix to the pr-gated upstream so it's covered by the universal mechanism.

Out of scope

• Per-protocol bespoke markers (the pr gate is the universal signal).
• Changing pre-PR gate semantics.

[waleedkadous]

@amrmelsayed — looping you in for a VSCode sanity-check, since this touches shared infrastructure you own.

What #927 does: reworks the dashboard Needs Attention to surface PRs via the universal pr gate (PR rows only) and deletes the bugfix-state-derived fallbacks (derivePrReady's bugfix && verified branch + the NeedsAttentionList builder-emit branch). Spec: codev/specs/927-needs-attention-surface-prs-vi.md (on builder/spir-927).

Why it touches VSCode: the fix is deliberately dashboard-local for the "no builder stand-in" rule, but it changes shared overview.ts infra that VSCode also consumes:

1. Keeps pr in GATE_LABELS / detectBlocked* — so the VSCode Needs Attention tree, gate toast, and status-bar counter should keep surfacing pr-gate-pending builders exactly as today. Intent: no VSCode change. Please confirm that's still the behavior you want (vs. the dashboard, which moves pr-gate to PR-rows-only).
2. Adds verify-approval to GATE_LABELS (label "verify review") — this is a new entry in shared blocked-detection, so it flows into the VSCode tree/toast/status-bar too. Please confirm it renders sanely there (the spec notes the VSCode toast GATE_ACTIONS has no verify-approval entry and falls back to a generic "Review" → open-terminal action — flagging in case you'd want a dedicated action).
3. Spec also recommends unifying detectBlockedSince onto Object.keys(GATE_LABELS) (it currently keeps a separate hardcoded gate array).

No action needed yet — the builder is heading into the Plan phase. Just want your eyes before it implements so we don't regress the VSCode surfaces. Flag anything and the builder will fold it into the plan.