@dev-loops/core 1.0.0-rc.4 → 1.0.0-rc.6

package/src/loop/gate-fanin.mjs

@@ -77,6 +77,93 @@ export function backoffMaxConcurrent(maxConcurrent) {
   return Math.max(1, Math.floor(cap / 2));
 }
 
+/**
+ * Reviewer-budget preflight for a gate fan-out (issue #1507).
+ *
+ * Before the conductor dispatches any reviewer, it derives how many reviewers
+ * the round needs (one per dispatch unit — fresh angles + re-verifications) and
+ * compares against the harness's remaining reviewer budget. When the budget
+ * cannot cover the dispatch, the preflight reports the shortfall BEFORE any
+ * reviewer spawns, naming the shortfall; the shortfall is a recorded, resumable
+ * state (completed per-angle artifacts stay valid for their head, so a later
+ * session resumes the fan-out instead of restarting it). A budget shortfall
+ * NEVER downgrades a required gate to `inline_single_agent` and NEVER produces a
+ * clean verdict — no new gate-exemption path (#1507 AC4).
+ *
+ * Pure: takes the dispatch plan + available budget, returns the decision. The
+ * conductor reads `artifact.fanout.preflight` (emitted by `write-gate-context`)
+ * and dispatches wave-by-wave only when `dispatch === true`; on `false` it
+ * records the shortfall (the artifact itself is the resumable record) and
+ * stops without spawning a single reviewer. `availableReviewers` is `null` when
+ * the harness does not expose a budget — no shortfall can be proven, so the
+ * preflight proceeds (today's behavior); it only blocks on a PROVEN shortfall.
+ *
+ * The returned `verdict` and `executionMode` are ALWAYS `null`: a shortfall is
+ * not a verdict. `buildPreMergeGateCheck` / `evaluateInlineFanoutMode` reject a
+ * gate with no clean current-head marker and a non-`fanout_fanin` execution
+ * mode, so a shortfall state fails closed at merge rather than yielding a clean
+ * or inline verdict (#1507 DoD).
+ *
+ * @param {{ name: string, angles: string[] }[]} dispatchGroups — `resolveFanoutGroups` output (fresh angles + re-verifications)
+ * @param {number|null} [availableReviewers] — harness remaining reviewer budget; null/non-finite = unknown/unexposed
+ * @param {{ completedAngles?: Iterable<string> }} [options] — `completedAngles`: angle names that
+ *   already have a clean per-angle findings artifact stamped for THIS head. A dispatch unit (group)
+ *   whose angles are ALL complete is excluded from the required count and from `pendingGroups`, so a
+ *   later session resumes the fan-out instead of restarting it (issue #1507 AC3): it re-runs the
+ *   preflight and dispatches only the groups not already complete at this head.
+ * @returns {{ ok: boolean, dispatch: boolean, requiredReviewers: number, availableReviewers: number|null, shortfall: number|null, reason: string, verdict: null, executionMode: null, pendingGroups: { name: string, angles: string[] }[], skippedGroups: { name: string, angles: string[] }[], completedAngles: string[] }}
+ */
+export function reviewerBudgetPreflight(dispatchGroups, availableReviewers, { completedAngles } = {}) {
+  const groups = Array.isArray(dispatchGroups) ? dispatchGroups : [];
+  const completedSet = new Set(
+    Array.isArray(completedAngles)
+      ? completedAngles
+      : completedAngles == null
+        ? []
+        : [...completedAngles],
+  );
+  // #1507 AC3: resume instead of restart. One reviewer per dispatch unit (a
+  // group of N angles is one reviewer's scoped dispatch — see resolveFanoutGroups /
+  // countFreshDispatchUnits), but a group already COMPLETE at this head — every
+  // one of its angles has a clean artifact stamped for this head — needs no
+  // reviewer and is excluded from the required count and the pending plan. The
+  // conductor dispatches only `pendingGroups`.
+  const groupIsComplete = (g) =>
+    Array.isArray(g?.angles) && g.angles.length > 0 && g.angles.every((a) => completedSet.has(a));
+  const pendingGroups = groups.filter((g) => !groupIsComplete(g));
+  const skippedGroups = groups.filter((g) => groupIsComplete(g));
+  // One reviewer per dispatch unit: a group of N angles is one reviewer's
+  // scoped dispatch, so the reviewer count is the pending dispatch-unit count,
+  // not the raw angle count.
+  const requiredReviewers = pendingGroups.length;
+  const verdict = null;
+  const executionMode = null;
+  const resume = { pendingGroups, skippedGroups, completedAngles: [...completedSet] };
+  if (typeof availableReviewers !== "number" || !Number.isFinite(availableReviewers)) {
+    return { ok: true, dispatch: true, requiredReviewers, availableReviewers: null, shortfall: null, reason: "budget_unknown", verdict, executionMode, ...resume };
+  }
+  // A negative/over-spent budget clamps to 0 (budget exhausted → shortfall for
+  // any non-empty round); a fractional budget truncates to the integer floor.
+  const available = Math.max(0, Math.trunc(availableReviewers));
+  if (requiredReviewers === 0) {
+    return { ok: true, dispatch: true, requiredReviewers: 0, availableReviewers: available, shortfall: null, reason: "no_reviewers_needed", verdict, executionMode, ...resume };
+  }
+  if (available >= requiredReviewers) {
+    return { ok: true, dispatch: true, requiredReviewers, availableReviewers: available, shortfall: null, reason: "budget_sufficient", verdict, executionMode, ...resume };
+  }
+  return {
+    ok: false,
+    dispatch: false,
+    requiredReviewers,
+    availableReviewers: available,
+    shortfall: requiredReviewers - available,
+    reason: "budget_shortfall",
+    verdict,
+    executionMode,
+    ...resume,
+  };
+}
+
 // Exported so other tools (e.g. scripts/loop/consolidate-fanin.mjs,
 // scripts/github/upsert-checkpoint-verdict.mjs) sort/rank/validate against
 // this single ordered copy of the severity vocabulary instead of each
@@ -736,6 +823,148 @@ export function consolidateFanin({ angleResults, blockCleanOnFindingSeverities }
   };
 }
 
+/**
+ * The judge's relevance-based disposition vocabulary — distinct from the
+ * severity-based `disposition` (accepted-for-fix/deferred/needs-answer) that
+ * `deriveDisposition` owns. The judge decides *where* a finding is acted on
+ * (this PR or a follow-up), never *whether* it is real: a `reject` is a
+ * relevance verdict (out-of-scope against a named non-goal or scope
+ * boundary), not a reproduction verdict. The fixer retains reproduction-based
+ * rejection; the judge owns relevance (#1525).
+ */
+export const JUDGE_DISPOSITIONS = Object.freeze(["act", "defer", "reject"]);
+
+/**
+ * Validate a judge verdict artifact shape (the dedicated `judge` agent's only
+ * write). Pure; throws on a malformed verdict rather than silently enriching
+ * findings with garbage. The judge is the designated memory across rounds, so
+ * its artifact is the authoritative relevance record — a malformed one fails
+ * closed rather than degrading to severity-only disposition.
+ *
+ * Shape:
+ * ```
+ * {
+ *   headSha: "<sha>",
+ *   scopeDrift: { verdict: "within_scope"|"drift_detected", rationale: "...", driftedAreas: ["..."] },
+ *   dispositions: [{ index, disposition: "act"|"defer"|"reject", rationale, criterion?, followUpDraft? }]
+ * }
+ * ```
+ *
+ * @param {unknown} verdict
+ * @returns {{ headSha: string, scopeDrift: object, dispositions: Array<object> }}
+ */
+export function validateJudgeVerdict(verdict) {
+  if (!verdict || typeof verdict !== "object" || Array.isArray(verdict)) {
+    throw new Error("judge verdict must be a JSON object");
+  }
+  const v = /** @type {Record<string, unknown>} */ (verdict);
+  if (typeof v.headSha !== "string" || v.headSha.trim().length === 0) {
+    throw new Error("judge verdict.headSha must be a non-empty string");
+  }
+  if (!v.scopeDrift || typeof v.scopeDrift !== "object" || Array.isArray(v.scopeDrift)) {
+    throw new Error("judge verdict.scopeDrift must be an object");
+  }
+  const sd = /** @type {Record<string, unknown>} */ (v.scopeDrift);
+  if (sd.verdict !== "within_scope" && sd.verdict !== "drift_detected") {
+    throw new Error("judge verdict.scopeDrift.verdict must be 'within_scope' or 'drift_detected'");
+  }
+  if (typeof sd.rationale !== "string" || sd.rationale.trim().length === 0) {
+    throw new Error("judge verdict.scopeDrift.rationale must be a non-empty string");
+  }
+  if (!Array.isArray(sd.driftedAreas)) {
+    throw new Error("judge verdict.scopeDrift.driftedAreas must be an array");
+  }
+  for (const [di, area] of sd.driftedAreas.entries()) {
+    if (typeof area !== "string" || area.trim().length === 0) {
+      throw new Error(`judge verdict.scopeDrift.driftedAreas[${di}] must be a non-empty string`);
+    }
+  }
+  if (!Array.isArray(v.dispositions)) {
+    throw new Error("judge verdict.dispositions must be an array");
+  }
+  const seenIndices = new Set();
+  for (const [i, d] of v.dispositions.entries()) {
+    if (!d || typeof d !== "object" || Array.isArray(d)) {
+      throw new Error(`judge verdict.dispositions[${i}] must be an object`);
+    }
+    const entry = /** @type {Record<string, unknown>} */ (d);
+    if (!Number.isInteger(entry.index) || entry.index < 0) {
+      throw new Error(`judge verdict.dispositions[${i}].index must be a non-negative integer`);
+    }
+    if (seenIndices.has(entry.index)) {
+      throw new Error(`judge verdict.dispositions[${i}].index ${entry.index} is a duplicate — the contract is one disposition per finding`);
+    }
+    seenIndices.add(entry.index);
+    if (!JUDGE_DISPOSITIONS.includes(entry.disposition)) {
+      throw new Error(`judge verdict.dispositions[${i}].disposition must be one of: ${JUDGE_DISPOSITIONS.join(", ")}`);
+    }
+    if (typeof entry.rationale !== "string" || entry.rationale.trim().length === 0) {
+      throw new Error(`judge verdict.dispositions[${i}].rationale must be a non-empty string naming the criterion, non-goal, or scope boundary`);
+    }
+    // followUpDraft is REQUIRED on a defer disposition (soft-cap contract: a
+    // deferred finding carries a fileable follow-up draft). Optional otherwise.
+    if (entry.disposition === "defer") {
+      if (!entry.followUpDraft || typeof entry.followUpDraft !== "object" || Array.isArray(entry.followUpDraft)) {
+        throw new Error(`judge verdict.dispositions[${i}].followUpDraft is required on a defer disposition`);
+      }
+      const draft = /** @type {Record<string, unknown>} */ (entry.followUpDraft);
+      if (typeof draft.title !== "string" || draft.title.trim().length === 0 || typeof draft.body !== "string") {
+        throw new Error(`judge verdict.dispositions[${i}].followUpDraft must have a non-empty title and a body string`);
+      }
+    }
+  }
+  return { headSha: v.headSha, scopeDrift: v.scopeDrift, dispositions: v.dispositions };
+}
+
+/**
+ * Merge the judge's relevance-based dispositions into the consolidated findings
+ * array (the flat per-finding shape `consolidateFanin` / `toFindingsLogShape`
+ * produce). The judge runs AFTER fan-in and BEFORE the fix pass (#1525): it
+ * receives the consolidated ledger, the issue's AC/DoD/non-goals, the PR's
+ * declared scope, and prior-round ledgers, and emits a per-finding disposition
+ * (`act` / `defer` / `reject`) plus a scope-drift verdict on the PR as a whole.
+ *
+ * This function enriches each finding with `judgeDisposition`, `judgeRationale`,
+ * and (for `defer`) `followUpDraft` so the disposition ledger and posted findings
+ * comment carry what was consciously not acted on and why. The severity-based
+ * `disposition` (accepted-for-fix/deferred/needs-answer) is LEFT INTACT — the
+ * judge's relevance axis is complementary, not a replacement (a real defect
+ * stays a real defect; the judge decides *where* it is fixed, not *whether* it
+ * is real).
+ *
+ * The fix pass consumes only the `act` list; the fixer retains reproduction-
+ * based rejection (a finding that does not reproduce is dead regardless of the
+ * judge's verdict) but stops deciding relevance.
+ *
+ * Pure. Fails closed (throws) when a disposition references an out-of-range
+ * index — a judge verdict that names a finding that is not in the ledger is a
+ * mismatch, never a silent enrichment.
+ *
+ * @param {Array<object>} findings — the flat consolidated findings array
+ * @param {object} judgeVerdict — the validated judge verdict artifact
+ * @returns {{ findings: Array<object>, scopeDrift: object }}
+ */
+export function applyJudgeDispositions(findings, judgeVerdict) {
+  const validated = validateJudgeVerdict(judgeVerdict);
+  const list = Array.isArray(findings) ? findings : [];
+  const enriched = list.map((f) => ({ ...f }));
+  for (const d of validated.dispositions) {
+    if (d.index >= enriched.length) {
+      throw new Error(`judge disposition index ${d.index} is out of range (findings has ${enriched.length} entries)`);
+    }
+    const target = enriched[d.index];
+    target.judgeDisposition = d.disposition;
+    target.judgeRationale = d.rationale;
+    if (typeof d.criterion === "string" && d.criterion.trim().length > 0) {
+      target.judgeCriterion = d.criterion.trim();
+    }
+    if (d.disposition === "defer" && d.followUpDraft) {
+      target.followUpDraft = d.followUpDraft;
+    }
+  }
+  return { findings: enriched, scopeDrift: validated.scopeDrift };
+}
+
 /**
  * Map consolidated findings into the `--findings` JSON shape consumed by
  * scripts/github/write-gate-findings-log.mjs (severity, angle, summary,
@@ -767,6 +996,21 @@ export function toFindingsLogShape(findings) {
     if (Number.isInteger(f.line) && f.line > 0) {
       entry.line = f.line;
     }
+    // Carry the judge's relevance-based dispositions through (#1525) so the
+    // durable ledger and posted findings comment show what was consciously not
+    // acted on and why.
+    if (typeof f.judgeDisposition === "string" && f.judgeDisposition.trim().length > 0) {
+      entry.judgeDisposition = f.judgeDisposition.trim();
+    }
+    if (typeof f.judgeRationale === "string" && f.judgeRationale.trim().length > 0) {
+      entry.judgeRationale = f.judgeRationale.trim();
+    }
+    if (typeof f.judgeCriterion === "string" && f.judgeCriterion.trim().length > 0) {
+      entry.judgeCriterion = f.judgeCriterion.trim();
+    }
+    if (f.followUpDraft && typeof f.followUpDraft === "object" && !Array.isArray(f.followUpDraft)) {
+      entry.followUpDraft = f.followUpDraft;
+    }
     return entry;
   });
 }

package/src/loop/handoff-envelope.mjs

@@ -130,6 +130,21 @@ register(INTERNAL_DEV_LOOP_STRATEGY.LOCAL_IMPLEMENTATION, "default", {
   activeNoticeAfterMs: DEFAULT_ACTIVE_NOTICE_MS,
 });
 
+// local_implementation · spike run (SPIKE-RELAXED-GATE-PROFILE, #1628): a
+// spike-mode spin resolves the relaxed `spike` gate profile instead of the
+// default local-implementation gate. Kept as its own acceptance key so the
+// generic default can stay approach-agnostic.
+register(INTERNAL_DEV_LOOP_STRATEGY.LOCAL_IMPLEMENTATION, "spike", {
+  criteria: [
+    { id: "spike-recorded", must: "The spike exploration and its recommendation are recorded (spike file + summary).", severity: "required" },
+    { id: "verify-green", must: "`npm run verify` passes with no failures.", severity: "required" },
+  ],
+  evidence: ["commands-run", "validation-output", "changed-files"],
+  maxFinalizationTurns: 6,
+  needsAttentionAfterMs: DEFAULT_NEEDS_ATTENTION_MS,
+  activeNoticeAfterMs: DEFAULT_ACTIVE_NOTICE_MS,
+});
+
 // wait_watch — dedicated window matching external healthy wait budget (policy-constants)
 register(INTERNAL_DEV_LOOP_STRATEGY.WAIT_WATCH, "default", {
   criteria: [
@@ -545,6 +560,11 @@ function resolveSubGate(strategy, gateState) {
   return "default";
 }
 
+/** True when the resolver output identifies a spike-mode run (#1628). */
+function isSpikeRun(resolverOutput) {
+  return Boolean(resolverOutput && resolverOutput.spikeIntakeState);
+}
+
 
 // ---------------------------------------------------------------------------
 // Deep freeze helper
@@ -580,7 +600,14 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
   if (!repo) throw new Error("handoff-envelope: repo slug is required (owner/name)");
 
   const gs = normalizeGateState(gateState);
-  const subGate = resolveSubGate(strategy, gs);
+  // SPIKE-RELAXED-GATE-PROFILE (#1628): a spike-mode spin (startup resolver
+  // result carrying `spikeIntakeState`) resolves the relaxed `spike` gate
+  // profile instead of the default local-implementation gate. The spike
+  // marker lives at the TOP level of the resolver output (the bundle does not
+  // carry it), so it is read off `resolverOutput` directly.
+  const subGate = (strategy === INTERNAL_DEV_LOOP_STRATEGY.LOCAL_IMPLEMENTATION && isSpikeRun(resolverOutput))
+    ? "spike"
+    : resolveSubGate(strategy, gs);
   // Normalize each source independently, then fall back on the normalized result
   // (not the raw value): a present-but-invalid gateState value must NOT shadow a
   // valid options.retrospectiveFindings fallback (issue #1077 review finding).

package/src/loop/issue-refinement-artifact.mjs

@@ -148,20 +148,25 @@ function findSectionByPatterns(sections, patterns) {
 }
 
 /**
- * Extract bullet items from a section body. Counts both `- [ ]`/`- [x]`
- * checklist items and top-level plain `- ` bullets (dash at column 0, so
- * nested/indented sub-bullets are not counted). Empty checkbox placeholders
- * (`- [ ]` / `- [x]` with no trailing text) are skipped, not counted, so a
- * section of only unfilled placeholders reports as unrefined. Returns the
- * trimmed item text for each matching line. The checkbox state (checked vs
- * unchecked) is intentionally not preserved: callers only need the item
- * text to satisfy the refinement-artifact contract.
+ * Parse bullet/checkbox items from a section body into item states. Each
+ * checkbox item (`- [ ]`/`- [x]`/`- [X]`) becomes `{ text, checked }`
+ * (`checked` true only for a ticked `[x]`/`[X]`); a top-level plain bullet
+ * (`- text`, dash at column 0 so nested/indented sub-bullets are not counted)
+ * becomes `{ text, checked: null }` — it has no checkbox to tick. Empty
+ * checkbox placeholders (`- [ ]` / `- [x]` with no trailing text) are skipped,
+ * not counted, so a section of only unfilled placeholders reports as unrefined.
+ * Code-fenced lines are skipped (same fence logic as parseMarkdownSections,
+ * issue #1025) so a body cannot spoof the AC/DoD gate with code-fenced
+ * checkboxes.
  *
- * This is only ever called on the body of an already-recognized AC/DoD
- * section (see `detectIssueRefinementArtifact`), so counting plain bullets
- * is scoped to those sections and never affects prose sections.
+ * Shared by `extractChecklistItems` (text-only) and the unticked-AC check
+ * (`extractUncheckedChecklistItems`) so the two never drift on what counts as
+ * a checklist item or on the checkbox-state read (#1621). Only ever called on
+ * the body of an already-recognized AC/DoD section (see
+ * `detectIssueRefinementArtifact`), so counting plain bullets is scoped to
+ * those sections and never affects prose sections.
  */
-export function extractChecklistItems(sectionBody) {
+function parseChecklistItems(sectionBody) {
   if (typeof sectionBody !== "string" || sectionBody.length === 0) {
     return [];
   }
@@ -171,9 +176,6 @@ export function extractChecklistItems(sectionBody) {
   let fence = null;
 
   for (const line of lines) {
-    // Checkboxes/bullets inside a fenced code span are non-interactive text, not
-    // real items — skip them so a body cannot spoof the AC/DoD gate with
-    // code-fenced checkboxes (issue #1025). Same fence logic as parseMarkdownSections.
     const step = stepFence(fence, line);
     fence = step.fence;
     if (step.insideFence) {
@@ -186,7 +188,10 @@ export function extractChecklistItems(sectionBody) {
     if (checkboxMatch) {
       const text = (checkboxMatch[1] ?? "").trim();
       if (text.length > 0) {
-        items.push(text);
+        // `checked` is true only for a ticked box; `[ ]` (space) is false.
+        // A plain bullet has no checkbox, so it stays `null` below — it is
+        // neither ticked nor unticked and does not count as an unticked AC.
+        items.push({ text, checked: /^\s*-\s+\[[xX]\]/u.test(line) });
       }
       continue;
     }
@@ -196,7 +201,7 @@ export function extractChecklistItems(sectionBody) {
     if (bulletMatch) {
       const text = bulletMatch[1].trim();
       if (text.length > 0) {
-        items.push(text);
+        items.push({ text, checked: null });
       }
     }
   }
@@ -204,12 +209,39 @@ export function extractChecklistItems(sectionBody) {
   return items;
 }
 
+/**
+ * Extract bullet items from a section body. Counts both `- [ ]`/`- [x]`
+ * checklist items and top-level plain `- ` bullets. Empty checkbox placeholders
+ * are skipped. Returns the trimmed item text for each matching line; the
+ * checkbox state is not preserved (use `extractUncheckedChecklistItems` for
+ * that). Thin wrapper over `parseChecklistItems` so the text-only contract
+ * stays byte-identical to its pre-#1621 shape.
+ */
+export function extractChecklistItems(sectionBody) {
+  return parseChecklistItems(sectionBody).map((item) => item.text);
+}
+
+/**
+ * Extract the text of UNCHECKED checkbox items (`- [ ]`) from a section body.
+ * A ticked box (`- [x]`/`- [X]`) and a plain bullet (no checkbox) are both
+ * excluded — only an actual unticked checkbox is an "unticked AC item"
+ * (#1621, ACCEPT-CRITERIA-VERIFY-AND-REFLECT). Empty placeholders are skipped.
+ * Thin wrapper over `parseChecklistItems` so the unticked read never drifts
+ * from `extractChecklistItems` on what counts as a checklist item.
+ */
+export function extractUncheckedChecklistItems(sectionBody) {
+  return parseChecklistItems(sectionBody)
+    .filter((item) => item.checked === false)
+    .map((item) => item.text);
+}
+
 /**
  * Detect a linked refinement doc path from the issue body.
  * Looks for explicit `tmp/refinement/<n>-plan.md` style paths and the
  * `## Refinement` / `## Plan` / `## Refinement doc` sections.
  */
 export function detectLinkedRefinementDoc(body) {
+
   if (typeof body !== "string" || body.length === 0) {
     return { found: false, path: null, reason: "empty-body" };
   }
@@ -246,6 +278,7 @@ export function detectLinkedRefinementDoc(body) {
  *   hasACs: boolean,
  *   source: string,
  *   acItems: string[],
+ *   uncheckedAcItems: string[],
  *   dodItems: string[],
  *   sections: string[],
  *   linkedDoc: { found: boolean, path: string|null, reason: string },
@@ -259,6 +292,7 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null }
       hasACs: false,
       source: REFINEMENT_SOURCE.MISSING,
       acItems: [],
+      uncheckedAcItems: [],
       dodItems: [],
       sections: [],
       linkedDoc: { found: false, path: null, reason: "empty-body" },
@@ -274,6 +308,11 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null }
   const dodSection = findSectionByPatterns(sections, DOD_SECTION_PATTERNS);
 
   const acItems = acceptanceSection ? extractChecklistItems(acceptanceSection.bodyLines.join("\n")) : [];
+  // Unticked AC checkboxes (`- [ ]`) of the spec-of-record — the
+  // ACCEPT-CRITERIA-VERIFY-AND-REFLECT precondition a clean pre_approval_gate
+  // must refuse on (#1621). Only actual unticked checkboxes count; a ticked
+  // box and a plain bullet (no checkbox) are both excluded.
+  const uncheckedAcItems = acceptanceSection ? extractUncheckedChecklistItems(acceptanceSection.bodyLines.join("\n")) : [];
   const dodItems = dodSection ? extractChecklistItems(dodSection.bodyLines.join("\n")) : [];
 
   const linkedDoc = detectLinkedRefinementDoc(body);
@@ -283,6 +322,7 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null }
       hasACs: true,
       source: REFINEMENT_SOURCE.ISSUE_BODY_AC,
       acItems,
+      uncheckedAcItems,
       dodItems,
       sections: sectionNames,
       linkedDoc,
@@ -296,6 +336,7 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null }
       hasACs: true,
       source: REFINEMENT_SOURCE.ISSUE_BODY_DOD,
       acItems,
+      uncheckedAcItems,
       dodItems,
       sections: sectionNames,
       linkedDoc,
@@ -309,6 +350,7 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null }
       hasACs: true,
       source: REFINEMENT_SOURCE.LINKED_DOC,
       acItems: [],
+      uncheckedAcItems: [],
       dodItems: [],
       sections: sectionNames,
       linkedDoc,
@@ -321,6 +363,7 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null }
     hasACs: false,
     source: REFINEMENT_SOURCE.MISSING,
     acItems: [],
+    uncheckedAcItems: [],
     dodItems: [],
     sections: sectionNames,
     linkedDoc,
@@ -444,6 +487,59 @@ function sectionHasBody(section) {
  * @param {{ body?: string, expectedIssue?: number, issueLess?: boolean }} input
  * @returns {{ checker: "validate-pr-body-spec", ok: boolean, errors: { code: string, message: string }[], sections: string[], acItems: string[], dodItems: string[], closesIssues: number[] }}
  */
+
+// ---------------------------------------------------------------------------
+// Grill sub-loop body predicates (GRILL-SUBLOOP-*, #1628)
+// ---------------------------------------------------------------------------
+// The loop-grill skill writes its raw Q&A transcript and synthesis to an
+// ephemeral tmp artifact and keeps only the canonical synthesized sections
+// (Acceptance criteria / Definition of done / Non-goals) plus the sanctioned
+// `<!-- loop-grill: ... -->` marker in the durable issue/PR body. The body
+// MUST NOT embed the raw grill transcript/synthesis/Q&A headings
+// (GRILL-SUBLOOP-NO-EMBED-SYNTHESIS). These pure predicates are the only
+// mechanically-enforceable part of that contract; the judgment-bound clauses
+// ("resolve every gap the grill decided", "stale contradicting prose") stay
+// agent-level.
+
+export const GRILL_MARKER_PATTERN = /<!--\s*loop-grill:\s*.*?-->/iu;
+
+/** Case-insensitive **section heading names** that embed grill material. */
+export const GRILL_EMBED_HEADING_PATTERNS = Object.freeze([
+  /^grill\s+findings$/iu,
+  /^grill\s+transcript$/iu,
+  /^grill\s+synthesis$/iu,
+  /^grill\s+q&a$/iu,
+  /^grill\s+qa$/iu,
+]);
+
+/**
+ * Detect the sanctioned `<!-- loop-grill: ... -->` marker. Pure predicate.
+ * @param {string} [body]
+ * @returns {boolean} true when the marker is present.
+ */
+export function detectGrillMarker(body = "") {
+  return typeof body === "string" && GRILL_MARKER_PATTERN.test(body);
+}
+
+/**
+ * Detect a grill transcript/synthesis/Q&A embed heading in the body. Pure
+ * predicate; returns the first offending heading name at any markdown level
+ * (# through ######) or null.
+ * @param {string} [body]
+ * @returns {string|null} the offending heading name, or null when none.
+ */
+export function detectGrillEmbedHeading(body = "") {
+  if (typeof body !== "string" || body.length === 0) return null;
+  for (const section of parseMarkdownSections(body)) {
+    for (const pattern of GRILL_EMBED_HEADING_PATTERNS) {
+      if (pattern.test(String(section.name))) {
+        return String(section.name);
+      }
+    }
+  }
+  return null;
+}
+
 export function validatePrBodySpec({ body = "", expectedIssue = null, issueLess = false } = {}) {
   if (issueLess && Number.isInteger(expectedIssue)) {
     // Fail closed at the library boundary too (not just the CLI): the two modes
@@ -537,10 +633,50 @@ export function decideEnqueueRefinementGate({ artifact, targetIsPickup, auto = f
   const reason =
     `Issue has no refinement artifact (none of: ${missing.join(", ")}). ` +
     "Add at least ONE of them — an Acceptance criteria section, a Definition of done section, or a linked refinement doc " +
-    "(e.g. run `/loop-grill <issue> --auto`, or the refiner) — before it enters the pickup queue.";
+    "(e.g. run `/dev-loops:loop-grill <issue> --auto` (or `/loop-grill <issue> --auto` in the dev-loops repo itself), or the refiner) — before it enters the pickup queue.";
   return { action: auto ? "divert" : "block", reason, missing };
 }
 
+/**
+ * Apply the pickup-column refinement gate to one issue: fetch the issue body,
+ * run `decideEnqueueRefinementGate`, and throw the canonical `GH_API_ERROR` /
+ * `MISSING_REFINEMENT_ARTIFACT` on failure. This is the single
+ * gate-application orchestration shared by `queue add` (enqueue-time) and
+ * `queue move` (move-time) — never a second copy. It returns the gate decision
+ * so add-only (divert/park) and move-only (refined-flag) handling stays with
+ * each caller.
+ *
+ * @param {{ issueNumber: number, repo: string, env: object, runChild: Function, auto?: boolean }} input
+ * @returns {Promise<{ action: "enqueue" } | { action: "divert"|"block", reason: string, missing: string[] }>}
+ */
+export async function runPickupRefinementGate({ issueNumber, repo, env, runChild, auto = false }) {
+  const bodyResult = await runChild(
+    "gh",
+    ["issue", "view", String(issueNumber), "--repo", repo, "--json", "body"],
+    env,
+  );
+  if (bodyResult.code !== 0) {
+    const detail = bodyResult.stderr?.trim() || `exit code ${bodyResult.code}`;
+    throw Object.assign(new Error(`gh issue view failed: ${detail}`), { code: "GH_API_ERROR" });
+  }
+  let bodyPayload;
+  try {
+    bodyPayload = JSON.parse(bodyResult.stdout);
+  } catch {
+    throw new Error("Invalid JSON input");
+  }
+  const body = typeof bodyPayload?.body === "string" ? bodyPayload.body : "";
+  const artifact = detectIssueRefinementArtifact({ body, issueNumber });
+  const decision = decideEnqueueRefinementGate({ artifact, targetIsPickup: true, auto });
+  if (decision.action === "block") {
+    throw Object.assign(new Error(decision.reason), {
+      code: "MISSING_REFINEMENT_ARTIFACT",
+      missing: decision.missing,
+    });
+  }
+  return decision;
+}
+
 /**
  * Map a draft-gate refinement check to the result surface consumed by
  * `evaluatePrGateCoordination`. The mapping keeps the contract

package/src/loop/main-checkout-ff.mjs

@@ -24,6 +24,7 @@
  * No imports so this file vendors into the `.claude/hooks/` bundle unchanged
  * (vendored modules may only import `node:` builtins or relative paths).
  */
+import path from "node:path";
 
 /**
  * Timeout (ms) for the `git worktree list` resolution step (the fetch-half budget;
@@ -56,3 +57,41 @@ export function buildMainCheckoutFastForwardCommand(mainCheckout) {
   // wrong branch. No state change, no git switch.
   return `git -C ${quoted} fetch origin main && [ "$(git -C ${quoted} rev-parse --abbrev-ref HEAD)" = main ] && git -C ${quoted} merge --ff-only origin/main`;
 }
+
+/**
+ * Worktree-cleanup timeout (ms) for the post-merge `git worktree remove` half.
+ */
+export const WORKTREE_CLEANUP_TIMEOUT_MS = 60_000;
+
+/**
+ * Build the best-effort post-merge worktree-removal command string (#1627).
+ *
+ * The dev-loop mandates removing the branch's worktree after merge, but neither
+ * the merge procedure nor the post-merge hooks performed it. This builds the
+ * shell command that runs the shared `cleanup-worktree.mjs` script FROM the main
+ * checkout (the hook's cwd can be inside the worktree being removed, which makes
+ * `git worktree remove` fail), and stays non-fatal: the script itself is fail-soft
+ * (refuses any path outside tmp/worktrees/dev-loops/, exits 0 on git errors), and
+ * the surrounding guard makes a consumer checkout without the script a silent no-op.
+ * `prNumber` is shell-escaped as a double-quoted argument; `mainCheckout` and the
+ * script path are POSIX single-quoted. Returns an empty string when no PR number
+ * (or no meaningful target) is available, so callers can skip cleanly.
+ *
+ * @param {string} mainCheckout - Absolute path to the main (primary) git checkout.
+ * @param {string | number | undefined} prNumber - Merged PR number (drives `--pr`).
+ * @returns {string} the cleanup command, or "" when `prNumber` is absent.
+ */
+export function buildWorktreeCleanupCommand(mainCheckout, prNumber) {
+  const pr = String(prNumber ?? "").trim();
+  // Validate the PR number is a positive integer BEFORE embedding it into the
+  // shell string; a caller passing a non-numeric string (could carry command
+  // substitution) is refused by returning "" — defense-in-depth in a public helper.
+  if (!/^[0-9]+$/u.test(pr)) {
+    return "";
+  }
+  const quotedMain = shellQuotePath(mainCheckout);
+  const script = shellQuotePath(path.join(mainCheckout, "scripts", "loop", "cleanup-worktree.mjs"));
+  // Guard the script's existence (consumer no-op) and keep the whole thing
+  // non-fatal with `|| true` — removal must never break a merge-completion flow.
+  return `if [ -f ${script} ]; then node ${script} --repo-root ${quotedMain} --pr "${pr}"; fi || true`;
+}