don-petry · Aug 2, 2026 · Apr 25, 2026 · Apr 25, 2026 · Apr 25, 2026 · Apr 25, 2026
@@ -560,6 +560,7 @@ jobs:
         run: |
           # github.token events do not trigger issues:labeled workflows; use the
           # PAT to fire repository_dispatch so Dev-Lead Agent is explicitly woken.
+          # Use --input so client_payload is sent as a JSON object, not a string.
           gh api "repos/${{ github.repository }}/dispatches" \
             -X POST \
             --input - <<EOF

@@ -179,6 +179,70 @@ jobs:
             });
             core.notice(`Runaway issue created: ${issue.data.html_url}`);
 
+      # Stall-PR detection net (#1410, epic #1402). The mirror image of the
+      # runaway scan above: a pure gh-API + jq sweep of every open PR for the
+      # SILENT failure mode the narrowed Class-2 timers (#1407/#1408) could
+      # introduce — a PR stuck CI-green + REVIEW_REQUIRED with no agent activity
+      # and no pending event, that no fast path re-fires. #860's lesson was that
+      # detection must be pushed, not pulled; this builds that instrument BEFORE
+      # the timers narrow. Detect-only — no PR is mutated. Sets HAS_STALL when any
+      # candidate is found, surfaced through the same health-check /
+      # automated-report issue channel. No new scheduled workload.
+      - name: Scan for stalled PRs
+        env:
+          GH_TOKEN: ${{ secrets.DON_PETRY_BOT_GH_PAT }}
+          REPO: ${{ github.repository }}
+        run: bash scripts/pr_stall_scan.sh
+
+      - name: Truncate stall report if needed
+        run: |
+          if [ -f pr_stall_report.md ]; then
+            if [ "$(wc -c < pr_stall_report.md)" -gt 60000 ]; then
+              last_line=$(awk '{s+=length($0)+1; if(s>60000){print NR-1; exit}} END{if(s<=60000) print NR}' pr_stall_report.md)
+              head -n "${last_line:-0}" pr_stall_report.md > pr_stall_report.md.tmp
+              mv pr_stall_report.md.tmp pr_stall_report.md
+              printf '\n\n---\n_Report truncated at 60 000 bytes._\n' >> pr_stall_report.md
+            fi
+          fi
+
+      - name: Create stall-candidate issue
+        if: env.HAS_STALL == 'true' && hashFiles('pr_stall_report.md') != ''
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3  # v9.0.0
+        with:
+          github-token: ${{ github.token }}
+          script: |
+            const fs = require('fs');
+            const report = fs.readFileSync('pr_stall_report.md', 'utf8');
+            if (!report.trim()) {
+              core.setFailed('Stall report file is empty');
+              return;
+            }
+            const today = new Date().toISOString().split('T')[0];
+            const titlePrefix = 'Stalled PR candidate(s) detected';
+            // Date-stamped title → a fresh issue every run. Close prior open ones.
+            const priors = await github.paginate(github.rest.issues.listForRepo, {
+              owner: context.repo.owner, repo: context.repo.repo,
+              state: 'open', labels: 'health-check,automated-report', per_page: 100,
+            });
+            for (const p of priors) {
+              if (!p.pull_request && p.title.startsWith(titlePrefix)) {
+                try {
+                  await github.rest.issues.update({
+                    owner: context.repo.owner, repo: context.repo.repo,
+                    issue_number: p.number, state: 'closed', state_reason: 'completed',
+                  });
+                } catch (err) { core.warning(`could not close prior digest #${p.number}: ${err.message}`); }
+              }
+            }
+            const issue = await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: `${titlePrefix} ${today}`,
+              body: report,
+              labels: ['health-check', 'automated-report'],
+            });
+            core.notice(`Stall issue created: ${issue.data.html_url}`);
+
       # Durable, affirmative MCP-connectivity monitor (#903, part of #676).
       # Additive final step: when .github/review-mcp.json is present, assert that
       # the configured server(s) handshake through the same flags engine.sh uses

@@ -65,6 +65,8 @@
             tests/test_pr_automation_budget.bats \
             tests/test_pr_runaway_regression.bats \
             tests/test_pr_runaway_detect.bats \
+            tests/test_pr_stall_detect.bats \
+            tests/test_pr_stall_regression.bats \
             tests/test_premature_closure_detect.bats \
             tests/test_ci_status.bats \
             tests/test_push_protection.bats \
@@ -194,7 +196,7 @@
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        # NOTE: persist-credentials is intentionally left at the default (true) —
        # vci_resolve_reusable needs `git fetch origin` to authenticate against this
        # private repo when resolving same-repo channel tags. Setting
        # persist-credentials: false would silently push every such caller into the

@@ -91,6 +91,18 @@ jobs:
             exit 1
           fi
 
+      - name: Guard — workflow-dispatch PAT present
+        # Without a workflow/actions:write PAT every dispatch returns HTTP 403 and
+        # the sweep "succeeds" while re-triggering nothing (the original #573 gap
+        # regression). Fail loudly instead of silently no-op'ing.
+        env:
+          GH_TOKEN: ${{ secrets.GH_PAT_DON_PETRY || secrets.GH_PAT_WORKFLOWS }}
+        run: |
+          if [ -z "${GH_TOKEN}" ]; then
+            echo "::error::GH_PAT_WORKFLOWS is required — GITHUB_TOKEN cannot start a dispatched run and the bot comment PAT lacks actions:write."
+            exit 1
+          fi
+
       - name: Run stuck-review sweep
         env:
           # PAT with workflow/actions:write scope required: GITHUB_TOKEN cannot

@@ -50,7 +50,13 @@ on:
       # migrates to `secrets: inherit`, after which they can be dropped (issue #1327).
       COPILOT_GITHUB_TOKEN:
         required: false
+      GH_PAT_DON_PETRY_COPILOT:
+        # don-petry's Copilot-subscription PAT (Copilot review engine). Canonical
+        # name under the GH_PAT_<ACCOUNT> schema; supersedes GH_PAT (below, kept as
+        # a transition fallback). The bot's own PATs keep their grandfathered names.
+        required: false
       GH_PAT:
+        # DEPRECATED alias of GH_PAT_DON_PETRY_COPILOT — kept during migration.
         required: false
       DON_PETRY_BOT_GH_PAT:
         required: false
@@ -314,6 +320,81 @@ jobs:
             fi
           fi
 
+      - name: Cache claude-code CLI
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: ~/.npm-global
+          key: claude-code-${{ env.CLAUDE_CODE_VERSION }}-${{ runner.os }}
+
+      - name: Verify auth scopes
+        # Inlined from scripts/verify-auth-scopes.sh so this step is self-contained
+        # when pr-review.yml is deployed to target repos that do not have the scripts/ dir.
+        run: |
+          set -euo pipefail
+
+          if auth_status="$(gh auth status 2>&1)"; then
+            :
+          else
+            auth_rc=$?
+            printf '%s\n' "$auth_status"
+            echo "::error::gh auth status failed"
+            exit "$auth_rc"
+          fi
+          printf '%s\n' "$auth_status"
+
+          # Fine-grained PATs are NOT supported — they fail at addPullRequestReview.
+          # Two detection methods: (1) prefix in auth status output; (2) gh auth token
+          # for gh versions that mask the prefix in status output (token never logged).
+          _fgpat=0
+          if grep -qi 'Token:.*github_pat_' <<< "$auth_status"; then
+            _fgpat=1
+          else
+            _tok="$(gh auth token 2>/dev/null || true)"
+            if [[ "${_tok:-}" == github_pat_* ]]; then
+              _fgpat=1
+            fi
+            unset _tok
+          fi
+          if [[ "$_fgpat" -eq 1 ]]; then
+            unset _fgpat
+            echo "::error::Fine-grained PAT detected — fine-grained PATs are not supported by this workflow."
+            echo "::error::Fine-grained PATs fail at addPullRequestReview (GraphQL: Resource not accessible by personal access token)."
+            echo "::error::Replace DON_PETRY_BOT_GH_PAT with a classic PAT that has repo, workflow, and read:org scopes."
+            echo "::error::See docs/pr-review-agent/setup.md → Troubleshooting for details."
+            exit 1
+          fi
+          unset _fgpat
+
+          scopes_line="$(grep 'Token scopes:' <<< "$auth_status" || true)"
+          normalized_scopes="${scopes_line//,/ }"
+          normalized_scopes="${normalized_scopes//$'\''/ }"
+
+          if [ -z "$normalized_scopes" ] || grep -qiE '(cannot determine|fine.grained)' <<< "$auth_status"; then
+            echo "::warning::Token scopes could not be determined. Skipping scope validation."
+            echo "::warning::Ensure the token has: repo + read:org (classic PAT) or contents + pull_requests:write."
+            exit 0
+          fi
+
+          if grep -qE "(^|[[:space:]])repo([[:space:]]|$)" <<< "$normalized_scopes"; then
+            if ! grep -qE "(^|[[:space:]])read:org([[:space:]]|$)" <<< "$normalized_scopes"; then
+              echo "::error::GH_TOKEN has 'repo' scope but is missing 'read:org'."
+              echo "::error::PRs with team-based reviewers will fail at 'gh pr view --json reviewRequests'."
+              echo "::error::Edit the classic PAT and check the 'read:org' box (no regeneration needed)."
+              exit 1
+            fi
+          else
+            if ! grep -qE "(^|[[:space:]])contents(:[^[:space:]]+)?([[:space:]]|$)" <<< "$normalized_scopes"; then
+              echo "::error::GH_TOKEN is missing required scope: contents"
+              echo "::error::Token must have either 'repo' + 'read:org' (classic) or 'contents' + 'pull_requests:write'"
+              exit 1
+            fi
+            if ! grep -qE "(^|[[:space:]])pull_requests(:write)?([[:space:]]|$)" <<< "$normalized_scopes"; then
+              echo "::error::GH_TOKEN is missing required scope: pull_requests with write access"
+              echo "::error::Token must have either 'repo' + 'read:org' (classic) or 'contents' + 'pull_requests:write'"
+              exit 1
+            fi
+          fi
+
       - name: Install review engine CLIs
         run: |
           set -euo pipefail

@@ -10,6 +10,8 @@ Agent profiles in `/agents/` are available org-wide — invocable from GitHub.co
 It also contains automated workflows (GitHub Actions agents running on events and schedules),
 prompts, scripts, and the scheduled reporting dashboards that run across the org.
 
+It also contains the scheduled PR review automation (workflows + scripts + prompts) that runs hourly across the org.
+
 ## Structure
 
 ```

@@ -492,3 +492,85 @@ update the table (and the role's §8 contract) in the same PR, or CI fails.
 The table's exact shape is fixed **here** (this document is the normative source); #1406
 consumes it. If the shape must change, it changes here first and #1406's fixtures change with
 it — never the reverse.
+
+---
+
+## 11. Narrowing the Class-2 backstop timers — stall detector, rollback trigger, monitoring window
+
+The Class-2 backstop timers that reconcile un-eventable transitions — `pr-review-sweep.yml`
+(§4, `backstop`) and `dev-lead-retry.yml` (§4, `self-heal`, the §6.3 leak) — are slated to be
+**narrowed** (#1407 / #1408) to cut the redundant fan-out they produce. Narrowing a safety net
+is exactly the pattern the #860 post-mortem warns against: it can trade a *known, noisy* failure
+mode (over-firing) for an *unknown, silent* one (a genuinely un-eventable transition that no fast
+path re-fires and, once the cron is narrowed, nothing sweeps). #1410 therefore builds the
+instrument **before** the net is narrowed, and defines the rollback path here so the decision is
+explicit, not tribal.
+
+### 11.1 The stall detector (the instrument)
+
+`scripts/lib/pr-stall-detect.sh` is a **detect-only** pure lib (mirroring
+`scripts/lib/pr-runaway-detect.sh`, §9 rule 2) — it never labels, comments, or halts. It flags an
+open PR that is **CI-green + `REVIEW_REQUIRED`, not reviewed at head, with no agent activity and no
+pending triggering event, idle longer than `STALL_MIN_AGE_MINUTES` (default 30 min — double the
+sweep's ≤15-min backstop cadence; **#1408 must re-derive this default when the sweep cadence
+is narrowed** so it remains ≥ 2× the new backstop interval)**. It is **fail-quiet on intentional stops**: a PR carrying
+`needs-human-review` (checked via `pr_has_escalation_label`, §6.2.3), `dev-lead:hands-off`, or
+`initiative:hold` (checked via a `STALL_HOLD_LABELS` loop) is never reported. The
+`<!-- pr-automation-budget exhausted -->` marker is **not inspected directly** — it is excluded
+only because budget exhaustion simultaneously applies `needs-human-review`; the marker alone does
+not gate stall detection, preserving re-engagement for PRs that have the marker but no hold label. `scripts/pr_stall_scan.sh` runs it over every open PR as an
+**additive step on the existing `daily-pr-review-health.yml`** and surfaces any candidate through
+the same health-check / automated-report issue channel — **no new scheduled workload** (§1: this
+adds a pushed signal and a documented human decision, not another automated brake). This is the
+push detection §7 rule 7 requires: the un-eventable green transition the narrowed cron would drop
+is caught here and **still resolves** (surfaced → human/backstop acts) instead of stalling unseen.
+
+### 11.2 The rollback trigger (the condition)
+
+**Trigger condition.** Roll back the narrowing if the stall detector reports **≥ 2 distinct
+stalled PRs within any rolling 24-hour window**, *or* **any single PR stalled for ≥ 4 hours** (≈8×
+the default threshold), during the monitoring window (§11.4). Either signal means the narrowed
+timer let a genuinely un-eventable transition sit unresolved — the silent failure mode the
+narrowing risked. A stall that is later explained by a human-gate marker does **not** count (it is
+excluded by design and never reported). One transient single-PR stall under the 4-hour bar is a
+watch item, not a revert.
+
+Both thresholds are deliberately low: the cost of a false rollback is a return to the *known* noisy
+state (fully recoverable), while the cost of tolerating a silent stall is the #860 blindness. When
+in doubt, revert.
+
+### 11.3 The revert procedure (the exact steps)
+
+The narrowing lands as one or more PRs that edit the `schedule.cron` (and/or the `workflow_run`
+scoping) of `pr-review-sweep.yml` / `dev-lead-retry.yml`. To revert:
+
+1. **Identify** the merged narrowing PR(s) for #1407 / #1408 (labelled against those issues).
+2. **Revert** them — `git revert <merge-sha>` for each, in reverse merge order — restoring
+   `pr-review-sweep.yml`'s guaranteed backstop cadence (`schedule: '2,17,32,47 * * * *'`, ≤15 min)
+   and `dev-lead-retry.yml`'s `schedule: '15 */2 * * *'`. Do **not** hand-edit the cron to a
+   guessed value; restore the exact pre-narrowing lines from history so the backstop returns to its
+   proven state.
+3. **Open the revert PR** referencing the triggering stall issue(s), and confirm CI green +
+   `validate-workflow-schedules` passing (the restored crons are non-minute-0, AGENTS.md
+   "Scheduled workflows").
+4. **Verify recovery**: after merge, confirm the previously-stalled PR(s) get re-reviewed on the
+   next backstop tick and the daily stall scan returns to all-clear.
+5. **Record** the rollback as a comment on the epic (#1402) and this story (#1410) — the go/no-go
+   audit trail this repo uses for every safety-net change (mirrors the fleet-remediation
+   human-gate record in AGENTS.md). Reverting is the *expected*, low-cost response to the trigger,
+   not an incident.
+
+### 11.4 The monitoring window (how long, who checks)
+
+**Window.** The narrowed timers run under observation for **14 days** after the narrowing merges
+(≥14 daily stall-scan runs — a full two weeks covers weekday *and* weekend PR cadence, since some
+un-eventable transitions only appear under low-traffic conditions). The change is considered
+**settled** only after 14 consecutive days with **zero** rollback-trigger hits (§11.2).
+
+**Who/what checks.** The **daily `daily-pr-review-health.yml` stall scan** is the automated watcher
+— it is the pushed signal, so no human has to remember to look (the #860 anti-pattern). A stall
+candidate opens a `health-check` / `automated-report` issue labelled for **dev-lead** attention,
+which is the human checkpoint. During the 14-day window, treat any stall-candidate issue as a
+rollback decision per §11.2 rather than a routine triage item. After the window settles, the stall
+scan remains as a **permanent** detector (it is cheap and detect-only) — settling ends the
+*heightened* watch, not the instrument.
@@ -107,6 +107,42 @@ inputs.
    marker) — the idempotency guarantee that let the standalone `idea-enhancer`
    be retired (#876).
 
+There is exactly **one** Discussion-triggered enhancer. The standalone
+`idea-enhancer.yml` (with its `scripts/idea-enhancer/` tooling) has been
+**removed** (#876) now that its capability is fully folded into the
+`feature-ideation` reusable workflow (epic #872) — so a human-authored idea is
+enhanced **once**, never twice.
+
+For each open, human-authored, not-yet-enhanced **Ideas** Discussion the folded
+enhancer posts **one** comment (sharpened problem/goal, repo + market context,
+impact/effort, suggested acceptance criteria). Bot-authored ideas are skipped —
+they are already AI-generated. It never approves, labels, or promotes — that
+stays with triage and the human gates.
+
+The enhancement logic lives in the **central** reusable `petry-projects/.github`
+(`feature-ideation-reusable.yml`); `.github-private` ships only the thin
+`feature-ideation.yml` caller stub (pinned to the `@feature-ideation/next`
+dogfood ring), which exposes the enhancement modes as `workflow_dispatch`
+inputs.
+
+- **Backfill sweep** — dispatch `feature-ideation` with `enhance_backlog: true`.
+  It sweeps the target repo's open, human-authored, not-yet-enhanced **Ideas**
+  Discussions and posts **exactly one** structured enhancement comment each.
+  Bot-authored and already-enhanced ideas are skipped. This is the safety-net
+  backfill that catches human ideas added before the folded enhancer went live.
+- **Dry-run** — dispatch with `dry_run: true` **and** `enhance_backlog: true`.
+  Every intended per-Discussion enhancement comment is logged to the JSONL
+  artifact and **nothing** is posted (one artifact entry per candidate
+  Discussion). The dry-run is free of model spend beyond candidate gathering.
+- **Marker continuity (cutover-safe).** The idempotency check honors **both**
+  the legacy `<!-- idea-enhancer:enhanced -->` marker and the canonical
+  `<!-- feature-ideation:enhanced -->` marker; new enhancement comments emit the
+  single canonical marker. So **no** idea enhanced by the old `idea-enhancer` is
+  re-enhanced after the cutover, and a repeated backfill is a no-op.
+- **Cost.** Operator-triggered (`workflow_dispatch`), **no new cron** — the
+  backfill reuses `feature-ideation`'s existing model budget and 20-minute
+  timeout, so it is cost-neutral-to-reducing.
+
 ### `idea-triage.yml` — weekly ripeness shortlist
 - Scans every open **Ideas** Discussion, scores each **Ripe / Soon / Not yet**
   on evidence, prerequisites, alignment, coverage, and freshness.