dev-loops 0.7.1 → 0.8.0

package/README.md

@@ -1,72 +1,65 @@
 # dev-loops
 
-Turn GitHub issues into merged PRs with zero manual steps between issue and approval.
+Turn a GitHub issue into a merged PR autonomously, up to a human-approval checkpoint.
 
-## What is a dev loop?
+**Harness-agnostic by design.** The same dev loop runs three ways over one shared core (`packages/core`): as a **Claude Code plugin**, as a **Pi extension**, and as a standalone **CLI**. Routing, gates, and phases are defined once in the core; the plugin and extension are thin integrations over that shared workflow.
 
-A dev loop is an AI-driven development cycle. It takes a GitHub issue through seven lifecycle phases — from intake to merge — with deterministic routing, self-correcting review gates, and autonomous execution until the human approval checkpoint.
+## What is a dev loop?
 
-**Lifecycle phases:**
+A dev loop takes a GitHub issue through seven lifecycle phases — from intake to merge — with deterministic routing, self-correcting review gates, and autonomous execution until a human approves. The phase is always consultable from the deterministic state model in `packages/core/src/loop/lifecycle-state.mjs`.
 
 | Phase | What happens |
 |---|---|
 | `issue_intake` | Normalize the issue, confirm scope, detect linked PRs |
-| `refinement` | Elaborate spec, run bounded audit, harden acceptance criteria |
+| `refinement` | Elaborate the spec, run a bounded audit, harden acceptance criteria |
 | `implementation` | Build the accepted scope on a feature branch or via Copilot |
-| `draft_gate` | Gate review at the draft→ready boundary before marking PR ready |
+| `draft_gate` | Gate review at the draft→ready boundary before marking the PR ready |
 | `feedback_resolution` | Fix, reply to, and resolve review threads on GitHub |
 | `pre_approval_gate` | Final gate review: verify evidence, CI, and unresolved threads |
 | `merge` | Merge the PR and write the retrospective checkpoint |
 
-Each phase is consultable from the deterministic state model in `packages/core/src/loop/lifecycle-state.mjs`. The public routing contract is [Public Dev Loop Contract](./skills/docs/public-dev-loop-contract.md).
+The public routing contract is the [Public Dev Loop Contract](./skills/docs/public-dev-loop-contract.md).
 
 ## Quick start
 
-Use **`dev-loop`** as the single public workflow entrypoint:
+`dev-loop` is the single public entrypoint. Drive it in natural language — it resolves the authoritative current state, picks the correct internal strategy, and routes deterministically. You never name internal strategies.
 
-- `start dev loop on issue 112` — start work on an issue
-- `auto dev loop on issue 112` — autonomous execution until human approval
-- `continue dev loop on PR 88` — continue follow-up on an open PR
+```text
+start dev loop on issue 112       # start work on an issue
+auto dev loop on issue 112        # run autonomously to the human-approval checkpoint
+continue dev loop on PR 88        # continue follow-up on an open PR
+```
 
-The `dev-loop` entrypoint resolves authoritative state, picks the correct internal strategy, and routes work deterministically. Users never need to choose internal strategy names. See the canonical shorthand example mapping in the [Public Dev Loop Contract](./skills/docs/public-dev-loop-contract.md).
+See the canonical shorthand mapping in the [Public Dev Loop Contract](./skills/docs/public-dev-loop-contract.md).
 
-### Direct commands
+## Commands
 
-The same entrypoints are also available as direct named commands — thin wrappers over the public contract, no separate routing:
+`dev-loop` (natural language) is the catch-all router — reach for the named commands below only when you want a direct, unrouted entrypoint. The syntax differs by harness:
 
-| Command | Equivalent intent |
-| --- | --- |
-| `/dev-loops:start <issue>` | start dev loop on issue `<issue>` |
-| `/dev-loops:auto <issue>` | auto dev loop on issue `<issue>` (autonomous until human approval) |
-| `/dev-loops:continue [issue\|pr]` | continue dev loop on `<issue\|pr>`; bare resumes the single in-progress board item |
-| `/dev-loops:start-spike <question>` | start a time-boxed spike from a question (or `--file <path>` for a pre-authored findings file) |
-| `/dev-loops:info <issue|pr>` | read-only state summary (`loop info`) |
-| `/dev-loops:status` | dev-loop readiness (gh auth, git repo, subagent) |
+- **Claude Code** exposes each as a plugin slash command: `/loop-start`, `/loop-auto`, …
+- **Pi** exposes the core entrypoints as subcommands of one command: `/dev-loops start`, `/dev-loops auto`, …
 
-`/dev-loops:dev-loop` remains the catch-all router. Inside Pi the same set is reachable as `/dev-loops start|auto|continue|start-spike|info|status …`.
+| Command | Claude Code | Pi | Does |
+|---|---|---|---|
+| start | `/loop-start <issue>` | `/dev-loops start <issue>` | Start a dev loop on an issue |
+| auto | `/loop-auto <issue>` | `/dev-loops auto <issue>` | Run autonomously to the human-approval checkpoint |
+| continue | `/loop-continue [issue\|pr]` | `/dev-loops continue [issue\|pr]` | Continue; bare resumes the in-progress board item |
+| start-spike | `/loop-start-spike <question>` | `/dev-loops start-spike <question>` | Time-boxed spike (or `--file <path>`) |
+| info | `/loop-info <issue\|pr>` | `/dev-loops info <issue\|pr>` | Read-only state summary |
+| status | `/loop-status` | `/dev-loops status` | Readiness check (gh auth, git repo, subagent) |
+| enqueue | `/loop-enqueue <issue\|pr\|text>` | — | Queue an issue/PR, or capture an idea as a grilled issue |
+| grill | `/loop-grill <issue\|plan> [--auto]` | — | Socratic Q&A grill of an issue or plan before the loop |
+| queue-status | `/loop-queue-status` | — | Show the queue board grouped by column |
 
-## Install from npm
+Beyond the per-issue loop entrypoints, the Pi `/dev-loops` command and the `dev-loops` CLI also expose standalone utilities: `help`, `status`, `doctor`, `gates` (`status` is the same readiness check as `loop-status` above). `hide` works only inside Pi — the `dev-loops hide` CLI subcommand is recognized but intentionally exits non-zero (session-local Pi UI behavior). Everything above is also available as a skill/agent — inside Pi, hand work to the `dev-loop` skill rather than calling internal routed skills (`local-implementation`, `copilot-pr-followup`, `final-approval`) directly.
 
-### CLI only
+## Install
 
-Run the CLI **version-pinned** to the plugin/extension you have installed. The pin is the
-single source of truth (`<version>` = your installed `dev-loops` version) and cannot drift:
-
-```bash
-npx dev-loops@<version> --help
-```
-
-A global `npm install -g dev-loops` is **not** the supported invocation path: the global
-binary updates independently of the plugin/extension and silently drifts out of version
-(#833/#1036). Install it only as an optional bare shell convenience.
+All examples pin to `<version>` = the `dev-loops` version you installed; keep the CLI, plugin, and extension on the same version so behavior can't drift.
 
 ### Claude Code plugin
 
-The repo ships a Claude Code plugin rooted at `.claude/` (manifest at
-`.claude/.claude-plugin/plugin.json`) exposing the dev-loop **agents, skills, and hooks**.
-
-Install it from the bundled marketplace catalog (`.claude-plugin/marketplace.json`) by running
-these slash commands inside Claude Code:
+The repo ships a plugin rooted at `.claude/` (manifest at `.claude/.claude-plugin/plugin.json`) exposing the dev-loop agents, skills, and hooks. Install it from the bundled marketplace catalog:
 
 ```text
 /plugin marketplace add mfittko/dev-loops    # register the marketplace
@@ -76,206 +69,113 @@ these slash commands inside Claude Code:
 Or load it directly for a single session without installing:
 
 ```bash
-claude --plugin-dir .claude                              # load it for a session
-claude --plugin-dir .claude plugin details dev-loops     # inspect the discovered components
+claude --plugin-dir .claude
 ```
 
-When installed from npm, point at the bundled copy: `claude --plugin-dir node_modules/dev-loops/.claude`.
+Installed from npm, point at the bundled copy: `claude --plugin-dir node_modules/dev-loops/.claude`.
 
-The plugin is self-contained: it bundles the shared contract docs and templates the skills
-reference, and strips Pi-runtime-only prose from the generated assets. The hooks provide the
-`gh pr ready` draft-gate guard and the main-agent read-only boundary (the read-only enforcement
-is opt-in via `DEVLOOPS_MAIN_AGENT_READONLY=1`). Skill references to a project's own `PLAN.md` /
-`AGENTS.md` resolve against the consumer repo, by design.
+The hooks provide the `gh pr ready` draft-gate guard and an opt-in read-only boundary for the main agent (`DEVLOOPS_MAIN_AGENT_READONLY=1`). Skill references to a consumer repo's own `PLAN.md` / `AGENTS.md` resolve against that repo, by design.
 
 ### Pi extension
 
-To use `/dev-loops` inside Pi:
-
 ```bash
-pi install npm:dev-loops        # global Pi extension
-dev-loops --help
+pi install npm:dev-loops@<version>       # global, pinned npm package
+pi install -l npm:dev-loops@<version>    # project-local (.pi/settings.json)
 ```
 
 You can also install from git:
 
 ```bash
-pi install git:github.com/mfittko/dev-loops    # global
-pi install -l git:github.com/mfittko/dev-loops # project-local
-```
-
-The CLI requires Node `>=24` and a GitHub-authenticated `gh` CLI for repository workflows. See [Requirements](#requirements).
-
-## Docker
-
-A deterministic container image with all required tooling for dev-loop operation.
-
-### Build
-
-```bash
-docker build -t dev-loops .
-```
-
-### Environment variables
-
-| Variable | Purpose | Required for smoke test |
-|---|---|---|
-| `GH_TOKEN` | GitHub personal access token for `gh` CLI and API calls | Yes |
-| `OPENAI_API_KEY` | LLM provider key (needed only when running `pi` / LLM-backed dev-loop operations) | No |
-
-### Smoke test
-
-Verify the image works with a minimal dev-loop info call:
-
-```bash
-docker run --rm -e GH_TOKEN="$GH_TOKEN" dev-loops dev-loops loop info --repo mfittko/dev-loops --issue 1
+pi install git:github.com/mfittko/dev-loops@<tag-or-sha>       # global
+pi install -l git:github.com/mfittko/dev-loops@<tag-or-sha>    # project-local
 ```
 
-### Toolchain verification
-
-Check that all required tools are reachable:
-
-```bash
-docker run --rm dev-loops node --version
-docker run --rm dev-loops pi --version
-docker run --rm dev-loops dev-loops --version
-docker run --rm dev-loops gh --version
-docker run --rm dev-loops git --version
-```
-
-### Repeatable builds
-
-The Dockerfile pins exact versions for Node.js (via base image), pi CLI, pi extensions, and gh CLI. Paired with the committed `package-lock.json`, repeat builds produce functionally identical toolchain versions.
-
-### Runtime patterns
-
-**Interactive Pi with host config (writable):**
+Once a project is trusted, Pi auto-installs missing packages on startup. Install `pi-subagents` the same way when the repo relies on async loop behavior.
 
-```bash
-docker run -it --rm \
-  -e GH_TOKEN="$GH_TOKEN" \
-  -v "$HOME/.pi:/home/node/.pi" \
-  dev-loops pi
-```
-
-Shares sessions, models, settings. Container writes session logs to host `~/.pi`.
+### CLI
 
-**Interactive Pi clean (no config sharing):**
+Run the CLI version-pinned:
 
 ```bash
-docker run -it --rm \
-  -e GH_TOKEN="$GH_TOKEN" \
-  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
-  dev-loops pi
+npx dev-loops@<version> --help
 ```
 
-Ephemeral `~/.pi` inside container. Provider auth via env vars.
-
-**Full dev-loop with live repo worktree:**
-
-```bash
-git clone --mirror git@github.com:owner/repo.git /tmp/mirror
-git --git-dir=/tmp/mirror worktree add /tmp/run /tmp/mirror/main
-
-docker run -it --rm \
-  -e GH_TOKEN="$GH_TOKEN" \
-  -v "$HOME/.pi:/home/node/.pi" \
-  -v /tmp/run:/workspace \
-  dev-loops pi
-```
+A global `npm install -g dev-loops` is an optional bare-shell convenience only — it is not version-pinned, updates independently of the plugin/extension, and can silently drift out of sync (#833/#1036). Prefer the pinned `npx` invocation.
 
-Mounts live repo worktree over baked-in `/workspace`. One isolated Pi session per container.
+## Requirements
 
-## Workflow posture
+Universal:
 
-- Use **`dev-loop`** as the single public façade for all routed work
-- Prefer the GitHub-first path for active implementation and release work
-- Use local implementation only when explicitly requested
-- Internal routed logic stays behind the public façade
+- Node `>=24`
+- `gh` installed and authenticated for GitHub/Copilot workflows
 
-This repo is shared Pi workflow infrastructure built on generic role agents plus thin workflow entrypoint agents where needed. Thin workflow entrypoint agents are allowed when they only load a skill and defer policy to it.
+Pi-harness only:
 
-Phase 8 is the active durable phase; Phase 7 second-repo pilot is deferred. See [Docs Index](./docs/index.md) for the full execution snapshot.
+- `pi-subagents` for async workflow behavior
+- A Pi host satisfying the peer dependencies `@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui`
 
 ## Configuration
 
-Gate review angles, refinement settings, persona mappings, and workflow defaults are config-driven via `.pi/dev-loop/defaults.yaml`. Consumer repos override values in `.devloops` at repo root (legacy `.pi/dev-loop/settings.yaml` still loads with a deprecation warning). The loader also accepts `.yml` and `.json` extensions and legacy `overrides.*` files as fallback formats. See [Extension Documentation](./extension/README.md) for details.
+Defaults ship in `packages/core/src/config/extension-defaults.yaml`. A repo-local `.pi/dev-loop/defaults.*` layer merges on top of them when present, then consumer repos override everything in a `.devloops` file at the repo root (`.devloops.yaml` / `.yml` / `.json` are also accepted); `.devloops` is authoritative when present. The legacy `.pi/dev-loop/settings.*` and `overrides.*` files load only as a fallback when no `.devloops` is present; when `.devloops` exists they are ignored (a deprecation warning still fires if they are present).
 
 ```bash
-npx dev-loops@<version> gates   # see what reviewers will check
+npx dev-loops@<version> gates   # print what reviewers will check
 ```
 
 Key surfaces:
-- **Gate angles** — which review lenses run at draft and pre-approval gates
-- **Persona prompts** — focused instructions per angle (DRY, KISS, YAGNI, SRP, SoC, and more)
-- **Refinement** — fan-out count and mode for parallel review variants; `refinement.maxCopilotRounds` caps Copilot re-review rounds (default `5`), and **`maxCopilotRounds: 0` disables the Copilot review gate entirely** for local-harness-only review (`draft_gate → pre_approval_gate`, no Copilot) — useful when the repo has no Copilot reviewer configured
+
+- **Gate angles** — which review lenses run at the draft and pre-approval gates
+- **Personas** — focused per-angle prompts (DRY, KISS, YAGNI, SRP, SoC, and more)
+- **Refinement** — fan-out count and mode for parallel review variants; `refinement.maxCopilotRounds` caps Copilot re-review rounds (default `5`). Set `maxCopilotRounds: 0` to disable the Copilot gate entirely — local-harness-only review (`draft_gate → pre_approval_gate`), useful when the repo has no Copilot reviewer configured.
 - **Autonomy** — which gates require operator confirmation
 - **Workflow defaults** — retrospective enforcement, draft-first posture, dev-mode policy
 
-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
+Full details: the shipped defaults in `packages/core/src/config/extension-defaults.yaml` and the loader in `packages/core/src/config/config.mjs`.
 
-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.
+## Docker
 
-**Pi extension:**
+A deterministic container image with all required tooling for dev-loop operation.
 
 ```bash
-pi install npm:dev-loops@<version>                         # global, pinned npm package
-pi install -l npm:dev-loops@<version>                      # project-local, pinned npm package
-pi install git:github.com/mfittko/dev-loops@<tag-or-sha>   # global, pinned git ref
-pi install -l git:github.com/mfittko/dev-loops@<tag-or-sha> # project-local, pinned git ref
-```
-
-Project-local installs write to `.pi/settings.json`; after the project is trusted, Pi auto-installs missing packages on startup. Install `pi-subagents` the same way when the repo depends on async loop behavior.
-
-Inside Pi, use `dev-loop` as the single public skill/agent entrypoint:
-
-```js
-subagent({
-  agent: "dev-loop",
-  task: "Start dev loop on issue 123 in owner/repo..."
-})
+docker build -t dev-loops .
 ```
 
-Do not call internal routed skills such as `local-implementation`, `copilot-pr-followup`, or `final-approval` directly; `dev-loop` selects them from the current GitHub/repo state.
+| Variable | Purpose | Required |
+|---|---|---|
+| `GH_TOKEN` | GitHub token for `gh` CLI and API calls | Yes |
+| `OPENAI_API_KEY` | LLM provider key (only for `pi` / LLM-backed operations) | No |
 
-The `/dev-loops` command surface covers the direct dev-loop entrypoints plus readiness and configuration UX:
+Smoke test the image with a minimal read-only info call:
 
 ```bash
-/dev-loops start <issue>     # dispatch: start dev loop on issue <issue>
-/dev-loops auto <issue>      # dispatch: auto dev loop on issue <issue>
-/dev-loops continue [issue|pr] # dispatch: continue dev loop on <issue|pr>; bare = current in-progress board item
-/dev-loops info <issue|pr>   # read-only state summary
-/dev-loops status
-/dev-loops doctor
-/dev-loops gates
+docker run --rm -e GH_TOKEN="$GH_TOKEN" dev-loops dev-loops loop info --repo mfittko/dev-loops --issue 1
 ```
 
-**CLI:**
+Verify the toolchain is reachable:
 
 ```bash
-npx dev-loops@<version> gates
+docker run --rm dev-loops node --version
+docker run --rm dev-loops pi --version
+docker run --rm dev-loops dev-loops --version
+docker run --rm dev-loops gh --version
 ```
 
-Use `npm install -g dev-loops` only as a bare shell convenience outside Pi; it is not version-pinned, can drift against the plugin/extension, and is not the supported invocation path (prefer `npx dev-loops@<version>`).
+The Dockerfile pins exact versions for Node.js (base image), the pi CLI, pi extensions, and gh CLI; paired with the committed `package-lock.json`, repeat builds produce functionally identical toolchains.
 
-The package exposes the `/dev-loops` extension command surface, the `dev-loops` shell CLI, and packaged skills from `package.json` `pi.skills`.
+**Runtime patterns:**
 
-See [Extension Documentation](./extension/README.md) for the full command and package-install contract.
+```bash
+# Interactive Pi sharing host config (sessions, models, settings write back to ~/.pi)
+docker run -it --rm -e GH_TOKEN="$GH_TOKEN" -v "$HOME/.pi:/home/node/.pi" dev-loops pi
 
-## Requirements
+# Interactive Pi, clean (ephemeral ~/.pi; provider auth via env)
+docker run -it --rm -e GH_TOKEN="$GH_TOKEN" -e OPENAI_API_KEY="$OPENAI_API_KEY" dev-loops pi
 
-- 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`
+# Full dev-loop over a live repo worktree mounted at /workspace
+git clone --mirror git@github.com:owner/repo.git /tmp/mirror
+git --git-dir=/tmp/mirror worktree add /tmp/run /tmp/mirror/main
+docker run -it --rm -e GH_TOKEN="$GH_TOKEN" -v "$HOME/.pi:/home/node/.pi" -v /tmp/run:/workspace dev-loops pi
+```
 
 ## Development
 
@@ -283,14 +183,20 @@ See [Extension Documentation](./extension/README.md) for the full command and pa
 npm run verify   # canonical root verification (tests + dev-loop tests)
 ```
 
-CI splits into a small changed-files gate plus parallel `verify` and conditional `viewer-smoke` jobs. `npm ci` + `npm run verify` run on every change, while the workspace-local Playwright WebKit cache and viewer smoke run only when files in the bounded inspect-run viewer surface or its smoke-path dependencies change.
+CI splits into a small changed-files gate plus a parallel `verify-suite` matrix (one leg per `test:*` suite) gated by a fail-closed `verify` job, and a conditional `viewer-smoke` job. On every change, `npm ci` runs and the verify suites run as parallel matrix legs; the Playwright/WebKit viewer smoke runs only when the bounded viewer surface or its smoke-path dependencies change.
+
+### Migrating from an earlier release
+
+Upgrading 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).
 
 ## Further reading
 
-- [Docs Index](./docs/index.md) — active docs, canonical-owner pointers, and current phase status
+- [Docs Index](./docs/index.md) — active docs and canonical-owner pointers
+- [README Audit Rubric](./docs/readme-audit-rubric.md) — semantic properties this README is audited against (on-demand LLM judge)
+- [Public Dev Loop Contract](./skills/docs/public-dev-loop-contract.md) — public routing contract
 - [Extension Documentation](./extension/README.md) — README-driven extension spec
 - [Scripts Documentation](./scripts/README.md) — deterministic script contracts
 - [UI Smoke Harness](./docs/ui-smoke-harness.md) — reusable local Playwright/WebKit smoke baseline
 - [UI Artifact Contract](./docs/ui-artifact-contract.md) — screenshot/state artifact contract and CI-promotion rules
-- [UI Designer Review Loop](./docs/ui-designer-review-loop.md) — designer + vision (`uiReviewMode: vision`) review loop contract
-- [Slides Story Review Loop](./docs/slides-story-review-loop.md) — bounded slides content & storytelling reviewer (narrative, not pixels)
+- [UI Designer Review Loop](./docs/ui-designer-review-loop.md) — designer + vision (`uiReviewMode: vision`) review loop
+- [Slides Story Review Loop](./docs/slides-story-review-loop.md) — bounded slides content & storytelling reviewer

package/agents/dev-loop.agent.md

@@ -16,12 +16,12 @@ Your job is to provide the callable `dev-loop` public façade and route to the c
 
 ## Handoff envelope mandate (first action)
 
-The agent's first action after resolving authoritative state must be to build the handoff envelope via `buildDevLoopHandoffEnvelope()` from `@dev-loops/core`.
+The agent's first action after resolving authoritative state MUST be to build the handoff envelope via `buildDevLoopHandoffEnvelope()` from `@dev-loops/core`.
 
 The envelope is the primary handoff artifact — it is derived from resolver output, settings, and gate state, and it determines:
 - `requiredReads` — the canonical ordered list of files to load
 - `nextAction` — the bounded task to execute
-- `stopRules` — stop boundaries that must not be crossed without authorization
+- `stopRules` — stop boundaries that MUST NOT be crossed without authorization
 - `acceptance` — self-validation criteria for declaring completion
 - `sanctionedCommands` — the operation → wrapper command map (reads/edits/lifecycle), plus the forbidden and orchestrator-owned lists. Carried by DEFAULT on every build so you never re-derive which wrapper performs a GitHub/loop operation. Do NOT restate the map here — the single source of truth is `scripts/loop/sanctioned-commands.mjs`, surfaced verbatim in the envelope.
 
@@ -44,7 +44,7 @@ NEVER fall back to `find /` or any unbounded filesystem walk to locate the CLI
 5. Load every path listed in `requiredReads` (in order).
 6. Execute `nextAction` constrained by `stopRules` and `acceptance`.
 
-**The agent must not load skills, route packs, or delegate work before the envelope is built and read.** The derivation contract is [Workflow Handoff Contract](../skills/docs/workflow-handoff-contract.md).
+**The agent MUST NOT load skills, route packs, or delegate work before the envelope is built and read.** The derivation contract is [Workflow Handoff Contract](../skills/docs/workflow-handoff-contract.md).
 
 Prose task composition is a fallback only when `buildDevLoopHandoffEnvelope()` is unavailable (missing `@dev-loops/core` package) — the handoff contract in `skills/docs/workflow-handoff-contract.md` applies in that fallback case.
 
@@ -54,7 +54,7 @@ After the handoff envelope is built and read, load the `dev-loop` skill ([Dev Lo
 
 When that skill is not available at the expected path, resolve it from the skill installation layout (see the skill's "Skill asset path resolution" section).
 
-This entrypoint must stay thin: do not restate the skill's phase sequencing or workflow policy here. The envelope owns handoff sequencing; the skill owns routed strategy execution procedures.
+This entrypoint MUST stay thin: do not restate the skill's phase sequencing or workflow policy here. The envelope owns handoff sequencing; the skill owns routed strategy execution procedures.
 
 Treat the deterministic public routing contract in [Public Dev Loop Contract](../skills/docs/public-dev-loop-contract.md) and the `dev-loop` skill as the authority for choosing the current execution path. Do not force users to choose internal strategy names up front.
 
@@ -75,9 +75,9 @@ If local facts, GitHub facts, and helper/state-machine output do not agree well
 This agent's frontmatter `tools:` comma-token scalar includes `subagent` (single-line comma form, no brackets — see #1111) and it sets `maxSubagentDepth: 3` to allow orchestrating parallel review, chains, and staged fix passes.
 <!-- /pi-only -->
 
-All delegation must originate from the handoff envelope: the envelope's `nextAction`, `requiredReads`, `stopRules`, and `acceptance` define the bounded task. The envelope is passed to child subagents as their primary handoff artifact.
+All delegation MUST originate from the handoff envelope: the envelope's `nextAction`, `requiredReads`, `stopRules`, and `acceptance` define the bounded task. The envelope is passed to child subagents as their primary handoff artifact.
 
-The pi-subagents skill is parent-only, so delegated subagents do not receive orchestration patterns. This section exists as the minimal locally-enforced subset needed for correct delegation — it is not a restatement of the full policy. The `dev-loop` skill owns all procedural rules; this section only declares the invariants the agent must follow when it cannot defer to the skill:
+The pi-subagents skill is parent-only, so delegated subagents do not receive orchestration patterns. This section exists as the minimal locally-enforced subset needed for correct delegation — it is not a restatement of the full policy. The `dev-loop` skill owns all procedural rules; this section only declares the invariants the agent MUST follow when it cannot defer to the skill:
 - One writer thread; `async: true` default; `context: "fresh"` for reviewers.
 - No child subagent spawning beyond assigned fanout work.
 - Bounded tasks with concrete scope, exit conditions, and validation expectations.
@@ -87,8 +87,8 @@ The pi-subagents skill is parent-only, so delegated subagents do not receive orc
 
 - **Prefer `intercom` when available.** If the `pi-intercom` extension is active, use `intercom({ action: "ask", ... })` instead of `contact_supervisor`. The `intercom` tool uses message-based delivery (no blocking tool-call state) — see the pi documentation for `intercom({ action: "ask", ... })` parameters and reply conventions.
 - **When `intercom` is unavailable,** do not call `contact_supervisor`. Instead, brief the supervisor to include the decision in the resume message when re-dispatching. The subagent states what it needs in the task description; the supervisor provides the answer on resume. This avoids the broken response path entirely.
-- **If `contact_supervisor` was already called** (legacy code or unavoidable): expect a ~60s idle timeout followed by a pause. On resume, the supervisor must inject the decision in the resume message — do not rely on `intercom` on resume when it was unavailable at call time.
-- **Timeout detection (supervisor-side):** if a `contact_supervisor` call has been pending for >30s, the supervisor should treat it as a probable timeout and prepare to inject the decision in the resume message on re-dispatch. The subagent cannot execute this detection while blocked inside `contact_supervisor`; the supervisor must observe the pending duration externally.
+- **If `contact_supervisor` was already called** (legacy code or unavoidable): expect a ~60s idle timeout followed by a pause. On resume, the supervisor MUST inject the decision in the resume message — do not rely on `intercom` on resume when it was unavailable at call time.
+- **Timeout detection (supervisor-side):** if a `contact_supervisor` call has been pending for >30s, the supervisor SHOULD treat it as a probable timeout and prepare to inject the decision in the resume message on re-dispatch. The subagent cannot execute this detection while blocked inside `contact_supervisor`; the supervisor MUST observe the pending duration externally.
 <!-- /pi-only -->
 
 ## Output

package/agents/fixer.agent.md

@@ -28,6 +28,7 @@ You are a focused review-fix agent. You take an existing pull request with revie
 
 ## Review Workflow
 1. Read unresolved review threads and any general review comments.
+   - Prefer the deterministic helper `scripts/github/list-review-threads.mjs --unresolved-only` to enumerate threads with their reply/resolve ids, rather than hand-writing a GraphQL query.
 2. Group related comments by file and identify the underlying concern behind each comment.
 3. Decide the best resolution for each concern: exact requested change, better alternative fix, explanation-only resolution, or escalation for expert judgment.
 4. If expert input is needed, stop before editing or resolving the thread and report the question, evidence, and options.

package/agents/refiner.agent.md

@@ -37,13 +37,13 @@ For the active phase, require and produce:
 
 - use exact wording from the source issue(s); when the governing input is a phase doc or other spec instead of an issue, use that source wording exactly for every explicit item in the matrix
 - include every explicit acceptance criterion, definition-of-done item, and non-goal; do not skip items
-- if no explicit definition of done exists, add a `Proposed DoD` subsection before the matrix
+- <!-- rule: REFINER-DOD-PROPOSED-SUBSECTION --> `REFINER-DOD-PROPOSED-SUBSECTION`: if no explicit definition of done exists, add a `Proposed DoD` subsection before the matrix
 - explicit risks, watchpoints, and unresolved questions
 - validation steps and tests to write first
-- durable decisions that should be preserved in the phase doc
+- durable decisions that SHOULD be preserved in the phase doc
 - when the phase includes a bounded audit or scan: prioritized findings, the highest-value follow-up candidates, and an explicit statement of what the current phase will not rewrite or broaden
 - When an audit artifact is provided, treat it as a first-class planning input: summarize the audited scope, list prioritized findings, include the highest-value follow-up candidates, and classify each meaningful finding as exactly one of current-phase scope/AC, DoD expectation, explicit non-goal / defer, or risk/watchpoint
-- Do not invent audit findings when no audit artifact was provided
+- <!-- rule: REFINER-NO-INVENT-AUDIT-FINDINGS --> `REFINER-NO-INVENT-AUDIT-FINDINGS`: Do not invent audit findings when no audit artifact was provided
 - when the phase includes watcher or predicate-driven behavior: explicit timeout semantics and negative-case expectations for non-target identities/events
 - when the phase relies on package-first shared helpers inside a source-loaded workspace: explicit integration expectations about whether local callers use published package imports or a thin source/workspace adapter during development
 - cross-check the phase's claims against the contracts and docs they reference (the autonomous docs-grill step, see ../docs/docs-grill-step.md): surface code-vs-doc drift, stale references, and contract-surface inaccuracies as refinement findings while the claims are still being verified
@@ -85,4 +85,4 @@ Return:
 
 ## Completion quality bar
 - A refinement is complete only when no item in the AC/DoD/Non-goal coverage matrix has status `Partial`, `Unmet`, or `Unverified`.
-- Any `Partial`, `Unmet`, or `Unverified` item means the refinement is still incomplete and must not be presented as ready.
+- Any `Partial`, `Unmet`, or `Unverified` item means the refinement is still incomplete and MUST NOT be presented as ready.

package/agents/review.agent.md

@@ -29,18 +29,15 @@ You are a focused pull request review agent. You review an implementation for co
 
 ## 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:
-
-- **No worktree isolation (mandatory):** you review in the PR's actual worktree/head — the same checkout the gate-context preamble ran in — never a fresh isolated worktree. You are read-only and never mutate files, so isolation buys nothing; a fresh worktree would also be checked out from `main` (not the PR head) and would lack the gitignored, worktree-local gate-context bundle below, so you'd silently review the wrong stale tree (#1135).
-- **Fresh-context guard (mandatory):** run `node scripts/github/verify-fresh-review-context.mjs --scope <angle> --context-path <gate-context-artifact-path>` at startup. If it reports `fresh: false` (exit 1) or any error — including a missing gate-context artifact (`gateContextPresent: false`), which is the fail-closed signal that you're not in the right worktree/head — refuse to proceed and report the failure; do not review on inherited context or without seeded 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.
+This agent has two modes. The default mode is the full-PR review described in the rest of this file. In **scoped angle-review mode** you are one per-angle reviewer of the gate-review fan-out. You are in this 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`).
+
+Its full execution shape is owned elsewhere — read those owners before reviewing and do not re-derive their rules here:
+
+- The build-once neutral bundle seeding, fresh-context guard (`verify-fresh-review-context.mjs`), no-worktree-isolation prohibition (#1135), single-angle read-only scope, and briefing composition are owned by the [Gate Review Sub-Loop Contract](../docs/gate-review-sub-loop-contract.md) (`GATE-EXEC-BUILD-ONCE-SEED`, `GATE-EXEC-BRIEFING-PREFIX`) — you receive only the neutral artifact + your angle, never the orchestrating agent's conversation, opinions, or state.
+- The adversarial reviewing behavior is owned by `COPILOT-FOLLOWUP-ADVERSARIAL-BRIEFING` in the [Copilot PR Follow-up Skill](../skills/copilot-pr-followup/SKILL.md): read the FULL diff (from `scope.diffPath`, or reconstruct it with `git diff` against the change base when `scope.diffPath` is null/missing — never a hunk-only review) plus the bundled adjacent code rather than re-deriving them, then hunt concrete `file:line` defects (edge cases, input validation, numeric coercion incl. NaN/Infinity/floats/negatives, null/undefined, boundary conditions, mismatched caller/callee contracts, dedup/identity bugs) over process nits, recording any scope-widening in the optional `contextWidened` field on your findings artifact.
+
+Follow those owners, then return your findings via the structured artifact below (this agent's canonical output contract):
+
 - **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
@@ -76,7 +73,7 @@ When NOT given an angle scope, behave exactly as the full-PR review agent descri
 - Prefer concrete findings with file references and impact over generic style commentary.
 - Distinguish clearly between must-fix findings, lower-severity risks, and informational gaps.
 - If the PR description omits required sections, is too thin to ground review without reconstructing intent from commits, or includes verdict status, evidence, or changelog content, treat that as a first-class review issue.
-- The review verdict must carry the acceptance-criteria and definition-of-done assessment in explicit markdown verification tables, including status plus concise evidence for each row.
+- The review verdict MUST carry the acceptance-criteria and definition-of-done assessment in explicit markdown verification tables, including status plus concise evidence for each row.
 - For follow-up reviews on the same PR, do not repost full AC/DoD tables: include only delta rows where status or supporting evidence changed, and explicitly note when there are no AC/DoD deltas.
 - When changelog coverage is needed, include a dedicated `## Changelog` section in the review verdict comment so post-merge automation can consume it without reading the PR description.
 

package/extension/README.md

@@ -101,7 +101,7 @@ The messaging distinguishes between local loop readiness and remote GitHub/Copil
 
 ## Configuration
 
-The dev-loop workflow is driven by a YAML config at `.pi/dev-loop/defaults.yaml` (shipped with the package) and an optional consumer settings file at `.devloops` at repo root (the loader also accepts `.devloops.yaml`, `.devloops.yml`, and `.devloops.json`; legacy `.pi/dev-loop/settings.*` and `overrides.*` still load as fallbacks with a deprecation warning).
+The dev-loop workflow is driven by the shipped defaults in `packages/core/src/config/extension-defaults.yaml`, an optional repo-local `.pi/dev-loop/defaults.*` layer that merges on top of them, and an optional consumer settings file at `.devloops` at repo root (the loader also accepts `.devloops.yaml`, `.devloops.yml`, and `.devloops.json`; legacy `.pi/dev-loop/settings.*` and `.pi/dev-loop/overrides.*` load only as a fallback when no `.devloops` is present, and are ignored when `.devloops` exists — a deprecation warning still fires).
 
 ### How consumers customize config
 
@@ -191,8 +191,9 @@ workflow:
 ### Config precedence
 
 1. Built-in defaults (`packages/core/src/config/config.mjs` `BUILT_IN_DEFAULTS`)
-2. Shipped defaults (`.pi/dev-loop/defaults.yaml` — committed in source repo)
-3. Consumer settings (`.devloops` at repo root — preferred; `.devloops.yaml`/`.devloops.yml`/`.devloops.json` also load; legacy `.pi/dev-loop/settings.*` and `overrides.*` still load as fallbacks with deprecation warning)
+2. Shipped defaults (`packages/core/src/config/extension-defaults.yaml`)
+3. Repo-local override layer (`.pi/dev-loop/defaults.*` — merges on top of the shipped defaults when present)
+4. Consumer settings (`.devloops` at repo root — preferred and authoritative when present; `.devloops.yaml`/`.devloops.yml`/`.devloops.json` also load; legacy `.pi/dev-loop/settings.*` and `.pi/dev-loop/overrides.*` load only as a fallback when no `.devloops` is present; when `.devloops` exists they are ignored, with a deprecation warning)
 
 ### Adding custom review angles
 
@@ -221,7 +222,7 @@ Current Phase 3+ contract:
 - this phase does not require a separate compiled build or `dist/` pipeline
 
 Root verification and test commands are intentionally explicit:
-- `npm run verify` is the canonical root verification path (`npm test` + `npm run test:dev-loop`)
+- `npm run verify` is the canonical root verification path; it runs every suite in parallel via `run-p` as a single aggregated command, and any suite failing fails verify
 - `npm test` runs the current root test suite (`test:assets`, `test:extension`, `test:scripts`, `test:core`, and `test:docs`)
 - `npm run test:extension`
 - `npm run test:extension` currently expands to one `node --import tsx --test ...` invocation in `package.json`; prefer the script entrypoint over copying the file list into downstream docs or runbooks