dev-loops 0.1.0

package/skills/copilot-pr-followup/SKILL.md

@@ -0,0 +1,380 @@
+---
+name: copilot-pr-followup
+description: >-
+  Internal routed strategy behind `dev-loop` for GitHub-first Copilot-owned PR
+  follow-up: inspect the canonical PR state, request or re-request Copilot when
+  appropriate, wait deterministically for new review activity, run narrow Pi
+  fix/reply/resolve passes, verify gate evidence, and stop for explicit human
+  approval before merge.
+compatibility: Internal routed strategy for Copilot PR follow-up. Needs gh auth for PR-followup automation.
+allowed-tools: read bash edit write subagent review_loop
+user-invocable: false
+---
+
+# Copilot PR Follow-up
+
+This skill is the canonical internal `copilot_pr_followup` route behind the public `dev-loop` façade.
+
+It is also the canonical internal owner of the shared post-PR mechanics used by this repo:
+PR discovery and interpretation, async watch behavior, fix / reply-resolve / re-request flow,
+gate sequencing, final approval, and merge-ready preconditions.
+
+## Route ownership
+
+Use this skill whenever the public router lands on any PR-follow-up path that shares the same
+post-PR mechanics:
+- `copilot_pr_followup`
+- `external_pr_followup`
+- `reviewer_fixer`
+- `wait_watch`
+
+Route-specific companion docs:
+- routed `issue_intake` work is implemented through this skill plus [Copilot Loop Operations](../docs/copilot-loop-operations.md) and [Issue Intake Procedure](../docs/issue-intake-procedure.md)
+- routed `final_approval` work is implemented through this skill's **Human approval checkpoint** section; [Final Approval](../final-approval/SKILL.md) is now a thin redirect to that canonical section
+- the deterministic state-machine/operator guide lives in [Copilot Loop Operations](../docs/copilot-loop-operations.md)
+
+## Operational cookbook
+
+All commands use the resolved skill scripts directory (see [Skill asset path resolution](#skill-asset-path-resolution) below).
+
+**1. Detect current loop state**
+```sh
+node <resolved-skill-scripts>/loop/detect-copilot-loop-state.mjs --repo <owner/name> --pr <number>
+```
+Emits JSON including `{ ok: true, state, allowedTransitions, nextAction, snapshot }`. Follow `nextAction`.
+
+**2. One-step detect → request → emit watch params (preferred handoff contract)**
+```sh
+node <resolved-skill-scripts>/loop/copilot-pr-handoff.mjs --repo <owner/name> --pr <number>
+```
+Use this helper output as source of truth for the normal routing seam. Interpret:
+- `requestWatchContract.routingState` for request-vs-watch posture
+- `requestWatchContract.requestStatus` and top-level `action` / `nextAction`
+- `watchArgs` only when `action: "watch"` and `requestWatchContract.watchEntryConfirmed=true`
+- `requestWatchContract.stopState` for explicit blocked/stop handling
+
+**3. Preferred async wait-boundary helper**
+```sh
+node <resolved-skill-scripts>/loop/run-watch-cycle.mjs --repo <owner/name> --pr <number>
+```
+Persistent async watch/fix loop, not handoff-only behavior: `watch → detect → if threads found, fix + reply + resolve → re-request → watch again → … → pre_approval_gate → merge`. **PERSISTENCE MODEL: Subagents do bounded implementation tasks and exit on external wait. The main session drives the loop and re-dispatches when continuation is feasible.** A single returned watch cycle is never completion by itself. If `cycleDisposition` is `pending` and `terminal` is `false`, the subagent exits on the wait boundary; the main session re-dispatches another watch boundary. Max watch timeout: **30 minutes** (from `policy-constants.mjs` COPILOT_REVIEW_WAIT_TIMEOUT_MS); expired budget + still `waiting_for_copilot_review` = hard stop. If the user explicitly asks for async handoff-only behavior, say that out loud and stop after the handoff boundary.
+
+**4. Low-level helpers**
+```sh
+node <resolved-skill-scripts>/github/request-copilot-review.mjs --help
+node <resolved-skill-scripts>/github/probe-copilot-review.mjs --help
+node <resolved-skill-scripts>/loop/detect-copilot-loop-state.mjs --help
+```
+
+For detailed machine guarantees, judgment calls, pre-follow-up planning rules, PR description rules, and timeout defaults, use [Copilot Loop Operations](../docs/copilot-loop-operations.md).
+
+## Required startup reads
+
+Read the canonical entrypoint briefing first: [Entrypoint Strategies](../docs/entrypoint-strategies.md#copilot-pr-follow-up). Then read only the contract docs needed for the current step:
+
+- [Agent Instructions](../../AGENTS.md) (repo constitution)
+- [Public Dev Loop Contract](../docs/public-dev-loop-contract.md) (always)
+- [Retrospective Checkpoint Contract](../docs/retrospective-checkpoint-contract.md) (when async state/resume applies)
+- Active GitHub issue/PR
+- Task-relevant source, tests, config, and CI
+
+Route-dependent: see [Copilot Loop Operations](../docs/copilot-loop-operations.md) and [Issue Intake Procedure](../docs/issue-intake-procedure.md) when relevant.
+Verify all material claims against source, tests, configuration, and CI.
+
+## Skill asset path resolution
+
+When this skill refers to helper paths such as `scripts/...` or `docs/...`, resolve them from the actual skill installation layout you are running, not from the active target repository checkout.
+
+Use this rule:
+- if the skill is installed as a normalized standalone copy, the required bundled contract docs live under the shared `../docs/` directory next to the installed skill directories; do not assume helper scripts are bundled unless that installed layout actually contains them
+- if you are working in the `dev-loops` source repository, this skill file lives under `skills/copilot-pr-followup/`, so source-repo helper scripts live two levels up at `../../scripts/`, while required bundled contract docs live one level up at `../docs/`
+- when in doubt, resolve helper paths relative to this [skill file](./SKILL.md) first, then verify the target file exists before running it
+
+Required bundled runtime contract docs for installed copies of this skill:
+- [Public Dev Loop Contract](../docs/public-dev-loop-contract.md)
+- [Retrospective Checkpoint Contract](../docs/retrospective-checkpoint-contract.md)
+- [Issue Intake Procedure](../docs/issue-intake-procedure.md)
+- [Copilot Loop Operations](../docs/copilot-loop-operations.md)
+
+Read those bundled `../docs/` files from the installed skill layout instead of assuming the source repository checkout is present. If any required bundled contract doc is missing from the installed skill layout, treat that as a packaging/installer bug.
+Do not assume `scripts/...` is repo-local to the target codebase you are operating on.
+
+## Authority and safety rules
+
+Source code, tests, CI, and config are authoritative. Generated wiki is navigation aid only. See [Confirmation Rules](../docs/confirmation-rules.md), [Stop Conditions](../docs/stop-conditions.md), and [Merge Preconditions](../docs/merge-preconditions.md) for authorization boundaries.
+
+## Structural quality
+
+Apply [Structural Quality](../docs/structural-quality.md) standards from the `deep` review angle during implementation and follow-up fixes.
+
+## Step 5: PR discovery and interpretation
+
+Treat the PR as the main working artifact once it exists.
+
+Inspect: PR body/title (must satisfy [PR description contract](../docs/copilot-loop-operations.md)), closing reference (operator-controlled; subagents must NOT modify), author, review summaries, unresolved comments, latest commits, CI results.
+
+At the issue-assignment seam, use `detect-initial-copilot-pr-state.mjs` and keep waiting when `waiting_for_initial_copilot_implementation`.
+
+When confirming whether Copilot is requested as a reviewer, do not rely solely on `gh pr view --json reviewRequests`. Use `request-copilot-review.mjs` (see [Operational cookbook](#operational-cookbook)). Do **not** request Copilot by posting literal `/copilot` or `/copilot re-review` PR comments. After draft→ready or fix push, explicitly decide whether another pass is desired; if yes, ensure green/credibly green posture first.
+
+Branch on the `request-copilot-review.mjs` machine-readable result:
+- `requested`: if another Copilot pass is actually desired, immediately re-baseline with `detect-copilot-loop-state.mjs` and follow its `nextAction` (enter persistent wait only through `dev-loops loop watch-cycle` or `gh run watch`)
+- `already-requested`: apply the same detector-first rebasing and wait branching as `requested`
+- `suppressed_same_head_clean`: report clean-converged state and stop unless `--force-rerequest-review` bypass is intentionally authorized
+- `unavailable`: report the limitation and stop
+- non-zero / unexpected failure: stop and report error
+
+Do not treat an attempted request as equivalent to a confirmed request.
+
+### Re-attachment guard (check for existing loop state first)
+
+Before entering issue-intake normalization or asking "what should we do" for a PR that
+already has an outer-loop checkpoint, check whether the checkpoint implies an auto-resume:
+
+1. Read the existing outer-loop checkpoint from
+   `tmp/copilot-loop/<owner>/<repo>/pr-<n>/outer-loop-state.json`.
+   Do **not** run `outer-loop.mjs` for this guard — it always rewrites the checkpoint
+   (including `timestamp` and potentially incrementing `waitCycles`).
+   Read the on-disk artifact without mutating it.
+2. If `outerAction` is `continue_wait`:
+   - The loop was waiting. The subagent exits; the main session re-dispatches a fresh
+     `dev-loop` async subagent that resumes from the checkpoint.
+3. If `outerAction` is `reenter_copilot_loop`:
+   - The copilot inner loop needs action. Run `copilot-pr-handoff.mjs` to determine the
+     exact next step and proceed.
+4. If `outerAction` is `reenter_reviewer_loop`:
+   - The reviewer inner loop needs action. Enter the reviewer-loop path.
+5. If `outerAction` is `stop`:
+   - Report the `reason` field and ask for direction.
+6. If no checkpoint exists or `outerAction` is `done`:
+   - Continue with normal step sequencing.
+
+Do not skip this guard when transitioning between async subagent runs on the same PR.
+The outer-loop checkpoint is the canonical re-attachment artifact for the subagent.
+
+## Step 6: Async watch behavior
+
+Start every wait seam with a detector refresh: `detect-copilot-loop-state.mjs --repo <owner/name> --pr <number>`.
+
+Allowed wait tools: `detect-copilot-loop-state.mjs` (one-shot), `dev-loops loop watch-cycle` (persistent), `copilot-pr-handoff.mjs --watch-status` (refresh after timeout/idle), `gh run watch <run-id> --repo <owner/name>` (CI with known run id). Otherwise exit and resume later from fresh detector call.
+
+Practical rules: do not poll manually. `waiting_for_copilot_review` → `run-watch-cycle.mjs` or report-and-resume. `waiting_for_ci` with pending/none CI → `gh run watch <run-id> --repo <owner/name>` (known run id) or report-and-resume. Bounded CI exception: zero current-head suites + previous-head green + local `npm run verify` passed → rerun detector with `--local-validation-head-sha` for `crediblyGreen` promotion. `ciStatus=failure` → stop/fix, never wait.
+
+Preferred approach:
+- route decisions through `copilot-pr-handoff.mjs` output; enter watcher only on `action: "watch"` with `watchEntryConfirmed=true`; prefer `dev-loops loop watch-cycle` for deterministic handoff → watch
+- `changed` → re-enter Step 7 fix/reply-resolve/validate immediately; do not stop after one watch cycle
+- `timeout`/`idle` → re-run `copilot-pr-handoff.mjs --watch-status <status>` once to refresh state; if still `waiting_for_copilot_review` after 30-minute watch budget exhausted, hard stop with `watch timeout — PR #<number> needs manual attention`
+- zero-timeout `idle` probes are for explicit one-shot status/reattach checks only; they are not the normal async wait mechanism
+- after a successful fix / reply-resolve / re-request cycle, returning to `waiting_for_copilot_review` is a persistence boundary: resume the watcher instead of reporting completion
+- if a child async run exits and the refreshed state remains non-terminal (for example `waiting_for_copilot_review`) before merge and without a hard stop, treat that as early exit and the main session re-dispatches the same-PR follow-up path when feasible (the subagent exits on external wait)
+- dispatch fix findings to `fixer` subagent; do not run inline fix passes in-watcher
+- do not report completion while unresolved Copilot feedback remains
+
+### Canonical async dispatch wording
+
+Every async dev-loop dispatch task body must include this clause verbatim so fresh-context subagents inherit the gate requirement:
+
+> Before reporting merge-ready or stopping at the human approval checkpoint, you must complete the pre_approval_gate procedure and verify that a visible clean checkpoint verdict comment exists on the PR for the current head SHA. Do not stop or report completion without this evidence.
+
+Key rules:
+- helper-owned sleep inside `dev-loops loop watch-cycle`, `dev-loops gate probe-copilot`, or `dev-loops loop watch-initial` is allowed
+- agent-authored shell polling is forbidden: do not use `nohup`, detached shell jobs, `tmux`, `screen`, or ad hoc `for i in $(seq ...)`, `while true`, `until ...; do sleep ...; done`, or `sleep`-retry bash loops
+- do not wrap repeated `gh pr view`, `gh pr checks`, `gh api`, or `detect-copilot-loop-state.mjs` calls inside shell polling loops
+- do not bypass session-based async notifications with detached shell automation
+- if Pi async subagents or the designated async follow-up skill are not appropriate or available, stop and report rather than improvising a shell watcher
+- the async-start contract is enforced in code: `outer-loop.mjs` fails closed without a visible Pi-managed async run id when `workflow.asyncStartMode: required`
+
+### Async delegation guard rules (#524)
+
+See [Async delegation guard rules](../dev-loop/SKILL.md#async-delegation-guard-rules-524) in the public `dev-loop` skill. Those rules are authoritative and apply to all async subagent dispatch in the PR-followup pipeline. The dev-loop skill is the single source of truth; this section exists only to ensure the rules are visible when this skill is loaded standalone.
+
+## Step 7: Pi review/fix follow-up loop
+
+This step covers four responsibilities: the draft gate right before `gh pr ready`, the narrower post-review follow-up loop once unresolved feedback exists, the pre-approval gate before calling the PR merge-ready, and the final approval / merge boundary.
+
+### Follow-up loop when unresolved feedback exists
+
+When unresolved feedback exists, use a narrow follow-up loop:
+
+1. inspect unresolved comments/threads and failing checks
+2. before the first local file write in each fixer pass on a Copilot-assigned PR, run `node <resolved-skill-scripts>/loop/pre-write-remote-freshness-guard.mjs --branch <headRefName>` as a required fail-closed guard
+   - source `<headRefName>` from authoritative PR state (`headRefName`), not from a local branch guess
+   - if the guard exits non-zero (`remote_ahead`), stop writing locally, reconcile to the refreshed remote head, then restart the fixer pass
+3. classify findings:
+   - must-fix: blocks gate; always fixed
+   - worth-fixing-now: blocks gate when `blockCleanOnFindingSeverities` includes it; fixed when blocking
+   - defer / non-blocking / disagree
+4. apply only the accepted narrow fixes
+5. run the smallest validation that honestly proves the fix
+6. if files changed, run `node <resolved-skill-scripts>/loop/pre-commit-branch-guard.mjs --expected-branch <headRefName>` immediately before every `git add && git commit` sequence as a required fail-closed guard
+   - source `<headRefName>` from authoritative PR state (`headRefName`), not from a local branch guess
+   - if the guard exits non-zero (`branch_mismatch`), stop and realign to the expected branch before staging or committing
+7. if files changed, push the resolving commit before any thread reply claims the fix is present
+8. when a comment or thread is actually addressed, reply on GitHub with a short resolution note that references the resolving commit SHA or commit URL when applicable
+   - for one thread, must use the deterministic helper `reply-resolve-review-thread.mjs` from the resolved skill scripts directory
+   - when the same bounded resolution note applies to multiple matching unresolved threads, use `reply-resolve-review-threads.mjs` instead of ad hoc inline `gh api` / `gh api graphql` mutations
+   - when using the single-thread helper, pair `--comment-id` and `--thread-id` from the same fresh PR thread snapshot rather than mixing ids across review rounds
+   - use a body file under `tmp/` rather than inline shell text for the single-thread reply body; for the batch helper, prefer stdin from that same `tmp/` body file rather than inline shell text
+   - when the intent is GitHub linkability, keep commit SHAs and issue/PR refs as plain text (for example 3ee82fc and owner/repo#70) and do not wrap them in backticks
+   - keep backticks for actual code/path/CLI literals only
+   - if either helper was newly added or recently changed, smoke-check it against one real thread before assuming the rest of the loop can rely on it
+9. before resolving an addressed review thread, run a post-fix verification checkpoint
+   - confirm the GitHub reply actually exists on the intended thread/comment, not only in local notes or helper stdout
+   - confirm the pushed current-head diff genuinely addresses the reviewer concern on the flagged lines or pattern; if the concern is only partially addressed, leave the thread open and explain what remains
+   - refresh the API-backed thread snapshot via `dev-loops gate capture-threads` and use that refreshed data — including the unresolved thread count — for follow-up decisions rather than prose assumptions
+   - if any verification check fails, do **not** resolve the thread; leave it open, add a short explanation when needed, and re-enter the fix/reply loop
+10. resolve the addressed review thread only after the reply is attached successfully, the verification checkpoint passes, and the concern is genuinely addressed
+    - do not stop at a local fix if GitHub-side reply/resolve is authorized
+11. after completing reply/resolve for a pass, verify zero unresolved threads remain via `dev-loops gate capture-threads` before proceeding
+    - if the refreshed snapshot reports unresolved threads, re-enter the reply/resolve loop for the missed threads
+12. only after GitHub-side reply/resolve work is done for the addressed threads and the refreshed thread snapshot proves zero unresolved threads remain, decide whether another Copilot pass is desired
+    - resolve the review-round cap from config via `resolveRefinementConfig(config, "maxCopilotRounds")` from `@dev-loops/core/config`; default config ships `maxCopilotRounds: 5`
+    - use the completed Copilot review-round count from `detect-copilot-loop-state.mjs` / `copilot-pr-handoff.mjs` as the current PR's review-round count
+    - if completed review rounds have reached the maximum (default: 5), do **not** re-request Copilot review
+    - when the round limit is reached **and** the refreshed thread snapshot proves zero unresolved threads **and** current-head CI is green or credibly green, treat that clean state as eligible for `pre_approval_gate` fallback instead of deadlocking on another Copilot rerequest
+    - when using that fallback, add a short round-exhaustion note to the visible `pre_approval_gate` gate evidence so the PR records why no further Copilot rerequest occurred
+    - if the round cap is reached before the PR is thread-clean or before CI is green/credibly green, reply-resolve any remaining intentionally deferred threads with a short `deferred to follow-up` note, then stop and report that the Copilot round limit was reached
+    - **Signal-gated re-request suppression:** the `detect-copilot-loop-state.mjs` state machine classifies review-thread comments by signal level (High/Mid/Low). High-signal (bugs, security, contract violations) always re-requests; Low-signal (cosmetic nits) never re-requests. When low-signal detection is enabled and thresholds are met, the machine returns a low-signal-converged terminal state routing to `pre_approval_gate` without further re-requests. See [Copilot Loop Operations](../docs/copilot-loop-operations.md) for full signal-level semantics.
+    - if that local validation is still known red, continue remediation instead of re-requesting Copilot
+    - after a fix push advances the PR head SHA, re-run `detect-copilot-loop-state.mjs` for the new head and apply the [Copilot CI Status Contract](../docs/copilot-ci-status-contract.md). Previous-head CI is stale; only current-head results unblock CI-dependent steps. if GitHub CI/checks for the updated head are known red for a fixable issue, continue remediation instead of re-requesting Copilot. only once the updated head is green or credibly green, explicitly re-request Copilot review for the new head. Always use `request-copilot-review.mjs` — never `gh api POST repos/.../requested_reviewers` directly.
+    - only enter a wait/watch loop if the request result is confirmed as `requested` or `already-requested`
+    - for `requested` / `already-requested`, immediately re-baseline with `detect-copilot-loop-state.mjs`; if the returned state is `waiting_for_copilot_review`, use `dev-loops loop watch-cycle` or stop/resume later, and if the returned state is `waiting_for_ci`, use `gh run watch` for a known run id or stop/resume later after that single detector refresh
+    - if the request result is `unavailable`, report that limitation and stop unless the user explicitly wants passive waiting anyway
+    - if the request command fails unexpectedly, stop and report the error rather than sleeping and hoping for a new review
+13. after a confirmed re-requested Copilot pass, refresh PR thread state again before reporting completion; if fresh Copilot threads exist, return to this follow-up loop rather than stopping at `review requested`
+14. after a confirmed re-request returns the PR to `waiting_for_copilot_review`, jump back to Step 6 and keep the same session alive; do not exit on `review requested` alone
+15. if scope has broadened, stop and ask before continuing
+
+Do not treat `fix applied locally` as the end of the loop when the workflow also requires GitHub-side reviewer follow-up. If comment/reply authorization is withheld, report explicitly that the code may be fixed while the PR conversation state remains unresolved.
+
+### Mandatory gate-comment command contract
+
+For every `draft_gate` or `pre_approval_gate` comment, you MUST run:
+
+```sh
+node <resolved-skill-scripts>/github/upsert-checkpoint-verdict.mjs \
+  --repo <owner/name> \
+  --pr <number> \
+  --gate <draft_gate|pre_approval_gate> \
+  --head-sha <current_head_sha> \
+  --verdict <clean|findings_present|blocked> \
+  --findings-summary "<summary>" \
+  --next-action "<next action>" --findings-severity-counts '{"must-fix":0,"worth-fixing-now":0,"defer":0}'
+```
+
+Do NOT use `gh pr comment`, `gh api`, or `gh pr review` for gate comments.
+
+`--force --force-reason` on `upsert-checkpoint-verdict.mjs` is a narrow operator-authorized CI override for the helper itself, not the default gate path. Use it only when the helper refuses gate entry solely because the current head is `blocked_needs_user_decision` with `ciStatus="failure"`, and only after the user explicitly authorizes ignoring that current-head CI failure for this one gate-comment upsert. It does **not** bypass stale-head checks, unresolved-thread / unsettled-review refusal, non-draft `draft_gate` refusal, merge conflicts, or other legality checks.
+
+### Draft gate contract (before marking PR ready for review)
+
+The canonical checkpoint verdict comment contract is [Gate Review Comment Contract](../../docs/gate-review-comment-contract.md). This section summarizes the procedural integration only.
+
+- **Gate name:** Draft gate
+- **Trigger / boundary:** right before running `gh pr ready` (draft → ready for review)
+- **Skip rule:** before entering the draft gate, run `detect-pr-gate-coordination-state.mjs` and check `draftGateAlreadySatisfied`. If `true`, skip the draft gate entirely — the draft→ready transition was already recorded. `draft_gate` is a one-time gate; do not re-post on new heads once clean draft-gate evidence exists for the transition record. (While the PR is still draft, advancing the head SHA does require a new draft-gate comment for the new head.) This skip rule applies only to the draft boundary.
+- **Execution directive:** run the checkpoint review chain defined in [Gate Review Sub-Loop Contract](../../docs/gate-review-sub-loop-contract.md) with the draft gate inspection angles resolved from config.
+- **Review angles:** resolved at runtime from config via `resolveGateAngles(config, "draft")` from `@dev-loops/core/config`. Default config enables all configured draft gate angle families; consumer repos may opt out individual angles via `excludeAngles`. Do **not** apply angles from the other gate; each gate owns its own angle list from config.
+- **CI prerequisite:** resolve the draft gate config first (`resolveGateConfig(config, "draft")`). When `requireCi=true` (default), wait for green current-head CI before entering `draft_gate`. When `requireCi=false`, the draft gate may proceed without green CI. This draft-only override does **not** relax `pre_approval_gate`; final approval and merge readiness still require green current-head CI.
+- **Pass criteria:** all configured draft gate angles pass; all findings at severities in `blockCleanOnFindingSeverities` are addressed; validation passes; no unrelated files are included.
+- **Next step after passing:** mark the PR ready for review.
+- **Non-substitution rule:** a clean `draft_gate` comment only authorizes the draft → ready-for-review transition for that head SHA. It does **not** satisfy `pre_approval_gate`, final-approval readiness, or merge-ready requirements.
+- **Required PR comment:** post a visible checkpoint verdict comment using the mandatory [Gate comment command](#mandatory-gate-comment-command-contract). Keep validation reporting concise: include command names with pass/fail status. Do **not** paste raw passing test output into the visible gate comment. If you include a failing validation excerpt, keep it focused and truncate it to a deterministic retained-prefix length before posting the comment. See [Gate Review Comment Contract](../../docs/gate-review-comment-contract.md). Do not run `gh pr ready` unless a visible `clean` `draft_gate` checkpoint verdict comment exists for the current head SHA. A checkpoint verdict comment for an older head SHA does not satisfy this requirement for the current head. If findings exist, the PR stays draft and needs fixes before retry. If fixes advance the head SHA while still draft, post a new checkpoint verdict comment for the new head. If the checkpoint verdict comment cannot be posted, fail closed and do not run `gh pr ready`.
+
+### Pre-approval gate contract
+
+This is the default pre-approval gate for this workflow boundary. The canonical checkpoint verdict comment contract is [Gate Review Comment Contract](../../docs/gate-review-comment-contract.md). This section summarizes the procedural integration only.
+
+- **Gate name:** Pre-approval gate
+- **Trigger / boundary:** right before calling a PR/branch review-complete, approval-ready, merge-ready, or ready for final handoff
+- **Execution directive:** run the checkpoint review chain defined in [Gate Review Sub-Loop Contract](../../docs/gate-review-sub-loop-contract.md) with the pre-approval gate inspection angles resolved from config. Retry rule: in subsequent cycles, only re-run reviewers that produced `findings_present` in the previous pass.
+- **Review angles:** resolved at runtime from config via `resolveGateAngles(config, "preApproval")` from `@dev-loops/core/config`. Default config enables all configured pre-approval gate angle families; consumer repos may opt out individual angles via `excludeAngles`.
+- **Persona mapping:** each angle resolves to a reviewer persona via `resolveReviewerRole(config, angle)` from `@dev-loops/core/config`. Include this prompt in each reviewer's briefing so the reviewer knows exactly what to look for.
+- **Pass criteria:** the sub-loop completes with verdict `clean`; all configured angles pass; if parallel execution is impractical, still run all configured lenses and explicitly record the limitation.
+- **Acceptance criteria verification:** follow the canonical procedure in [Acceptance Criteria Verification](../docs/acceptance-criteria-verification.md) before posting the `pre_approval_gate` comment.
+- **Next step after passing:** continue the Step 7 flow and then proceed to the human approval checkpoint below.
+- **Non-substitution rule:** a clean `pre_approval_gate` comment is separate from `draft_gate` evidence. It governs final-approval readiness for that head SHA; it does **not** replace the required `draft_gate` evidence for leaving draft.
+- **Required PR comment:** post a visible checkpoint verdict comment using the mandatory [Gate comment command](#mandatory-gate-comment-command-contract). Keep validation reporting concise: include command names with pass/fail status. Do **not** paste raw passing test output into the visible gate comment. If you include a failing validation excerpt, keep it focused and truncate it to a deterministic retained-prefix length before posting the comment. Do not declare final-approval readiness unless a visible `clean` `pre_approval_gate` checkpoint verdict comment exists for the current head SHA. Final-approval readiness must not rely only on local or hidden artifacts; the visible PR comment is the required auditable evidence. If the checkpoint verdict comment cannot be posted, fail closed and do not declare final-approval readiness. A checkpoint verdict comment for an older head SHA does not satisfy this requirement for the current head. If findings exist, follow-up fixes are required before final approval. The `pre_approval_gate` procedure must be entered and completed (visible comment posted) before any merge-ready or approval-ready declaration. Skipping the gate is not recoverable by asserting convergence. If fixes advance the head SHA, post a new checkpoint verdict comment for the new head.
+
+### Conflict-resolution gate
+
+Before any merge-ready or final-approval claim, run `detect-pr-gate-coordination-state.mjs` for the current PR. If it reports `gateBoundary=conflict_resolution` or `mergeStateStatus` is conflicted, stop the normal gate path immediately and use this recovery flow:
+
+1. fetch fresh `origin/main`, confirm the current PR head SHA, and summarize the conflict scope from `mergeStateStatus` plus any reported `conflictFiles`
+2. ask for explicit authorization before any rebase or other branch-state-changing reconciliation command
+3. after authorization, reconcile locally on the PR branch; default to rebase onto latest `origin/main`, unless the operator explicitly chooses another conflict-resolution command
+4. auto-resolve simple conflicts when the correct fix is mechanical and clearly in scope; report complex conflicts explicitly and fix them manually only for in-scope files
+5. rerun the smallest honest local validation for the touched conflict slice
+6. rerun `detect-pr-gate-coordination-state.mjs` for the new head
+7. because the head changed, rerun `pre_approval_gate` for the new head before any approval-ready or merge-ready claim
+8. wait for current-head CI again before retrying merge evaluation
+9. if the chosen reconciliation rewrote branch history (for example rebase), ask for explicit authorization before `git push --force-with-lease`, then continue the loop on the updated head
+
+`mergeStateStatus: CLEAN` alone is not enough to resume approval or merge claims. The existing merge-ready preconditions still apply: zero unresolved review threads, a clean current-head `pre_approval_gate`, and green current-head CI.
+
+### Merge-ready preconditions
+
+See [Merge Preconditions](../docs/merge-preconditions.md). Verify: zero unresolved threads (via `dev-loops gate capture-threads`), visible clean `draft_gate` + current-head `pre_approval_gate`, green CI. Fresh-context review follows [Gate Review Sub-Loop Contract](../../docs/gate-review-sub-loop-contract.md).
+
+### Human approval checkpoint
+
+After merge-ready preconditions pass, verify [Merge Preconditions](../docs/merge-preconditions.md) authoritatively before reporting merge-ready. Stop at the human approval checkpoint by default. Cross-check via `dev-loops gate capture-threads` (not prose assertion).
+Follow [Merge Preconditions](../docs/merge-preconditions.md): stop at `waiting_for_merge_authorization` after approval unless merge explicitly authorized. Run pre-merge gate evidence check before any `gh pr merge`.
+
+### Mechanical pre-merge gate evidence check
+
+Immediately before any `gh pr merge`, run:
+
+```sh
+node <resolved-skill-scripts>/github/detect-checkpoint-evidence.mjs \
+  --repo <owner/name> \
+  --pr <number>
+```
+
+This helper is always-on: it uses `gh api` to fetch visible PR issue comments and fails closed unless both required gate comments exist: a clean `draft_gate` comment for the one-time draft boundary and a clean current-head `pre_approval_gate` comment. Do not run `gh pr merge` if this command exits non-zero. There is no opt-out flag. Resolved threads, green CI, clean Copilot rereview, or local notes do not substitute for this successful helper output. If a final approval or merge boundary sees `gh pr merge` without a same-boundary successful check, treat that as a workflow violation and stop.
+
+### Mandatory post-merge retrospective checkpoint write
+
+After a merge succeeds (or an explicit retrospective skip is authorized), write the durable retrospective checkpoint before exiting the subagent session:
+
+```sh
+node <resolved-skill-scripts>/loop/checkpoint-contract.mjs --state complete --notes "<one-line retrospective summary>"
+```
+
+For an explicit skip:
+
+```sh
+node <resolved-skill-scripts>/loop/checkpoint-contract.mjs --state skipped --reason "<why retrospective is skipped>"
+```
+
+Do not report completion or advance to the next PR queue item until `.pi/dev-loop-retrospective-checkpoint.json` is updated to `complete` or `skipped`.
+
+## Validation policy
+
+Follow [Validation Policy](../docs/validation-policy.md). Default: `npm run verify` before PR creation, gate entry, and merge. For repo-local examples: `npm run test:dev-loop` for skill scripts, contract tests for templates, `git diff --check` for docs. When CI runs exist, use `gh run watch` or `detect-copilot-loop-state.mjs` instead of `sleep`-based polling. Distinguish: locally validated, full PR-equivalent checks, awaiting CI.
+
+## Confirmation checkpoints
+
+See [Confirmation Rules](../docs/confirmation-rules.md). Stop and ask before GitHub mutations (edits, assignments, labels, comments, reviews, thread resolution, commits, pushes, merges, workflows) unless explicitly authorized.
+
+## Stop conditions
+
+Follow [Stop Conditions](../docs/stop-conditions.md). Genuine stops: `blocked` state, `done`, `approval_ready` without merge auth, ambiguous state, scope drift. Non-stops: `waiting` watcher states, quiet observations.
+
+## Anti-patterns
+
+See [Anti-patterns](../docs/anti-patterns.md). Key repo-specific additions:
+- Use `reply-resolve-review-thread.mjs` / `reply-resolve-review-threads.mjs` helpers instead of ad hoc `gh api`/`gh api graphql` thread-mutation commands. Do NOT use `gh pr comment`, `gh api`, or `gh pr review` for gate comments (use `upsert-checkpoint-verdict.mjs`).
+- Do not declare merge-ready without visible `pre_approval_gate` comment on current head SHA. Do not declare merge-ready based solely on `mergeable_state: clean` + CI green without gate evidence. CI green + resolved threads alone is insufficient.
+- Do not blind-run `gh pr merge`/`gh pr update-branch`/unapproved rebase when conflicted. Do not dispatch async dev-loop tasks that omit the pre-approval gate requirement.
+- Do not assume generated wiki is authoritative over code or CI.
+
+## Output expectations
+
+When using this skill, keep user-facing summaries concise and operational.
+
+A good status update should say:
+- what issue or PR you inspected
+- current state
+- what the next recommended action is
+- whether authorization is needed before taking it

package/skills/dev-loop/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: dev-loop
+description: >-
+  Single public dev-loop entrypoint. Resolve canonical current state first,
+  then load only route-specific internal skills.
+user-invocable: true
+compatibility: Pi skill for git+GitHub repositories. Requires gh auth; async follow-up works best in Pi/TelePi sessions.
+allowed-tools: read bash edit write subagent review_loop
+---
+
+**No-implicit-start rule:** Never start implementation without explicit instruction.
+
+**Work-origin rule:** All work must originate from a tracked artifact: a GitHub issue (tracker-first) or a persisted markdown plan file (local-planning). See [Artifact Authority Contract](../docs/artifact-authority-contract.md) for canonical mode definitions and settings. No work may originate from a PR or direct local change unless explicitly requested.
+
+# Unified Dev Loop
+
+This is the public `dev-loop` façade — a summary of the authoritative routing contract. The authoritative contract is [Public Dev Loop Contract](../docs/public-dev-loop-contract.md). Runtime evaluator: `@dev-loops/core/loop/public-dev-loop-routing`. For status/progress/readiness/merge-state/next-step queries, resolve authoritative artifact identity first; for issue targets, identity resolution is handled by the startup resolver. Fail closed to reconcile/unknown when unresolved. When an open linked PR exists, treat it as the single canonical artifact for the issue and reuse it instead of opening another PR.
+
+## Installed skill layout
+
+Required installed runtime contract docs are shared bundled copies under `../docs/` from this skill directory. Read those bundled `../docs/` files from the installed skill layout — do not assume a source checkout. If a required bundled contract doc is missing, treat it as a packaging/installer bug.
+
+## Startup procedure
+
+### Main agent (read-only)
+
+The main agent must **always** dispatch the `dev-loop` async subagent for any dev-loop work.
+Do not run `dev-loops loop startup` or any startup resolver in the main agent.
+The resolver requires `PI_SUBAGENT_RUN_ID` for async-required routes (the default `required` mode); the startup resolver can also run without it for non-async routes. Regardless, only the `dev-loop` async subagent runs it — never the main agent.
+
+### Dev-loop subagent (post-dispatch)
+
+The subagent resolves authoritative state via the startup resolver (`npx dev-loops loop startup --issue <n>` for issues, `npx dev-loops loop startup --pr <n>` for PRs), then immediately builds the handoff envelope via `npx dev-loops loop build-envelope --input <resolver-output.json>`. The envelope determines `requiredReads`, `nextAction`, `stopRules`, and `acceptance` — load only those files, execute only that bounded task. It is the first handoff artifact consumed before loading any route pack. See [Workflow Handoff Contract](../docs/workflow-handoff-contract.md) for the derivation contract.
+
+**Retrospective checkpoint gate:** the resolver reads `.pi/dev-loop-retrospective-checkpoint.json` and injects the state. When the checkpoint is `missing` and the repo config `workflow.requireRetrospective` (set via `.devloops` at repo root) is `true`, the resolver returns `needs_reconcile`. Complete or explicitly skip the retrospective before starting.
+
+**Pre-delegation gate (mandatory — subagent only):** Before delegating async work targeting an existing PR, the dev-loop subagent must run `node scripts/loop/copilot-pr-handoff.mjs --repo <owner/name> --pr <number>` and abort if `action: "stop"`. When `terminal: true`, proceed inline. When `terminal: false`, resolve the blocking condition first.
+
+**Worktree cwd (mandatory — subagent only):** Always use a worktree checkout for git operations, file reads/writes, and validation commands — never use the `main` checkout.
+
+**Worktree fetch (mandatory — subagent only):** Always run `git fetch origin` before creating or reusing any worktree.
+
+### Resume from existing loop state
+
+When the startup resolver returns a fresh-start routing but an existing outer-loop checkpoint
+(`tmp/copilot-loop/<owner>/<repo>/pr-<n>/outer-loop-state.json`) is present on disk, the
+subagent must check the checkpoint before treating the start as a fresh intake or follow-up:
+
+1. Read the outer-loop checkpoint (authored by `outer-loop.mjs`).
+2. If `outerAction` is `continue_wait`, `reenter_copilot_loop`, or `reenter_reviewer_loop`:
+   - Skip issue-intake normalization or fresh-intake routing.
+   - Route directly to the existing PR's follow-up path (the PR number is in the
+     checkpoint's `pr` field). For `reenter_copilot_loop`, enter the copilot-pr-followup
+     path. For `reenter_reviewer_loop`, enter the reviewer-loop path.
+   - Use the checkpoint's `copilotState` and `reviewerState` as last-known context for
+     re-attachment, then re-baseline with fresh detectors (`copilot-pr-handoff.mjs`
+     or `detect-copilot-loop-state.mjs`) before acting on the state.
+3. If `outerAction` is `stop`:
+   - Report the `reason` field and the authoritative state from the checkpoint.
+   - `stop` means the loop is blocked or needs a human decision; ask for direction
+     rather than guessing or starting fresh.
+4. If no checkpoint exists, or `outerAction` is `done`:
+   - Treat as normal fresh startup (the existing startup resolver path).
+
+This eliminates the manual "report-and-resume" or "exit and resume later" pattern when the
+deterministic state already knows the next action.
+
+The outer-loop checkpoint is the canonical re-attachment artifact. Do not rely on chat
+context, local notes, or prose recollection of "where we left off."
+
+## Route table
+
+Load only the route-specific internal skill required by `selectedStrategy`:
+
+| Strategy | Route pack to load |
+| --- | --- |
+| `local_implementation` | [Local Implementation Skill](../local-implementation/SKILL.md) |
+| `issue_intake` | [Copilot PR Follow-up Skill](../copilot-pr-followup/SKILL.md) + [Copilot Loop Operations](../docs/copilot-loop-operations.md) + [Issue Intake Procedure](../docs/issue-intake-procedure.md) |
+| `copilot_pr_followup` | [Copilot PR Follow-up Skill](../copilot-pr-followup/SKILL.md) + [Copilot Loop Operations](../docs/copilot-loop-operations.md) |
+| `external_pr_followup` | same as `copilot_pr_followup` |
+| `reviewer_fixer` | same as `copilot_pr_followup` |
+| `wait_watch` | same as `copilot_pr_followup` |
+| `final_approval` | same as `copilot_pr_followup` + [Final Approval Skill](../final-approval/SKILL.md) |
+
+Do not preload route packs before the resolver selects the strategy.
+
+## Async dispatch
+
+**Async dispatch rule (enforced):** the resolver enforces fail-closed for GitHub-first strategies when `canonicalStateSummary.requiresAsyncDispatch` is `true` (default `required` mode). Inline invocation without `PI_SUBAGENT_RUN_ID` is rejected only for those routes. See [Startup procedure](#startup-procedure).
+
+
+## Fallback gate-comment poster
+
+When the `@dev-loops/core` package is not installed in the consumer repo, the full `scripts/github/upsert-checkpoint-verdict.mjs` helper (referenced from the copilot-pr-followup skill procedure) is unavailable. To keep the PR audit trail intact in that mode, the dev-loop skill ships a small gh-only fallback poster at `scripts/post-gate-verdict-fallback.mjs` (relative to the dev-loop skill root) that renders the same visible comment format and fails closed if posting cannot succeed.
+
+Use the fallback poster only when the full helper cannot be reached:
+
+1. Detect the missing helper: try `node scripts/github/upsert-checkpoint-verdict.mjs --help` from the consumer repo. If the script is absent or imports fail, switch to the fallback path.
+2. Invoke the fallback from the installed dev-loop skill directory: `node <resolved-skill-scripts>/post-gate-verdict-fallback.mjs --repo <owner/name> --pr <number> --head-sha <sha> --verdict <clean|findings_present|blocked> (--findings-summary <text> | --findings-file <path>) --next-action <text> [--gate <draft_gate|pre_approval_gate>]`.
+3. Treat every successful fallback-posted gate comment as a one-shot create with no idempotent same-head update: if the agent reruns the gate on the same head, a duplicate comment will be created. Detect duplicates manually and update manually if needed.
+4. Treat every fallback-posted gate comment as a degraded audit-trail artifact: the visible body uses the same parser-stable shape as the full helper (gate name, head SHA, verdict, blocking severities when applicable, findings summary, next action), but the helper skips stale-head detection, gate-coordination validation, blocking-severity count enforcement, and the internal-only PR short-circuit.
+5. If the fallback helper exits non-zero, stop the gate and report the posting failure: do not mark the PR ready for review and do not proceed to merge readiness until the comment is posted.
+
+When `@dev-loops/core` is available again, switch back to the full helper. The fallback poster is a degraded path, not a permanent replacement.
+
+## Read-only info shortcut
+
+The main agent may handle info/handoff requests directly via `npx dev-loops loop info` without dispatching the async `dev-loop` subagent:
+- `npx dev-loops loop info --issue <n>` — human-readable issue state summary (strategy, route, linked PR, next action)
+- `npx dev-loops loop info --pr <n>` — human-readable PR state summary (branch, CI, threads, rounds, action)
+- `npx dev-loops loop info --issue <n> --json` — machine-readable JSON output
+
+## Guard rules (subagent reference)
+
+**Handoff envelope precedence:** The subagent builds the envelope immediately after authoritative-state resolution and treats it as the first handoff artifact. Read it first, load only `requiredReads`, execute `nextAction`. See [Dev-loop subagent](#dev-loop-subagent-post-dispatch). Derivation contract: [Workflow Handoff Contract](../docs/workflow-handoff-contract.md).
+
+**Handoff contract rule:** When no envelope is present, use the `workflow-handoff-contract.md` contract. Never delegate with abbreviated task summaries. Include deterministic routing inputs, explicit `cwd`, bounded task scope, exit conditions.
+
+**Inline-first rule:** Prefer inline commands over nested async delegation when managing a single PR. Use nested delegation only for parallel fan-out or when the parent needs to continue other work.
+
+**Bounded async task contract:** Break work into discrete tasks with clear inputs, explicit outputs, bounded scope. No shell polling — use `run-watch-cycle.mjs` or `gh run watch`.
+
+**Round-cap budget check (enforced):** After every watch cycle, fix pass, or reply-resolve, check whether completed Copilot review rounds have reached the maximum (default: 5). Stop re-requesting Copilot review when the limit is reached — never re-request after the cap.
+
+## Shorthand issue-based auto trigger contract
+
+- `auto dev loop on issue <n>` → public `dev-loop` intent `auto_continue_current` after authoritative current-state resolution
+- Continue through GitHub/Copilot loop until stop condition or human approval checkpoint
+- Stop at the human approval checkpoint by default unless merge explicitly authorized
+
+## No gate exemptions
+
+All PRs must pass the full gate pipeline before merge. No scope is exempt: docs-only, tooling, meta, configuration, internal-process — all require `draft_gate`, current-head `pre_approval_gate` evidence, and Copilot review (except internal-only PRs detected by path pattern, which skip the Copilot convergence requirement).
+
+## Authority boundary
+
+- Source code, tests, config, CI, and shared contract docs are authoritative.
+- Main-agent delegation contract: [Main Agent Contract](../docs/main-agent-contract.md) — absolute read-only boundary; all mutations flow through `dev-loop` async subagent.
+- Before any state-changing action, get explicit confirmation unless already authorized.
+- A question requires an answer, not an action.
+- Stop and ask rather than guessing when facts don't agree.