@dev-loops/core 0.7.2 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -41,6 +41,7 @@
     "./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",

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/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/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 = [];
@@ -499,6 +501,41 @@ export function validatePrBodySpec({ body = "", expectedIssue = null, issueLess
   };
 }
 
+/**
+ * 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",

package/src/loop/pr-gate-coordination.mjs

@@ -34,6 +34,16 @@ export const REFINEMENT_ARTIFACT_STATUS = Object.freeze({
 
 export const REFINEMENT_ARTIFACT_FINDING = "missing_refinement_artifact";
 
+/**
+ * `refinementArtifact.specSource` values: which of the three sanctioned
+ * spec-of-record origins (artifact-authority-contract.md) backed the check.
+ */
+export const REFINEMENT_ARTIFACT_SPEC_SOURCE = Object.freeze({
+  LINKED_ISSUE: "linked_issue",
+  PR_BODY: "pr_body",
+  PLAN_FILE: "plan_file",
+});
+
 export const PR_CHECKPOINT_ACTION = Object.freeze({
   RUN_DRAFT_GATE: "run_draft_gate",
   MARK_READY_FOR_REVIEW: "mark_ready_for_review",
@@ -227,7 +237,15 @@ function normalizeRefinementArtifactStatus(value) {
   return REFINEMENT_ARTIFACT_STATUS.UNKNOWN;
 }
 
-function formatRefinementBlockedReason(linkedIssue, status) {
+// Issue-less refinement artifacts (specSource "pr_body"/"plan_file") carry
+// their own validation-failure reason from the detector; that reason must
+// replace the "linked issue" wording, which does not apply when the PR is the
+// spec-of-record and no linked issue was ever expected.
+function formatRefinementBlockedReason(linkedIssue, status, refinementArtifact) {
+  const specSource = refinementArtifact?.specSource;
+  if (specSource != null && specSource !== REFINEMENT_ARTIFACT_SPEC_SOURCE.LINKED_ISSUE && typeof refinementArtifact?.reason === "string" && refinementArtifact.reason.length > 0) {
+    return `The draft gate cannot complete: ${refinementArtifact.reason} finding=${REFINEMENT_ARTIFACT_FINDING}`;
+  }
   if (linkedIssue !== null && Number.isInteger(linkedIssue)) {
     return `Linked issue #${linkedIssue} has no refinement artifact (Acceptance criteria / DoD / linked refinement doc). Run refinement first, add ACs/DoD to the issue, then re-open the draft PR. finding=${REFINEMENT_ARTIFACT_FINDING}`;
   }
@@ -864,7 +882,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         allowedNextActions,
         forbiddenActions,
         nextAction: PR_CHECKPOINT_ACTION.REPORT_BLOCKED,
-        reason: formatRefinementBlockedReason(refinementLinkedIssue, refinementArtifactStatus),
+        reason: formatRefinementBlockedReason(refinementLinkedIssue, refinementArtifactStatus, refinementArtifact),
         mergeStateStatus,
         conflictFiles,
         refinementArtifact,

package/src/loop/refinement-grill-state.mjs

@@ -0,0 +1,173 @@
+/**
+ * Deterministic state machine for the refinement/grill sub-loop.
+ *
+ * The refinement loop runs the grill as a CLOSED, DETERMINISTIC sub-loop:
+ * detect-gaps -> auto-answer -> synthesize -> re-grill -> terminal. The
+ * iteration lives entirely in the transition graph below; the LLM answer and
+ * synthesis enter ONLY as a bounded input consumed at the `await_answers`
+ * state (and reflected in the `synthesized` snapshot flag), never as hidden
+ * orchestration inside a deterministic coordinator script (keeps
+ * OPS-NO-INLINE-INTERPRETER, #1224, clean).
+ *
+ * Mirrors the shape of `reviewer-loop-state.mjs` / `copilot-loop-state.mjs`:
+ * a frozen STATE vocabulary, a frozen TRANSITIONS adjacency table, a
+ * `normalize*Snapshot` canonicalizer, and a pure `interpret*State` that maps a
+ * point-in-time snapshot to exactly one current state plus its legal exits.
+ *
+ * Honest handoff: when a gap is genuinely unanswerable (only-`inferred`, no
+ * citation), the machine reaches `needs_human_handoff` naming the question
+ * rather than fabricating an answer to force convergence.
+ */
+
+export const GRILL_STATE = Object.freeze({
+  LOAD_TARGET: "load_target",
+  DETECT_GAPS: "detect_gaps",
+  AWAIT_ANSWERS: "await_answers",
+  SYNTHESIZE: "synthesize",
+  RE_GRILL: "re_grill",
+  GRILL_CLEAN: "grill_clean",
+  NEEDS_HUMAN_HANDOFF: "needs_human_handoff",
+  BLOCKED_NEEDS_USER_DECISION: "blocked_needs_user_decision",
+});
+
+// The iterate-to-clean loop: detect_gaps -> await_answers -> synthesize ->
+// re_grill, with re_grill either re-entering detect_gaps (a new answerable gap
+// surfaced) or terminating at grill_clean (fixed point). Any I/O/parse failure
+// fails closed to blocked_needs_user_decision; any unresolved (uncitable) gap
+// terminates honestly at needs_human_handoff.
+export const GRILL_TRANSITIONS = Object.freeze({
+  [GRILL_STATE.LOAD_TARGET]: [
+    GRILL_STATE.DETECT_GAPS,
+    GRILL_STATE.BLOCKED_NEEDS_USER_DECISION,
+  ],
+  [GRILL_STATE.DETECT_GAPS]: [
+    GRILL_STATE.AWAIT_ANSWERS,
+    GRILL_STATE.GRILL_CLEAN,
+    GRILL_STATE.NEEDS_HUMAN_HANDOFF,
+    GRILL_STATE.BLOCKED_NEEDS_USER_DECISION,
+  ],
+  [GRILL_STATE.AWAIT_ANSWERS]: [
+    GRILL_STATE.SYNTHESIZE,
+    GRILL_STATE.NEEDS_HUMAN_HANDOFF,
+    GRILL_STATE.BLOCKED_NEEDS_USER_DECISION,
+  ],
+  [GRILL_STATE.SYNTHESIZE]: [
+    GRILL_STATE.RE_GRILL,
+    GRILL_STATE.BLOCKED_NEEDS_USER_DECISION,
+  ],
+  [GRILL_STATE.RE_GRILL]: [
+    GRILL_STATE.DETECT_GAPS,
+    GRILL_STATE.GRILL_CLEAN,
+    GRILL_STATE.NEEDS_HUMAN_HANDOFF,
+    GRILL_STATE.BLOCKED_NEEDS_USER_DECISION,
+  ],
+  [GRILL_STATE.GRILL_CLEAN]: [],
+  [GRILL_STATE.NEEDS_HUMAN_HANDOFF]: [],
+  [GRILL_STATE.BLOCKED_NEEDS_USER_DECISION]: [],
+});
+
+const GRILL_NEXT_ACTIONS = Object.freeze({
+  [GRILL_STATE.LOAD_TARGET]: "Load the target issue/PR/plan body for grilling",
+  [GRILL_STATE.DETECT_GAPS]: "Run the loop-grill gap detectors on the loaded spec",
+  [GRILL_STATE.AWAIT_ANSWERS]: "Consume the bounded answer input: --auto self-answer with a citation, or ask the human interactively",
+  [GRILL_STATE.SYNTHESIZE]: "Synthesize Acceptance criteria / Definition of done / Non-goals into the body; write raw Q&A only to the ephemeral tmp artifact",
+  [GRILL_STATE.RE_GRILL]: "Re-run gap detection to check for a fixed point",
+  [GRILL_STATE.GRILL_CLEAN]: "Grill reached a fixed point; synthesized spec is clean",
+  [GRILL_STATE.NEEDS_HUMAN_HANDOFF]: "Stop and hand off the named unanswerable question(s) to the human; headless parks with the recorded reason",
+  [GRILL_STATE.BLOCKED_NEEDS_USER_DECISION]: "Stop and request explicit user direction",
+});
+
+const VALID_SURFACES = new Set(["issue", "pr", "plan"]);
+
+function normalizeCount(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0
+    ? Math.floor(value)
+    : 0;
+}
+
+function normalizeStringOrNull(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+/**
+ * Canonicalize a raw grill snapshot into a deterministic shape.
+ *
+ * @param {object} raw
+ * @returns {object}
+ */
+export function normalizeGrillSnapshot(raw) {
+  if (!raw || typeof raw !== "object") {
+    throw new Error("Snapshot must be a non-null object");
+  }
+
+  return {
+    surface: VALID_SURFACES.has(raw.surface) ? raw.surface : "issue",
+    targetRef: normalizeStringOrNull(raw.targetRef),
+
+    loaded: Boolean(raw.loaded),
+    loadFailed: Boolean(raw.loadFailed),
+
+    detectRan: Boolean(raw.detectRan),
+    // answerable gaps still awaiting an answer this pass
+    openGapCount: normalizeCount(raw.openGapCount),
+    // uncitable gaps that must hand off honestly (never fabricated)
+    unresolvedGapCount: normalizeCount(raw.unresolvedGapCount),
+
+    // the bounded LLM answer input, consumed at await_answers
+    answersReady: Boolean(raw.answersReady),
+    // synthesized AC/DoD/Non-goals applied to the body this iteration
+    synthesized: Boolean(raw.synthesized),
+
+    // post-synthesis re-grill fixed-point signals
+    reGrillRan: Boolean(raw.reGrillRan),
+    reGrillFixedPoint: Boolean(raw.reGrillFixedPoint),
+  };
+}
+
+/**
+ * Deterministically interpret the current refinement-grill state.
+ *
+ * @param {object} snapshot
+ * @returns {{state: string, allowedTransitions: string[], nextAction: string}}
+ */
+export function interpretRefinementGrillState(snapshot) {
+  const s = normalizeGrillSnapshot(snapshot);
+
+  let state;
+
+  if (s.loadFailed) {
+    // Fail closed on any load/parse failure, from any point in the loop.
+    state = GRILL_STATE.BLOCKED_NEEDS_USER_DECISION;
+  } else if (!s.loaded) {
+    state = GRILL_STATE.LOAD_TARGET;
+  } else if (s.unresolvedGapCount > 0) {
+    // Honest handoff outranks everything else: never fabricate to converge.
+    state = GRILL_STATE.NEEDS_HUMAN_HANDOFF;
+  } else if (s.synthesized) {
+    if (!s.reGrillRan) {
+      // Synthesis applied -> re-grill to check the fixed point.
+      state = GRILL_STATE.RE_GRILL;
+    } else if (s.reGrillFixedPoint) {
+      state = GRILL_STATE.GRILL_CLEAN;
+    } else {
+      // Re-grill surfaced a new answerable gap -> iterate.
+      state = GRILL_STATE.DETECT_GAPS;
+    }
+  } else if (s.answersReady) {
+    // Bounded answer input present -> apply synthesis.
+    state = GRILL_STATE.SYNTHESIZE;
+  } else if (s.detectRan) {
+    // Detection ran with no unresolved and no pending answers:
+    // open gaps -> await answers; zero gaps -> clean fixed point
+    // (also the already-refined, zero-iteration path).
+    state = s.openGapCount > 0 ? GRILL_STATE.AWAIT_ANSWERS : GRILL_STATE.GRILL_CLEAN;
+  } else {
+    state = GRILL_STATE.DETECT_GAPS;
+  }
+
+  return {
+    state,
+    allowedTransitions: [...GRILL_TRANSITIONS[state]],
+    nextAction: GRILL_NEXT_ACTIONS[state],
+  };
+}