dev-loops 0.7.2 → 0.8.0

package/skills/docs/required-rules.json

@@ -1,6 +1,7 @@
 {
   "requiredRules": [
     "ACCEPT-CRITERIA-VERIFY-AND-REFLECT",
+    "ANTIPATTERN-FANIN-WAIT",
     "ARTIFACT-LIGHTWEIGHT-BODY-INVARIANTS",
     "ARTIFACT-LIGHTWEIGHT-PLAN-FILE-EXCLUSIVE",
     "ARTIFACT-STRATEGY-ENUM-FAIL-CLOSED",
@@ -56,6 +57,10 @@
     "GATE-EXEC-REGATE-MANDATORY",
     "GATE-EXEC-SEPARATE-CHAINS",
     "GATE-SKIP-NOT-RECOVERABLE-BY-CONVERGENCE",
+    "GRILL-SUBLOOP-HONEST-HANDOFF",
+    "GRILL-SUBLOOP-ITERATE-TO-CLEAN",
+    "GRILL-SUBLOOP-NO-EMBED-SYNTHESIS",
+    "GRILL-SUBLOOP-STATE-MACHINE",
     "INTAKE-LINKED-PR-HELPER-DELEGATION",
     "INTAKE-NEW-IDEA-SAFETY",
     "INTAKE-STOP-STATES",
@@ -79,9 +84,11 @@
     "OPS-NO-INLINE-INTERPRETER",
     "QUEUE-BOARD-LINKED",
     "QUEUE-BOARD-QUERY-FAIL-CLOSED",
+    "QUEUE-BOARD-SYNC-CONTINUOUS",
     "QUEUE-BOOTSTRAP-ONLY-MUTATOR",
     "QUEUE-COLUMN-CANONICAL",
     "QUEUE-COLUMN-NO-REMOVE",
+    "QUEUE-ENQUEUE-REFINEMENT-GATE",
     "QUEUE-LIVE-PICKUP-SOURCE",
     "QUEUE-NEXTUP-EMPTY-FAIL-CLOSED",
     "QUEUE-NEXTUP-SOURCE",
@@ -144,6 +151,15 @@
     "WORKTREE-DEDUPE",
     "WORKTREE-DEFAULT-USE",
     "WORKTREE-DEPS-ISOLATED",
-    "WORKTREE-FALLBACK"
+    "WORKTREE-FALLBACK",
+    "COPILOT-FOLLOWUP-VERIFY-BEFORE-RESOLVE",
+    "INTAKE-TIMEOUT-ROUTE-ON-SEAM-EXIT",
+    "INTAKE-TIMEOUT-SURFACE-BUDGET-EXHAUSTED",
+    "INTAKE-REPO-SLUG-RESOLVE-FIRST",
+    "FACADE-COPILOT-INTERNAL-ONLY",
+    "REFINER-DOD-PROPOSED-SUBSECTION",
+    "REFINER-NO-INVENT-AUDIT-FINDINGS",
+    "COPILOT-FOLLOWUP-REREQUEST-GREEN-GATE",
+    "COPILOT-FOLLOWUP-RESOLVE-AFTER-REPLY"
   ]
 }

package/skills/docs/retrospective-checkpoint-contract.md

@@ -96,8 +96,8 @@ If the gate result is `needs_reconcile`, the caller MUST NOT proceed with the pr
 <!-- rule: RETRO-ADVISORY-NEVER-GATE -->
 The retrospective is **advisory**: it runs, records flagged raw-call / discipline
 observations honestly, and passes them back to the conductor (main agent) to
-**decide** what to do with them — but it MUST NOT block a merge or any lifecycle
-transition. The pre-merge retrospective gate (`evaluateRetrospectiveMergeApproval`
+**decide** what to do with them — but it MUST NOT block a merge or any PR-lifecycle
+transition of the current run. The pre-merge retrospective gate (`evaluateRetrospectiveMergeApproval`
 and the `requireRetrospectiveGate` / `requireRetrospectiveInternalTooling` config
 keys) has been **removed**. There is no `retrospective_gate_pending` / `blocked`
 disposition on account of the internal-tooling raw-call record.
@@ -135,10 +135,13 @@ scripts legitimately call `gh`/GraphQL internally; that is the tooling. The rule
 targets the agent's own top-level shell calls, not a script's internals.
 
 **Write-op allowlist (verifier only):** `gh pr merge`, `gh pr ready`,
-`gh issue create`, `gh issue edit` have no internal wrapper today. The deterministic
-verifier records these as `allowedWriteOps` rather than violations so they are
-surfaced distinctly, not as breaches. Close the gap with a wrapper to remove an
-entry. None of these block anything.
+`gh issue create` have no internal wrapper today. `gh issue edit` now has one
+(`scripts/github/edit-issue.mjs`) and stays as a belt-and-suspenders entry — like
+`gh label create` (`scripts/github/create-label.mjs`) — so a bare invocation
+surfaced from the wrapper's own subprocess is not miscounted as a breach. The
+deterministic verifier records all of these as `allowedWriteOps` rather than
+violations so they are surfaced distinctly, not as breaches. Close the gap with a
+wrapper to remove or reframe a no-wrapper entry. None of these block anything.
 
 **Inline-interpreter check item:** the raw-call scan below mechanically catches
 `node -e`/`python3 -c`/heredoc calls as a `rawCallViolations` entry — the same

package/skills/docs/validation-policy.md

@@ -17,7 +17,7 @@ Canonical owner for validation requirements across all workflow families.
 ## Coverage requirements
 
 <!-- rule: VALIDATE-COVERAGE-THRESHOLD -->
-`VALIDATE-COVERAGE-THRESHOLD`: Changed files MUST have ≥90% coverage for lines, statements, functions, and branches, and non-trivial logic MUST be test-first.
+`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.
 
@@ -65,7 +65,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
@@ -108,7 +108,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/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