@dev-loops/core 0.7.1 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -38,8 +38,10 @@
     "./loop/plan-file-promote-contract": "./src/loop/plan-file-promote-contract.mjs",
     "./loop/plan-file-refine-contract": "./src/loop/plan-file-refine-contract.mjs",
     "./loop/pr-gate-coordination": "./src/loop/pr-gate-coordination.mjs",
+    "./loop/pr-lifecycle": "./src/loop/pr-lifecycle.mjs",
     "./loop/pr-title-markers": "./src/loop/pr-title-markers.mjs",
     "./loop/public-dev-loop-routing": "./src/loop/public-dev-loop-routing.mjs",
+    "./loop/refinement-grill-state": "./src/loop/refinement-grill-state.mjs",
     "./loop/queue-board-ordering": "./src/loop/queue-board-ordering.mjs",
     "./loop/queue-board-sync": "./src/loop/queue-board-sync.mjs",
     "./loop/queue-driver": "./src/loop/queue-driver.mjs",
@@ -55,6 +57,9 @@
     "./loop/timeout-policy": "./src/loop/timeout-policy.mjs",
     "./loop/tracker-pr-state": "./src/loop/tracker-pr-state.mjs",
     "./loop/ui-e2e-scoping": "./src/loop/ui-e2e-scoping.mjs",
+    "./projects/list-queue-items": "./src/projects/list-queue-items.mjs",
+    "./projects/move-queue-item": "./src/projects/move-queue-item.mjs",
+    "./projects/resolve-project": "./src/projects/resolve-project.mjs",
     "./harness": "./src/harness/index.mjs",
     "./loop/worktree-guard": "./src/loop/worktree-guard.mjs",
     "./loop/tracker-first-loop-state": "./src/loop/tracker-first-loop-state.mjs"

package/src/claude/hook-decisions.mjs

@@ -61,7 +61,7 @@ export const DEV_LOOP_AGENT_TYPE = "dev-loop";
  *     clean current-head draft_gate + pre_approval_gate). The loop runs this check before merging;
  *     gating it here closes the hole where a hand-run `gh pr merge` skips the pre-approval gate
  *     entirely. Everything else passes through.
- *   - raw `gh issue create` / `gh issue comment` / `gh pr comment` — blocked ONLY when the call
+ *   - raw `gh issue create` / `gh issue comment` / `gh issue edit` / `gh pr comment` — blocked ONLY when the call
  *     originates from a SUBAGENT context (`agentType` is a non-null string) and targets the repo.
  *     Sanctioned external writes flow through node wrappers (gate-verdict comments via
  *     `upsert-checkpoint-verdict.mjs`, review replies via `reply-resolve*.mjs`, board sync,
@@ -85,7 +85,7 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
     return ALLOW;
   }
   // Subagent-scoped external-write guard: block ad-hoc `gh issue create`/`gh issue comment`/
-  // `gh pr comment` on the target repo from a subagent, so external writes flow through the
+  // `gh issue edit`/`gh pr comment` on the target repo from a subagent, so external writes flow through the
   // sanctioned node wrappers. The main-agent/operator path (agentType null) is unaffected (#1051).
   if (typeof agentType === "string" && commandContainsRawExternalWrite(command)) {
     const cwdTargets = (repoSlug ?? "").toLowerCase() === TARGET_REPO_SLUG.toLowerCase();
@@ -101,9 +101,10 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
       return {
         decision: "deny",
         reason:
-          "Ad-hoc GitHub issue/PR creation and comments from a subagent are blocked. Use the sanctioned " +
+          "Ad-hoc GitHub issue/PR creation, comments, and edits from a subagent are blocked. Use the sanctioned " +
           "node wrappers instead — gate-verdict comments via scripts/github/upsert-checkpoint-verdict.mjs, " +
-          "review-thread replies via scripts/github/reply-resolve*.mjs, board sync, or scripts/github/comment-issue.mjs. " +
+          "review-thread replies via scripts/github/reply-resolve*.mjs, board sync, issue comments via " +
+          "scripts/github/comment-issue.mjs, or issue-body edits via scripts/github/edit-issue.mjs. " +
           "Direct `gh issue create` is reserved for the main agent / operator.",
       };
     }

package/src/config/config.mjs

@@ -98,6 +98,12 @@ const GatesConfig = z.strictObject({
   // and every angle configured across this config's own draft/preApproval/
   // spike gates (angles + mandatoryAngles).
   anglePool: z.array(z.string().trim().min(1)).optional(),
+  // Fail-closed enforcement that a fanout_fanin gate's recorded per-angle
+  // provenance names only angles in the gate's configured pool (angles +
+  // mandatoryAngles) — ad-hoc/foreign angle labels are rejected rather than
+  // silently accepted. Default true (reject); set false to warn instead of
+  // fail. See resolveRejectForeignAngles / docs/gate-review-sub-loop-contract.md.
+  rejectForeignAngles: z.boolean().default(true),
 });
 
 const AutonomyConfig = z.strictObject({
@@ -143,6 +149,10 @@ const LocalImplementationConfig = z.strictObject({
     enabled: z.boolean(),
     maxFiles: z.number().int().min(1),
     maxLines: z.number().int().min(1),
+    // Copilot review round cap for light-dispatched PRs (#1210). Composes with
+    // (does not replace) refinement.maxCopilotRounds — see
+    // resolveEffectiveCopilotRoundCap.
+    maxCopilotRounds: z.number().int().nonnegative().default(1),
   }).optional(),
 });
 
@@ -193,6 +203,7 @@ const FileGatesConfig = z.strictObject({
   maxFanoutReviewers: z.number().int().min(1).max(64).optional(),
   postFindingsComments: z.boolean().optional(),
   anglePool: z.array(z.string().trim().min(1)).optional(),
+  rejectForeignAngles: z.boolean().optional(),
 });
 
 // Partial persona entries for file-level config (allows omitting fields)
@@ -252,7 +263,7 @@ export const BUILT_IN_DEFAULTS = Object.freeze({
     devModeDefault: false,
   }),
   localImplementation: Object.freeze({
-    lightMode: Object.freeze({ enabled: false, maxFiles: 3, maxLines: 200 }),
+    lightMode: Object.freeze({ enabled: false, maxFiles: 3, maxLines: 200, maxCopilotRounds: 1 }),
   }),
   queue: Object.freeze({
     maxParallel: 3,
@@ -1021,6 +1032,17 @@ export function resolveRequireFanoutProvenance(config) {
   return config?.gates?.requireFanoutProvenance === true;
 }
 
+/**
+ * Resolve whether a fan-out provenance entry naming an angle outside the
+ * gate's configured pool should FAIL (default) or only WARN.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {boolean}
+ */
+export function resolveRejectForeignAngles(config) {
+  return config?.gates?.rejectForeignAngles !== false;
+}
+
 /**
  * Resolve whether the consolidated gate fan-out findings should be posted as a
  * visible, marker-tagged PR comment.
@@ -1061,6 +1083,33 @@ export function resolveLightMode(config) {
   };
 }
 
+/**
+ * Resolve the effective Copilot review round cap for a PR (#1210).
+ *
+ * Full PRs (lightweight=false) use `refinement.maxCopilotRounds` unchanged
+ * (default 5). Light-dispatched PRs compose with it rather than replacing it:
+ * `effective = min(localImplementation.lightMode.maxCopilotRounds ?? 1,
+ * refinement.maxCopilotRounds)` — so setting `refinement.maxCopilotRounds: 0`
+ * disables Copilot rounds everywhere, including lightweight, with that one
+ * setting.
+ *
+ * @param {DevLoopConfig} config
+ * @param {{ lightweight?: boolean }} [options]
+ * @returns {number}
+ */
+export function resolveEffectiveCopilotRoundCap(config, { lightweight = false } = {}) {
+  // Clamp here, not only in the zod schema: programmatically-built config
+  // objects bypass schema defaulting/validation, and a negative cap must never
+  // reach round-cap comparisons.
+  const maxCopilotRounds = Math.max(0, /** @type {number} */ (resolveRefinementConfig(config, "maxCopilotRounds")));
+  if (!lightweight) return maxCopilotRounds;
+  const lightMaxRounds = config?.localImplementation?.lightMode?.maxCopilotRounds;
+  const effectiveLightCap = typeof lightMaxRounds === "number" && Number.isFinite(lightMaxRounds)
+    ? Math.max(0, lightMaxRounds)
+    : 1;
+  return Math.min(effectiveLightCap, maxCopilotRounds);
+}
+
 /** Label that forces full fan-out regardless of change size. */
 export const GATE_FULL_LABEL = "gate:full";
 
@@ -1161,6 +1210,36 @@ export function resolveAnglePool(config) {
   return [...new Set([...Object.keys(BUILTIN_PERSONAS), ...configured])];
 }
 
+/**
+ * Resolve a gate's ANGLE ENFORCEMENT CONTRACT: the mandatory angles a
+ * fanout_fanin verdict must cover and the pool its recorded angles must stay
+ * within. Single source of truth for all angle-coverage enforcement consumers
+ * (ledger write, verdict-comment write, merge-evidence read) so they agree.
+ *
+ * - `mandatoryAngles` is filtered through `excludeAngles`: a config that
+ *   excludes a mandatory angle must not deadlock every fanout write (the
+ *   angle would be missing-mandatory if omitted yet foreign if recorded).
+ * - `pool` is `resolveGateAngles` (configured angles ∪ mandatoryAngles, minus
+ *   excludeAngles); when `additiveAngles` is enabled it widens to the global
+ *   lens catalog (`resolveAnglePool`) too — dynamic resolution may
+ *   legitimately dispatch catalog angles then — with `excludeAngles` still a
+ *   hard ceiling. A null pool skips the foreign-angle check entirely.
+ *
+ * @param {DevLoopConfig} config
+ * @param {"draft"|"preApproval"|"spike"} gate
+ * @returns {{ mandatoryAngles: string[], pool: string[]|null }}
+ */
+export function resolveGateAngleContract(config, gate) {
+  const gateConfig = resolveGateConfig(config, gate);
+  const excluded = new Set(gateConfig.excludeAngles);
+  const mandatoryAngles = gateConfig.mandatoryAngles.filter((a) => !excluded.has(a));
+  let pool = resolveGateAngles(config, gate);
+  if (gateConfig.additiveAngles && pool !== null) {
+    pool = [...new Set([...pool, ...resolveAnglePool(config)])].filter((a) => !excluded.has(a));
+  }
+  return { mandatoryAngles, pool };
+}
+
 /**
  * Resolve gate angles dynamically when `dynamicAngles` is enabled in config.
  *

package/src/config/extension-defaults.yaml

@@ -44,6 +44,9 @@ gates:
       - renderer-security
       - determinism
       - pr-comments
+      - contradiction-lens
+      - code-conformance
+      - semantic-drift
     excludeAngles: []
     required: true
     requireCi: true
@@ -66,6 +69,9 @@ gates:
       - dip
       - docs
       - pr-checklist-matrix
+      - contradiction-lens
+      - correctness-final
+      - ui-validation
     excludeAngles: []
     required: true
     mandatoryAngles:

package/src/github/copilot-helpers.mjs

@@ -15,6 +15,149 @@ export function isCopilotLogin(login) {
   return typeof login === "string" && /^copilot(?:[^a-z]|$)/i.test(login);
 }
 
+// Anti-summon literal: bare-text `@copilot` or a `/copilot*` slash command. Both
+// the write-side sanitizer and the read-side guard scan key off this shape so a
+// gate-evidence comment can quote the rule (inside a code span/fenced block)
+// without arming the request-copilot-review.mjs anti-summon guard. The token
+// regex carries the same left word-boundary as the guard regex so the sanitizer
+// never mangles text the guard would not arm on (e.g. user@copilot.example).
+const COPILOT_SUMMON_TOKEN_RE = /(?<=^|\W)(@copilot|\/copilot[a-z0-9_-]*)/gi;
+const COPILOT_SUMMON_WORD_BOUNDARY_RE = /(?:^|\W)(@copilot|\/copilot)(?:$|\W)/i;
+// GFM inline code span: an N-backtick run, lazy content, closed by a same-length
+// run. Covers single-backtick spans as well as double-backtick spans wrapping a
+// literal backtick.
+const INLINE_CODE_SPAN_RE = /(`+)[\s\S]*?\1(?!`)/g;
+const ZERO_WIDTH_JOINER = "\u200D";
+
+// Apply `transformLine` to every markdown line OUTSIDE a fenced code block
+// (```/~~~), leaving fence-delimiter lines and fenced content untouched.
+// Mirrors the fenced-block tracking scripts/docs/validate-rule-ownership.mjs
+// uses for its own lexical scan.
+function transformNonFencedLines(text, transformLine) {
+  const lines = String(text).split(/\r?\n/);
+  let inFencedBlock = false;
+  let fencedDelimiter = "";
+  const transformed = lines.map((line) => {
+    const rawTrimmed = line.trim();
+    const fenceMatch = rawTrimmed.match(/^(```|~~~)/);
+    if (fenceMatch) {
+      if (!inFencedBlock) {
+        inFencedBlock = true;
+        fencedDelimiter = fenceMatch[1];
+        return line;
+      }
+      if (rawTrimmed.startsWith(fencedDelimiter)) {
+        inFencedBlock = false;
+        fencedDelimiter = "";
+        return line;
+      }
+    }
+    if (inFencedBlock) {
+      return line;
+    }
+    return transformLine(line);
+  });
+  return transformed.join("\n");
+}
+
+// Apply `replaceSegment` to every part of a line that lies OUTSIDE an inline
+// code span (any N-backtick GFM span), leaving span content untouched.
+function transformOutsideSpans(line, replaceSegment) {
+  let result = "";
+  let last = 0;
+  for (const span of line.matchAll(INLINE_CODE_SPAN_RE)) {
+    result += replaceSegment(line.slice(last, span.index));
+    result += span[0];
+    last = span.index + span[0].length;
+  }
+  return result + replaceSegment(line.slice(last));
+}
+
+// Wrap bare `@copilot`/`/copilot*` tokens in backticks so a comment can quote the
+// anti-summon rule without arming it. Tokens already inside an inline code span
+// are left untouched.
+function wrapBareSummonTokensInLine(line) {
+  return transformOutsideSpans(line, (segment) => segment.replace(COPILOT_SUMMON_TOKEN_RE, "`$1`"));
+}
+
+// Does this single (non-fenced) line still arm the guard scan after inline code
+// spans are dropped? Mirrors stripMarkdownCodeForScan's per-line step. Spans are
+// replaced with a SPACE, not the empty string: the fragments flanking a span
+// must never be rejoined into a token that was not present ("@copi`x`lot" is not
+// a summon), while a token directly abutting a span ("text`x`@copilot", which
+// GitHub renders as a real mention) still arms.
+function lineArmsSummonGuard(line) {
+  return COPILOT_SUMMON_WORD_BOUNDARY_RE.test(line.replace(INLINE_CODE_SPAN_RE, " "));
+}
+
+const ZWJ_FALLBACK_RE = /(?<=^|\W)([@/])(copilot)/gi;
+
+// Sanitize one line, verifying against the guard scan. Backtick-wrapping is the
+// primary neutralization (visible, greppable), but pre-existing backticks on the
+// line can destabilize it two ways: an UNBALANCED stray backtick pairs with an
+// inserted one and re-exposes the token to the guard's span-stripping, and
+// adjacent spans (e.g. a span ending right before the token's new wrap) can make
+// the wrapped line re-tokenize differently on the next pass, re-wrapping the
+// token and growing the comment by one backtick per rewrite. The wrapped result
+// is therefore accepted only when it is BOTH guard-inert AND a fixed point of
+// the wrapper (re-wrapping it changes nothing); otherwise fall back to inserting
+// a zero-width joiner into the residual tokens still outside the wrapped line's
+// spans — invisible, guard-inert, and idempotent (the joined token no longer
+// matches the summon shape). Working on the wrapped line (not the original)
+// preserves every stable backtick wrap and keeps the joiner out of legitimate
+// pre-existing code spans.
+function sanitizeSummonLine(line) {
+  const wrapped = wrapBareSummonTokensInLine(line);
+  if (!lineArmsSummonGuard(wrapped) && wrapBareSummonTokensInLine(wrapped) === wrapped) {
+    return wrapped;
+  }
+  return transformOutsideSpans(wrapped, (segment) => segment.replace(ZWJ_FALLBACK_RE, `$1${ZERO_WIDTH_JOINER}$2`));
+}
+
+export function sanitizeCopilotSummonTokens(text) {
+  return transformNonFencedLines(String(text), sanitizeSummonLine);
+}
+
+// Drop all markdown code content (fenced blocks entirely, inline code spans
+// per line) from `text`, leaving only the bare-text markdown to scan. Unlike
+// transformNonFencedLines (which leaves fenced lines verbatim — correct for
+// sanitizing, where code content must not be rewritten), fenced content here
+// must be REMOVED rather than kept: leaving it in place would let bare text
+// inside a fence still match the anti-summon scan.
+function stripMarkdownCodeForScan(text) {
+  const lines = String(text).split(/\r?\n/);
+  let inFencedBlock = false;
+  let fencedDelimiter = "";
+  const kept = [];
+  for (const line of lines) {
+    const rawTrimmed = line.trim();
+    const fenceMatch = rawTrimmed.match(/^(```|~~~)/);
+    if (fenceMatch) {
+      if (!inFencedBlock) {
+        inFencedBlock = true;
+        fencedDelimiter = fenceMatch[1];
+      } else if (rawTrimmed.startsWith(fencedDelimiter)) {
+        inFencedBlock = false;
+        fencedDelimiter = "";
+      }
+      continue;
+    }
+    if (inFencedBlock) {
+      continue;
+    }
+    // Space (not empty-string) replacement: see lineArmsSummonGuard.
+    kept.push(line.replace(INLINE_CODE_SPAN_RE, " "));
+  }
+  return kept.join("\n");
+}
+
+// The request-copilot-review.mjs anti-summon guard scan: true when `text`
+// contains a bare-text (not code-spanned/fenced) `@copilot` or `/copilot`
+// occurrence. Quoting the rule inside backticks or a fenced block is exempt.
+export function containsBareCopilotSummon(text) {
+  return COPILOT_SUMMON_WORD_BOUNDARY_RE.test(stripMarkdownCodeForScan(text));
+}
+
 export function normalizeTimestamp(value) {
   if (typeof value !== "string" || value.trim().length === 0) {
     return null;

package/src/loop/bash-command-classify.mjs

@@ -234,18 +234,19 @@ function extractRepoFlagsFromGhSubcmdVerbSegments(command, subcmd, verb) {
 
 /**
  * The raw external-write verb forms that must be blocked when originating from a subagent:
- * ad-hoc GitHub issue/PR creation and comments run directly via `gh` (not the sanctioned node
- * wrappers). Each entry is `[subcmd, verb]`.
+ * ad-hoc GitHub issue/PR creation, comments, and edits run directly via `gh` (not the sanctioned
+ * node wrappers). Each entry is `[subcmd, verb]`.
  */
 const EXTERNAL_WRITE_VERB_FORMS = Object.freeze([
   ["issue", "create"],
   ["issue", "comment"],
+  ["issue", "edit"],
   ["pr", "comment"],
 ]);
 
 /**
- * Whether `command` contains a raw `gh issue create`, `gh issue comment`, or `gh pr comment`
- * invocation in ANY shell segment (ignoring --help/-h). PreToolUse gate use only — the gate
+ * Whether `command` contains a raw `gh issue create`, `gh issue comment`, `gh issue edit`, or
+ * `gh pr comment` invocation in ANY shell segment (ignoring --help/-h). PreToolUse gate use only — the gate
  * blocks these when they originate from a subagent context. Node-wrapper commands
  * (`node scripts/github/comment-issue.mjs …`) never match (first token is `node`, not `gh`).
  * @param {string} command @returns {boolean}
@@ -255,8 +256,8 @@ export function commandContainsRawExternalWrite(command) {
 }
 
 /**
- * Return `{ segment, explicitRepo }` for every raw external-write segment across all three verb
- * forms (`gh issue create` / `gh issue comment` / `gh pr comment`). PreToolUse gate use only —
+ * Return `{ segment, explicitRepo }` for every raw external-write segment across all four verb
+ * forms (`gh issue create` / `gh issue comment` / `gh issue edit` / `gh pr comment`). PreToolUse gate use only —
  * lets the gate decide in-scope-ness per segment so a leading out-of-scope write can't shield a
  * later in-scope one. `explicitRepo` is the segment's `--repo`/`-R` value or null.
  * @param {string} command @returns {{ segment: string, explicitRepo: string|null }[]}

package/src/loop/gate-fanin.mjs

@@ -116,6 +116,51 @@ export function provenanceConsistencyError(prov) {
   return null;
 }
 
+/**
+ * Base angle name for a delta-suffixed re-review entry (`<angle>-delta-at-...`,
+ * e.g. `pr-checklist-matrix-delta-at-current-head`): a re-review scoped to only
+ * the current head's delta still counts toward its base angle for both
+ * mandatory-angle coverage and pool-membership checks.
+ *
+ * @param {string} angle
+ * @returns {string}
+ */
+function baseAngleName(angle) {
+  return angle.replace(/-delta-at-.+$/, "");
+}
+
+/**
+ * Validate a recorded fan-out angle list against a gate's configured angle
+ * contract: every mandatory angle must be represented, and — when a pool is
+ * supplied — every recorded angle must be a member of it (delta-suffixed
+ * angles count toward their {@link baseAngleName}). Pure; shared by the write
+ * path (write-gate-findings-log's `provenance.perAngle`, upsert-checkpoint-verdict's
+ * `--findings-json` per-angle results) and the merge-evidence read path
+ * (detect-checkpoint-evidence re-validating the ledger's `provenance.perAngle`)
+ * so all three enforce identically.
+ *
+ * @param {unknown} recordedAngles — array of `{ angle: string, ... }` entries (provenance.perAngle or normalized per-angle findings)
+ * @param {object} [gateAngleContract]
+ * @param {string[]} [gateAngleContract.mandatoryAngles] — angles that must always be represented
+ * @param {string[]|null} [gateAngleContract.pool] — configured angle pool; null/omitted skips the foreign-angle check
+ * @returns {{ missingMandatory: string[], foreignAngles: string[] }}
+ */
+export function checkFanoutAngleCoverage(recordedAngles, { mandatoryAngles = [], pool = null } = {}) {
+  const recorded = Array.isArray(recordedAngles)
+    ? recordedAngles
+      .map((e) => (e && typeof e === "object" && typeof e.angle === "string" ? e.angle.trim() : ""))
+      .filter((a) => a.length > 0)
+    : [];
+  const recordedBases = new Set(recorded.map(baseAngleName));
+  const missingMandatory = mandatoryAngles.filter((a) => !recordedBases.has(a));
+  let foreignAngles = [];
+  if (Array.isArray(pool) && pool.length > 0) {
+    const poolSet = new Set(pool);
+    foreignAngles = [...new Set(recorded.filter((a) => !poolSet.has(baseAngleName(a))))];
+  }
+  return { missingMandatory, foreignAngles };
+}
+
 /**
  * Default cap on parallel fan-out reviewers when a caller does not supply one.
  * Mirrors the config default (gates.maxFanoutReviewers).

package/src/loop/handoff-envelope.mjs

@@ -280,6 +280,9 @@ function deriveRequiredReads(bundle, resolverOutput) {
  * (scripts/github/resolve-tracker-local-spec.mjs), which the envelope does not
  * model (deriveSpecSource coerces it to null).
  */
+// Distinct from refinementArtifact.specSource (linked_issue|pr_body|plan_file,
+// REFINEMENT_ARTIFACT_SPEC_SOURCE in packages/core/src/loop/pr-gate-coordination.mjs):
+// same field name, different object, different value space — intentionally separate enums.
 export const CANONICAL_SPEC_SOURCE = Object.freeze({
   PHASE_DOC: "phase_doc",
   PR_BODY: "pr_body",

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

@@ -378,6 +378,8 @@ function extractClosingIssueNumbers(body) {
   // backtick-run-delimited span (equal-length runs pair, so ``a `b` c`` works).
   // ponytail: not full CommonMark span matching; an unbalanced stray backtick
   // over-strips toward fail-closed, which is the safe direction for this gate.
+  // Revisit with a real CommonMark span parser only if valid closing refs in
+  // backtick-heavy bodies start being over-stripped into false negatives.
   const text = unfenced.join("\n").replace(/(`+)[\s\S]*?\1/gu, " ");
   const seen = new Set();
   const numbers = [];
@@ -411,18 +413,34 @@ function sectionHasBody(section) {
  * Validate that a PR body carries every invariant required to serve as the
  * lightweight spec-of-record: Objective/why, in-scope, explicit non-goals,
  * testable Acceptance criteria (>=1 checklist item), Definition of done
- * (>=1 checklist item), Open questions/risks, and a GitHub closing-keyword
- * issue reference (`Closes #N` and GitHub's other accepted forms — the
- * lightweight path's `Closes #N` linkage, issue #1181). Reuses the generic
- * markdown logic (parseMarkdownSections / AC + DoD patterns /
- * extractChecklistItems) so there is no parallel validator. Fails closed:
- * every missing invariant is reported under its distinct `missing_*` code.
- * Pure; no side effects.
+ * (>=1 checklist item), Open questions/risks, and — unless explicit
+ * issue-less mode is requested — a GitHub closing-keyword issue reference
+ * (`Closes #N` and GitHub's other accepted forms — the lightweight path's
+ * `Closes #N` linkage, issue #1181). Reuses the generic markdown logic
+ * (parseMarkdownSections / AC + DoD patterns / extractChecklistItems) so
+ * there is no parallel validator. Fails closed: every missing invariant is
+ * reported under its distinct `missing_*` code. Pure; no side effects.
  *
- * @param {{ body?: string, expectedIssue?: number }} input
+ * Issue-less mode (`issueLess: true`, issue #1210): the narrative invariants
+ * stay unconditional, but the closing-issue linkage flips from REQUIRED to
+ * FORBIDDEN — the PR is the sole artifact, so it MUST NOT carry a closing
+ * reference to an issue that doesn't back it. A present reference in this
+ * mode fails closed under `unexpected_closing_issue_reference`, distinct
+ * from `missing_closing_issue_reference` (tracker-backed mode, the default)
+ * so callers can tell "no issue expected" apart from "issue expected but
+ * absent". `expectedIssue` and `issueLess` are mutually exclusive; callers
+ * pick exactly one mode (tracker-backed, with or without a specific
+ * expected issue) or issue-less — never both.
+ *
+ * @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[] }}
  */
-export function validatePrBodySpec({ body = "", expectedIssue = 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
+    // are contradictory and silently preferring one would hide caller bugs.
+    throw new Error("validatePrBodySpec: issueLess and expectedIssue are mutually exclusive; pass exactly one issue-linkage mode");
+  }
   const bodyText = typeof body === "string" ? body : "";
   const sections = parseMarkdownSections(bodyText);
   const errors = [];
@@ -453,7 +471,14 @@ export function validatePrBodySpec({ body = "", expectedIssue = null } = {}) {
   }
 
   const closesIssues = extractClosingIssueNumbers(bodyText);
-  if (closesIssues.length === 0) {
+  if (issueLess) {
+    if (closesIssues.length > 0) {
+      errors.push({
+        code: "unexpected_closing_issue_reference",
+        message: `Issue-less PR body MUST NOT carry a closing reference to an issue that doesn't back it (found ${closesIssues.map((n) => `#${n}`).join(", ")}).`,
+      });
+    }
+  } else if (closesIssues.length === 0) {
     errors.push({
       code: "missing_closing_issue_reference",
       message: "Missing a GitHub closing-keyword issue reference (e.g. `Closes #123`).",
@@ -476,6 +501,41 @@ export function validatePrBodySpec({ body = "", expectedIssue = null } = {}) {
   };
 }
 
+/**
+ * Decide what an enqueue caller should do with a refinement-artifact result,
+ * so an un-refined item never lands in the Next Up pickup column in the first
+ * place. The draft gate remains the backstop for whatever slips through.
+ *
+ * Pure decision table, no I/O:
+ *   - target isn't the pickup column, or the artifact is present → enqueue
+ *     as requested.
+ *   - pickup target, artifact missing, interactive caller → block (caller
+ *     throws; no mutation).
+ *   - pickup target, artifact missing, headless/auto caller → divert (caller
+ *     parks the item in the non-pickup column instead of failing the run).
+ *
+ * @param {{ artifact: ReturnType<typeof detectIssueRefinementArtifact>, targetIsPickup: boolean, auto?: boolean }} input
+ * @returns {{ action: "enqueue" } | { action: "block"|"divert", reason: string, missing: string[] }}
+ */
+export function decideEnqueueRefinementGate({ artifact, targetIsPickup, auto = false }) {
+  // `artifact.finding === null` is the explicit "has ANY refinement artifact"
+  // signal (AC checklist OR DoD checklist OR linked doc) — clearer than reading
+  // `hasACs`, whose name understates that a DoD or linked doc also satisfies it.
+  if (!targetIsPickup || artifact.finding === null) {
+    return { action: "enqueue" };
+  }
+  const missing = [
+    "Acceptance criteria section",
+    "Definition of done section",
+    "linked refinement doc",
+  ];
+  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.";
+  return { action: auto ? "divert" : "block", reason, missing };
+}
+
 /**
  * Map a draft-gate refinement check to the result surface consumed by
  * `evaluatePrGateCoordination`. The mapping keeps the contract

package/src/loop/plan-file-promote-contract.mjs

@@ -43,6 +43,28 @@ export const PLAN_FILE_PROMOTE_ACTION = Object.freeze({
  */
 export const PLAN_FILE_PR_FRONT_MATTER_KEY = "prNumber";
 
+/**
+ * Build the plan-file promotion marker sentence: the single source of truth
+ * for the PR-body text that names the committed plan doc as the spec-of-record.
+ * `buildPromotionPrBody` emits it and `PLAN_FILE_PROMOTION_DOC_PATH_PATTERN`
+ * (below) parses it back out — keep the two in lockstep.
+ *
+ * @param {string} docPath  repo-relative path of the committed plan doc
+ * @returns {string}
+ */
+export function buildPlanFilePromotionMarker(docPath) {
+  return `Spec-of-record: the committed plan doc \`${docPath}\` is the authority for this work.`;
+}
+
+/**
+ * Matches the marker sentence `buildPlanFilePromotionMarker` produces and
+ * captures the plan doc path. The captured path is bounded to a single line
+ * and a `.md` suffix so a multi-line/unbounded body cannot smuggle an
+ * oversized or cross-line "path".
+ */
+export const PLAN_FILE_PROMOTION_DOC_PATH_PATTERN =
+  /Spec-of-record: the committed plan doc `([^`\n]{1,200}?\.md)`/u;
+
 /**
  * Minimal additive front-matter support for plan files (an escalated extension
  * to P1's format): a leading `---\n...\n---\n` block of simple `key: value`
@@ -219,7 +241,7 @@ export function buildPromotionPrBody({ planDocPath, acceptanceCriteria, definiti
   const safeAc = neutralizeIssueCloseKeywords(ac);
   const safeDod = neutralizeIssueCloseKeywords(dod);
   return [
-    `Spec-of-record: the committed plan doc \`${docPath}\` is the authority for this work.`,
+    buildPlanFilePromotionMarker(docPath),
     "This PR was opened by PR-FIRST promotion; no tracker issue exists.",
     "",
     "## Acceptance criteria",