dev-loops 0.3.0 → 0.4.0

package/scripts/loop/run-watch-cycle.mjs

@@ -5,7 +5,10 @@ import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helper
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION } from "@dev-loops/core/loop/public-dev-loop-routing";
 import { watchCopilotReview } from "../github/probe-copilot-review.mjs";
+import { watchCiStatus } from "../github/probe-ci-status.mjs";
 import { runHandoff } from "./copilot-pr-handoff.mjs";
+import { STATE } from "@dev-loops/core/loop/copilot-loop-state";
+import { DEFAULT_POLL_INTERVAL_MS } from "@dev-loops/core/loop/policy-constants";
 import { detectCopilotSessionActivity } from "./detect-copilot-session-activity.mjs";
 import { parseArgs } from "node:util";
 import {
@@ -124,16 +127,33 @@ function buildWatchCycleContractTrace({
   cycleDisposition,
   sessionActivity = null,
   workflowRunWatch = null,
+  ciWatchArgs = null,
+  ciWatchStatus = null,
 }) {
-  const boundaryClassification = handoff.action !== "watch"
-    ? (handoff.loopDisposition === "blocked"
+  // The CI-watch branch (waiting_for_ci) routes through probe-ci-status.mjs even
+  // though handoff.action !== "watch". It is an observational wait, so it mirrors
+  // the Copilot watch classification: a quiet timeout is a HEALTHY_WAIT, while
+  // success/failure/changed route a follow-up. Without this the boundary-action
+  // path below would misclassify a CI timeout as routed_followup.
+  const isCiWatch = ciWatchArgs !== null;
+  const isWatchBoundary = handoff.action === "watch" || isCiWatch;
+  const observedStatus = isCiWatch ? ciWatchStatus : watchStatus;
+  const boundaryClassification = isWatchBoundary
+    ? (observedStatus === "timeout" || observedStatus === "idle"
+      ? DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.HEALTHY_WAIT
+      : DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.ROUTED_FOLLOWUP)
+    : handoff.loopDisposition === "blocked"
       ? DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.BLOCKED
       : handoff.terminal
         ? DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.TERMINAL
-        : DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.ROUTED_FOLLOWUP)
-    : watchStatus === "changed"
-      ? DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.ROUTED_FOLLOWUP
-      : DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.HEALTHY_WAIT;
+        : DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.ROUTED_FOLLOWUP;
+  const healthyWait = boundaryClassification === DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.HEALTHY_WAIT;
+  const helper = handoff.action === "watch"
+    ? "scripts/github/probe-copilot-review.mjs"
+    : isCiWatch
+      ? "scripts/github/probe-ci-status.mjs"
+      : null;
+  const effectiveArgs = isCiWatch ? ciWatchArgs : watchArgs;
   return {
     handoff: {
       action: handoff.action,
@@ -142,38 +162,37 @@ function buildWatchCycleContractTrace({
       terminal: Boolean(handoff.terminal),
     },
     waitStrategy: {
-      helper: handoff.action === "watch" ? "scripts/github/probe-copilot-review.mjs" : null,
-      mode: handoff.action === "watch"
-        ? "persistent_watch"
-        : "not_applicable",
-      effectiveTimeoutMs: watchArgs?.timeoutMs ?? null,
-      effectivePollIntervalMs: watchArgs?.pollIntervalMs ?? null,
+      helper,
+      mode: isWatchBoundary ? "persistent_watch" : "not_applicable",
+      effectiveTimeoutMs: effectiveArgs?.timeoutMs ?? null,
+      effectivePollIntervalMs: effectiveArgs?.pollIntervalMs ?? null,
       timeoutPolicyClassification: watchTimeoutPolicy?.classification ?? null,
     },
     orchestration: {
       emittedWatchArgs: handoff.watchArgs ?? null,
-      effectiveWatchArgs: watchArgs,
+      effectiveWatchArgs: effectiveArgs,
+      ciWatchArgs,
       sessionActivity,
       workflowRunWatch,
     },
-    stateRefresh: handoff.action === "watch"
+    stateRefresh: isWatchBoundary
       ? {
           boundaryKind: "post_watch_or_probe",
-          observedStatus: watchStatus,
+          observedStatus,
           refreshRequired: true,
-          refreshReason: watchStatus === "changed"
-            ? "Watch boundaries with fresh activity require an authoritative state refresh before routing the follow-up path."
-            : "Healthy watch boundaries are observational only; refresh authoritative state before treating timeout/idle as stop or completion.",
+          refreshReason: healthyWait
+            ? "Healthy watch boundaries are observational only; refresh authoritative state before treating timeout/idle as stop or completion."
+            : "Watch boundaries with fresh activity require an authoritative state refresh before routing the follow-up path.",
         }
       : null,
     stopReason: {
       classification: boundaryClassification,
       terminal: Boolean(handoff.terminal),
       cycleDisposition,
-      reason: handoff.action === "watch"
-        ? (watchStatus === "changed"
-          ? "Fresh watcher activity requires follow-up instead of staying in a healthy wait boundary."
-          : "Quiet watcher boundaries remain healthy waits and must not be treated as terminal completion by themselves.")
+      reason: isWatchBoundary
+        ? (healthyWait
+          ? "Quiet watcher boundaries remain healthy waits and must not be treated as terminal completion by themselves."
+          : "Fresh watcher activity requires follow-up instead of staying in a healthy wait boundary.")
         : handoff.nextAction,
     },
   };
@@ -236,6 +255,7 @@ export async function runWatchCycle(
     ghCommand = "gh",
     runHandoffImpl = runHandoff,
     watchCopilotReviewImpl = watchCopilotReview,
+    watchCiStatusImpl = watchCiStatus,
     detectCopilotSessionActivityImpl = detectCopilotSessionActivity,
     fetchPrHeadBranchImpl = fetchPrHeadBranch,
     watchWorkflowRunImpl = watchWorkflowRun,
@@ -267,6 +287,39 @@ export async function runWatchCycle(
   if (handoff.watchTimeoutPolicy !== undefined) {
     result.watchTimeoutPolicy = handoff.watchTimeoutPolicy;
   }
+  // Provider-agnostic CI wait (#917): a waiting_for_ci boundary would otherwise
+  // dead-end at action:"stop". Route it to the helper-owned CI watcher
+  // (CircleCI / GH Actions / external commit-status), not gh run watch.
+  if (handoff.action !== "watch" && handoff.state === STATE.WAITING_FOR_CI) {
+    // Mirror determineWatchTimeout but with a CI-specific context label so
+    // timeout diagnostics read "CI wait" instead of "Copilot review wait".
+    const ciTimeoutMs = enforceExternalHealthyWaitTimeout({
+      timeoutMs: EXTERNAL_HEALTHY_WAIT_TIMEOUT_POLICY.defaultTimeoutMs,
+      contextLabel: "CI wait",
+    });
+    const ciWatchArgs = {
+      repo: options.repo,
+      pr: options.pr,
+      pollIntervalMs: DEFAULT_POLL_INTERVAL_MS,
+      timeoutMs: ciTimeoutMs,
+    };
+    const ciWatch = await watchCiStatusImpl(ciWatchArgs, { env, ghCommand });
+    result.ciWatchArgs = ciWatchArgs;
+    result.ciWatch = ciWatch;
+    result.watchStatus = ciWatch.status;
+    // success/failure/changed all need authoritative re-detection (follow-up);
+    // a quiet timeout stays a healthy pending wait.
+    result.cycleDisposition = ciWatch.status === "timeout" ? "pending" : "needs_followup";
+    result.terminal = false;
+    result.contractTrace = buildWatchCycleContractTrace({
+      handoff,
+      watchTimeoutPolicy: result.watchTimeoutPolicy ?? null,
+      cycleDisposition: result.cycleDisposition,
+      ciWatchArgs,
+      ciWatchStatus: ciWatch.status,
+    });
+    return result;
+  }
   if (handoff.action !== "watch") {
     result.contractTrace = buildWatchCycleContractTrace({
       handoff,

package/scripts/projects/add-queue-item.mjs

@@ -3,7 +3,8 @@ import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.
 import { runChild as _runChild } from "../_cli-primitives.mjs";
 import { parseArgs } from "node:util";
 
-const USAGE = `Usage: dev-loops project add --repo <owner/name> --project <number|id> --item <number>
+const USAGE = `Usage: dev-loops queue add --repo <owner/name> --project <number|id> --item <number>
+       dev-loops project add … (back-compat alias for "queue add")
 
 Add an existing issue or PR to a GitHub Projects V2 board.
 
@@ -11,7 +12,8 @@ Options:
   --repo <owner/name>         Required. Repository containing the issue/PR.
   --project <number|id>       Required. Project number (integer) or node ID.
   --item <number>             Required. Issue or PR number to add.
-  --status <name>             Initial Status column (default: "Backlog").
+  --column <name>             Initial Status column (default: "Backlog").
+  --status <name>             Back-compat alias for --column.
   --help, -h                  Show this help.
 
 Output (stdout):
@@ -41,6 +43,7 @@ function parseCliArgs(argv) {
       repo: { type: "string" },
       project: { type: "string" },
       item: { type: "string" },
+      column: { type: "string" },
       status: { type: "string" },
       help: { type: "boolean", short: "h" },
     },
@@ -81,7 +84,13 @@ function parseCliArgs(argv) {
         args.item = val;
         break;
       }
+      case "column":
+        args.column = requireValue(token, "--column requires a value");
+        break;
       case "status":
+        // Back-compat alias for --column (issue #912). Kept separate so a
+        // conflicting `--column X --status Y` is rejected rather than silently
+        // resolved by argv order.
         args.status = requireValue(token, "--status requires a value");
         break;
       default:
@@ -375,9 +384,15 @@ async function main(args, { env = process.env, runChild } = {}) {
   if (!Number.isInteger(itemNumber) || itemNumber < 1) {
     throw Object.assign(new Error("--item is required and must be a positive integer"), { code: "INVALID_ITEM" });
   }
-  const targetStatus = (args.status ?? "Backlog").trim();
+  if (args.column != null && args.status != null && args.column.trim() !== args.status.trim()) {
+    throw Object.assign(
+      new Error(`Conflicting --column ("${args.column}") and --status ("${args.status}") — pass only one (prefer --column).`),
+      { code: "INVALID_ARGS", usage: USAGE },
+    );
+  }
+  const targetStatus = (args.column ?? args.status ?? "Backlog").trim();
   if (!targetStatus) {
-    throw Object.assign(new Error("--status must not be empty"), { code: "INVALID_STATUS" });
+    throw Object.assign(new Error("--column must not be empty"), { code: "INVALID_STATUS" });
   }
 
   // 1. Resolve owner
@@ -542,4 +557,4 @@ if (isDirectCliRun(import.meta.url)) {
   });
 }
 
-export { main };
+export { main, parseCliArgs };

package/scripts/projects/archive-done-items.mjs

@@ -6,7 +6,8 @@ import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.
 import { runChild as _runChild } from "../_cli-primitives.mjs";
 import { parseArgs } from "node:util";
 
-const USAGE = `Usage: dev-loops project archive-done --repo <owner/name> [--project <number|id>] [--older-than <duration>] [--dry-run]
+const USAGE = `Usage: dev-loops queue archive-done --repo <owner/name> [--project <number|id>] [--older-than <duration>] [--dry-run]
+       (dev-loops project archive-done … is a back-compat alias)
 
 Archive GitHub Projects V2 items whose issue/PR has been closed for at least the
 given duration. Operator-triggered (no webhooks). Uses archiveProjectV2Item.

package/scripts/projects/ensure-queue-board.mjs

@@ -6,7 +6,8 @@ import { parse as parseYaml } from "yaml";
 import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { runChild as _runChild } from "../_cli-primitives.mjs";
 
-const USAGE = `Usage: dev-loops project ensure --repo <owner/name> [--project <number>] [--title <title>] [--link-repo <owner/name>] [--repair-rename]
+const USAGE = `Usage: dev-loops queue ensure --repo <owner/name> [--project <number>] [--title <title>] [--link-repo <owner/name>] [--repair-rename]
+       (dev-loops project ensure … is a back-compat alias)
 
 --repair-rename    Rename semantically equivalent Status columns to the standard names
                    (e.g. "Ready" -> "Next Up"). Without this flag the helper only

package/scripts/projects/list-queue-items.mjs

@@ -3,7 +3,8 @@ import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.
 import { runChild as _runChild } from "../_cli-primitives.mjs";
 import { parseArgs } from "node:util";
 
-const USAGE = `Usage: dev-loops project list --repo <owner/name> --project <number|id> [--column <name>] [--limit <n>]
+const USAGE = `Usage: dev-loops queue list --repo <owner/name> --project <number|id> [--column <name>] [--limit <n>]
+       (dev-loops project list … is a back-compat alias)
 
 List GitHub Projects V2 items filtered by Status column, ordered by position
 ascending. Returns machine-readable JSON.

package/scripts/projects/move-queue-item.mjs

@@ -3,7 +3,8 @@ import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.
 import { runChild as _runChild } from "../_cli-primitives.mjs";
 import { parseArgs } from "node:util";
 
-const USAGE = `Usage: dev-loops project move --repo <owner/name> --project <number|id> --item <number|node-id> --to-column <name>
+const USAGE = `Usage: dev-loops queue move --repo <owner/name> --project <number|id> --item <number|node-id> --to-column <name>
+       (dev-loops project move … is a back-compat alias)
 
 Move a GitHub Projects V2 item between Status columns.
 

package/scripts/projects/reorder-queue-item.mjs

@@ -4,10 +4,11 @@ import { runChild as _runChild } from "../_cli-primitives.mjs";
 import { parseArgs } from "node:util";
 
 const USAGE = `Usage:
-  dev-loops project reorder --repo <owner/name> --project <number|id> --item <number|node-id> [--after <number|node-id>]
-  dev-loops project reorder move-to-top <ref> --repo <owner/name> --project <number|id>
-  dev-loops project reorder move-after <ref> <after-ref> --repo <owner/name> --project <number|id>
-  dev-loops project reorder order <ref1> <ref2> ... --repo <owner/name> --project <number|id>
+  dev-loops queue reorder --repo <owner/name> --project <number|id> --item <number|node-id> [--after <number|node-id>]
+  dev-loops queue reorder move-to-top <ref> --repo <owner/name> --project <number|id>
+  dev-loops queue reorder move-after <ref> <after-ref> --repo <owner/name> --project <number|id>
+  dev-loops queue reorder order <ref1> <ref2> ... --repo <owner/name> --project <number|id>
+  (dev-loops project reorder … is a back-compat alias)
 
 Reorder GitHub Projects V2 items by board position via updateProjectV2ItemPosition.
 

package/scripts/projects/sync-item-status.mjs

@@ -4,7 +4,8 @@ import { runChild as _runChild } from "../_cli-primitives.mjs";
 import { syncBoardStatus } from "@dev-loops/core/loop/queue-board-sync";
 import { parseArgs } from "node:util";
 
-const USAGE = `Usage: dev-loops project sync-status --repo <owner/name> --item <number> --to-column <name>
+const USAGE = `Usage: dev-loops queue sync-status --repo <owner/name> --item <number> --to-column <name>
+       (dev-loops project sync-status … is a back-compat alias)
 
 Sync a queued issue/PR's board Status column on a dev-loop transition (e.g.
 PR opened → "In Progress", merged → "Done"). Resolves the board from .devloops

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

@@ -166,9 +166,9 @@ The outer-loop checkpoint is the canonical re-attachment artifact.
 
 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.
+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), `dev-loops loop watch-ci --repo <owner/name> --pr <number>` (provider-agnostic CI: CircleCI / Actions / external commit-status), `gh run watch <run-id> --repo <owner/name>` (Actions-only fallback when the run id is known). 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.
+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 → `dev-loops loop watch-ci --repo <owner/name> --pr <number>` (provider-agnostic; covers CircleCI / Actions / external commit-status) or report-and-resume; `gh run watch <run-id>` is an Actions-only fallback. `dev-loops loop watch-cycle` also auto-routes a `waiting_for_ci` boundary to this CI watcher. 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
@@ -251,7 +251,7 @@ When unresolved feedback exists, use a narrow follow-up loop:
     - 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
+    - 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 `dev-loops loop watch-ci` (provider-agnostic CI wait; `gh run watch` is an Actions-only fallback) 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`
@@ -322,7 +322,7 @@ The canonical checkpoint verdict comment contract is [Gate Review Comment Contra
 - **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.
-- **Board status sync (best-effort, after ready-for-review):** once the PR is created/marked ready for review, sync the linked issue's board item to "In Progress" so the queue board reflects active work without a manual `add-queue-item --status`:
+- **Board status sync (best-effort, after ready-for-review):** once the PR is created/marked ready for review, sync the linked issue's board item to "In Progress" so the queue board reflects active work without a manual `dev-loops queue sync-status --to-column <col>`:
   ```sh
   node <resolved-skill-scripts>/projects/sync-item-status.mjs --repo <owner/name> --item <linked-issue> --to-column "In Progress"
   ```
@@ -370,6 +370,8 @@ See [Merge Preconditions](../docs/merge-preconditions.md). Verify: zero unresolv
 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`.
 
+When `approval.humanHandoff.enabled` is set, don't just park silently at this stop: run `dev-loops gate offer-human-handoff --repo <owner/name> --pr <number>` to surface candidate reviewers/assignees, then **offer** them to the operator. Only on operator confirmation, route the PR with `--assign <login>` / `--request-review <login>`. This is OFFER-only — never auto-assign. See the `approval.humanHandoff` section in [Merge Preconditions](../docs/merge-preconditions.md); it pairs with `autonomy.humanMergeOnly`.
+
 ### Mechanical pre-merge gate evidence check
 
 Immediately before any `gh pr merge`, run:
@@ -400,15 +402,15 @@ Do not report completion or advance to the next PR queue item until `.pi/dev-loo
 
 ### Post-merge board archive (best-effort)
 
-After the retrospective checkpoint write, optionally tidy the queue board locally:
+After the retrospective checkpoint write, run the post-merge board archive as a standard step of the post-merge hook (see [Merge Preconditions](../docs/merge-preconditions.md) "Post-merge"):
 
 ```sh
-node <resolved-skill-scripts>/projects/archive-done-items.mjs --repo <owner/name>
+node <resolved-skill-scripts>/projects/archive-done-items.mjs --repo <owner/name> || true
 ```
 
 Board and threshold resolve from `.devloops` (`queue.projectNumber`/`queue.boardTitle`, `queue.archiveOlderThanDays`, default 7d), using local `gh` auth — no CI, cron, or PAT. This step is best-effort and NON-FATAL: ignore any failure and never let it block the merge or the retrospective.
 
-Alongside the archive step, sync the linked issue's board item to "Done" so the queue board reflects the merge without a manual `add-queue-item --status`:
+Alongside the archive step, sync the linked issue's board item to "Done" so the queue board reflects the merge without a manual `dev-loops queue sync-status --to-column <col>`:
 
 ```sh
 node <resolved-skill-scripts>/projects/sync-item-status.mjs --repo <owner/name> --item <linked-issue> --to-column "Done"

package/skills/dev-loop/SKILL.md

@@ -27,7 +27,7 @@ Required installed runtime contract docs are shared bundled copies under `../doc
 
 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.
-For async-required routes (config `workflow.asyncStartMode`, default `required`) the resolver needs an async run-id marker (`DEVLOOPS_RUN_ID`, or the `PI_SUBAGENT_RUN_ID` alias) that the Pi harness injects when it dispatches the async subagent; under the Claude Code harness the requirement is relaxed automatically (no marker needed). The startup resolver also runs without a marker for non-async routes. Regardless, only the `dev-loop` subagent runs it — never the main agent.
+For async-required routes (config `workflow.asyncStartMode`, default `required`) the resolver needs an async run-id marker (`DEVLOOPS_RUN_ID`) that the harness injects when it dispatches the async subagent; under the Claude Code harness the requirement is relaxed automatically (no marker needed). The startup resolver also runs without a marker for non-async routes. Regardless, only the `dev-loop` subagent runs it — never the main agent.
 <!-- /pi-only -->
 
 ### Resolve authoritative state
@@ -94,7 +94,7 @@ 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 an async run-id marker (`DEVLOOPS_RUN_ID`, or the `PI_SUBAGENT_RUN_ID` alias) is rejected for those routes. Under the Claude Code harness this requirement is relaxed automatically. See [Startup procedure](#startup-procedure).
+**Async dispatch rule (enforced):** the resolver fails closed for GitHub-first strategies when `canonicalStateSummary.requiresAsyncDispatch` is `true` (default `required` mode) — inline invocation without an async run-id marker (`DEVLOOPS_RUN_ID`) is rejected for those routes. Under the Claude Code harness this requirement is relaxed automatically. See [Startup procedure](#startup-procedure).
 
 
 ## Fallback gate-comment poster

package/skills/docs/anti-patterns.md

@@ -11,7 +11,7 @@ Canonical owner for anti-pattern guidance across all workflow families.
 5. **Duplicate worktree paths**: Check `git worktree list` before creating new worktrees; reuse existing matching worktrees.
 6. **Main-checkout mutation**: Reserve main checkout for inspection/control; use `tmp/worktrees/` paths for mutation work.
 7. **Spelunking tooling internals instead of using the public surface**: Do not read installed package internals, scan tooling source, or run ad-hoc scripts to understand a tool's behavior. Use the CLI, its `--help` subcommands, and `skills/docs/`. Read tool source only when the task is to inspect or change that tool, or when a concrete failure path is inside it and no public CLI/docs path exists. Once a failure is concrete, search changed files for the exact pattern — don't run duplicate broad searches.
-8. **Hand-editing the queue file when a board is configured**: When a GitHub Projects board is configured (`queue.projectNumber`/`queue.boardTitle` in `.devloops`), the board is the authoritative queue MEMBERSHIP and ordering source — not just status. Add work via the board (`dev-loops project add ... --status "Next Up"`), not by hand-editing `.pi/dev-loop-queue.json`; the queue runner reconciles board `Next Up` items into queue entries before each run. See the operator guides under `docs/` (queue board usage/setup) for the workflow.
+8. **Hand-editing the queue file when a board is configured**: When a GitHub Projects board is configured (`queue.projectNumber`/`queue.boardTitle` in `.devloops`), the board is the authoritative queue MEMBERSHIP and ordering source — not just status. Add work via the board (`dev-loops queue add ... --column "Next Up"`), not by hand-editing `.pi/dev-loop-queue.json`; the queue runner reconciles board `Next Up` items into queue entries before each run. See the operator guides under `docs/` (queue board usage/setup) for the workflow.
 
 ## Light mode exception
 

package/skills/docs/copilot-loop-operations.md

@@ -51,7 +51,7 @@ For tracker-first MVP `story -> PR -> tracker sync` work, the source-repo refere
 
 4. Branch on the detector output instead of inventing a polling loop:
    - `state=waiting_for_copilot_review` with `snapshot.copilotReviewOnCurrentHead=false`: do **not** poll manually; either run `node <resolved-skill-scripts>/loop/run-watch-cycle.mjs --repo <owner/name> --pr <number>` for persistent async waiting or report the wait state and resume later after the single detector call
-   - `state=waiting_for_ci` with `snapshot.ciStatus` in `{ "pending", "none" }`: do **not** poll manually by default; use `gh run watch <run-id> --repo <owner/name>` when the current-head run id is already known, otherwise report pending CI and resume later after the single detector refresh. Bounded exception: if GitHub created zero current-head check suites/statuses, the previous head rollup was green, and local `npm run verify` already passed for the same current head, rerun `detect-copilot-loop-state.mjs` with `--local-validation-head-sha <current-head-sha>` so the detector can promote that exact zero-suite case to `snapshot.ciStatus="crediblyGreen"` instead of waiting forever on raw `none`.
+   - `state=waiting_for_ci` with `snapshot.ciStatus` in `{ "pending", "none" }`: do **not** poll manually by default; use `dev-loops loop watch-ci --repo <owner/name> --pr <number>` to block-wait on the combined check/status state (provider-agnostic — CircleCI, GitHub Actions, and any external commit-status / check-run). `gh run watch <run-id>` is an Actions-only fallback when the current-head run id is already known and you know the gating checks are GitHub Actions. Either way, on `timeout`/`changed` report pending CI and resume later after the single detector refresh. Bounded exception: if GitHub created zero current-head check suites/statuses, the previous head rollup was green, and local `npm run verify` already passed for the same current head, rerun `detect-copilot-loop-state.mjs` with `--local-validation-head-sha <current-head-sha>` so the detector can promote that exact zero-suite case to `snapshot.ciStatus="crediblyGreen"` instead of waiting forever on raw `none`.
    - `snapshot.ciStatus="failure"` remains a stop/fix state, never a wait loop
 
 5. For reviewer-side draft-review work, run `node <resolved-skill-scripts>/loop/detect-reviewer-loop-state.mjs --repo <owner/name> --pr <number> [--reviewer-login <login>] [--local-state <path>]`.

package/skills/docs/issue-intake-procedure.md

@@ -224,6 +224,10 @@ gh pr edit <pr-number> --repo <resolved-repo> --title "..." --body-file <body-fi
 gh pr ready <pr-number> --repo <resolved-repo>
 gh pr review <pr-number> --repo <resolved-repo> --approve --body "..."
 node <resolved-skill-scripts>/github/detect-checkpoint-evidence.mjs --repo <resolved-repo> --pr <pr-number>
+```
+
+The merge itself is gated, not implied by the lines above. Before any `gh pr merge`, follow [Merge Preconditions](./merge-preconditions.md): all preconditions (green CI, clean `draft_gate` + current-head `pre_approval_gate`, zero unresolved threads, explicit merge authorization) must hold. Critically, when `autonomy.humanMergeOnly: true` is set, merge is a fixed human-only action — `resolveEffectiveMergeAuthorized` fails closed, the agent **never** runs `gh pr merge`, and instead reports merge-ready + gate evidence and hands off to a human. Only when **not** `humanMergeOnly` and merge is explicitly authorized may the agent run:
+```sh
 gh pr merge <pr-number> --repo <resolved-repo> --squash --delete-branch
 ```
 

package/skills/docs/merge-preconditions.md

@@ -32,9 +32,73 @@ A marker is allowed only while the PR is still in draft; it must be removed befo
 - `"Merge authorized if gates green"` is valid explicit authorization
 - Implied approval from prior turns is not sufficient
 
+### `autonomy.humanMergeOnly` — fixed human-only merge (non-overridable)
+
+When a repo sets `autonomy.humanMergeOnly: true` in `.devloops`, merge is a fixed
+human action and this authorization step is **non-overridable**:
+
+- `resolveAutonomyStopAt` always includes `merge`, even if `stopAt` is set to `[]`.
+- The effective merge authorization fails closed: `resolveEffectiveMergeAuthorized`
+  returns `false` regardless of the `mergeAuthorized` envelope flag or an explicit
+  "merge" instruction. The lifecycle resolver therefore never advances to the merge
+  state and parks at the `pre_approval_gate` human-merge handoff.
+- The agent still runs the full mechanical pre-merge evidence check and reports
+  merge-ready + gate evidence, then hands off to a human to perform `gh pr merge`.
+  The agent **never** runs `gh pr merge` itself.
+
+This makes human-gated merge an enforced repo invariant, not a per-run default an
+explicit instruction can unlock.
+
+### `approval.humanHandoff` — offer to assign a human at the handoff (opt-in)
+
+When a repo sets `approval.humanHandoff.enabled: true` in `.devloops`, the loop
+does not just park silently at the human-merge stop — at the
+`pre_approval_gate` / `waiting_for_merge_authorization` boundary it **offers**
+to route the PR to a named human (pairs with `autonomy.humanMergeOnly`: when
+human-merge is enforced, the handoff names who should take it). Disabled by
+default; no candidate sourcing when disabled.
+
+```yaml
+approval:
+  humanHandoff:
+    enabled: true
+    candidatesFrom: [codeowners, recent-committers]
+    assignees: [alice, bob]
+```
+
+At the handoff boundary, resolve and surface candidates:
+
+```sh
+dev-loops gate offer-human-handoff --repo <owner/name> --pr <number>
+```
+
+This prints the deduped, ordered candidate list (priority:
+`assignees` > `codeowners` for the touched paths (last-match-wins) >
+`recent-committers` to those paths, PR author/bots excluded). It assigns no one.
+
+**OFFER-only — the operator confirms the assignee** (auto-assigning without
+confirmation is a non-goal). On confirmation, perform the action:
+
+```sh
+dev-loops gate offer-human-handoff --repo <owner/name> --pr <number> \
+  --assign <login> --request-review <login>
+```
+
+which runs `gh pr edit --add-assignee` / `--add-reviewer` for the confirmed
+human(s).
+
 ## Post-merge
 
-- Remove merged worktree: `git worktree remove --force <path> && git worktree prune`
+- Remove merged worktree (canonical): `node scripts/loop/cleanup-worktree.mjs --repo-root <main> (--issue <n> | --pr <n>)`.
+  It resolves the namespaced path, runs `git worktree remove --force <path> && git worktree prune` (the underlying
+  mechanism) from the main checkout, and refuses any path not under `tmp/worktrees/dev-loops/`. See
+  [worktree guidance](../../docs/worktree-guidance.md).
+- Archive long-done queue items (operator-induced, NOT a cron): `node scripts/projects/archive-done-items.mjs --repo <owner/name> || true`.
+  Runs as part of this post-merge hook. It applies the configured `queue.archiveOlderThanDays` (default `7d`) and archives
+  board items whose issue/PR has been closed at least that long. Best-effort: run it as a standard post-merge step but ignore
+  any non-zero exit (a successful run that finds nothing to archive exits 0; a board/config-resolution/API error exits
+  non-zero, which the `|| true` masks) — a failure here must never block merge completion. See
+  [projects queue usage](../../docs/projects-queue-usage.md).
 - Clean up stale branches
 
 ## Cross-references

package/skills/docs/stop-conditions.md

@@ -10,6 +10,7 @@ Canonical owner for agent stop / wait / block conditions across all workflow fam
 | `done` lifecycle state | all | Terminal stop |
 | `approval_ready` without explicit merge auth | `final_approval` | Stop at approval gate |
 | `merge_ready` without explicit merge auth | all | Stop at `waiting_for_merge_authorization` |
+| `autonomy.humanMergeOnly: true` | all | Always stop at merge for human action, even with explicit merge auth — agent never runs `gh pr merge` (see [Merge preconditions](merge-preconditions.md)) |
 | Ambiguous / contradictory state | all | Fail closed to `needs_reconcile` |
 | Missing authoritative startup inputs | `dev-loop` | Fail closed |
 

package/skills/docs/tracker-first-loop-state.md

@@ -1,7 +1,7 @@
 # Tracker-First Story-to-PR Contract
 
 This document defines the adapter-agnostic MVP contract for the tracker-first
-story-to-PR workflow in `pi-dev-loops`.
+story-to-PR workflow in `dev-loops`.
 
 **MVP invariant: one tracker work item → one GitHub PR.**
 
@@ -43,9 +43,9 @@ are out of scope for this slice.
 | PR lifecycle facts | GitHub | Draft / ready-for-review, open / merged / closed, branch, head SHA |
 | PR review and CI facts | GitHub | Reviewer assignments, review states, check-run results, merge status |
 | Decision content | ADR / RFC artifacts (when linked) | Architecture decisions and RFCs referenced from PR body |
-| PR projection and reverse-sync logic | `pi-dev-loops` | Title/body/label generation rules, state mapping, sync triggers |
+| PR projection and reverse-sync logic | `dev-loops` | Title/body/label generation rules, state mapping, sync triggers |
 
-`pi-dev-loops` **does not** become the canonical owner of any business fields.
+`dev-loops` **does not** become the canonical owner of any business fields.
 It provides projection and sync logic only.
 
 ## 3. PR Projection Contract
@@ -234,9 +234,9 @@ This contract is intentionally narrower than the parent epics:
 
 ## 7. Related
 
-- Parent workflow-family epic: [mfittko/pi-dev-loops#17](https://github.com/mfittko/pi-dev-loops/issues/17)
-- Umbrella artifact model epic: [mfittko/pi-dev-loops#19](https://github.com/mfittko/pi-dev-loops/issues/19)
-- This contract (first implementable slice): [mfittko/pi-dev-loops#21](https://github.com/mfittko/pi-dev-loops/issues/21)
+- Parent workflow-family epic: [mfittko/dev-loops#17](https://github.com/mfittko/dev-loops/issues/17)
+- Umbrella artifact model epic: [mfittko/dev-loops#19](https://github.com/mfittko/dev-loops/issues/19)
+- This contract (first implementable slice): [mfittko/dev-loops#21](https://github.com/mfittko/dev-loops/issues/21)
 - Copilot loop state graph: [Copilot Loop State Graph](../../docs/copilot-loop-state-graph.md)
 - Reviewer loop state graph: [Reviewer Loop State Graph](../../docs/reviewer-loop-state-graph.md)
 

package/skills/local-implementation/SKILL.md

@@ -72,7 +72,13 @@ For the `local_implementation` strategy, before any planning or implementation m
 node scripts/loop/pre-flight-gate.mjs --expected-branch <working-branch> --check-subagents
 ```
 
-Before creating or reusing a worktree for local implementation, always run `git fetch origin` first. Always create worktrees from a freshly fetched `origin/main`. The fetched `origin/main` is the authoritative base for all worktree creation.
+Before creating or reusing a worktree for local implementation, use the canonical lifecycle entrypoint, which fetches the base remote, then creates-or-reuses the worktree at its namespaced path and provisions it in one step:
+
+```sh
+node scripts/loop/ensure-worktree.mjs --repo-root <main> --issue <n>
+```
+
+This creates (or reuses) the worktree at `tmp/worktrees/dev-loops/<kind>-<n>` from a freshly fetched `origin/main` (the authoritative base for all worktree creation) and provisions its gitignored runtime files. Raw `git worktree add -b <branch> tmp/worktrees/dev-loops/<kind>-<n> origin/main` is the underlying mechanism `ensure-worktree.mjs` runs for you. See [worktree guidance](../../docs/worktree-guidance.md).
 
 This validates:
 - Worktree isolation (current directory is under `tmp/worktrees/`)
@@ -85,7 +91,7 @@ Note: `--check-subagents` is advisory — it reports availability but does not b
 
 This gate does **not** apply to other routed strategies (`copilot_pr_followup`, `external_pr_followup`, `reviewer_fixer`, `wait_watch`, `final_approval`, `issue_intake`). Those strategies have their own execution rules and may edit code from any checkout as needed.
 
-Development-only bypass (`PI_PREFLIGHT_BYPASS=1`) exists for testing the gate itself but must not be used in production workflow runs. The bypass variable is a testing convenience, not an operational escape hatch.
+Development-only bypass (`DEVLOOPS_PREFLIGHT_BYPASS=1`) exists for testing the gate itself but must not be used in production workflow runs. The bypass variable is a testing convenience, not an operational escape hatch.
 
 ## Narrow failure-triage fast path