dev-loops 0.7.1 → 0.8.0

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

@@ -1,7 +1,8 @@
 # Tracker-First Story-to-PR Contract
 
-This document defines the adapter-agnostic MVP contract for the tracker-first
-story-to-PR workflow in `dev-loops`.
+Canonical owner for the adapter-agnostic MVP contract for the tracker-first
+story-to-PR workflow in `dev-loops`, and for the tracker-first loop state
+machine (#449).
 
 **MVP invariant: one tracker work item → one GitHub PR.**
 
@@ -30,7 +31,8 @@ Implementation for each:
 | Epic / PRD reference | Optional linked metadata only; no roll-up or automation in this slice |
 | ADR / RFC reference | Optional linked metadata only; no decision-sync in this slice |
 
-**Invariant:** For any single tracker work item in scope, there is at most
+<!-- rule: TRACKER-ONE-ACTIVE-PR -->
+For any single tracker work item in scope, there MUST be at most
 one active GitHub PR at a time. Multi-PR workflows and roll-up automation
 are out of scope for this slice.
 
@@ -57,6 +59,9 @@ already-correct PR leaves it unchanged.
 
 ### 3.1 Required PR Metadata
 
+<!-- rule: TRACKER-PROJECTION-REQUIRED-METADATA -->
+Every projected PR MUST carry the following fields:
+
 | Field | Rule |
 |---|---|
 | PR title | `[{TRACKER_ID}] {tracker item title}` — bracketed tracker identifier followed by the item title verbatim |
@@ -64,7 +69,7 @@ already-correct PR leaves it unchanged.
 | PR body — Summary section | Required. Brief description of the change implemented in this PR. |
 | PR body — Acceptance Criteria section | Required. Copied or linked from the tracker item's acceptance criteria. |
 | Labels | Required: `tracker:{TRACKER_ID}`. Optional reference labels: `epic:{EPIC_ID}`, `prd:{PRD_ID}` when references are present. |
-| Draft state | PR must start as a draft. It must not be marked ready-for-review until development work is complete. |
+| Draft state | PR MUST start as a draft. It MUST NOT be marked ready-for-review until development work is complete. |
 
 ### 3.2 Optional Reference Metadata
 
@@ -85,9 +90,9 @@ They are read-only metadata in this slice and do not trigger any automation:
 2. **On tracker item field change**: Re-apply projection rules to PR title,
    body, and labels. Leave any sections not covered by projection rules
    (e.g. reviewer-added review comments) intact.
-3. **Idempotent regeneration**: If the PR already has the correct title, body
-   sections, and labels, no mutation is performed. Projection is a no-op
-   when the current state already matches the target.
+3. <!-- rule: TRACKER-PROJECTION-IDEMPOTENT --> **Idempotent regeneration**: Projection MUST be a no-op when the PR already has the correct
+   title, body sections, and labels — re-applying the rules to an already-correct PR MUST NOT
+   mutate it.
 
 ### 3.4 PR Body Template
 
@@ -120,7 +125,7 @@ implementations map canonical action names to tracker-native field updates.
 | `pr_merged` — PR merged | `set_done` | Tracker moves to done/completed terminal state |
 | `pr_closed_unmerged` — PR closed without merge | `none` | No automatic terminal transition; human decision required |
 | `no_tracker_item` | `none` | No tracker item to update |
-| `blocked_needs_user_decision` | `none` | Stop and report; no automatic tracker update |
+| <!-- rule: TRACKER-BLOCKED-FAIL-CLOSED --> `blocked_needs_user_decision` | `none` | An unexpected or contradictory snapshot MUST stop and report; the helper MUST NOT apply an automatic tracker update |
 
 ### 4.2 Event Triggers
 

package/skills/docs/validation-policy.md

@@ -4,9 +4,8 @@ Canonical owner for validation requirements across all workflow families.
 
 ## Default validation
 
-- `npm run verify` is the default repo-level local validation path
-- Must pass before: PR creation, gate entry, merge
-- At minimum: `npm test && npm run test:dev-loop`
+<!-- rule: VALIDATE-VERIFY-BEFORE-GATE -->
+`VALIDATE-VERIFY-BEFORE-GATE`: `npm run verify` is the default repo-level local validation path and MUST pass before PR creation, gate entry, and merge; at minimum this means `npm test && npm run test:dev-loop`.
 
 ## Gate-specific requirements
 
@@ -17,8 +16,8 @@ Canonical owner for validation requirements across all workflow families.
 
 ## Coverage requirements
 
-- ≥90% coverage for lines, statements, functions, and branches on changed files
-- Test-first for all non-trivial logic
+<!-- rule: VALIDATE-COVERAGE-THRESHOLD -->
+`VALIDATE-COVERAGE-THRESHOLD`: Changed files SHOULD maintain ≥90% coverage for lines, statements, functions, and branches (not enforced by the shipped verify config; treat it as the working target), and non-trivial logic MUST be test-first.
 
 ## Cross-references
 

package/skills/local-implementation/SKILL.md

@@ -13,7 +13,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,47 +61,38 @@ When the local spec already lives in a tracker issue:
 - resolve the tracker reference deterministically from a GitHub issue URL or explicit `<owner/name>` + issue number
 - use the bounded GitHub helper `scripts/github/resolve-tracker-local-spec.mjs` when you need a machine-readable spec bundle
 - treat the tracker issue title/body/url/state as the durable local spec bundle
-- do not create or read [Phase Plan](../../docs/phases/phase-x.md) for that same tracker-backed session
+- the no-duplicate-phase-doc rule is owned by `ARTIFACT-TRACKER-FIRST-NO-DUP` in [Artifact Authority Contract](../docs/artifact-authority-contract.md); do not read [Phase Plan](../../docs/phases/phase-x.md) for that same tracker-backed session either
 - 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
-- for tracker-backed sessions, always open PRs through the canonical `dev-loops pr create` path, which is ALWAYS draft and always assigned — self-assigned by default (`--assignee @me` when none is given; honors an explicit `--assignee <login>` / `-a <login>`), never 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 ...`. Do not create a fresh PR directly in ready-for-review state unless the user explicitly overrides that policy for the current PR scope. The draft gate inspection is a real workflow boundary.
-- do not suggest a direct local-main merge for tracker-backed sessions; do not merge the working branch into local `main` at phase completion
+- <!-- 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
 
 ### Step 0: Pre-flight gate (mandatory for local_implementation)
 
-For the `local_implementation` strategy, before any planning or implementation mutation, run the pre-flight gate:
+<!-- rule: LOCAL-PREFLIGHT-GATE-MANDATORY -->
+For the `local_implementation` strategy, before any planning or implementation mutation, you MUST run the pre-flight gate:
 
 ```sh
 node scripts/loop/pre-flight-gate.mjs --expected-branch <working-branch> --check-subagents
 ```
 
-Before creating or reusing a worktree for local implementation, use the canonical lifecycle entrypoint, which fetches the base remote, then creates-or-reuses the worktree at its namespaced path and provisions it in one step:
+Before creating or reusing a worktree for local implementation, use the canonical lifecycle entrypoint (`WORKTREE-CREATE-PROVISION`, see [Worktree usage guidance](../../docs/worktree-guidance.md#create-or-reuse--provision-ensure-worktreemjs)):
 
 ```sh
 node scripts/loop/ensure-worktree.mjs --repo-root <main> --issue <n>
 ```
 
-This creates (or reuses) the worktree at `tmp/worktrees/dev-loops/<kind>-<n>` from a freshly fetched `origin/main` (the authoritative base for all worktree creation) and provisions its gitignored runtime files. Raw `git worktree add -b <branch> tmp/worktrees/dev-loops/<kind>-<n> origin/main` is the underlying mechanism `ensure-worktree.mjs` runs for you. See [worktree guidance](../../docs/worktree-guidance.md).
+This validates worktree isolation (current directory under `tmp/worktrees/`) and branch identity (current branch matches the working branch); `--check-subagents` only reports subagent availability and is advisory (fails-open, does not block the gate). If the gate fails, **stop and fix the violation** before proceeding — do not bypass it in normal workflow execution.
 
-This validates:
-- Worktree isolation (current directory is under `tmp/worktrees/`)
-- Branch identity (current branch matches the working branch)
-- Subagent availability (subagents should be used for fan-out when available)
-
-If the gate fails, **stop and fix the violation** before proceeding. Do not bypass the gate in normal workflow execution.
-
-Note: `--check-subagents` is advisory — it reports availability but does not block the gate. The worktree and branch checks are the mandatory gates.
-
-This gate does **not** apply to other routed strategies (`copilot_pr_followup`, `external_pr_followup`, `reviewer_fixer`, `wait_watch`, `final_approval`, `issue_intake`). Those strategies have their own execution rules and may edit code from any checkout as needed.
-
-Development-only bypass (`DEVLOOPS_PREFLIGHT_BYPASS=1`) exists for testing the gate itself but must not be used in production workflow runs. The bypass variable is a testing convenience, not an operational escape hatch.
+This gate does **not** apply to other routed strategies (`copilot_pr_followup`, `external_pr_followup`, `reviewer_fixer`, `wait_watch`, `final_approval`, `issue_intake`); those strategies have their own execution rules and may edit code from any checkout as needed. The development-only bypass (`DEVLOOPS_PREFLIGHT_BYPASS=1`) exists for testing the gate itself and MUST NOT be used in production workflow runs — it is a testing convenience, not an operational escape hatch.
 
 ## Narrow failure-triage fast path
 
-When resuming local implementation with dirty work or an observed failing command, use this path before broad discovery:
+<!-- rule: LOCAL-FAILURE-TRIAGE-ORDER -->
+When resuming local implementation with dirty work or an observed failing command, you MUST follow this ordered path before broad discovery:
 
 1. run startup once from the relevant worktree/context
 2. inspect current state with `git status` and the changed files
@@ -115,20 +106,13 @@ Follow [Anti-patterns](../docs/anti-patterns.md) for the general tooling-interna
 
 ### Step 1
 
-- Implement **one phase at a time**.
-- Do not refine later phases in detail before the current phase is complete.
+- <!-- 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.
-- Work **test-first** for all non-trivial logic.
-- Maintain **90% coverage** thresholds.
+- <!-- 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.
-- For phase-doc-backed local sessions, keep durable phase intent and acceptance criteria in [Phase Plan](../../docs/phases/phase-x.md); for tracker-backed local sessions, keep that durable intent in the tracker issue and do not duplicate it into [Phase Plan](../../docs/phases/phase-x.md). Keep detailed execution artifacts in `tmp/`.
-- Treat `tmp/` as temporary local execution state. Do not rely on it as durable repo history and do not force-add it to git unless the user explicitly wants checked-in examples or fixtures.
+- 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.
-- Do implementation work on a dedicated local branch, not directly on `main`.
-- If the repo has no commits yet, still create the working branch first so the first commits land off `main`; only move `main` forward after review and validation.
-- Use small atomic local commits as progress checkpoints whenever a coherent slice is green and reviewable.
-- Before a branch is considered review-complete, approval-ready, merge-ready, or ready for final handoff, run the default pre-approval gate as a full review / fix loop with the review angles resolved from config (`resolveGateAngles(config, "preApproval")`), then apply accepted fixes and rerun validation. Shipped defaults include the `deep` angle.
-- A phase is only fully complete when its scoped work, required support files, artifacts, validation, review/fix pass, commit(s), and finalization (merge into local `main` for phase-doc-backed sessions; PR merge for tracker-backed sessions) are done, or when the only remaining step is an explicitly noted authorization-gated finalization action.
+- Branch, commit, pre-approval-gate, and finalization mechanics: see [Branch / review / merge policy](#branch--review--merge-policy), [Commit policy](#commit-policy), and [Implementation loop for the phase](#implementation-loop-for-the-phase) below.
 - When subagents are used, log what each subagent was asked to do and what it concluded.
 - If [Project Plan](../../PLAN.md) is too rough or ambiguous to safely start the current phase, do not guess: run a clarification/interview step with the user first.
 
@@ -138,32 +122,14 @@ Apply [Structural Quality](../docs/structural-quality.md) from the `deep` review
 
 ## Light mode (small changes)
 
-Light mode is wired into gate dispatch. A PR that is **under threshold** (≤ `maxLines` lines changed AND ≤ `maxFiles` files, per `.devloops` field `localImplementation.lightMode` — this repo sets `maxLines: 20`, `maxFiles: 2`; the shipped built-in default has light mode disabled (`enabled: false`); if enabled without explicit values it falls back to `maxFiles: 3` / `maxLines: 200`) AND carries no `gate:full` label collapses BOTH `draft_gate` and `pre_approval_gate` to a single inline single-agent correctness + no-op check. The Copilot review request and its polling are skipped.
-
-**Escalation:**
-1. Auto-escalate — if the inline check surfaces any finding whose severity is in the gate's `blockCleanOnFindingSeverities` (i.e. ≥ `worth-fixing-now`), dispatch escalates to full fan-out.
-2. Label override — the `gate:full` label forces full fan-out regardless of PR size.
-
-The `draft_gate` boundary (draft → ready) is still recorded because `requireDraftFirst` is honored: light mode only changes HOW the gate runs (inline vs fan-out), not WHETHER the draft boundary exists.
-
-Dispatch is resolved deterministically via `resolveGateDispatchMode(config, gate, { scope, hasFullLabel, inlineFindingSeverities })` from `@dev-loops/core/config`. `scripts/loop/resolve-gate-dispatch.mjs` is the CLI wrapper the orchestrator calls, combining `detect-change-scope.mjs` output with the `gate:full` label fact.
+<!-- rule: LOCAL-LIGHT-MODE-CONFIG-SURFACE -->
+`localImplementation.lightMode` (`.devloops` field; this repo sets `maxLines: 20`, `maxFiles: 2`) is this skill's config surface for light-mode gate dispatch. Gate-collapse mechanics, escalation, and dispatch resolution (`resolveGateDispatchMode`, `scripts/loop/resolve-gate-dispatch.mjs`) are owned by [Light-mode inline acceptance](../../docs/gate-review-sub-loop-contract.md#light-mode-inline-acceptance-under-threshold-micro-prs); this skill MUST NOT redefine them.
 
 Use `scripts/loop/detect-change-scope.mjs` to determine scope:
 ```sh
 node scripts/loop/detect-change-scope.mjs
 ```
 
-**Override threshold:**
-```yaml
-localImplementation:
-  lightMode:
-    enabled: true
-    maxFiles: 2
-    maxLines: 20
-```
-
-Scope above threshold falls back to the full fan-out/fan-in path.
-
 ## Deterministic logging structure
 
 Treat the workflow as three layers:
@@ -409,7 +375,8 @@ If the review finds real issues, revise the merged plan and briefly update the r
 
 ### 6. Only then start implementation
 
-Do not begin coding before the merged phase plan has passed review.
+<!-- rule: LOCAL-PLAN-REVIEW-GATE -->
+You MUST NOT begin coding before the merged phase plan has passed review.
 Update `manifest.json` to show that phase implementation has started.
 
 ## Task breakdown & delegation
@@ -428,7 +395,8 @@ into parallel executable tasks and dispatch them to the right specialist subagen
 
 ### Delegation contract
 
-Dispatch implementation tasks to dedicated specialist agents:
+<!-- rule: LOCAL-DELEGATION-TABLE -->
+Implementation tasks MUST be dispatched to dedicated specialist agents per this table:
 
 | Task type | Delegate to |
 |---|---|
@@ -528,7 +496,7 @@ After the phase plan passes review:
 5. Run the default pre-approval gate as a full review / fix loop on the branch before calling it review-complete, approval-ready, merge-ready, or ready for final handoff:
    - resolve review angles from config: `resolveGateAngles(config, "preApproval")` from `@dev-loops/core/config` (shipped defaults enable all 11 pre-approval gate angle families; consumer repos may opt out individual angles via `excludeAngles`); run via the chain prescription below
    - run the resolved angle-focused passes in parallel with fresh context when practical
-   - if parallel execution is impractical (for example due to tooling or resource constraints), run all angles sequentially and explicitly record why parallel execution was impractical in `Phase Review` (`tmp/phases/phase-x/review.md`) (or the equivalent merged review artifact)
+   - the sequential-fallback rule is owned by `GATE-EXEC-FANOUT-SEQUENTIAL-FALLBACK` in [Gate Review Sub-Loop Contract](../../docs/gate-review-sub-loop-contract.md); when it applies, record the fallback in `Phase Review` (`tmp/phases/phase-x/review.md`) (or the equivalent merged review artifact)
    - for each angle, resolve its persona and prompt via `resolveReviewerRole(config, angle)` — start each reviewer in fresh context with a concise briefing including the angle-specific prompt, the branch/phase, intended behavior, acceptance criteria, relevant files or artifacts, and current validation status
    - run the mandatory chain defined in [Gate Review Sub-Loop Contract](../../docs/gate-review-sub-loop-contract.md). Retry rule: in subsequent cycles, only re-run reviewers that produced findings in the previous pass. Do not fork the parent session for parallel reviewers; write a compact handoff artifact under `tmp/` and point the reviewer at it.
    - when reviewer subagents stumble on raw source-tree reads (for example unresolved build artifacts or import assumptions), generate a deterministic diff/review artifact under `tmp/` and have reviewers inspect that artifact instead of the raw file set
@@ -542,8 +510,8 @@ After the phase plan passes review:
 9. Write `Retrospective` (`tmp/phases/phase-x/retrospective.md`) using [Retrospective Template](../dev-loop/templates/retrospective.md).
 10. Update `tmp/phases/phase-x/manifest.json` and `tmp/phases/index.json`.
 11. Update [Implementation State](../../docs/IMPLEMENTATION_STATE.md).
-12. **Exit validation gate — no uncommitted changes.** Before the subagent session terminates, run `git status --porcelain` and verify the output is empty. If uncommitted changes exist, first determine whether they are intended implementation changes or unintended/post-validation deltas. Revert any unintended or speculative changes. For intended changes, rerun the narrowest justified validation (`npm run verify` or equivalent) before staging and committing with an appropriate message; for tracker-backed sessions, also push the branch. A subagent session that exits with uncommitted changes in the worktree is a workflow defect and must not be treated as a clean completion. After committing, verify `git status --porcelain` is empty before declaring phase completion.
-13. For tracker-backed sessions, create the PR from the working branch using the canonical `dev-loops pr create --assignee @me --repo <owner/name> --base main --head <branch> --title "..." --body-file <body-file>` (always draft, self-assigned by default; `--assignee @me` is the default and is shown here for clarity). When the `dev-loops` CLI helper is unavailable, use the equivalent `create-pr.mjs` script directly: `node <resolved-skill-scripts>/github/create-pr.mjs --repo <owner/name> --assignee @me --base main --head <branch> --title "..." --body-file <body-file>`. Never open a PR with raw `gh pr create`. The PR body must contain `Closes #N` (or `Fixes #N`) for the linked issue. Do not create a fresh PR directly in ready-for-review state unless the user explicitly overrides that policy.
+12. <!-- rule: LOCAL-COMMIT-BEFORE-EXIT --> **Exit validation gate — no uncommitted changes.** Before the subagent session terminates, run `git status --porcelain` and verify the output is empty. If uncommitted changes exist, first determine whether they are intended implementation changes or unintended/post-validation deltas. Revert any unintended or speculative changes. For intended changes, rerun the narrowest justified validation (`npm run verify` or equivalent) before staging and committing with an appropriate message; for tracker-backed sessions, also push the branch. A subagent session that exits with uncommitted changes in the worktree is a workflow defect and MUST NOT be treated as a clean completion. After committing, verify `git status --porcelain` is empty before declaring phase completion.
+13. For tracker-backed sessions, create the PR from the working branch: `dev-loops pr create --assignee @me --repo <owner/name> --base main --head <branch> --title "..." --body-file <body-file>` (fallback when the CLI helper is unavailable: `node <resolved-skill-scripts>/github/create-pr.mjs --repo <owner/name> --assignee @me --base main --head <branch> --title "..." --body-file <body-file>`); never raw `gh pr create`. Draft/assignment/`Closes #N` policy: [LOCAL-PR-CREATE-CANONICAL](#tracker-backed-local-implementation) above.
 14. If authorized, merge the fully reviewed, locally validated phase branch back into local `main` (phase-doc-backed sessions) or proceed through the PR gate pipeline (tracker-backed sessions).
 15. If authorization for PR creation or merge is still pending (commit authorization is already enforced by the exit validation gate in step 12), mark the phase as `awaiting-finalization` rather than `completed`, and record exactly which finalization step is pending.
 
@@ -556,85 +524,32 @@ The retrospective must capture:
 - what should change in the skill or workflow next time
 - what a fresh session should know before the next phase
 
-This is the infrastructure for self-improvement. Do not skip it.
+<!-- rule: LOCAL-RETROSPECTIVE-REQUIRED -->
+This is the infrastructure for self-improvement; you MUST NOT skip it.
 
 ## Dev mode
 
-Dev mode is for improving the local implementation loop itself while using it.
-
-A repository may also declare a formal-dev-mode default through `.devloops` field `workflow.devModeDefault`. Treat that config as the policy source of truth when present, but explicit user opt-in or opt-out for the current run still wins. Runtime consumption of that config may be staged separately from this documentation update.
-
-Trigger it when the user explicitly asks for dev mode, self-improvement mode, or says they want the skill to refine itself as it goes.
-
-In dev mode, after the normal phase summary and retrospective are written, run one extra bounded self-improvement pass before moving on:
-
-1. collect a deterministic context bundle for the phase using:
-   - `../dev-loop/scripts/dev-mode-context.mjs`
-   - output to `tmp/phases/phase-x/dev-mode-context.json`
-2. review the phase artifacts and logs with emphasis on the workflow itself:
-   - planning quality
-   - review quality
-   - validation friction
-   - bash exit-code-1 patterns
-   - places where skill or agent prompts should be tightened
-   - places where deterministic tooling should replace ad hoc work
-3. write `Dev Mode Retrospective` (`tmp/phases/phase-x/dev-mode-retrospective.md`)
-   - this is the required dev-mode retrospective artifact
-   - it should name the highest-value prompt/workflow follow-ups revealed by the phase
-4. optionally write `Dev Mode Review` (`tmp/phases/phase-x/dev-mode-review.md`) when separate analytical notes help support the retrospective
-5. apply at least one bounded follow-up update to a relevant skill and/or agent prompt
-   - deterministic tooling, docs, templates, or tests may accompany that change
-   - but they do not replace the required prompt update
-   - keep the change phase-bounded and tied directly to the retrospective findings
-6. write `Dev Mode Skill Changes` (`tmp/phases/phase-x/dev-mode-skill-changes.md`)
-   - record which skill and/or agent prompts changed
-   - record any supporting tooling/docs/template changes that accompanied them
-   - if no prompt update can be justified safely, stop and report that dev-mode exit criteria were not met
-7. if skill scripts or deterministic tooling changed, rerun the skill-local tests
-8. stop after this bounded self-improvement pass; do not recurse into endless self-editing loops
-
-Dev mode is still phase-bounded. It improves the loop around the completed phase; it does not authorize work on the next product phase.
+Dev mode improves the local implementation loop itself while using it. A repo may declare a default via `.devloops` field `workflow.devModeDefault`; explicit user opt-in/opt-out for the current run still wins over that default. Trigger it when the user explicitly asks for dev mode, self-improvement mode, or says they want the skill to refine itself as it goes.
 
-## tmp/ logging requirements
+After the normal phase summary and retrospective, run one extra bounded self-improvement pass:
 
-At minimum, each phase should leave behind:
-- a durable phase doc at [Phase Plan](../../docs/phases/phase-x.md)
-- local `tmp/` execution artifacts needed to resume and audit the phase, including:
-  - `manifest.json`
-  - `Variant A` (`tmp/phases/phase-x/variant-a.md`)
-  - `Variant B` (`tmp/phases/phase-x/variant-b.md`)
-  - `merged-plan.md`
-  - `review.md`
-  - `summary.md`
-  - `retrospective.md`
-  - optional `Variant C` (`tmp/phases/phase-x/variant-c.md`) when a third variant was actually useful
-  - `bash-exit-1.jsonl` when any bash call during the phase exited with code `1`
-  - `clarification.md` when a plan-sufficiency interview or auto-clarification step was needed
-  - subagent summaries when subagents were used
-  - raw subagent outputs only when they were saved separately on purpose
-  - in dev mode: `dev-mode-context.json`, `dev-mode-retrospective.md`, and `dev-mode-skill-changes.md`
-  - optional in dev mode: `dev-mode-review.md` when separate analytical notes were useful
-
-These `tmp/` artifacts are normally temporary and do not need to be checked into git.
-
-Also log validation output summaries and notable decisions if they help evaluate the local dev loop later.
-
-Additionally, append every bash call that exits with code `1` to:
-- `tmp/phases/phase-x/bash-exit-1.jsonl`
+1. Collect a deterministic context bundle: `../dev-loop/scripts/dev-mode-context.mjs` → `tmp/phases/phase-x/dev-mode-context.json`.
+2. Review the phase artifacts/logs for planning quality, review quality, validation friction, bash exit-code-1 patterns, and places where prompts or deterministic tooling should improve.
+3. Write `Dev Mode Retrospective` (`tmp/phases/phase-x/dev-mode-retrospective.md`) — required; name the highest-value prompt/workflow follow-ups revealed by the phase.
+4. Optionally write `Dev Mode Review` (`tmp/phases/phase-x/dev-mode-review.md`) when separate analytical notes help.
+5. Apply at least one bounded follow-up update to a relevant skill and/or agent prompt (supporting tooling/docs/template changes may accompany it but do not replace the prompt update), kept phase-bounded and tied directly to the retrospective findings.
+6. Write `Dev Mode Skill Changes` (`tmp/phases/phase-x/dev-mode-skill-changes.md`) recording which prompts and supporting changes landed; if no prompt update can be justified safely, stop and report that dev-mode exit criteria were not met.
+7. If skill scripts or deterministic tooling changed, rerun the skill-local tests.
+8. Stop after this bounded pass — do not recurse into endless self-editing loops.
+
+Dev mode is still phase-bounded: it improves the loop around the completed phase and does not authorize work on the next product phase.
 
-Use the deterministic helper:
-- `../dev-loop/scripts/log-bash-exit-1.mjs`
+## tmp/ logging requirements
 
-Each line should be one JSON object with at least:
-- `timestamp`
-- `phase`
-- `cwd`
-- `command`
-- `exitCode`
-- `purpose`
-- `summary`
+<!-- rule: LOCAL-TMP-EPHEMERAL-STATE -->
+The required durable-doc + `tmp/` artifact set for a phase is defined once in [Deterministic logging structure](#deterministic-logging-structure); this section MUST NOT duplicate that list. Those artifacts are normally temporary and do not need to be checked into git; do not force-add them unless the user explicitly wants checked-in examples or fixtures. Also log validation output summaries and notable decisions if they help evaluate the local dev loop later.
 
-If useful, also include truncated `stdout` and `stderr` fields or a path to a larger saved artifact. This log is for improving the local dev loop itself, so do not skip it just because the command was exploratory.
+Additionally, append every bash call that exits with code `1` to `tmp/phases/phase-x/bash-exit-1.jsonl` using the deterministic helper `../dev-loop/scripts/log-bash-exit-1.mjs`. Each line is one JSON object with at least `timestamp`, `phase`, `cwd`, `command`, `exitCode`, `purpose`, `summary` (optionally truncated `stdout`/`stderr` or a path to a larger saved artifact). This log improves the local dev loop itself, so do not skip it just because the command was exploratory.
 
 ## Stop conditions
 
@@ -642,29 +557,20 @@ See [Stop Conditions](../docs/stop-conditions.md). Local-specific stops: phase c
 
 ## Branch / review / merge policy
 
-- Do not implement directly on `main`.
-- Start or switch to a dedicated local working branch before the first mutating step.
-- If the repository is unborn (no commits yet), still create the working branch first and make the initial atomic commits there.
-- Use atomic local commits to log progress, but only for coherent reviewable slices.
-- Before merging, run a full parallel review / fix loop and resolve accepted findings on the same branch.
-- Rerun validation after review-driven fixes.
-- A phase is not operationally closed until its branch state is captured in commit history and the reviewed branch has been finalized according to session type (merged into local `main` for phase-doc-backed sessions; merged via GitHub PR for tracker-backed sessions), unless authorization for that finalization is still pending.
-- For tracker-backed sessions, the handoff path is always: push the working branch → open a PR → merge via GitHub; never merge the working branch into local `main`.
-- PR creation always goes through `dev-loops pr create`, which is ALWAYS draft and always assigned — self-assigned by default (`--assignee @me` when none is given; honors an explicit `--assignee <login>` / `-a <login>`), never via raw `gh pr create`, and 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 ...`. Do not create a fresh PR directly in ready-for-review state unless the user explicitly overrides that policy for the current PR scope. The draft gate inspection is a real workflow boundary, so a new PR must exist in draft before `gh pr ready` is eligible.
-- When authorization is pending, record the phase as `awaiting-finalization` and describe the exact missing step.
+- Implement on a dedicated local working branch, never directly on `main`, switching to it before the first mutating step; if the repo is unborn (no commits yet), still create the working branch first and make the initial atomic commits there.
+- Use atomic local commits to log progress, but only for coherent reviewable slices — [Commit policy](#commit-policy) below governs commit timing/authorization.
+- Before merging, run a full parallel review / fix loop and resolve accepted findings on the same branch; rerun validation after review-driven fixes.
+- A phase is not operationally closed until its branch state is captured in commit history and the reviewed branch has been finalized according to session type (merged into local `main` for phase-doc-backed sessions; merged via GitHub PR for tracker-backed sessions); when authorization for that finalization is still pending, record the phase as `awaiting-finalization` and describe the exact missing step.
+- For tracker-backed sessions, the handoff path is always: push the working branch → open a PR → merge via GitHub; never merge the working branch into local `main`. PR creation follows [LOCAL-PR-CREATE-CANONICAL](#tracker-backed-local-implementation) above; a new PR must exist in draft before `gh pr ready` is eligible.
 - For phase-doc-backed sessions, merge the fully reviewed, locally validated branch back into local `main` when authorized.
 - Behind-branch integration before merge (for example a sibling PR merged first and both touch shared files): prefer a merge commit (`git merge origin/main`) over rebase + force-push. Since dev-loop PRs are squash-merged, intermediate branch history is discarded at merge time, so a merge commit lands an identical result on `main` while avoiding a non-fast-forward push to the remote. Force-push (`--force-with-lease` only, never bare `--force`) remains acceptable only for a branch the loop solely owns and where no integration alternative exists (rare); document that carve-out rather than leaving it implicit. After any integration that changes the head SHA, re-verify gate evidence at the new head (existing behavior — see [Merge Preconditions](../docs/merge-preconditions.md#required-before-merge)).
 
 ## Commit policy
 
-- Do not commit speculative work.
-- Do not commit before the relevant validation for that slice passes.
+- Do not commit speculative work or before the relevant validation for that slice passes.
 - Immediately before every `git add && git commit` sequence, assert branch identity with `git branch --show-current` and stop if it does not match the intended local working branch.
-- Keep commits small and phase-bounded.
-- Do not leave completed phase work stranded off `main`; once the reviewed branch is ready and authorized, finalize it according to session type (merge into local `main` for phase-doc-backed sessions; complete via PR merge for tracker-backed sessions).
-- Commit only when the coordination/main agent has decided the slice or phase is ready. **Exception:** in non-interactive subagent sessions, commit authorization is implicit — the subagent was dispatched to implement and must commit before exiting (see the commit sub-bullet under implementation loop step 3 and the exit validation gate in step 12).
+- Commit only when the coordination/main agent has decided the slice or phase is ready. **Exception:** in non-interactive subagent sessions, commit authorization is implicit — the subagent was dispatched to implement and must commit before exiting, enforced by [LOCAL-COMMIT-BEFORE-EXIT](#implementation-loop-for-the-phase) (implementation loop step 12; `git status --porcelain` must be empty before the session terminates).
 - If commit/merge authorization has not yet been given, do not call the phase `completed`; call it `awaiting-finalization` instead.
-- **Subagent exit contract:** before a subagent session terminates, the exit validation gate (implementation loop step 12) must pass — `git status --porcelain` must be empty. A subagent that exits with uncommitted changes in the worktree has not completed its task, regardless of what was implemented.
 
 ## Anti-patterns
 

package/skills/loop-grill/SKILL.md

@@ -1,10 +1,11 @@
 ---
 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.
+  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
 ---
@@ -14,15 +15,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:
@@ -35,9 +44,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.
@@ -91,15 +103,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:
 
@@ -107,19 +124,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
@@ -154,7 +175,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