dev-loops 0.2.7 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,75 @@
 
 All notable changes to this project will be documented in this file.
 
+## Unreleased
+
+## 0.4.0
+
+### Added
+
+- **Opt-in human reviewer/assignee handoff at the pre-approval gate** (#920, pairs with #910). A new `approval.humanHandoff` config (`{ enabled (default false), candidatesFrom: ["codeowners"|"recent-committers"], assignees: [...] }`) plus `scripts/github/resolve-handoff-candidates.mjs` resolve a deduped, priority-ordered candidate list (configured `assignees` → CODEOWNERS last-match-wins for the PR's changed paths → recent committers via `git log`, excluding the PR author/bots; team handles flagged). `dev-loops gate offer-human-handoff --repo <o/n> --pr <n> [--assign <login>] [--request-review <login>]` prints the offer and, only on an explicit `--assign`/`--request-review` flag, runs `gh pr edit --add-assignee/--add-reviewer` — OFFER-only, never auto-assigns. Surfaced at the human-merge handoff so `autonomy.humanMergeOnly` routes the PR to a named human instead of parking silently. Disabled by default; fail-soft per source.
+- **Provider-agnostic CI watcher `dev-loops loop watch-ci`** (#917). A block-waiting watcher (`scripts/github/probe-ci-status.mjs`) that polls a PR's combined check-run + commit-status state for the current head SHA until terminal or timeout — covering GitHub Actions, CircleCI, and any external commit-status/check-run, unlike Actions-only `gh run watch`. It short-circuits to `changed` when the head SHA advances mid-wait so the loop re-baselines. The no-checks path is race-safe: a fresh push where a provider (CircleCI/Actions) hasn't posted its first status yet is NOT settled green on the first poll — the watcher awaits a 2-consecutive-zero-check-poll grace before settling `none`→`success`, treats PR `statusCheckRollup`-expected-but-unreported checks as pending, and never fabricates green from a transient `gh api`/parse failure (an errored fetch forces pending; a persistent error settles `timeout`, never success).
+- **`autonomy.humanMergeOnly` — fixed, non-overridable human-merge rule** (#910). Repos with a hard "a human must perform the merge" rule can now set `autonomy.humanMergeOnly: true` in `.devloops`, making merge an enforced repo invariant rather than a per-run default an explicit instruction can unlock. When set: `resolveAutonomyStopAt` always includes `merge` (even if `stopAt` is `[]`); the new authoritative gate `resolveEffectiveMergeAuthorized(mergeAuthorized, config)` fails closed — it returns `false` regardless of the `mergeAuthorized` envelope flag / explicit "merge" instruction — and the lifecycle resolver (`resolveLifecycleState`) therefore never advances to the terminal merge state, parking instead at the `pre_approval_gate` human-merge handoff. The agent still runs the full mechanical pre-merge evidence check and reports merge-ready, but never runs `gh pr merge` itself. The `queue run` path routes its `--merge-authorized` flag through the same gate. New resolvers `resolveHumanMergeOnly` / `resolveEffectiveMergeAuthorized` in `@dev-loops/core/config`; see [skills/docs/merge-preconditions.md](skills/docs/merge-preconditions.md).
+- **Managed worktree lifecycle** (#909). dev-loops now owns the full worktree lifecycle through one shared canonical-path resolver. (1) **Namespaced naming:** loop-owned worktrees live at `tmp/worktrees/dev-loops/<kind>-<number>` (e.g. `issue-909`, `pr-908`) with no branch suffix, so the path is recomputable from the issue/PR number alone — `resolveWorktreePath({ repoRoot, kind, number })` (in `@dev-loops/core/loop/handoff-envelope`) is the single source of truth for create/provision/cleanup. (1a) **Lifecycle entrypoint:** `scripts/loop/ensure-worktree.mjs --repo-root <p> (--issue <n> | --pr <n>)` is the canonical create+provision command — it fetches the base remote, creates the worktree at the canonical path (or reuses one that already exists there, reporting a conflict instead of clobbering a different branch), then invokes the provisioning core in the same step, printing `{ ok, path, created|reused, provision }`. (2) **Auto-provisioning:** a new `.devloops` `worktree` section (`copyOnInit` / `linkOnInit`, both opt-in arrays of repo-relative literal paths or glob patterns) drives `scripts/loop/provision-worktree.mjs`, which copies (`fs.cp`) or absolute-symlinks the configured gitignored files/dirs from the main checkout into a fresh worktree — directories recurse, sources outside the main checkout are rejected, missing sources / empty globs fail soft, and reuse is idempotent. It does not run `npm install` and is not a `node_modules` mirror. (3) **Namespace-scoped cleanup:** `scripts/loop/cleanup-worktree.mjs` resolves the canonical path and runs `git worktree remove --force` + `git worktree prune` from the main checkout, refusing any path not under `tmp/worktrees/dev-loops/` and failing soft on git errors. See [docs/worktree-guidance.md](docs/worktree-guidance.md).
+- **Consumer migration guide** (#769): [`docs/migrating-to-dev-loops.md`](docs/migrating-to-dev-loops.md) walks existing `pi-dev-loops` consumers through every breaking change — package name (`pi-dev-loops`→`dev-loops`, `@pi-dev-loops/core`→`@dev-loops/core`), repo slug, the full `PI_*`→`DEVLOOPS_*` env-var mapping (a deliberate clean break with no aliases), and the `.devloops` config location. Linked from the README. The env vars are not shimmed by design (`0.x`, YAGNI); the legacy `.pi/dev-loop/settings.yaml` config path still loads with a deprecation warning.
+
+### Changed
+
+- **Post-merge board archive is now a standard step of the post-merge hook** (#918). `archive-done-items.mjs` (applying `queue.archiveOlderThanDays`, default 7d) is wired into the canonical `merge-preconditions.md` "Post-merge" surface alongside worktree cleanup, and the copilot-pr-followup post-merge step is no longer framed as merely optional. Operator-induced (runs after merge); best-effort — the hook ignores a non-zero exit so a failed archive never blocks merge completion. NOT a cron/scheduled job.
+- **Queue management surfaced under `dev-loops queue`** (#912). The queue board management commands (`add`, `list`, `reorder`, `move`, `sync-status`, `archive-done`, `ensure`) are now discoverable and runnable under `dev-loops queue <sub>` alongside the existing `queue run` — `dev-loops queue --help` lists them all with one-line descriptions. They delegate to the same `scripts/projects/*.mjs` implementations; `dev-loops project <sub>` is retained as a back-compat alias group (lowest-churn: the routing table is data-driven, so `queue` reuses the existing script mappings). Flag consistency: `queue add` now accepts `--column <name>` for the Status column (matching `queue list`), with `--status <name>` kept as a back-compat alias. `move`/`sync-status` keep their distinct `--to-column`. Removes the only reason to hand-write `gh api graphql` for queue work.
+- **BREAKING: Node floor raised `>=20` → `>=24`** (#911). `engines.node` is now `>=24` in both `dev-loops` and `@dev-loops/core` (the latter previously declared no floor). CI already runs Node 24; this makes the supported floor explicit and unlocks Node 24 stdlib (e.g. native `fsp.glob`/`path.matchesGlob`). Consumers on Node < 24 must upgrade.
+- **BREAKING: all `PI_*` environment variables renamed to `DEVLOOPS_*` — no aliases, no fallback** (#905). Completing the env-var neutralization left half-done by the rebrand (#763, surfaced in #769), every dev-loops-owned operational env var is now `DEVLOOPS_*`-only; the previous neutral-first alias pattern (which honored `PI_SUBAGENT_RUN_ID` / `PI_SUBAGENT_AVAILABLE` as fallbacks) is removed. This is a deliberate `0.x` breaking change — consumers must rename their env vars (migration covered by #769). Mapping: `PI_SUBAGENT_RUN_ID`→`DEVLOOPS_RUN_ID`, `PI_SUBAGENT_AVAILABLE`→`DEVLOOPS_SUBAGENT_AVAILABLE`, `PI_PREFLIGHT_BYPASS`→`DEVLOOPS_PREFLIGHT_BYPASS`, `PI_PREPUSH_BYPASS`→`DEVLOOPS_PREPUSH_BYPASS`, `PI_WORKTREE_BYPASS`→`DEVLOOPS_WORKTREE_BYPASS`, `PI_DEV_LOOPS_DEBUG`→`DEVLOOPS_DEBUG`, `PI_DEV_LOOP_STALE_RUNNER_MAX_AGE_MS`→`DEVLOOPS_STALE_RUNNER_MAX_AGE_MS`, `PI_DEV_LOOP_DETACHED`→`DEVLOOPS_DETACHED`. The Pi-runtime-injected vars dev-loops reads only to *integrate* with the Pi harness (`PI_SESSION`, `PI_INTERACTIVE`, `PI_AGENT_SESSIONS_DIR`, `PI_SUBAGENT_SESSIONS_DIR`, `PI_SUBAGENT_ASYNC_RUNS_DIR`, `PI_SUBAGENT_ASYNC_RESULTS_DIR`) are external Pi-platform contract vars and intentionally unchanged. A `cli-harness-agnostic` guard now asserts the code is harness-agnostic: no dev-loops-owned `PI_*` env var survives, and the Pi-runtime-injected vars may only be read at the harness-adapter boundary (`pi-adapter.mjs`, `conductor-monitor.mjs`) — a `PI_*` read anywhere else in code fails.
+
+- **Remaining `pi-dev-loops` → `dev-loops` identity references aligned** (#906, closes #768). Residual stale-slug strings in a contract doc (and its generated `.claude` mirror) were corrected, guarded by the `docs-identity-contract` test so user-facing identity surfaces stay consistent.
+
+### Fixed
+
+- **`queue run` no longer fabricates `done` for undispatched items** (#913, data-integrity). The queue driver is a deterministic adapter over the board, not the orchestration harness — but its missing-orchestrator path fell back to a per-entry `{ ok: true, pr: null }`, which silently marked every `Next Up` item `done` and moved it to **Done** with `pr: null`/`runId: null` in ~1s without any work happening (a single resolve pass would "complete" an entire backlog untouched). The driver now requires a verifiable terminal signal (an orchestrator-supplied result, e.g. a merged PR) before reflecting an item to Done; with no orchestrator wired (`runEntry`) in the current harness, `dev-loops queue run` is a no-op that leaves every board column unchanged and reports `reason: "no-orchestrator"`. The legit reflect path (real merged PR → Done) is preserved.
+- **Queue board `Next Up` membership now resolves from a title-only `.devloops` config** (#904, closes #901). `resolveNextUpOrder` passed the project number as a raw number, which `list-queue-items`' string-only `--project` guard rejected — so a board configured by `queue.boardTitle` alone reported "Board configured but unavailable; nothing to run" and never read `Next Up`. The project ref is now passed as a string.
+
+## 0.3.0
+
+### Added
+
+- **Gate fan-out/fan-in review sub-loop** (epic #867, #895). The draft and pre-approval gates now run as a real fan-out on a **build-once neutral context bundle**: a deterministic context-builder script resolves review angles and builds ONE neutral bundle (full diff + adjacent code), then each independent, read-only `review` agent is seeded with that identical bundle verbatim and scoped to one angle, and a fan-in step consolidates the per-angle verdicts into a disposition ledger. The cost win is work-dedup (build once vs. N× re-derivation; a shared-prefix prompt-cache is an opportunistic bonus) — there is no fork primitive and no Workflow-tool dependency. Verdicts record their execution mode (`--execution-mode fanout_fanin | inline_single_agent`, with `--inline-reason`; #875) so the audit trail shows how the gate was actually run. See [docs/gate-review-sub-loop-contract.md](docs/gate-review-sub-loop-contract.md).
+  - **Context-builder handoff + dynamic angles** (#880, #895). A `write-gate-context` step emits the per-gate scope/diff artifact plus a deterministic, neutral `adjacentCode` bundle (each changed file's 1-hop import callers/callees/imports, with size guards + a stripped/truncated/missing manifest) that every reviewer is seeded with verbatim, and angles are resolved dynamically (configurable `mandatory` set plus `gates.dynamicAngles`), bounded by `gates.maxFanoutReviewers` (default 8).
+  - **Independent scoped reviewers + fan-in consolidation** (#881, #895). Per-angle `review` agents are independent fresh-context Agents seeded with the neutral bundle (never inheriting the main agent's state); they emit structured findings, and `consolidateFanin` merges them and computes the `fanout_fanin` verdict against `blockCleanOnFindingSeverities` (`must-fix`, `worth-fixing-now`).
+  - **Full-diff + adversarial scoped review with scope widening** (#886, #885, #895). The context-builder builds the full PR diff and a generous adjacent-code bundle once, and reviewers use it as their base and widen only per-angle when needed. Reviewers run adversarially against the complete change — this surfaced real defects (arg coercion, head-SHA casing, markdown injection, dead seams) that the prior single-pass review missed.
+- **Fan-out findings posted to the PR** (#888, #887). The gate posts a single marker-tagged, idempotent PR comment listing its findings so Copilot and humans see them, and the loop fixes/resolves its own findings as it does Copilot comments. Opt out with `gates.postFindingsComments: false` (default on).
+- **Configured board drives queue membership** (#884, #864). A configured GitHub Projects board's `Next Up` column is now the authoritative source of queue membership and ordering (not just status); emptiness reports a precise verdict (`queue_empty` / `board_empty` / `board_unavailable`) instead of a misleading generic message.
+
+### Changed
+
+- **Gate fan-out evidence enforcement is now ON by default** (#882, #879, epic #867 final phase). A clean gate verdict requires the gate to have run via `--execution-mode fanout_fanin` with a findings-log ledger for the head SHA; the pre-merge evidence check fails closed otherwise. Repos can opt out with `gates.requireFanoutEvidence: false`.
+- **Board status auto-syncs on dev-loop transitions** (#883, #874). A linked issue's board Status column is synced on loop transitions (e.g. PR opened → `In Progress`, merged → `Done`) via local `gh` auth — best-effort and non-fatal. Repairs the `move-queue-item` lookup that passed numeric (not string) project/item refs.
+
+### Fixed
+
+- **Skill shims import `@dev-loops/core` via its package specifier** (#890). `skills/dev-loop/scripts/log-bash-exit-1.mjs` and `phase-files.mjs` previously reached into core through cross-package relative paths (`../../../packages/core/src/...`), which are broken on disk for npm consumers because the published `dev-loops` package ships `skills/` but not `packages/core/`. They now import via the `@dev-loops/core` `exports` map. A contract test guards against reintroducing relative cross-package imports under `skills/`.
+- **Draft-gate deadlock on ready PRs resolved** (#891). Posting a `draft_gate` verdict on a PR that is already ready-for-review (e.g. opened directly as ready) no longer dead-ends. `upsert-checkpoint-verdict` now (a) treats an already-satisfied draft gate as an idempotent no-op instead of a hard error, and (b) when a ready PR still needs clean draft-gate evidence, performs the draft→post→ready transition automatically — preserving the caller's execution mode (`fanout_fanin`), findings, and ledger. This is the fanout-aware analogue of `reconcile-draft-gate` (which only posts inline and so cannot satisfy `requireFanoutEvidence` on the draft gate).
+- **PR self-assignment is now mechanically enforced** (#894). The draft-PR wrapper is renamed `scripts/github/create-draft-pr.mjs` → `scripts/github/create-pr.mjs` (`dev-loops pr create-draft` → `dev-loops pr create`, with the old subcommand kept as a deprecated alias). It now defaults `--assignee @me` when no `--assignee` is given (while still honoring an explicit `--assignee <login>`), so every PR opened through the canonical path is ALWAYS a draft and is always assigned — self-assigned by default — closing the silent gap where unassigned PRs (e.g. #889, #892, #893) missed the owner's assignee inbox. A new contract guard (`test/contracts/canonical-pr-creation-contract.test.mjs`) fails if any skill/agent procedure doc instructs opening a PR with raw `gh pr create`.
+- **Post-round-cap convergence deadlock resolved** (#896). At the Copilot round cap with clean threads + green CI, a post-cap head that Copilot will not re-review now routes to a clean fallback that permits the `pre_approval_gate` to review the current head, instead of dead-ending at `ready_to_rerequest_review` (the deadlock #848 intended to prevent). Root cause: the coordination-context loader did not pass the resolved config into the loop interpreter, so `maxCopilotRounds` was unseen and `ROUND_CAP_CLEAN_FALLBACK` never resolved; the draft-gate round-reset is now a shared helper so `request-copilot-review` and `detect-pr-gate-coordination-state` agree on the round count. Genuinely-blocked states (failing/unconfirmed CI, unresolved feedback, conflicts, missing draft-gate evidence) still hold.
+- **Gate verdict renders consolidated per-angle findings structurally** (#898). A `fanout_fanin` verdict comment renders the per-angle fan-in findings as a readable list (per-angle verdict + findings) via a new `--findings-json`, instead of collapsing the summary to a single run-on line. The gate-evidence parse contract is preserved (a single-line digest still anchors the `Findings summary:` field, and `gateEvidenceNote` is carried), input shape is validated (per-angle or flat-grouped; unrecognized input is rejected rather than silently dropped), and `--findings-summary` remains the inline fallback.
+
+## 0.2.8
+
+### Added
+
+- **Local post-merge board archive** (#869). The dev-loop post-merge step archives `Done`-column board items older than a configurable threshold (`.devloops` `queue.archiveOlderThanDays`, default 7d) using local `gh` auth — best-effort, non-fatal, no CI/cron/PAT. On-demand `dev-loops project archive-done` is unchanged.
+- **Gate execution-mode disclosure scaffolding** (#867, partial). Gate verdicts can record `--execution-mode` / `--inline-reason`; opt-in `gates.requireFanoutEvidence` (default off) is available. (Live fan-out/fan-in execution remains follow-up.)
+
+### Fixed
+
+- **`dev-loops project move` repaired** (#865). Item lookup now resolves both issue/PR number and node-id refs against a single paginated board-item list; fixes the `ITEM_NOT_FOUND` (unpaginated `first:10`) and the invalid `ProjectV2.item` GraphQL query.
+
+### Changed
+
+- **Index-based arg parsers migrated to `node:util.parseArgs`** (#857, #870). The remaining `argv[++i]` parsers across `scripts/projects`, `scripts/loop`, `scripts/claude`, and `archive-done-items.mjs` now use `parseArgs`; CLI contracts preserved and boolean flags reject an explicit inline `=value`.
+
+### Documentation
+
+- **Tooling-internals anti-pattern promoted** (#861, #863). The "use the CLI/`--help`/`skills/docs/` instead of reading tooling source" rule is now a canonical entry in `skills/docs/anti-patterns.md`, with a local failure-triage fast path and pointers from the `developer`/`fixer` agents.
+
 ## 0.2.7
 
 ### Fixed

package/README.md

@@ -89,7 +89,7 @@ pi install git:github.com/mfittko/dev-loops    # global
 pi install -l git:github.com/mfittko/dev-loops # project-local
 ```
 
-The CLI requires Node `>=20` and a GitHub-authenticated `gh` CLI for repository workflows. See [Requirements](#requirements).
+The CLI requires Node `>=24` and a GitHub-authenticated `gh` CLI for repository workflows. See [Requirements](#requirements).
 
 ## Docker
 
@@ -199,6 +199,12 @@ Key surfaces:
 
 Full details: [Extension Documentation](./extension/README.md) and `.pi/dev-loop/defaults.yaml`.
 
+### Migrating from an earlier release
+
+Upgrading an install from before the rename to `dev-loops`? The package name, repo slug,
+and all `PI_*` environment variables changed (the env vars are a clean break — no aliases).
+See the [migration guide](./docs/migrating-to-dev-loops.md) for the full change list.
+
 ## Package surface
 
 The `dev-loops` package ships both a standalone CLI and a Pi extension. Consumer repos should prefer pinned Pi package installs; global npm installs are optional, not part of the Pi runtime contract.
@@ -247,7 +253,7 @@ See [Extension Documentation](./extension/README.md) for the full command and pa
 
 ## Requirements
 
-- Node `>=20`
+- Node `>=24`
 - `gh` installed and authenticated for GitHub/Copilot workflows
 - `pi-subagents` for async workflow assumptions
 - A Pi host that satisfies peer dependencies on `@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui`

package/agents/developer.agent.md

@@ -19,6 +19,7 @@ You are a focused implementation agent. You take a single clearly-scoped coding
 - Do not re-plan the broader milestone unless a blocker forces it.
 - Stay within the requested scope and files unless a small adjacent fix is required to complete the task safely.
 - Preserve existing project conventions and package/runtime behavior.
+- Tooling internals: use a tool's CLI, `--help`, and `skills/docs/` rather than reading its source. See [Anti-patterns](../skills/docs/anti-patterns.md#core-anti-patterns).
 
 ## Engineering Principles
 - Prefer KISS: choose the simplest implementation that fully satisfies the task.

package/agents/fixer.agent.md

@@ -24,6 +24,7 @@ You are a focused review-fix agent. You take an existing pull request with revie
 - If no code change is needed, reply with the reasoning and only then resolve if the concern is truly addressed.
 - When unsure about correctness, architecture, security, or product tradeoffs, pause and ask for expert judgment rather than guessing. Use the available project workflow for expert review when possible, or clearly report the decision needed.
 - Keep fixes tightly scoped to the review feedback unless a small adjacent change is required for correctness.
+- Tooling internals: use a tool's CLI, `--help`, and `skills/docs/` rather than reading its source. See [Anti-patterns](../skills/docs/anti-patterns.md#core-anti-patterns).
 
 ## Review Workflow
 1. Read unresolved review threads and any general review comments.

package/agents/review.agent.md

@@ -27,6 +27,36 @@ You are a focused pull request review agent. You review an implementation for co
 - Only perform a full re-review when the caller explicitly requests one (e.g., "full review", "review from scratch", "re-review everything"), or when no prior review by that reviewer exists.
 - Explicitly state the delta scope at the top of the output (e.g., "Delta review covering commits since `abc1234` on 2026-05-07").
 
+## Scoped angle-review mode
+
+This agent has two modes. The default mode is the full-PR review described in the rest of this file. The **scoped angle-review mode** is the per-angle reviewer of the gate-review fan-out ([Gate Review Sub-Loop Contract](../docs/gate-review-sub-loop-contract.md)): the gate skill builds ONE deterministic, neutral context bundle (diff + adjacent code) and seeds each independent `review` agent with that identical bundle, each scoped to exactly one review concern. You receive only the neutral artifact + your angle — never the main (orchestrating) agent's conversation, opinions, or state.
+
+You are in scoped angle-review mode when the invocation supplies a single review `<angle>` plus a gate-context artifact path (`tmp/gate-context/<repo-slug>/pr-<N>/<gate>-<headSha>.json`, written by `scripts/github/write-gate-context.mjs`). Review like an external code reviewer hunting real bugs, not a process auditor: your job is to find concrete defects in the changed code and its call paths, not to remark that "there is no test" or that a doc section is thin. In that mode:
+
+- **Fresh-context guard (mandatory):** run `node scripts/github/verify-fresh-review-context.mjs --scope <angle>` at startup. If it reports `fresh: false` (exit 1) or any error, refuse to proceed and report contamination — do not review on inherited context. "Fresh" here means your context is the **neutral builder artifact + your angle**, and explicitly NOT the main agent's conversation/state or a prior reviewer session's state. The injected neutral bundle is the INTENDED seed (allowed); main-agent or cross-session state bleed still fails closed.
+- **Use the PROVIDED neutral bundle as your base; do NOT re-derive it from scratch:** the gate-context artifact carries the diff (`scope.diffPath`) and a deterministic, neutral adjacent-code bundle in `adjacentCode` (each changed file plus its 1-hop import in/out-edges, with a `stripped`/`truncated`/`missing` manifest). Start from this bundle — it is the build-once, work-deduped seed shared verbatim across all reviewers. Only widen (load more files) per-angle when the bundle genuinely lacks something your angle needs; do not re-build the whole diff/adjacent-code graph yourself.
+- **Single-angle scope:** review ONLY the supplied angle's concern. Read the gate-context artifact for the resolved angle set, change scope (branch, head SHA, touched files), acceptance-criteria pointer, and validation posture. Do not review other angles; the fan-in pass consolidates across angles.
+- **Read the FULL diff, not just hunks:** the gate-context artifact records `scope.diffPath` (a repo-relative path to the complete captured diff) and `scope.changedFiles` (full repo-relative paths). Read the entire diff from `scope.diffPath`; if it is `null` or missing, reconstruct it yourself with `git diff` against the change's base (e.g. `git diff origin/main...HEAD` or the branch/head SHA in `scope`). Do not review off a partial or summarized hunk list — you must see every changed line for your angle.
+- **Reason about ADJACENT related code from the bundle first:** the `adjacentCode` bundle already includes the changed files' callers, callees, and imports (1-hop). Read those entries before opening anything else. For each changed function, trace the real call paths a defect would flow through, and confirm that caller and callee contracts still match (argument shapes, return shapes, error/null conventions, units). If the bundle truncated or stripped a file you need (see its `truncated`/`stripped` manifest), open that file directly to widen.
+- **Review ADVERSARIALLY — hunt concrete defects:** actively try to break the changed code. Hunt for edge cases, missing or wrong input validation, numeric coercion bugs (NaN, Infinity, floats where integers are assumed, negative values, string-to-number coercion), null/undefined handling, off-by-one and boundary conditions, mismatched caller/callee contracts, and dedup/identity bugs (wrong key, reference vs. value equality, unstable ordering). For every finding, give the concrete `file:line` plus the specific failing scenario or input that triggers the defect — not high-altitude "is there a test?" commentary.
+- **Strictly read-only, but WIDEN SCOPE when needed:** never edit files, stage, commit, push, request reviews, resolve threads, or post PR comments. Findings are returned via the output artifact only; fixes are applied later by the fix cycle, not by this agent. Because you are read-only, you MAY open any additional repository files required to judge your angle (callers, callees, contracts, sibling modules, configs, tests) — widening to read adjacent code is expected and safe. Record every file/module you consulted beyond the briefing's `changedFiles`/`diffPath` in the optional `contextWidened` field on your output artifact.
+- **Structured findings artifact:** return a single JSON object the fan-in consolidator (`@dev-loops/core/loop/gate-fanin`) can parse, written to the deterministic per-angle path `tmp/gate-reviews/<repo-slug>/pr-<N>/<gate>-<headSha>/<angle>.json`:
+
+  ```json
+  {
+    "angle": "<angle>",
+    "verdict": "clean" | "findings_present",
+    "findings": [
+      { "severity": "must-fix" | "worth-fixing-now" | "defer", "file": "<path>", "line": 0, "summary": "<concise>", "recommendation": "<concise fix>" }
+    ],
+    "contextWidened": ["<adjacent-path-consulted>", "..."]
+  }
+  ```
+
+  `verdict` is `clean` iff `findings` is empty; otherwise `findings_present`. `severity` uses the gate vocabulary (`must-fix` | `worth-fixing-now` | `defer`). `file`/`line`/`recommendation` are optional per finding. `contextWidened` is optional: list the adjacent files/modules you opened beyond the briefing to judge this angle (omit or leave empty if you reviewed only `changedFiles`).
+
+When NOT given an angle scope, behave exactly as the full-PR review agent described below.
+
 ## Review Focus
 - Scope correctness: does the implementation match the PR description's change summary, the stated acceptance criteria, and the relevant plan?
 - Acceptance criteria coverage: are the stated acceptance criteria complete, testable, and actually satisfied?

package/cli/index.mjs

@@ -22,16 +22,19 @@ const SUBCOMMAND_ROUTES = {
     "upsert-verdict":     "scripts/github/upsert-checkpoint-verdict.mjs",
     "detect-evidence":    "scripts/github/detect-checkpoint-evidence.mjs",
     "write-findings-log": "scripts/github/write-gate-findings-log.mjs",
+    "post-findings":      "scripts/github/post-gate-findings.mjs",
     "request-copilot":    "scripts/github/request-copilot-review.mjs",
     "probe-copilot":      "scripts/github/probe-copilot-review.mjs",
     "capture-threads":    "scripts/github/capture-review-threads.mjs",
     "reply-resolve":      "scripts/github/reply-resolve-review-threads.mjs",
+    "offer-human-handoff": "scripts/github/offer-human-handoff.mjs",
   },
   loop: {
     startup:        "scripts/loop/resolve-dev-loop-startup.mjs",
     "build-envelope": "scripts/loop/build-handoff-envelope.mjs",
     outer:          "scripts/loop/outer-loop.mjs",
     "watch-cycle":  "scripts/loop/run-watch-cycle.mjs",
+    "watch-ci":     "scripts/github/probe-ci-status.mjs",
     handoff:        "scripts/loop/copilot-pr-handoff.mjs",
     "watch-initial": "scripts/loop/watch-initial-copilot-pr.mjs",
     "loop-state":           "scripts/loop/detect-copilot-loop-state.mjs",
@@ -43,7 +46,7 @@ const SUBCOMMAND_ROUTES = {
     "debt-remediate":       "scripts/loop/debt-remediate.mjs",
   },
   pr: {
-    "create-draft":     "scripts/github/create-draft-pr.mjs",
+    create:             "scripts/github/create-pr.mjs",
     "ready-for-review": "scripts/github/ready-for-review.mjs",
     "reconcile-draft":  "scripts/github/reconcile-draft-gate.mjs",
   },
@@ -53,10 +56,18 @@ const SUBCOMMAND_ROUTES = {
     move:    "scripts/projects/move-queue-item.mjs",
     reorder: "scripts/projects/reorder-queue-item.mjs",
     "archive-done": "scripts/projects/archive-done-items.mjs",
+    "sync-status": "scripts/projects/sync-item-status.mjs",
     ensure:  "scripts/projects/ensure-queue-board.mjs",
   },
   queue: {
     run:            "scripts/loop/run-queue.mjs",
+    list:    "scripts/projects/list-queue-items.mjs",
+    add:     "scripts/projects/add-queue-item.mjs",
+    move:    "scripts/projects/move-queue-item.mjs",
+    reorder: "scripts/projects/reorder-queue-item.mjs",
+    "archive-done": "scripts/projects/archive-done-items.mjs",
+    "sync-status": "scripts/projects/sync-item-status.mjs",
+    ensure:  "scripts/projects/ensure-queue-board.mjs",
   },
   inspect: {
     run:    "scripts/loop/inspect-run.mjs",
@@ -67,34 +78,54 @@ const SUBCOMMAND_ROUTES = {
   },
 };
 
+// Back-compat subcommand aliases: { category: { oldName: { canonical, notice } } }.
+// Aliases keep existing callers working while emitting a one-line deprecation
+// notice to stderr so they migrate to the canonical subcommand.
+const SUBCOMMAND_ALIASES = {
+  pr: {
+    "create-draft": {
+      canonical: "create",
+      notice: "[dev-loops] `pr create-draft` is deprecated; use `pr create` (always draft, self-assigned by default).",
+    },
+  },
+};
+
+function resolveSubcommandAlias(category, subcommand) {
+  return SUBCOMMAND_ALIASES[category]?.[subcommand] ?? null;
+}
+
 const TOP_LEVEL_COMMANDS = new Set(["help", "status", "doctor", "gates", "hide"]);
 
 const HELP_CATEGORY_LABELS = {
   gate: "Gate verdicts, evidence, and review operations",
   loop: "Loop lifecycle",
   pr: "PR helpers",
-  project: "GitHub Projects queue helpers",
+  queue: "Queue board: run + management (add/list/reorder/move/sync-status/archive)",
+  project: "Alias for queue (GitHub Projects queue helpers)",
   inspect: "Inspection (Pi extension only)",
   refine: "Epic tree refinement verification",
 };
 
-const TOP_LEVEL_HELP_CATEGORY_ORDER = ["gate", "loop", "pr", "project", "inspect", "refine"];
+const TOP_LEVEL_HELP_CATEGORY_ORDER = ["gate", "loop", "pr", "queue", "project", "inspect", "refine"];
 
 const SUBCOMMAND_DESCRIPTIONS = {
   gate: {
     "upsert-verdict": "Post/update gate review comment",
     "detect-evidence": "Check merge preconditions",
     "write-findings-log": "Write disposition ledger",
+    "post-findings": "Post gate fan-out findings comment",
     "request-copilot": "Request Copilot review",
     "probe-copilot": "Poll for Copilot review activity",
     "capture-threads": "Capture review threads",
     "reply-resolve": "Reply and resolve review threads",
+    "offer-human-handoff": "Offer to assign PR to a human reviewer/assignee",
   },
   loop: {
     startup: "Resolve dev-loop startup bundle",
     "build-envelope": "Build handoff envelope from startup output",
     outer: "Run outer-loop detection",
     "watch-cycle": "Run Copilot wait cycle",
+    "watch-ci": "Block-wait on provider-agnostic CI (CircleCI/Actions/external)",
     handoff: "Copilot PR handoff",
     "watch-initial": "Watch initial Copilot PR",
     "loop-state": "Detect Copilot loop state",
@@ -106,7 +137,7 @@ const SUBCOMMAND_DESCRIPTIONS = {
     "debt-remediate": "File debt remediation issues",
   },
   pr: {
-    "create-draft": "Create draft PR",
+    create: "Create PR (always draft, self-assigned by default)",
     "ready-for-review": "Mark PR ready for review",
     "reconcile-draft": "Reconcile non-draft PR",
   },
@@ -116,10 +147,18 @@ const SUBCOMMAND_DESCRIPTIONS = {
     move: "Move queue item between Status columns",
     reorder: "Reorder items (move-to-top/move-after/order, --dry-run)",
     "archive-done": "Archive closed Done items older than a duration",
+    "sync-status": "Sync a queued issue/PR's board Status column (best-effort)",
     ensure: "Create/repair queue board bootstrap surface",
   },
   queue: {
     run: "Run queue driver",
+    list: "List queue board items",
+    add: "Add issue/PR to queue board",
+    move: "Move queue item between Status columns",
+    reorder: "Reorder items (move-to-top/move-after/order, --dry-run)",
+    "archive-done": "Archive closed Done items older than a duration",
+    "sync-status": "Sync a queued issue/PR's board Status column (best-effort)",
+    ensure: "Create/repair queue board bootstrap surface",
   },
   inspect: {
     run: "Inspect run state",
@@ -275,16 +314,19 @@ function resolveSubcommandRoute(args) {
     return { error: `Missing subcommand for '${category}'. Available: ${subs}` };
   }
 
-  const subcommand = args[1];
+  const requestedSubcommand = args[1];
+  const alias = resolveSubcommandAlias(category, requestedSubcommand);
+  const subcommand = alias ? alias.canonical : requestedSubcommand;
   const scriptPath = routes[subcommand];
   if (!scriptPath) {
     const subs = Object.keys(routes).join(", ");
-    return { error: `Unknown subcommand '${subcommand}' for '${category}'. Available: ${subs}` };
+    return { error: `Unknown subcommand '${requestedSubcommand}' for '${category}'. Available: ${subs}` };
   }
 
   return {
     scriptPath: path.resolve(REPO_ROOT, scriptPath),
     forwardedArgs: args.slice(2),
+    ...(alias ? { deprecationNotice: alias.notice } : {}),
   };
 }
 
@@ -313,9 +355,17 @@ function parseTopLevelCommand(argv) {
     }
     // Check if any remaining arg is --help — delegate to script
     if (args.slice(1).some((a) => a === "--help" || a === "-h")) {
-      const scriptPath = routes[sub];
+      const alias = resolveSubcommandAlias(cmd, sub);
+      const resolvedSub = alias ? alias.canonical : sub;
+      const scriptPath = routes[resolvedSub];
       if (!scriptPath) return { kind: "category_help", category: cmd };
-      return { kind: "subcommand_help", scriptPath: path.resolve(REPO_ROOT, scriptPath) };
+      return {
+        kind: "subcommand_help",
+        scriptPath: path.resolve(REPO_ROOT, scriptPath),
+        // Surface the deprecation notice on the --help fast-path too, so a
+        // deprecated alias signals migration in help mode (not only on dispatch).
+        ...(alias ? { deprecationNotice: alias.notice } : {}),
+      };
     }
     const route = resolveSubcommandRoute(args);
     if (route) return { kind: "subcommand", ...route };
@@ -345,6 +395,7 @@ export async function runCli({
       return 0;
     }
     case "subcommand_help": {
+      if (fromTop.deprecationNotice) { writeLines(stderr, [fromTop.deprecationNotice]); }
       const result = spawnSync("node", [fromTop.scriptPath, "--help"], {
         cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
       });
@@ -383,6 +434,7 @@ export async function runCli({
     }
     case "subcommand": {
       if (fromTop.error) { writeLines(stderr, [fromTop.error]); return 1; }
+      if (fromTop.deprecationNotice) { writeLines(stderr, [fromTop.deprecationNotice]); }
       const scriptArgs = fromTop.forwardedArgs || [];
       const result = spawnSync("node", [fromTop.scriptPath, ...scriptArgs], {
         cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],

package/extension/README.md

@@ -210,7 +210,7 @@ Config is validated at runtime by Zod schemas (`packages/core/src/config/config.
 ## Runtime / build / test contract
 
 Current Phase 3+ contract:
-- Node runtime floor: `>=20` (from `package.json`)
+- Node runtime floor: `>=24` (from `package.json`)
 - Pi host expectations are documented from current peer dependencies rather than a tested pinned Pi version range
 - the extension is source-loaded from `./extension/index.ts` through `package.json` `pi.extensions`
 - the package exposes `skills` through `package.json` `pi.skills` for install-based global skill loading

package/package.json

@@ -15,7 +15,7 @@
     "pi-package"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=24"
   },
   "workspaces": [
     "packages/*"
@@ -68,7 +68,7 @@
   },
   "dependencies": {
     "mermaid": "11.15.0",
-    "@dev-loops/core": "^0.2.7"
+    "@dev-loops/core": "^0.4.0"
   },
   "repository": {
     "type": "git",
@@ -78,7 +78,7 @@
     "url": "https://github.com/mfittko/dev-loops/issues"
   },
   "homepage": "https://github.com/mfittko/dev-loops#readme",
-  "version": "0.2.7",
+  "version": "0.4.0",
   "files": [
     "cli/",
     "lib/",

package/scripts/README.md

@@ -68,16 +68,17 @@ Failure behavior:
 - malformed arguments, invalid JSON, and `gh` failures emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
 - live capture is only allowed when both `--repo` and `--pr` are present
 
-### `scripts/github/create-draft-pr.mjs`
+### `scripts/github/create-pr.mjs`
 
-Thin wrapper around `gh pr create` for draft-first PR creation.
+Canonical wrapper around `gh pr create`. Every PR opened through this tool is ALWAYS a draft and is always assigned — self-assigned by default (`--assignee @me` when none is given), while still honoring an explicit `--assignee <login>`. Never call raw `gh pr create` to open a PR. (`dev-loops pr create` dispatches here; the legacy `dev-loops pr create-draft` subcommand still works as a deprecated alias.)
 
 Usage:
-- `node scripts/github/create-draft-pr.mjs [gh pr create args...]`
-- `node <resolved-skill-scripts>/github/create-draft-pr.mjs [gh pr create args...]`
+- `node scripts/github/create-pr.mjs [gh pr create args...]`
+- `node <resolved-skill-scripts>/github/create-pr.mjs [gh pr create args...]`
 
 Contract:
-- injects exactly one `--draft` when the caller did not already supply it
+- injects exactly one `--draft` when the caller did not already supply it (draft is the only mode)
+- self-assigns by default (defaults `--assignee @me` when no `--assignee` is provided); honors an explicit `--assignee <login>` when one is given
 - rejects `--ready` before invoking `gh`; use `gh pr ready` later after draft-gate approval
 - forwards every other argument to `gh pr create` unchanged and in order
 - preserves the underlying `gh pr create` stdout, stderr, and exit code without wrapping success output
@@ -498,7 +499,7 @@ Contract:
 - enters watch only when request state is confirmed (`requested` or `already-requested`) and emits exact `watchArgs` + `watchTimeoutPolicy`
 - watch refresh (`--watch-status`) is observational-only; rely on refreshed `loopDisposition` + `terminal` to decide whether to continue or stop
 - explicit stop/blocked routing is machine-readable via `action: "stop"` plus `requestWatchContract.stopState`
-- when `PI_SUBAGENT_RUN_ID` is set to a non-empty value, the helper enforces one-runner-per-PR ownership and returns `runnerOwnership` details when a conflicting or displaced run must stop
+- when `DEVLOOPS_RUN_ID` is set to a non-empty value, the helper enforces one-runner-per-PR ownership and returns `runnerOwnership` details when a conflicting or displaced run must stop
 
 Success output shape:
 - `{ "ok": true, "action": "watch"|"fix"|"stop", "state": "...", "allowedTransitions": [...], "nextAction": "...", "snapshot": {...}, "reviewRequestStatus"?: "...", "watchStatus"?: "...", "autoRerequestEligible": true|false, "sameHeadCleanConverged": true|false, "loopDisposition": "...", "terminal": true|false, "requestWatchContract": { "action": "...", "nextAction": "...", "requestStatus": "requested"|"already-requested"|"unavailable"|"failed"|"none", "routingState": "copilot_request_confirmed_waiting"|"ready_state_needs_copilot_request"|"draft_reset_requires_ready_state_reentry"|"non_ready_state", "watchEntryConfirmed": true|false, "watchArgs": { ... }|null, "stopState"?: "unavailable"|"blocked"|"draft_requires_ready_state_reentry"|"no_automatic_next_step" }, "watchTimeoutPolicy"?: { "classification": "external_healthy_wait", "minimumTimeoutMs": 1800000, "defaultTimeoutMs": 1800000 }, "watchArgs"?: { ... } }`
@@ -721,7 +722,7 @@ Fetches the live PR head SHA plus visible PR issue comments, then summarizes the
 latest valid `draft_gate` and `pre_approval_gate` checkpoint verdict comments.
 Use this when a fresh session needs authoritative visible gate evidence for the
 current head before running `gh pr ready` or declaring final-approval readiness.
-When `PI_SUBAGENT_RUN_ID` is set to a non-empty value, it also enforces async runner ownership before reading GitHub facts, so stale/displaced runs fail closed before merge.
+When `DEVLOOPS_RUN_ID` is set to a non-empty value, it also enforces async runner ownership before reading GitHub facts, so stale/displaced runs fail closed before merge.
 
 Required:
 - `--repo <owner/name>`

package/scripts/_core-helpers.mjs

@@ -19,6 +19,7 @@ export {
   normalizeTimestamp,
   parseGateReviewCommentBody,
   parseGateReviewCommentMarkerBody,
+  resolveDraftGateRoundResetMs,
   summarizeCopilotReviews,
   summarizeGateReviewCommentMarkers,
   summarizeGateReviewComments,

package/scripts/claude/headless-dev-loop.mjs

@@ -20,6 +20,7 @@
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
 
 import { ensureRunId } from "@dev-loops/core/loop/run-context";
 import {
@@ -28,22 +29,61 @@ import {
   DEFAULT_CLAUDE_BIN,
 } from "@dev-loops/core/claude/headless-entry";
 
-function parseArgs(argv) {
+function parseCliArgs(argv) {
   const opts = { dryRun: false, claudeBin: DEFAULT_CLAUDE_BIN };
-  const requireValue = (name, i) => {
-    const v = argv[i + 1];
-    if (v === undefined || v.startsWith("--")) throw new Error(`${name} requires a value`);
+  const requireValue = (name, token) => {
+    const v = token.value;
+    if (typeof v !== "string" || v.length === 0 || v.startsWith("--")) {
+      throw new Error(`${name} requires a value`);
+    }
     return v;
   };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--dry-run") opts.dryRun = true;
-    else if (a === "--issue") { opts.issue = requireValue(a, i); i++; }
-    else if (a === "--pr") { opts.pr = requireValue(a, i); i++; }
-    else if (a === "--claude-bin") { opts.claudeBin = requireValue(a, i); i++; }
-    else if (a === "--prompt") { opts.prompt = requireValue(a, i); i++; }
-    else throw new Error(`unknown argument: ${a}`);
+
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      "dry-run": { type: "boolean" },
+      issue: { type: "string" },
+      pr: { type: "string" },
+      "claude-bin": { type: "string" },
+      prompt: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw new Error(`unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    switch (token.name) {
+      case "dry-run":
+        if (token.value !== undefined) {
+          throw new Error(`unknown argument: ${token.rawName}=${token.value}`);
+        }
+        opts.dryRun = true;
+        break;
+      case "issue":
+        opts.issue = requireValue("--issue", token);
+        break;
+      case "pr":
+        opts.pr = requireValue("--pr", token);
+        break;
+      case "claude-bin":
+        opts.claudeBin = requireValue("--claude-bin", token);
+        break;
+      case "prompt":
+        opts.prompt = requireValue("--prompt", token);
+        break;
+      default:
+        throw new Error(`unknown argument: ${token.rawName}`);
+    }
   }
+
   if (opts.issue != null && opts.pr != null) {
     throw new Error("--issue and --pr are mutually exclusive");
   }
@@ -53,7 +93,7 @@ function parseArgs(argv) {
 function main(argv) {
   let opts;
   try {
-    opts = parseArgs(argv);
+    opts = parseCliArgs(argv);
   } catch (error) {
     process.stderr.write(JSON.stringify({ ok: false, error: error.message }) + "\n");
     return 1;