---
name: "dev-loop"
description: "Single public dev-loop entrypoint. Resolve canonical current state first, then load only route-specific internal skills."
allowed-tools: Read Bash Edit Write Agent
user-invocable: true
---
<!-- GENERATED from skills/dev-loop/SKILL.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->


**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), a persisted markdown plan file (local-planning), or — on the sanctioned lightweight path — the PR description itself as the spec-of-record (`--lightweight`, `canonicalSpecSource: pr_body`; no committed plan artifact; issue-less PR-first is size-gated by the same weighted light-mode cap predicate as gate dispatch unless `localImplementation.issueless` sanctions it at any change scope). See [Artifact Authority Contract](../docs/artifact-authority-contract.md) for canonical mode definitions and settings. No work may originate from a PR (other than the sanctioned lightweight PR-body-as-spec path) or a 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

**Review intent short-circuit (issue #1850):** A plain review request against a PR ("review PR #N", "review this PR") is NOT a continue/fix/merge request. In interactive intent handling, recognize it before ordinary startup and dispatch to the [Review Skill](../review/SKILL.md) (`/dev-loops:loop-review <pr>`, or `/loop-review <pr>` in this repo). A harness that drives startup directly selects the same route deterministically with `loop startup --pr <n> --review`; the selector is read-only and ownership-exempt, so routing no longer depends on an agent interpreting intent prose. The route performs no assignee claim, branch push, fix commit, merge, board move, or lifecycle gate evidence. Any continue/fix/merge/watch request proceeds through ordinary startup and remains ownership-gated as before.

**Startup claim (`--claim`):** On an unassigned target, pass `--claim` only when the user's own request explicitly asked to start or continue a loop on that exact target. Queue pickup, `info`, review routes and any request that does not name the target never pass `--claim`. A classifier or permission denial of the `--claim` startup call is a `DEV-LOOP-RUNNER-STOP-CONDITIONS` stop: quote the denial verbatim and do not retry in another command form.

**"Run the gates" is NOT review intent (issue #1913):** `review` is a `GATE_NAME` but it gates nothing (informational, blocks no transition — see the tier comment in `scripts/github/_gate-names.mjs`: `LIFECYCLE_GATES` vs `REVIEW_GATE`). So a request phrased around *gating* — "run this PR through the gates", "gate this PR", "gate PR #N" — with NO explicit "review" word MUST NOT match the review short-circuit above. The discriminator is the same one question the vocabulary encodes: **does it block a lifecycle transition?** "Run the gates" means the lifecycle gates (`draft_gate`, `pre_approval_gate`), which run inside the ordinary loop via the startup flow below — NOT the standalone `review` command. Route these requests through `loop startup`/`resolve-dev-loop-startup.mjs` like any other continue request; do not dispatch `/loop-review`.

### Resolve authoritative state

For an initial Codex conductor spawn, MAIN first consumes the config-only
`gate resolve-role --conductor --harness codex` result and applies its native
overrides per [Codex coordinator dispatch](../docs/main-agent-contract.md#codex-coordinator-dispatch).
Startup remains the child's first workflow action; configuration/native refusal
stops dispatch without an inherited replacement.

> Under the Claude Code harness the main session dispatches the `dev-loops:dev-loop` coordinator (`dev-loop` inside the dev-loops repo itself). The coordinator is one agent: it runs these steps and drives its own children. The main session runs no gate, fixer or reviewer step. The coordinator has an opt-in read-only boundary for tracked repo files and code-verification/build commands (`DEVLOOPS_COORDINATOR_READONLY=1`, enforced by the guard hooks). See [Main Agent Contract](../docs/main-agent-contract.md).

Resolve authoritative state via the startup resolver (`dev-loops-run cli/index.mjs loop startup --issue <n>` for issues, `dev-loops-run cli/index.mjs loop startup --pr <n>` for PRs), then immediately build the handoff envelope via `dev-loops-run cli/index.mjs loop build-envelope --input <resolver-output.json>` (exception: when the dispatch prompt is a pull pointer, the pulled coordinator work order is the handoff envelope and no new envelope is built; see "Pull-pointer dispatch" in `agents/dev-loop.agent.md`). 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` (resolved from the repo's main checkout, not cwd-relative, so a worktree and the main checkout always see the same file) and, when the repo config `workflow.requireRetrospective` (set via `.devloops` at repo root) is `true`, bounds newer base-branch commits with local git ancestry and classifies each through GitHub's commit-to-PR association. A `complete`/`skipped` record becomes `missing` only when a newer commit is associated with a PR merged into the configured base branch; direct/release commits, unmerged PRs, and PRs merged into another base do not open a cycle. An unresolvable recorded SHA or unverifiable association fails closed to `missing`. When the resulting state is `missing`, the resolver still routes the unit normally and reports the obligation in the bundle as `pendingRetrospectives` (`[{ pr, mergeCommit }]`, or `pr: null, mergeCommit: null` with a `reason` code when the merge cannot be identified). The orchestrator dispatches each reported retrospective in parallel with the unit. `merge-pr` enforces the obligation fail-closed through its `retrospective_checkpoint` precondition (ADR 0125). Run or explicitly discharge the retrospective, carrying the cycle identity via `checkpoint-contract.mjs --repo`/`--pr`/`--merge-commit` (required for `complete`/`skipped`) and — for `complete` — the fresh-context provenance via `--retro-context fresh --record-source <path>` (mandatory per `RETRO-FRESH-CONTEXT-MANDATORY`; an inline self-authored retro fails the checkpoint).

**Pre-flight PR gate (mandatory):** Before working an existing PR, run `dev-loops-run cli/index.mjs loop handoff --repo <owner/name> --pr <number>` and interpret its machine output per [Interpreting Copilot completion versus PR lifecycle completion](../docs/copilot-loop-state-graph.md#interpreting-copilot-completion-versus-pr-lifecycle-completion). A `direct_gate` or clean terminal open-PR outcome ends only the Copilot sub-loop and consults fresh `loop gate-coordination`; every other `action: "stop"` aborts unless that section reports a closed or merged PR as done. Exception: when the handoff returns `action: "stop"` with `state: "pr_draft"` and the startup output for this PR carries `draftStart`, the PR is an existing draft and a valid start target. Do not abort on that stop. Run `dev-loops-run cli/index.mjs loop gate-coordination --repo <owner/name> --pr <number>` and follow its `nextAction`. Without `draftStart`, the `pr_draft` stop still aborts (Copilot-assigned draft, review-only start, unreadable PR). Consultation grants neither pre-approval nor merge. Ready-for-review and the Copilot review request require a clean current-head `draft_gate` verdict.

**Worktree cwd (mandatory):** Always use a worktree checkout for git operations, file reads/writes, and validation commands — never use the `main` checkout.

Read [worktree-guidance.md](../docs/worktree-guidance.md#default-rule-use-a-worktree-for-mutating-local-work) before mutation. `WORKTREE-DEFAULT-USE` requires `git -C <absolute-worktree-path> …` and absolute file paths even if the shell cwd appears correct. The [default-branch guards](../docs/worktree-guidance.md#default-branch-guard) are defense-in-depth, not a substitute.

**Worktree fetch (mandatory):** 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
dev-loop 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.
   - Re-run startup for that canonical PR, build and validate its fresh envelope,
     and load its `requiredReads` before executing a destination action. The
     checkpoint does not bypass a changed route's ownership or gate requirements.
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).

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` | [Wait / Watch Procedure](../docs/wait-watch-procedure.md) |
| `final_approval` | same as `copilot_pr_followup` + [Final Approval Skill](../final-approval/SKILL.md) |
| `review` | [Review Skill](../review/SKILL.md) |

Do not preload route packs before the resolver selects the strategy.

## Async dispatch

**Async dispatch rule (enforced):** the resolver fails closed for GitHub-first strategies when `canonicalStateSummary.requiresAsyncDispatch` is `true` (default `required` mode) — inline invocation without async-context evidence (`DEVLOOPS_RUN_ID`, the legacy `PI_SUBAGENT_RUN_ID` alias, or the native Pi async-runner markers `PI_SUBAGENT_CHILD=1` + `PI_SUBAGENT_PARENT_SESSION`) is rejected for those routes. Under the Claude Code harness this requirement is relaxed automatically. 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 `dev-loops-run 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, 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.

### Stale-installed-CLI: prefer worktree-source verdict/ledger tooling (#1661)

Before posting a `pre_approval_gate` (or `draft_gate`) verdict, resolve which layout the verdict/ledger tooling should run from via the deterministic helper (issue #1661):

```sh
node <resolved-skill-scripts>/loop/resolve-verdict-ledger-source.mjs --jq .preferredSource
```

When `preferredSource` is `worktree` (installed dev-loops CLI older than the current source/worktree), run `upsert-checkpoint-verdict.mjs`, `write-gate-findings-log.mjs`, and `detect-checkpoint-evidence.mjs` from the worktree/source `scripts/` layout — the stale installed CLI lacks the gate-evidence CI exclusion and would otherwise block verdict posting on `WAITING_FOR_CI`. When `installed`, use the resolved skill-scripts (installed) layout as usual. The copilot-pr-followup skill's [Skill asset path resolution](../copilot-pr-followup/SKILL.md#skill-asset-path-resolution) owns the full rule; this is the entrypoint pointer.

## Read-only info shortcut

Info/handoff requests can be served directly via `dev-loops-run cli/index.mjs loop info` (read-only; no full dev-loop run required):
- `dev-loops-run cli/index.mjs loop info --issue <n>` — human-readable issue state summary (strategy, route, linked PR, next action)
- `dev-loops-run cli/index.mjs loop info --pr <n>` — human-readable PR state summary (branch, CI, threads, rounds, action)
- `dev-loops-run cli/index.mjs loop info --issue <n> --json` — machine-readable JSON output

## Reading tool output (token-economical convention)

<!-- rule: BASE-JQ-OUTPUT-GUARANTEE -->
`BASE-JQ-OUTPUT-GUARANTEE`: every operator-facing JSON-result dev-loops command MUST accept `--jq`/`--silent` through the single shared emit path (`scripts/lib/jq-output.mjs`), enforced by the `jq-output-base-guarantee` contract test.

When you need a fact from a dev-loops JSON-emitting script, climb this ladder and stop at the first rung that answers the question — never read more output than you need:

1. **Prefer the dev-loops subcommand / concise mode.** Use `loop info` or a script's `--concise`/`--summary` mode (e.g. `run-watch-cycle.mjs --concise`, `probe-copilot-review.mjs --concise`) for a human-readable digest. The concise modes surface loop state, Copilot round count, unresolved/actionable thread counts, round-cap-clean eligibility, CI status, next action, and the current round's new Copilot comment bodies.
2. **`--silent` / `-s` for a yes/no check.** Reads ZERO output: `… --jq '<predicate>' --silent; echo $?` exits `0` for true / `1` for false. Without `--jq`, `--silent` maps the script's success (`ok:true`) to exit `0`, failure to `1` — unless the tool documents a stricter `--silent` contract in its own usage text (e.g. `request-copilot-review.mjs` exits `0` only for `status: "requested"`). Example: `probe-copilot-review.mjs --repo o/r --pr N --timeout 0 --jq '.status=="idle"' -s`.
3. **`--jq <filter>` to extract a single field.** `--jq`/`--silent` are a BASE-CLI GUARANTEE across every operator-facing JSON-result dev-loops command — each accepts a gh-style `--jq` filter (jq subset: field access, `.[]`/`.[N]`, `|`, `select(...)`, `==`/`!=`/`<`/`<=`/`>`/`>=`, `length`, `keys`), not just a named subset. (A few scripts are out of scope — e.g. build/smoke tooling, dashboard servers, dormant/unwired adapters, and scripts that write JSON to a file rather than stdout — each carried with its reason in the contract test's exclusion list.) It prints only the filtered value. An invalid filter fails closed (stderr + exit `2`), distinct from a clean predicate-false (silent exit `1`). This is enforced by a contract test (`test/contracts/jq-output-base-guarantee-contract.test.mjs`) that fails the build if a new JSON-emitting command ships without wiring the shared `scripts/lib/jq-output.mjs` emit path. Need several fields at once instead of one? `--fields a,b,c` returns the named TOP-LEVEL SCALAR fields as one tab-separated line, in the requested order — one call instead of N `--jq` calls. Consume with `cut -f<n>` when a field may be null/empty, e.g. `cut -f2 < <(cmd --fields a,b,c)`: it handles an empty/leading cell correctly. `IFS=$'\t' read -r A B C < <(cmd --fields a,b,c)` is safe only when every cell is known non-empty — empty/leading tabs are IFS whitespace and get collapsed, so a null cell misbinds the rest. Same fail-closed posture as `--jq`: an unknown or non-scalar field, or combining `--fields` with `--jq`/`--silent`, fails closed (stderr + exit `2`).
4. **Use a dev-loops wrapper for `gh` reads — never an agent-level raw `gh`.** A raw `gh` call is a recorded advisory retro violation (issue #1077: reported, never blocking). If no script covers the read you need, treat it as a tooling gap: file/build a thin wrapper (reuse `scripts/lib/jq-output.mjs`, like the ones below), don't shell out. The reads/edits that already have wrappers:
   - CI run-log tail (a failing PR's job log) → `scripts/github/fetch-ci-logs.mjs --repo <o/r> --pr <n> [--failed-only] [--tail <n>]`, **never raw `gh run view --log`/`--log-failed`**. (`probe-ci-status.mjs` names the failed checks; this returns the LOG.)
   - Issue list/filter → `scripts/github/list-issues.mjs --repo <o/r> [--state <open|closed|all>] [--label <l>] [--limit <n>]`, **never raw `gh issue list`**. (The queue tool lists the project board; this is for arbitrary issue queries.)
   - Issue comment → `scripts/github/comment-issue.mjs --repo <o/r> --issue <n> (--body <text> | --body-file <path>)`, **never raw `gh issue comment`**. Returns `{ ok, commentUrl }`.
   - Edit an existing issue/PR comment → `scripts/github/edit-comment.mjs --repo <o/r> --comment-id <n> (--body <text> | --body-file <path>)`, **never raw `gh api -X PATCH .../issues/comments/{id}`**. Covers both issue comments and PR issue-comments (same REST endpoint). Returns `{ ok, commentUrl }`.
   - Issue edit (title/body/assignee/milestone/state) → `scripts/github/edit-issue.mjs --repo <o/r> --issue <n> [--title <t>] [--body <b> | --body-file <path>] [--add-assignee <u>] [--remove-assignee <u>] [--milestone <m>] [--state <open|closed>] [--reason <completed|not_planned>]`, **never raw `gh issue edit` / `gh issue close` / `gh issue reopen`**. `--state` runs the close/reopen call after any other edits. Returns `{ ok, repo, issue, edited }`.
   - Issue facts read (body/state/author/labels/etc.) → `scripts/github/view-issue.mjs --repo <o/r> --issue <n> [--json <fields>]`, **never raw `gh issue view`**. Returns the issue body that `list-issues.mjs` does not; the sanctioned reader for issue bodies (parallel to `view-pr`).
   - PR facts read (branch/state/mergeStateStatus/head SHA/etc.) → `scripts/github/view-pr.mjs --repo <o/r> --pr <n> [--json <fields>]`, **never raw `gh pr view`**. (For composite loop-routing/CI facts prefer `loop info --pr`; this is the thin field-read counterpart.)
   - PR edit (title/body/assignee/milestone) → `scripts/github/edit-pr.mjs --repo <o/r> --pr <n> [--title <t>] [--body <b> | --body-file <path>] [--add-assignee <u>] [--remove-assignee <u>] [--milestone <m>]`, **never raw `gh pr edit`**. Returns `{ ok, repo, pr, edited }`.
   - PR checks/status → `scripts/github/probe-ci-status.mjs --repo <o/r> --pr <n> --timeout 0` for a single live combined-CI check, **never raw `gh pr checks`**. (Provider-agnostic; drop the `--timeout 0` to block-wait.)
   - Post-drive gate-evidence audit (does the PR have its posted draft_gate + pre_approval_gate verdicts?) → `scripts/github/audit-gate-evidence.mjs --repo <o/r> --pr <n>` (**never raw issue-comment reads**); it scans BOTH verdict surfaces (PR reviews + issue comments, see GATE-EVIDENCE-AUDIT-TWO-SURFACES), so a verdict posted only as a PR review is never reported missing (#1729).
   - Reconcile a stuck `gate-evidence` required status at merge-readiness → `scripts/github/reconcile-gate-evidence-status.mjs --repo <o/r> --pr <n>`. Run it right after the post-drive audit and before the human-approval/merge checkpoint. When the current-head verdict evidence is satisfied but the `gate-evidence` commit status is stuck non-green (a `cancel-in-progress`-cancelled or read-after-write-raced verdict-post re-fire, issue #1935), it re-fires the run so the status flips to `success` without a manual `gh run rerun`. Fail-closed: when the evidence is genuinely missing it re-fires nothing (ADR 0057, see [Merge Preconditions](../docs/merge-preconditions.md)).
   - Merge (the sanctioned merge path, orchestrator-owned) → `scripts/github/merge-pr.mjs --repo <o/r> --pr <n> --human-approved-by <login>` (`--method squash|merge|rebase`, `--stable-release`), **never raw `gh pr merge`**. It runs the full merge-precondition set fail-closed and refuses with a machine-readable reason naming the failing precondition; a verified `--human-approved-by <login>` is mandatory. See [Merge Preconditions](../docs/merge-preconditions.md#sanctioned-merge-wrapper-issue-1939).

   These accept the same `--jq`/`--silent` output flags as every other JSON-emitting script (base-CLI guarantee) — including `probe-ci-status.mjs`, watch-shaped as it is.
5. **NEVER `| python3` or `node -e`** to parse tool JSON. If a field you need is missing from a script's output, add it to the script (or its concise mode), not an inline parser.

## Guard rules

**Handoff envelope precedence:** The dev-loop builds the envelope immediately after authoritative-state resolution and treats it as the first handoff artifact (for a pull-pointer dispatch the pulled coordinator work order is the envelope and no new one is built; see "Pull-pointer dispatch" in `agents/dev-loop.agent.md`). Read it first, load only `requiredReads`, execute `nextAction`. The envelope's stable body + `requiredReads` are byte-identical across rounds for the same target+gate — the only per-round-varying values live in the trailing `gateState` block, which is **volatile: read it last, or re-derive it fresh via detectors right before acting** (this keeps the stable prefix cache-warm across fresh reviewer spawns — #1462). See [Resolve authoritative state](#resolve-authoritative-state). 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`. Fan-out reviewer waits (gate sub-loops or any Agent-tool fan-out) follow `ANTIPATTERN-FANIN-WAIT` in [Anti-patterns](../docs/anti-patterns.md): await completion via the harness notification or the reviewer's findings artifact at its deterministic path and join via the sanctioned fan-in CLI (`dev-loops-run cli/index.mjs gate consolidate-fanin`) — never transcript-tail, `node -e`/`python3`-parse tool JSON, or `sleep`-poll.

**Spec authority is engaged by default on every gate round (issue 2008 / ADR 0061):** before
fan-out dispatch, run the CLI seam that derives the run's spec/digest identities so the skill
never hand-derives them:

```sh
content_digest=$(dev-loops-run scripts/loop/spec-context.mjs --repo <owner/name> --issue <linked_issue_number> \
  --content-file <reviewed-content-path> --head-sha <current_head_sha> \
  --spec-out <spec-path> --identity-out <identity-path> --jq '.contentDigest')
```

On a fixer-push re-entry round (a prior clean round's `--approvals-out` record exists), also derive
the AC7 affected-criteria producer's input:

```sh
dev-loops-run scripts/loop/spec-context.mjs changed-paths --base <prior_approved_head_sha> --head <current_head_sha> \
  --jq '.changedFiles' > <changed-paths-path>
```

**AC1 identity stamp on every durable record (issue 2008 / ADR 0061):** the SAME call also writes
the round's revision-identity stamp once via `--identity-out <identity-path>`
(`{ specDigest, headSha, contentDigest, checkedCriteria }`). Pass `--spec-authority <identity-path>`
to every durable record writer this round invokes — `consolidate-fanin --spec-authority
<identity-path>`, `write-gate-findings-log.mjs --spec-authority <identity-path>`,
`upsert-checkpoint-verdict.mjs --spec-authority <identity-path>`, and (on a carry-forward round)
`resolve-angle-carry-forward.mjs --spec-authority <identity-path>` — so every gate/fixer/
carry-forward record pins both revision identities and the checked criteria, re-entry-safe from
any record type. Full per-writer flag detail: Gate Review Sub-Loop Contract Phase 3.5.

**Gate fan-out dispatch (inline imperative — #1637):** When the gate coordinator (`GATE-EXEC-GATE-COORDINATOR` in [Gate Review Sub-Loop Contract](../docs/gate-review-sub-loop-contract.md)) dispatches the `draft_gate` / `pre_approval_gate` fan-out (parallel fresh-context reviewers seeded from the one neutral context bundle), it MUST join their results through the sanctioned fan-in CLI — not by hand-rolling the wait. Never hand-roll reviewer dispatch via `Promise.all(runs.run)` + transcript-tailing; await each reviewer's findings artifact at its deterministic output path (`tmp/gate-reviews/<repo-slug>/pr-<N>/<gate>-<headSha>/<angle>.json`) and consolidate via ONE call, always with `--spec-authority <identity-path>` from above:

```sh
dev-loops-run cli/index.mjs gate consolidate-fanin --findings-dir <dir> --head-sha <current_head_sha> --gate <gate> \
  --expected-dispatch-units <n> --out <findings-json-path> --ledger-out <ledger-path> \
  --emit-plan <emit-plan-path> --spec-authority <identity-path> --jq '.severityCounts'
```

**Judge between fan-in and the fixer (Phase 3.5 wired, #1658):** after fan-in, before the
durable findings-log write, the gate coordinator (`GATE-EXEC-GATE-COORDINATOR`) follows
[Phase 3.5](../docs/gate-review-sub-loop-contract.md#phase-35--judge-relevance-disposition-1525)
and dispatches the dedicated `judge` agent (`agents/judge.agent.md`) with only the compact
`dispatchPrompt` that `scripts/loop/emit-judge-work-order.mjs` prints (ADR 0106); the judge pulls
its work order, which pins the consolidated ledger, the spec-context output, the round's evidence
(PR declared scope and diff) and the prior-round judge verdicts. It then awaits its two verdict artifacts: the relevance verdict at
`tmp/gate-judge/<repo-slug>/pr-<N>/<gate>-<headSha>/<roundId>/judge-verdict.json` and the spec-authority
verdict at the sibling `spec-authority-verdict.json` (its only writes). The gate coordinator
writes the durable ledger with `write-gate-findings-log --judge-verdict <verdict-path>
--spec-authority <identity-path>` using those completed verdicts; posting the visible gate
verdict stays with the dev-loop coordinator. The gate coordinator then runs the deterministic
bridge to derive the fixer's act list for Phase 4, always with the spec-authority flags, plus the
durable-approval flags across re-entry:

```sh
dev-loops-run cli/index.mjs gate judge-pass --repo <owner/name> --pr <N> --gate <gate> --head-sha <current_head_sha> \
  --findings-file <ledger-path> --judge-verdict <verdict-path> --judge-plan <judge-plan-path> \
  --out <act-list-path> --ledger-out <enriched-ledger-path> \
  --spec-file <spec-path> --content-digest "$content_digest" --spec-authority-verdict <spec-authority-verdict-path> \
  [--prior-approvals <prior-approvals-path> --approvals-out <approvals-out-path>] \
  [--changed-paths <changed-paths-path> --coverage-map <coverage-map-path>]
```

`--judge-plan` is the emitter's printed `planPath`. `--prior-approvals`/`--approvals-out` thread across re-entry rounds (the first round on a fresh
approval chain has no prior-approvals record to pass yet); `--changed-paths`/`--coverage-map` are
supplied together only when a coverage map exists for the linked issue and this round is a
fixer-push re-entry (`resolveAffectedCriteria`, ADR 0061 AC7) — otherwise judge-pass keeps its
all-stale fallback. The fix pass consumes ONLY `--out`'s act list (the judge's `act` findings); a
`judge-pass` fail-closed (any case in the Gate Review Sub-Loop Contract Phase 3.5 list) means re-run the judge at the current head, never a
silent severity-only fallback or a silent skip of spec authority. See Gate Review Sub-Loop Contract
Phase 3.5 and `skills/docs/spec-authority-contract.md` for the enforcement rules these flags carry.

After the fixer commits the act-list fix and before it pushes, the dev-loop coordinator runs the
delta-mode pre-push review (`PRE-PUSH-DELTA-TRIGGER` in the
[Pre-push review contract](../docs/pre-pr-review-contract.md#delta-mode)), which owns the
baseline, input, result, three-review bound and freshness rules. `dev-loops-run cli/index.mjs loop pre-push-delta`
builds the reviewer input and checks each result against the current worktree head. Pass `--pr-head <the full PR head SHA just read from GitHub>`, and brief the delta reviewer that it MUST NOT push (`PRE-PUSH-DELTA-PUSH-AUTHORITY`) and name `input.patchPath`, `input.evidenceRule` and `input.sealCommand` in the brief (pass the briefed absolute result path to the input run as `--result-path`). On the act-list route, pass the required `--findings-log <the reviewed round's findings log>` to the input run only (never pass `--handback`; only the fixer's emitted `handbackCheck` does); the thread route and the `--result` run take none. On Claude Code, join the fixer and the delta reviewer in the same turn with `dev-loops-run cli/index.mjs gate wait-for-units --artifact <hand-back path> --after <reference path> [--timeout <seconds>]`, where the hand-back path is the fixer work order's `joinRef` (the emitter prints it; for a full-phase fixer it is the final-on-write report) or the delta reviewer's `--result` path, and the reference path is the emitted fixer plan or the delta input run's `input.patchPath`. The result file can parse before the delta reviewer seals it. Run the `--result` check. On `evidence_unsealed`, wait for the reviewer's hand-back to name the seal output (the completion notification is the sanctioned wait for this one case) and re-run `--result`; a second `evidence_unsealed` re-runs the input run with a fresh `--result-path` before re-dispatching the reviewer, and that re-run counts against the three delta invocations. Never end the turn before the join returns, with one exception: a full-phase fixer join that times out follows `COORDINATOR-SINGLE-CHILD-JOIN-NOTIFICATION-FALLBACK` (`COORDINATOR-SINGLE-CHILD-JOIN` and the fallback are owned by the [Gate Review Sub-Loop Contract](../docs/gate-review-sub-loop-contract.md)).

Before gate dispatch, read `ANTIPATTERN-FANIN-WAIT` in [Anti-patterns](../docs/anti-patterns.md) and Phase 3 of [Gate Review Sub-Loop Contract](../docs/gate-review-sub-loop-contract.md) for the full refusal conditions.

**Bounded test runs (enforced — #1650):** Bound every directly launched focused suite containing gh mocks with `bun test --timeout <ms> <file>` (Bun's per-test timeout flag; `scripts/run-bun-test.mjs` already passes it). Do not wrap the command in a `timeout N` shell wrapper. Output truncation does not bound execution. `bun run verify` already bounds its suites. Bun is the development runner; Node `>=24` consumer-runtime and npm publication checks remain explicit exceptions.

**Bounded Copilot/CI watch (enforced — #1660):** Use `dev-loops-run cli/index.mjs gate probe-copilot --timeout 300`; pass an explicit bounded `--timeout <seconds>`. On outcome "pending" run `reissue` unchanged per `GATE-EXEC-BOUNDED-WAIT-CAP`; re-check only on a settled timeout. Never launch an unbounded blocking watch. Never wrap a sanctioned command in a `timeout N` shell wrapper: the wrapper hides the `dev-loops-run` head from operator allow rules, and the PreToolUse Bash-gate denies it.

<!-- rule: DEV-LOOP-PROBE-TIMEOUT-CEILING -->
`DEV-LOOP-PROBE-TIMEOUT-CEILING`: every Copilot or CI probe call MUST pass an explicit `--timeout`. `probe-copilot-review.mjs`, `wait-pr-checks.mjs`, and `dev-loops-run cli/index.mjs loop watch-ci` / `probe-ci-status.mjs` default to 1800 s. Under `GATE-EXEC-BOUNDED-WAIT-CAP` in [Gate review sub-loop contract](../docs/gate-review-sub-loop-contract.md) one call waits at most about 170 seconds, because the harness moves a subagent's foreground call to the background after 180 seconds. A longer `--timeout` returns `outcome: "pending"` with a `reissue` command. Run `reissue` unchanged in the foreground until the wait settles.

**Foreground inline probe, never a sleep-poll or bare-`&` probe (enforced — #2065):** Under the Claude Code harness the Copilot/CI wait MUST be a bounded FOREGROUND inline probe — `probe-copilot-review.mjs` or `wait-pr-checks.mjs` with an explicit `--timeout <seconds>` (`0` = a single immediate foreground check). The one sanctioned non-foreground wait is a command started through the harness background-command mechanism and awaited through its exit notification (owner `COPILOT-FOLLOWUP-WAIT-TOOLS`). Claude Code has no async wake for a bare-`&` shell-backgrounded wait, so it never joins one. Two forms are FORBIDDEN. The first is any `while`/`until`/`for` loop that runs `sleep`, foreground or backgrounded (whole-command): a sleep loop has no use a sanctioned wait does not cover (ADR 0244). The second is bare-`&` backgrounding of a probe/wait script (`dev-loops-run scripts/github/probe-copilot-review.mjs … &`): it orphans the shell past the agent stop. The PreToolUse Bash-gate denies these for the coordinator and every subagent (`commandContainsDetachedWaitTool`), actor-independently and fail-closed. Run the probe in the foreground. On outcome "pending" run `reissue` unchanged per `GATE-EXEC-BOUNDED-WAIT-CAP`; re-check only on a settled timeout. (A `SubagentStop` background-shell reaper safety-net, for whatever slips past prevention, is tracked as follow-up #2296.)

**Bounded, exhaustively (dispatch discipline, #1907):** the two guardrails above name the two most-hit failure modes, not the boundary of the rule — this agent runs sanctioned tools bare, never behind a `timeout N` shell wrapper, and every watch/probe carries the tool's own explicit `--timeout <seconds>`. A command without its own timeout flag relies on the harness tool-call timeout. An unbounded blocking watch is never sanctioned.

**Gate fan-out dispatch discipline (bounded-parallel default, #1907):** gate fan-out is bounded-parallel by DEFAULT — a wave releases up to `gates.fanout.maxConcurrent` dispatch units together in ONE call, never as N sequential blocking calls. Under Pi that call is `subagent({ workflowScriptPath, cwd, async: false, timeoutMs })` whose script body returns exactly ONE `runs.all([...])` with one item per unit, each carrying a unique non-empty `key`; this shape needs pi-subagents ≥0.57 (`tasks: [...]` was removed in 0.41.0), and the repo's `Dockerfile` pins a compatible release; N per-unit blocking `subagent` calls for one wave are the shape Pi's foreground guard rejects and MUST never be used. `gates.fanout.sequential: true` is the documented load fallback for a SIGTERM-prone environment, never the default. A transient dispatch failure (429/5xx) retries the same unit with exponential backoff; a hard 4xx (e.g. `402`) escalates to the supervisor/operator immediately instead of retrying into the same wall; provider choice stays a per-dispatch decision (`STICKY-PROVIDER-PIN`). Post-merge, the only remaining steps are the main-green check, one board-move attempt, and the final report — never re-running consolidation machinery whose artifacts already exist. Owning rules: `GATE-EXEC-FANOUT-SEQUENTIAL-FALLBACK`, `GATE-EXEC-DISPATCH-RETRY-BACKOFF`, `GATE-EXEC-END-OF-RUN-CONTRACT` in [Gate Review Sub-Loop Contract](../docs/gate-review-sub-loop-contract.md); `STICKY-PROVIDER-PIN` in [Anti-patterns](../docs/anti-patterns.md).

**Blocking join for a nested single-child step, never sleep-poll (#1907):** when this run's turn is awaiting a nested child IT dispatched — a judge, a fixer, or a single reviewer — join it with a blocking dispatch (`async: false`) or one `bg_wait` nonBlocking subscription. Do not sleep-poll for it and do not end the turn to await it, except the single turn end that `COORDINATOR-SINGLE-CHILD-JOIN-NOTIFICATION-FALLBACK` sanctions for a full-phase fixer join on Claude Code (observed failure: repeated 180/240/300s sleep loops). This is the actionable alternative behind `END-TURN-AND-AWAIT-WAKE` in [Anti-patterns](../docs/anti-patterns.md); see [dev-loop agent — Subagent delegation](../../agents/dev-loop.md#subagent-delegation) for the agent-contract pin of the same rule.

**Agent-level stall → auto-fresh-dispatch (#1669):** When a dev-loop child shows no turn progress for `workflow.stallDetection.thresholdMinutes` (default 5) with no pending supervisor request, auto-bail to a fresh-context dispatch (carrying worktree state + a recovery brief) instead of waiting through a manual interrupt+resume. Distinguish a TRUE stall (no turn progress) from a SANCTIONED long watch (an active bash/subagent tool call that heartbeats its runner claim) — a fresh runner-coordination heartbeat exempts a run from stall. Detector + probe: `dev-loops-run scripts/loop/detect-agent-stall.mjs --repo <owner/name> [--pr <n>] [--status <path>]`. See [Agent-level stall detection](../docs/agent-stall-detection.md). Interrupt+resume remains the manual fallback.

**Round-cap budget check (enforced):** After every watch cycle, fix pass, or reply-resolve, check whether completed Copilot review rounds have reached the resolved round cap (`refinement.maxCopilotRounds`, default 5; light-dispatched PRs resolve the lower `resolveEffectiveCopilotRoundCap`, default 1 — owned by `COPILOT-FOLLOWUP-ROUND-CAP`). Stop re-requesting Copilot review when the limit is reached **within that review cycle**. Exception: the post-convergence new-cycle re-request carve-out is owned by `COPILOT-FOLLOWUP-ROUND-CAP`. It applies only with `refinement.requireCopilotConvergenceAtLatestHead: true`. Read these gate-cadence facts via the token-economical convention above (`run-watch-cycle.mjs --concise`, or `--jq`/`--silent` for a single field/predicate) — never `| python3` or `node -e`.

<!-- rule: DEV-LOOP-RUNNER-STOP-CONDITIONS -->
`DEV-LOOP-RUNNER-STOP-CONDITIONS`: the dev-loop coordinator MUST stop and report, and never self-waives, when any of these occurs:

- a size-budget `escalate` or `block` outcome;
- an ADR tripwire trip (`check-adr-tripwire.mjs`), except that on `nextAction: resolve_adr_tripwire` the coordinator stops and reports, and the orchestrator runs `dev-loops-run cli/index.mjs pr waive-adr-tripwire` (orchestrator-owned) per `ADR-TRIPWIRE-STANDING-WAIVER` in [Decision record contract](../docs/decision-record-contract.md), quoting the typed refusal reason if the writer refuses;
- a harness permission or classifier denial, or an interruption.

The size-budget `block` and tripwire stops apply at the ready boundary (`nextAction` `resolve_adr_tripwire`, `resolve_size_budget` or `report_blocked`). Advisory `adrTripwire`/`sizeBudget` hits in a draft round (`nextAction: run_draft_gate`) are reported in the draft hand-back per `ADR-TRIPWIRE-EARLY-SURFACE` in [Decision record contract](../docs/decision-record-contract.md) and are not a stop condition. During draft rounds a size-budget `escalate` is advisory (reported in the hand-back). After the ready flip the existing runner stop on `escalate` applies, and merge-pr's `size_budget_human_approval` enforces the approve-merge marker.

On a denial the coordinator quotes the denial text verbatim in its report and does not retry the denied call in any command form.

## 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

## Headless auto-refine of parked un-refined items

Headless/`--auto` only; skip for interactive runs or a specific `--issue`/`--pr`
target. `add-queue-item.mjs` parks unrefined issues (`refined:false, diverted:true,
parkedColumn, reason`) without grilling. When pickup is empty, the orchestrator
must run this bounded sub-loop before idling; deterministic scripts own only the
park/allow decision and discovery (`OPS-NO-INLINE-INTERPRETER`).

1. **Discover:** `dev-loops-run cli/index.mjs queue parked-unrefined --repo <owner/name>`
   auto-resolves the project from `.devloops` and returns `{ issueNumber, reason, missing }`
   using the enqueue completeness check. Empty list → normal fail-closed idle.
   Process ascending `issueNumber`, at most one grill attempt per item per session.
2. **Auto-refine:** run `/dev-loops:loop-grill <issueNumber> --auto`
   (repo-local: `/loop-grill <issueNumber> --auto`). Use the skill's synthesis;
   never reimplement it or move LLM grilling into a coordinator script.
3. **Promote:** after `grill-clean` and confirmation by `detectIssueRefinementArtifact`,
   run `dev-loops-run cli/index.mjs queue move --repo <owner/name> --item <issueNumber> --to-column "<pickup column>"`
   to the configured Next Up column, then advance. Do not use `add-queue-item`:
   the parked item already exists, so that command is an idempotent no-op.
4. **Unrefinable:** if unresolved items remain or AC/DoD/linked-doc completeness
   still fails, leave it parked; no move or re-enqueue. Surface its discovery
   `reason` and advance, without another grill attempt this session. Never
   hand-move an unrefined item to pickup.

After every discovered item has had one attempt, enter normal fail-closed idle.
Retry still-parked items only in a later session.

## 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) — how dev-loop work is structured per harness (Pi: read-only main agent + async-subagent dispatch; Claude: the main session dispatches the `dev-loops:dev-loop` coordinator, which runs the steps as one agent driving its own children).
- 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.
- Cross-harness regression contract: [Cross-Harness Regression Contract](../docs/cross-harness-regression-contract.md).
