dev-loops 0.7.2 → 0.8.0

package/.claude/skills/local-implementation/SKILL.md

@@ -9,7 +9,7 @@ user-invocable: false
 
 # Local Implementation
 
-This skill is the canonical internal `local_implementation` route behind the public `dev-loop` façade.
+Canonical owner for the internal `local_implementation` route behind the public `dev-loop` façade.
 
 Use it only after the public dispatcher has already resolved `selectedStrategy: local_implementation`. This skill owns the local phase procedure and artifact discipline for that route; it does not redefine the shipped runtime semantics of helper CLIs, shared loop logic, or extension commands.
 
@@ -61,7 +61,7 @@ When the local spec already lives in a tracker issue:
 - sync durable scope / acceptance / status changes back to the tracker issue rather than maintaining a duplicate local phase doc
 - keep `tmp/` as temporary local execution state only; it does not become a second durable spec surface
 - for tracker-backed sessions, the handoff path is always: push the working branch → open a PR → merge via GitHub
-- <!-- rule: LOCAL-PR-CREATE-CANONICAL --> for tracker-backed sessions, you MUST open PRs through the canonical `dev-loops pr create` path — always draft and always assigned — self-assigned by default (`--assignee @me` when none is given; honors an explicit `--assignee <login>` / `-a <login>`) — and MUST NOT open them via raw `gh pr create`. The PR body MUST contain `Closes #N` (or `Fixes #N`) for the linked issue so GitHub auto-closes it on merge. When `.devloops` sets `workflow.requireDraftFirst` to true, use `dev-loops pr create --assignee @me ...`; the draft-first requirement itself is owned by [`OPS-DRAFT-FIRST-PR`](../docs/copilot-loop-operations.md).
+- <!-- rule: LOCAL-PR-CREATE-CANONICAL --> for tracker-backed sessions, you MUST open PRs through the canonical `dev-loops pr create` path — always draft and always assigned — self-assigned by default (`--assignee @me` when none is given; honors an explicit `--assignee <login>` / `-a <login>`) — and MUST NOT open them via raw `gh pr create`. The PR body MUST contain `Closes #N` (or `Fixes #N`) for the linked issue so GitHub auto-closes it on merge. When `.devloops` sets `workflow.requireDraftFirst` to true, use `dev-loops pr create --assignee @me ...`; the always-draft creation mechanism is owned by [`OPS-DRAFT-FIRST-PR`](../docs/copilot-loop-operations.md) — `create-pr.mjs` is unconditionally draft-only regardless of the toggle, which separately governs whether the draft-gate boundary is enforced before ready.
 - <!-- rule: LOCAL-TRACKER-NO-DIRECT-MERGE --> `LOCAL-TRACKER-NO-DIRECT-MERGE`: for tracker-backed sessions, agents MUST NOT suggest a direct local-main merge and MUST NOT merge the working branch into local `main` at phase completion
 
 ## Primary execution rules
@@ -104,7 +104,7 @@ Follow [Anti-patterns](../docs/anti-patterns.md) for the general tooling-interna
 
 - <!-- rule: LOCAL-PHASE-ONE-AT-A-TIME --> You MUST implement **one phase at a time** and MUST NOT refine later phases in detail before the current phase is complete.
 - Use the `refiner` agent for phase-refinement work when subagents are available; escalate RFC-worthy technical decisions to the parent session / human operator.
-- <!-- rule: LOCAL-TEST-FIRST-COVERAGE --> You MUST work **test-first** for all non-trivial logic and SHOULD maintain **90% coverage** thresholds (coverage is not enforced by the shipped verify config; treat it as the working target).
+- <!-- rule: LOCAL-TEST-FIRST-COVERAGE --> You MUST work **test-first** for all non-trivial logic; coverage thresholds are owned by [VALIDATE-COVERAGE-THRESHOLD](../docs/validation-policy.md).
 - Log detailed iteration artifacts under `tmp/` using the required structure below.
 - Spec-of-record split (phase-doc-backed vs. tracker-backed vs. lightweight): see [Tracker-backed local implementation](#tracker-backed-local-implementation) above.
 - When a phase changes durable product truth in ways `PLAN.md` should express (for example command surface, accepted product decisions, resolved open questions, or scope changes), update [Project Plan](../../PLAN.md) before closing the phase.

package/.claude/skills/loop-grill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "loop-grill"
-description: "Standalone pre-loop Socratic Q&A grill for issues (tracker-first) or local plan files (local-planning). Detects spec gaps, asks clarifying questions (interactive) or self-answers them from codebase context (--auto), then writes a ## Grill findings section back to the source artifact."
+description: "Standalone pre-loop Socratic Q&A grill for issues (tracker-first), PR bodies, or local plan files (local-planning). Detects spec gaps, asks clarifying questions (interactive) or self-answers them from codebase context (--auto), then synthesizes Acceptance criteria / Definition of done / Non-goals into the body while keeping the raw Q&A only in an ephemeral tmp artifact."
 allowed-tools: Read Bash Edit Write
 user-invocable: false
 ---
@@ -12,15 +12,23 @@ A standalone, on-demand pre-loop grilling skill. Run it against an issue or a lo
 
 It is entirely separate from the in-loop docs-grill (`docs/docs-grill-step.md`), which audits code/doc drift while the loop runs. This skill operates on the *spec* before any implementation begins.
 
+## State machine
+
+This grill is the bounded, closed sub-loop modeled by `packages/core/src/loop/refinement-grill-state.mjs` (detector `scripts/loop/detect-refinement-grill-state.mjs`), rendered on the State atlas; see `docs/refinement-grill-state-graph.md`. It obeys `GRILL-SUBLOOP-STATE-MACHINE`, `GRILL-SUBLOOP-ITERATE-TO-CLEAN`, `GRILL-SUBLOOP-NO-EMBED-SYNTHESIS`, and `GRILL-SUBLOOP-HONEST-HANDOFF`. Iteration lives in the transition graph; the answer/synthesis is the bounded input consumed at the `await_answers` state.
+
 ## Interface
 
 ```
 /loop-grill <issue-number>             # tracker-first, interactive
 /loop-grill <issue-number> --auto      # tracker-first, auto-answer
+/loop-grill <pr-url-or-number>         # PR body, interactive
+/loop-grill <pr-url-or-number> --auto  # PR body, auto-answer
 /loop-grill <path/to/plan.md>          # local-planning, interactive
 /loop-grill <path/to/plan.md> --auto   # local-planning, auto-answer
 ```
 
+PR bodies are supported the same way as issues: fetch/edit the PR body via the existing PR wrappers (`scripts/github/view-pr.mjs` / `scripts/github/edit-pr.mjs`), never raw `gh`.
+
 ## Argument validation (fail-closed)
 
 Before doing anything else:
@@ -33,9 +41,12 @@ Before doing anything else:
 
 ## Step 1 — Load the target
 
-- **Tracker-first:** fetch the issue body (title + description + any existing `## Grill findings` section).
+- **Tracker-first:** fetch the issue body (title + description).
+- **PR body:** fetch the PR body via `scripts/github/view-pr.mjs` (never raw `gh`).
 - **Local-planning:** read the plan file from disk.
 
+"Is it refined" is decided by `detectIssueRefinementArtifact` (`packages/core/src/loop/issue-refinement-artifact.mjs`) — the single source of truth, same as the enqueue gate; do not add a divergent check. An already-refined artifact (AC/DoD present) is a zero-iteration `grill_clean`: do not rewrite the body.
+
 ## Step 1b — Surface external resources
 
 Before detecting gaps, scan the loaded content for external resource references: links, other repo URLs, API endpoints, doc URLs, screenshots, or Playwright navigation descriptors.
@@ -89,15 +100,20 @@ Record the evidence source for every answer. Flag a question as **`unresolved`**
 
 Do not silently guess an `inferred` answer when no evidence can be cited — flag it `unresolved` instead.
 
-## Step 4 — Write back (replace-section semantics)
+## Step 4 — Write back (synthesize sections; raw Q&A to tmp only)
 
-Write a `## Grill findings` section back to the source artifact using **replace-section** semantics:
+Synthesize the answers into the body as sharpened `## Acceptance criteria`, `## Definition of done`, and `## Non-goals` sections. Per canonical heading, use **replace-section** semantics:
 
-- **Find** the existing `## Grill findings` section: the range from the `## Grill findings` heading through the next `##`-level heading (exclusive) or end of file.
-- **Replace** that range in place with the new section content.
-- If no `## Grill findings` section exists, **append** it.
+- **Find** the existing section: the range from that `##`-level heading through the next `##`-level heading (exclusive) or end of file.
+- **Replace** that range in place with the synthesized content; if the section is absent, **append** it.
 - This makes re-runs idempotent — no accumulated noise, no duplicate sections.
-- If parsing the section boundary fails, **abort with an error** rather than silently truncating.
+- If parsing a section boundary fails, **abort with an error** rather than silently truncating.
+
+The body carries ONLY the synthesized sharpened sections. Do NOT write a `## Grill findings` section and do NOT embed the raw Q&A table in the body (`GRILL-SUBLOOP-NO-EMBED-SYNTHESIS`).
+
+If a body migrated from older embed behavior still carries a `## Grill findings` section, **remove** it as part of write-back — strip from that heading through the next `##`-level heading (exclusive) or end of file, using the same replace-section boundary logic. This is a removal-only migration, never a re-introduction of the embed.
+
+Write the raw Q&A transcript ONLY to the gitignored, ephemeral, session-scoped artifact `tmp/issues/issue-<n>/grill/<timestamp>.md` (`tmp/` is already gitignored; never committed). For PR-body and plan-file surfaces, use the same tmp path shape scoped by surface (issues: `tmp/issues/issue-<n>/grill/`; a parallel `tmp/...` path for PR/plan).
 
 **Tracker-first write-back:** update the GitHub issue body using:
 
@@ -105,19 +121,23 @@ Write a `## Grill findings` section back to the source artifact using **replace-
 gh issue edit <n> --repo <owner/repo> --body-file <tmp-path>
 ```
 
-The `## Grill findings` section lives in the issue body, not as a comment. Do not use `comment-issue.mjs` here — that creates a comment, not a body update.
+The synthesized sections live in the issue body, not as a comment. Do not use `comment-issue.mjs` here — that creates a comment, not a body update.
+
+**PR-body write-back:** update the PR body via `scripts/github/edit-pr.mjs` (never raw `gh`), same replace-section semantics.
 
-**GitHub body size guard:** issue bodies are capped at 65,536 characters. Before writing back, check whether the updated body would exceed this limit. If so, warn: `Warning: updated body would exceed GitHub's 65,536-character limit — write-back skipped. Truncate the findings or the issue body manually.` Do not silently truncate.
+**GitHub body size guard:** issue/PR bodies are capped at 65,536 characters. Before writing back, check whether the updated body would exceed this limit. If so, warn: `Warning: updated body would exceed GitHub's 65,536-character limit — write-back skipped. Sharpen the sections or the body manually.` Do not silently truncate.
 
 **Local-planning write-back:** update the plan file in place using the edit tool.
 
 ## Output artifact format
 
-The `## Grill findings` section written to the artifact:
+Two distinct artifacts:
 
-```markdown
-## Grill findings
+1. **Synthesized body sections** (issue/PR/plan body): only `## Acceptance criteria`, `## Definition of done`, and `## Non-goals`, sharpened from the answers. No raw Q&A.
 
+2. **Raw Q&A transcript** (ephemeral `tmp/issues/issue-<n>/grill/<timestamp>.md` only — never the body):
+
+```markdown
 <!-- loop-grill: <timestamp> mode:<interactive|auto> -->
 
 ### Resolved gaps
@@ -152,7 +172,7 @@ When `CONTEXT.md` is absent from the repo root, skip the context-source check si
 
 ## Idempotency guarantee
 
-Running `/loop-grill` twice on the same target must produce a single `## Grill findings` section, not two. The replace-section logic handles the already-present-section case. On the second run, if the gap set is identical to the first run, the section content is replaced with an equivalent section (same questions, same answers, updated timestamp).
+Running `/loop-grill` twice on the same target must not accumulate duplicate sections: the per-heading replace-section logic replaces the synthesized `## Acceptance criteria` / `## Definition of done` / `## Non-goals` sections in place. An already-refined target is a zero-iteration `grill_clean` and its body is left unchanged. The raw Q&A transcript is written to a fresh timestamped tmp file per run; the body never carries it.
 
 ## Non-goals
 

package/AGENTS.md

@@ -16,7 +16,7 @@
 - When creating GitHub issues via `gh issue create`, always include `--assignee @me` so the new artifact is self-assigned.
 - When creating PRs in this repo, use the canonical `dev-loops pr create ...` path (always draft, self-assigned by default; `--assignee @me` is the default) — never raw `gh pr create`.
 - Never start implementation (file mutation, branch creation, PR creation) without explicit instruction. "Queue," "add to list," "track," "note" are NOT implementation triggers. Only proceed when the user says "start," "go," "implement," "do it," "work on," or equivalent imperative. Confirm if unsure.
-- All work must originate from a tracked artifact: a GitHub issue (tracker-first) or a persisted markdown plan file (local-planning). See [Artifact Authority Contract](skills/docs/artifact-authority-contract.md) for canonical mode definitions and settings. No work may originate from a PR or direct local change unless explicitly requested.
+- All work must originate from a tracked artifact: a GitHub issue (tracker-first), a persisted markdown plan file (local-planning), or — on the sanctioned lightweight path — the PR description itself as the spec-of-record (`--lightweight`, `canonicalSpecSource: pr_body`; no committed plan artifact). See [Artifact Authority Contract](skills/docs/artifact-authority-contract.md) for canonical mode definitions and settings. No work may originate from a PR (other than the sanctioned lightweight PR-body-as-spec path) or a direct local change unless explicitly requested.
 - Implement one phase at a time; if durable repo docs explicitly record a reprioritization exception, follow [Implementation State](docs/IMPLEMENTATION_STATE.md) and the active phase doc.
 - Keep compatibility surface minimal; do not add legacy aliases, wrappers, or duplicate docs unless explicitly requested.
 - A question requires an answer, not an action. When the user asks a question — even one implying criticism or correction — answer first before taking any action. Do not treat a question as implicit authorization to act.

package/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+## 0.8.0 - 2026-07-08
+
+<!-- Release date is set at tag time; see the release runbook. This section is prepared ahead of the v0.8.0 tag. -->
+
+Everything merged since v0.7.1 — the v0.7.x contract-audit epic (#1104) plus follow-on release-gate fixes. **Versioning note:** most of these commits are ancestors of the `v0.7.2` tag and therefore already ship in the published `0.7.2` npm artifact, but `v0.7.2`'s release notes documented only the #1241 packaging hotfix (see the 0.7.2 section below). This section backfills that omitted changelog and adds the nine changes that genuinely postdate the `v0.7.2` tag (#1240, #1242, #1244, #1249, #1250, #1253, #1254, #1256, and #1236/#1252); it becomes the notes for the eventual `v0.8.0` tag.
+
+### Added
+
+- **Issue-less lightweight PR-first flow (#1210/#1215).** A PR with no backing issue can drive the lightweight path with a configurable composed Copilot round cap; such PRs auto-enqueue as board items so they are still tracked (#1218/#1226).
+- **State-machine conformance and invariant harness (#1148/#1189).** Built on a rule-ownership foundation (#1183). The PR lifecycle state machine is exported from `@dev-loops/core` as the single source for docs, the state atlas, and the conformance harness (#1193/#1216), and `public-dev-loop-routing` is wired into the L2/L3 conformance harness so all five machines are covered (#1233/#1239).
+- **Inline reviewer briefing prefix (#1220/#1229).** The reviewed content is carried inline, size-capped and hash-enforced, on top of invariant-prefix-first reviewer briefings with prefix-hash enforcement (#1207/#1214).
+- **First-class loop primitives (#1198/#1223).** `list-review-threads` and `wait-pr-checks`, plus a sanctioned `edit-issue.mjs` wrapper for AC-reflection body edits (#1253) and a refinement-artifact-at-enqueue requirement so no un-refined item enters Next Up (#1251/#1254).
+- **State-atlas fullscreen lightbox for diagrams (#1217).** Diagrams open in a fullscreen lightbox for readable inspection.
+
+### Fixed
+
+- **Package-escaping `@dev-loops/core` imports broke consumer installs (#1241).** Shipped as the v0.7.2 hotfix; full detail is in the 0.7.2 section below.
+- **Converge-then-gate enforced at `pre_approval` entry (#1190/#1219).** Retires the known gap where a gate could run before Copilot convergence.
+- **Fanout provenance fails closed on missing mandatory or foreign angles (#1196/#1225).** Briefing-prefix verification is also scoped by (gate, headSha) (#1249).
+- **Reviewer-loop submission-failure edges join the transition table (#1200/#1221).** Copilot summon literals are sanitized on write with a code-span-aware guard and an honest blocked status (#1213/#1222).
+- **Issue-less lightweight PR-first three-origin contracts reconciled (#1242).** Adds a gate-coordination `specSource` branch; a contradiction sweep covers gate-skip scoping, coverage-modality ownership, and advisory wording (#1244).
+- **run-claim coordination file anchored at the git common dir, not CWD (#1250).** The per-PR runner lease now resolves its coordination file from the shared git common dir, so a runner started from a different worktree/CWD attaches to the same lease instead of forking a second one.
+- **`queue --item` accepts the full node-ID alphabet across the projects scripts (#1227/#1230).** The `--item` node-ID parser now accepts the complete GitHub node-ID character set, so board items whose IDs use previously-rejected characters resolve consistently across the projects scripts.
+- **release.yml dispatches npm-publish.yml explicitly after creating the release (#1187/#1188).** Pages deploy is bumped to deploy-pages v5 (#1211/#1212) and the gate-hub flowchart renders left-to-right (#1208/#1209).
+- **docs-validator manifest gap and corpus→manifest completeness (#1238).** Epic AC1/AC2 zero-states restored — canonical-owner openers plus remaining phrase pins (#1240).
+
+### Changed
+
+- **Contract corpus condensation + single-owner rule IDs.** Rule ownership migrated to single-owner IDs across the gate, queue, loop, worktree, intake, and public-loop clusters, with residual normative phrase-pins retired to a zero-pin end state (#1149–#1159, #1191–#1206). Inline interpreters were banned from coordinator flows in favor of sanctioned paths by reference (#1224/#1228), a final corpus condensation sweep rewired rule IDs with zero semantic change (#1236/#1252), and RFC-2119 modality was harmonized on newly-tagged merge/confirmation clauses (#1256).
+
 ## 0.7.2 - 2026-07-06
 
 ### Fixed

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