@dev-loops/core 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -37,6 +37,9 @@
     "./loop/issue-refinement-artifact": "./src/loop/issue-refinement-artifact.mjs",
     "./loop/phase-files": "./src/loop/phase-files.mjs",
     "./loop/policy-constants": "./src/loop/policy-constants.mjs",
+    "./loop/plan-file-intake-contract": "./src/loop/plan-file-intake-contract.mjs",
+    "./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-title-markers": "./src/loop/pr-title-markers.mjs",
     "./loop/public-dev-loop-routing": "./src/loop/public-dev-loop-routing.mjs",
@@ -48,6 +51,8 @@
     "./loop/reviewer-loop-state": "./src/loop/reviewer-loop-state.mjs",
     "./loop/run-context": "./src/loop/run-context.mjs",
     "./loop/run-inspection": "./src/loop/run-inspection.mjs",
+    "./loop/spike-exit-contract": "./src/loop/spike-exit-contract.mjs",
+    "./loop/spike-intake-contract": "./src/loop/spike-intake-contract.mjs",
     "./loop/steering": "./src/loop/steering.mjs",
     "./loop/timeout-policy": "./src/loop/timeout-policy.mjs",
     "./loop/tracker-pr-state": "./src/loop/tracker-pr-state.mjs",

package/src/config/config.mjs

@@ -53,6 +53,12 @@ const GatesConfig = z.strictObject({
   // `requireCi` is only behaviorally configurable for the draft gate.
   // preApproval always requires CI even if config repeats `requireCi`.
   preApproval: GateConfig.optional(),
+  // Relaxed spike gate profile (#965). A spike's deliverable is a findings doc,
+  // not production code, so it should not carry the full draft → pre-approval →
+  // Copilot production set. Resolved through the same config-merge layering and
+  // the same resolveGateConfig path as draft/preApproval — no new strategy→knob
+  // resolver. Absent for non-spike work, so production gates are unaffected.
+  spike: GateConfig.optional(),
   // Fail-closed enforcement that a gate verdict was produced by the
   // fan-out/fan-in review sub-loop (executionMode === "fanout_fanin" plus a
   // durable findings-log ledger), not an inline single-agent run. Default
@@ -105,6 +111,11 @@ const WorkflowConfig = z.strictObject({
   asyncStartMode: z.enum(["required", "allowed"]).default("required"),
   requireRetrospective: z.boolean(),
   requireRetrospectiveGate: z.boolean().default(false),
+  // Developer-mode retro step (#982): enforce internal-tooling-only execution
+  // (no agent-level raw gh/python/node -e) in the retrospective gate. This is the
+  // dev-loops maintainers' own dogfooding discipline — opt-in, default OFF so
+  // consumers of the extension are never blocked by it.
+  requireRetrospectiveInternalTooling: z.boolean().default(false),
   requireDraftFirst: z.boolean(),
   devModeDefault: z.boolean(),
 });
@@ -140,6 +151,16 @@ const WorktreeConfig = z.strictObject({
   linkOnInit: z.array(z.string().trim().min(1)).optional(),
 });
 
+/**
+ * Local-planning config (#949): where persisted markdown plan files (phase-doc
+ * format) live when work originates from a plan file rather than a tracker
+ * issue. `plansDir` is a repo-relative directory; defaults to the existing
+ * phase-docs directory. See skills/docs/plan-file-contract.md.
+ */
+const LocalPlanningConfig = z.strictObject({
+  plansDir: z.string().trim().min(1).optional(),
+});
+
 /** Internal path whitelist for internal-only PR detection — flat array of regex strings */
 const InternalPatternsConfig = z.array(z.string().trim().min(1)).min(1);
 
@@ -159,6 +180,7 @@ const FileGateConfig = GateConfig.partial();
 const FileGatesConfig = z.strictObject({
   draft: FileGateConfig.optional(),
   preApproval: FileGateConfig.optional(),
+  spike: FileGateConfig.optional(),
   requireFanoutEvidence: z.boolean().optional(),
   maxFanoutReviewers: z.number().int().min(1).max(64).optional(),
   postFindingsComments: z.boolean().optional(),
@@ -190,6 +212,7 @@ export const DevLoopConfigSchema = z.strictObject({
   personas: PersonasConfig.optional(),
   internalPathPatterns: InternalPatternsConfig.optional(),
   worktree: WorktreeConfig.optional(),
+  localPlanning: LocalPlanningConfig.optional(),
 });
 
 // ============================================================================
@@ -215,6 +238,7 @@ export const BUILT_IN_DEFAULTS = Object.freeze({
     asyncStartMode: "required",
     requireRetrospective: false,
     requireRetrospectiveGate: false,
+    requireRetrospectiveInternalTooling: false,
     requireDraftFirst: false,
     devModeDefault: false,
   }),
@@ -239,6 +263,7 @@ export const BUILT_IN_DEFAULTS = Object.freeze({
     "^test/",
   ]),
   worktree: Object.freeze({ copyOnInit: Object.freeze([]), linkOnInit: Object.freeze([]) }),
+  localPlanning: Object.freeze({ plansDir: "docs/phases/" }),
 });
 
 // ============================================================================
@@ -260,6 +285,7 @@ export const FileConfigSchema = z.strictObject({
   personas: FilePersonasConfig.optional(),
   internalPathPatterns: InternalPatternsConfig.optional(),
   worktree: WorktreeConfig.partial().optional(),
+  localPlanning: LocalPlanningConfig.partial().optional(),
 });
 
 // ============================================================================
@@ -916,7 +942,7 @@ export function resolveRefinement(config) {
  * flags always resolve to stable defaults.
  *
  * @param {DevLoopConfig} config
- * @param {"draft"|"preApproval"} gate
+ * @param {"draft"|"preApproval"|"spike"} gate
  * @returns {{ angles: string[]|null, excludeAngles: string[], mandatoryAngles: string[], required: boolean, requireCi: boolean, blockCleanOnFindingSeverities: string[], dynamicAngles: boolean }}
  */
 export function resolveGateConfig(config, gate) {
@@ -1116,7 +1142,7 @@ export async function resolveGateAnglesDynamic(config, gate, { diff } = {}) {
  * for the requested key.
  *
  * @param {DevLoopConfig} config
- * @param {"asyncStartMode"|"requireRetrospective"|"requireRetrospectiveGate"|"requireDraftFirst"|"devModeDefault"} key
+ * @param {"asyncStartMode"|"requireRetrospective"|"requireRetrospectiveGate"|"requireRetrospectiveInternalTooling"|"requireDraftFirst"|"devModeDefault"} key
  * @returns {string|boolean}
  */
 export function resolveWorkflowConfig(config, key) {
@@ -1132,6 +1158,10 @@ export function resolveWorkflowConfig(config, key) {
     return config?.workflow?.requireRetrospectiveGate ?? DEFAULT_WORKFLOW_CONFIG.requireRetrospectiveGate;
   }
 
+  if (key === "requireRetrospectiveInternalTooling") {
+    return config?.workflow?.requireRetrospectiveInternalTooling ?? DEFAULT_WORKFLOW_CONFIG.requireRetrospectiveInternalTooling;
+  }
+
   if (key === "requireDraftFirst") {
     return config?.workflow?.requireDraftFirst ?? DEFAULT_WORKFLOW_CONFIG.requireDraftFirst;
   }
@@ -1177,6 +1207,24 @@ export function resolveWorktreeConfig(config) {
   return { copyOnInit: list(wt?.copyOnInit), linkOnInit: list(wt?.linkOnInit) };
 }
 
+/**
+ * Resolve the local-planning plans directory from the merged dev-loop config.
+ *
+ * Returns the configured `localPlanning.plansDir` (trimmed) when present and
+ * non-empty, otherwise the built-in default (`docs/phases/`) — the existing
+ * phase-docs directory. See skills/docs/plan-file-contract.md.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {string}
+ */
+export function resolvePlansDir(config) {
+  const raw = config?.localPlanning?.plansDir;
+  if (typeof raw === "string" && raw.trim().length > 0) {
+    return raw.trim();
+  }
+  return BUILT_IN_DEFAULTS.localPlanning.plansDir;
+}
+
 /**
  * Resolve the human-handoff config from the merged dev-loop config (#920).
  *

package/src/config/extension-defaults.yaml

@@ -49,6 +49,9 @@ gates:
     requireCi: true
     mandatoryAngles:
       - pr-description
+  # Gate findings comments live ON the PR (the local-first spec-of-record /
+  # human-review surface), so they are evidence, not tracker noise — keep them on.
+  postFindingsComments: true
   preApproval:
     angles:
       - dry
@@ -67,11 +70,27 @@ gates:
     required: true
     mandatoryAngles:
       - pr-checklist-matrix
+  # Relaxed spike gate profile (#965). A spike's deliverable is a findings doc,
+  # not production code, so it is intentionally lighter than the production
+  # draft -> pre-approval -> Copilot set: a small docs-first angle set, not a
+  # required gate, and no CI prerequisite. Resolved through the same
+  # config-merge layering and resolveGateConfig path as draft/preApproval; only
+  # applies to spike-mode work, so production gates are unaffected.
+  spike:
+    angles:
+      - scope
+      - docs
+    excludeAngles: []
+    required: false
+    requireCi: false
+    mandatoryAngles: []
 
 # Autonomy: only merge requires operator confirmation by default.
 autonomy:
   stopAt:
     - merge
+  # Local-first never auto-merges; a human always merges.
+  humanMergeOnly: true
 
 # Workflow enforcement defaults.
 workflow:
@@ -82,6 +101,11 @@ workflow:
   # repo-root .devloops, which takes precedence over these extension defaults.
   requireRetrospective: false
   requireRetrospectiveGate: false
+  # Internal-tooling-only retro check (#982) is a DEVELOPER-MODE step — the dev-loops
+  # maintainers' own dogfooding discipline. It must never block a consumer's state
+  # changes (consumers may legitimately use raw gh/python/node -e), so it ships OFF.
+  # The dev-loops repo opts in via its own repo-root .devloops (takes precedence here).
+  requireRetrospectiveInternalTooling: false
   requireDraftFirst: true
   # Dev mode is the dev-loop self-improvement mode — it edits the loop's own skill/agent prompts
   # after a phase, which is only meaningful in the dev-loops repo. Shipped defaults must not force
@@ -89,6 +113,11 @@ workflow:
   # via its own repo-root .devloops (which takes precedence over these extension defaults).
   devModeDefault: false
 
+# Local-planning: where persisted markdown plan files (phase-doc format) live
+# when work originates from a plan file rather than a tracker issue (#949).
+localPlanning:
+  plansDir: docs/phases/
+
 # Light-mode threshold for small local changes.
 localImplementation:
   lightMode:
@@ -99,7 +128,9 @@ localImplementation:
 # Queue defaults (repo-specific projectNumber/boardTitle omitted by design).
 queue:
   maxParallel: 3
-  maxAutoFiledIssues: 10
+  # Local-first is PR-first (issues are skipped, #952), so auto-filing issues is
+  # near-zero; a low cap keeps tracker noise minimal, especially early.
+  maxAutoFiledIssues: 1
   reDispatchMaxRetries: 1
 
 # Persona registry used by gate review angle resolution.

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

@@ -0,0 +1,56 @@
+/**
+ * Local-planning plan-file intake state machine.
+ *
+ * A `--plan-file` startup hands the dev-loop a phase-doc-format plan that lives
+ * outside the tracker. Before promotion there is no issue to key a worktree on,
+ * so this intake stage classifies how far the plan has progressed through
+ * refinement. The classification drives whether the next step is refinement or
+ * promotion.
+ *
+ * This evaluator mirrors the `DEV_LOOP_ISSUE_ASSIGNMENT_SEAM` precedent: a
+ * frozen enum plus a pure, deterministic function. It performs no GitHub or
+ * filesystem side effects — the caller supplies the section-presence facts it
+ * has already read.
+ */
+
+export const PLAN_FILE_INTAKE_STATE = Object.freeze({
+  /** Plan carries only the base authoring sections; refinement has not run. */
+  NEW_PLAN_NEEDS_REFINEMENT: "new_plan_needs_refinement",
+  /** Plan also carries Acceptance criteria + Definition of done; refinement already ran. */
+  PLAN_REFINED_READY_FOR_PROMOTION: "plan_refined_ready_for_promotion",
+  /** Inputs are ambiguous, conflicting, or unusable; fail closed. */
+  AMBIGUOUS_FAIL_CLOSED: "ambiguous_fail_closed",
+});
+
+/**
+ * Refinement-marker sections a plan gains once refinement has run on top of the
+ * base authoring sections.
+ */
+export const PLAN_FILE_REFINEMENT_SECTIONS = Object.freeze(["Acceptance criteria", "Definition of done"]);
+
+/**
+ * Pure intake-state classifier.
+ *
+ * @param {object} facts
+ * @param {boolean} facts.baseSectionsValid  whether the plan passes the base-section validator (Status/Objective/In scope/Explicit non-goals)
+ * @param {boolean} facts.hasAcceptanceCriteria  whether a non-empty Acceptance criteria section is present
+ * @param {boolean} facts.hasDefinitionOfDone  whether a non-empty Definition of done section is present
+ * @returns {{ state: string }} one of PLAN_FILE_INTAKE_STATE values
+ */
+export function evaluatePlanFileIntakeState({ baseSectionsValid, hasAcceptanceCriteria, hasDefinitionOfDone } = {}) {
+  // A plan that fails the base contract should already have been rejected by the
+  // caller; treating it as intake input here is ambiguous, so fail closed.
+  if (baseSectionsValid !== true) {
+    return { state: PLAN_FILE_INTAKE_STATE.AMBIGUOUS_FAIL_CLOSED };
+  }
+  // Refinement markers must be present as a pair. A plan carrying exactly one of
+  // the two refinement sections is partially refined in an undefined way; fail
+  // closed instead of guessing whether to refine or promote.
+  if (hasAcceptanceCriteria === true && hasDefinitionOfDone === true) {
+    return { state: PLAN_FILE_INTAKE_STATE.PLAN_REFINED_READY_FOR_PROMOTION };
+  }
+  if (hasAcceptanceCriteria !== true && hasDefinitionOfDone !== true) {
+    return { state: PLAN_FILE_INTAKE_STATE.NEW_PLAN_NEEDS_REFINEMENT };
+  }
+  return { state: PLAN_FILE_INTAKE_STATE.AMBIGUOUS_FAIL_CLOSED };
+}

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

@@ -0,0 +1,234 @@
+/**
+ * Local-planning plan-file PR-FIRST promotion (P4).
+ *
+ * This is the P4 promotion step. A plan refined to the
+ * `plan_refined_ready_for_promotion` state (P3 refinement produces it; P2
+ * defines the intake-state machine) is the spec-of-record. Promotion
+ * commits that plan doc and opens EXACTLY ONE draft PR — it never mints a
+ * GitHub issue. The PR body links the committed plan doc path and carries the
+ * full Acceptance criteria + Definition of done so the PR is a self-contained
+ * spec-of-record that can enter the existing PR-followup loop unchanged
+ * (`loop startup --pr <n>`), with no new lifecycle state and no issue.
+ *
+ * This module is pure: it decides promote-eligibility, parses/serializes the
+ * plan↔PR link (a minimal YAML front-matter block), and builds the PR body
+ * text. It performs no GitHub mutation, no network calls, and no filesystem
+ * I/O. The CLI owns ALL I/O (read plan file, git add/commit/branch, call
+ * create-pr.mjs, write the PR number back). That keeps the
+ * no-issue-mint / zero-pre-promotion-mutation guarantee structural here: there
+ * is no gh/network surface to reach from this module.
+ *
+ * It composes the already-shipped P2 intake-state machine: promotion is only
+ * eligible from `plan_refined_ready_for_promotion` (the state P3 refinement
+ * produces).
+ */
+
+import {
+  evaluatePlanFileIntakeState,
+  PLAN_FILE_INTAKE_STATE,
+} from "./plan-file-intake-contract.mjs";
+
+/** Promotion actions the eligibility decision can return. */
+export const PLAN_FILE_PROMOTE_ACTION = Object.freeze({
+  /** Eligible: commit the plan doc and open exactly one draft PR. */
+  PROMOTE: "promote",
+  /** Already linked to an open PR; idempotent no-op (report the existing PR). */
+  ALREADY_PROMOTED: "already_promoted",
+});
+
+/**
+ * Front-matter key that records the opened PR number on the plan doc, forming
+ * the plan→PR half of the bidirectional link (the PR body carries the doc path,
+ * the PR→plan half).
+ */
+export const PLAN_FILE_PR_FRONT_MATTER_KEY = "prNumber";
+
+/**
+ * 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`
+ * lines. Plans without a leading `---` are returned with an empty front-matter
+ * object and the full text as the body, so existing front-matter-free plans are
+ * never broken.
+ *
+ * ponytail: a flat scalar `key: value` parser, not a YAML engine. The only
+ * front-matter this contract reads/writes is `prNumber:` (an integer); upgrade
+ * to the `yaml` dep already in @dev-loops/core if richer front-matter is needed.
+ *
+ * @param {string} markdownText
+ * @returns {{ frontMatter: Record<string, string>, body: string }}
+ */
+export function parsePlanFrontMatter(markdownText) {
+  const text = typeof markdownText === "string" ? markdownText : "";
+  // The opening fence must be the very first line.
+  const fenceMatch = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/u.exec(text);
+  if (!fenceMatch || fenceMatch.index !== 0) {
+    return { frontMatter: {}, body: text };
+  }
+  const block = fenceMatch[1];
+  const body = text.slice(fenceMatch[0].length);
+  const frontMatter = {};
+  for (const rawLine of block.split(/\r?\n/u)) {
+    const line = rawLine.trim();
+    if (line.length === 0) continue;
+    const sep = line.indexOf(":");
+    if (sep === -1) continue;
+    const key = line.slice(0, sep).trim();
+    if (key.length === 0) continue;
+    // Plan content is untrusted: never let prototype-pollution keys through.
+    if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+    frontMatter[key] = line.slice(sep + 1).trim();
+  }
+  return { frontMatter, body };
+}
+
+/**
+ * Read the linked PR number from a plan's front-matter. Returns a positive
+ * integer when present and valid, otherwise null.
+ *
+ * @param {string} markdownText
+ * @returns {number | null}
+ */
+export function readLinkedPrNumber(markdownText) {
+  const { frontMatter } = parsePlanFrontMatter(markdownText);
+  const raw = frontMatter[PLAN_FILE_PR_FRONT_MATTER_KEY];
+  if (typeof raw !== "string" || raw.length === 0) return null;
+  if (!/^\d+$/u.test(raw)) return null;
+  const n = Number.parseInt(raw, 10);
+  return Number.isInteger(n) && n > 0 ? n : null;
+}
+
+/**
+ * Serialize a plan back to text with the given PR number recorded in
+ * front-matter (the plan→PR link). Preserves an existing leading front-matter
+ * block's other keys and sets/replaces `prNumber`; adds a fresh block to a plan
+ * that had none. Idempotent: re-serializing with the same number reproduces the
+ * same text.
+ *
+ * @param {string} markdownText  current plan text (with or without front-matter)
+ * @param {number} prNumber  positive integer PR number to record
+ * @returns {string}
+ */
+export function writeLinkedPrNumber(markdownText, prNumber) {
+  if (!Number.isInteger(prNumber) || prNumber <= 0) {
+    throw new Error("writeLinkedPrNumber requires a positive integer prNumber");
+  }
+  const { frontMatter, body } = parsePlanFrontMatter(markdownText);
+  const merged = { ...frontMatter, [PLAN_FILE_PR_FRONT_MATTER_KEY]: String(prNumber) };
+  const lines = Object.entries(merged).map(([key, value]) => `${key}: ${value}`);
+  return `---\n${lines.join("\n")}\n---\n${body}`;
+}
+
+/**
+ * Pure promote-eligibility decision.
+ *
+ * Fail-closed: promotion is eligible ONLY from the
+ * `plan_refined_ready_for_promotion` state (produced by P3 refinement). Any other intake state returns
+ * `ok: false` with a reason and no action — the caller must make zero GitHub
+ * mutation on that path. When the plan already carries a linked PR number in
+ * front-matter, the decision is `already_promoted` (idempotent: open nothing,
+ * report the existing PR).
+ *
+ * @param {object} facts
+ * @param {boolean} facts.baseSectionsValid  whether the plan passes the base-section validator
+ * @param {boolean} facts.hasAcceptanceCriteria  whether a non-empty Acceptance criteria section is present
+ * @param {boolean} facts.hasDefinitionOfDone  whether a non-empty Definition of done section is present
+ * @param {number|null} [facts.existingPrNumber]  PR number already recorded in the plan's front-matter, if any
+ * @returns {{ ok: boolean, action?: string, reason?: string, planFileIntakeState?: string, existingPrNumber?: number }}
+ */
+export function evaluatePromoteEligibility({
+  baseSectionsValid,
+  hasAcceptanceCriteria,
+  hasDefinitionOfDone,
+  existingPrNumber = null,
+} = {}) {
+  const state = evaluatePlanFileIntakeState({
+    baseSectionsValid,
+    hasAcceptanceCriteria,
+    hasDefinitionOfDone,
+  }).state;
+
+  // The ready gate: promotion only acts on a fully-refined plan. A plan that
+  // still needs refinement, is ambiguous, or fails the base contract is not
+  // promotable here; fail closed so the CLI makes no GitHub mutation.
+  if (state !== PLAN_FILE_INTAKE_STATE.PLAN_REFINED_READY_FOR_PROMOTION) {
+    return { ok: false, reason: "not_ready_for_promotion", planFileIntakeState: state };
+  }
+
+  // Idempotency: a plan already linked to a PR has been promoted. Report the
+  // existing PR and open nothing.
+  if (Number.isInteger(existingPrNumber) && existingPrNumber > 0) {
+    return {
+      ok: true,
+      action: PLAN_FILE_PROMOTE_ACTION.ALREADY_PROMOTED,
+      planFileIntakeState: state,
+      existingPrNumber,
+    };
+  }
+
+  return { ok: true, action: PLAN_FILE_PROMOTE_ACTION.PROMOTE, planFileIntakeState: state };
+}
+
+/**
+ * Neutralize GitHub issue-closing keywords (`closes #12`, `fixes #3`,
+ * `resolved #7`, …) by wrapping the keyword+reference in inline code, which
+ * GitHub does not parse as a closing reference. The AC/DoD section bodies are
+ * untrusted plan content; an accidental `Closes #123` in a plan would otherwise
+ * flow into the PR body and auto-close an unrelated issue on merge — breaking
+ * the PR-FIRST guarantee that promotion never closes a tracker artifact.
+ *
+ * ponytail: handles the realistic `#<n>` form; cross-repo (`owner/repo#n`) and
+ * full-URL closing refs are not neutralized — out of scope for local plans.
+ */
+function neutralizeIssueCloseKeywords(text) {
+  return String(text).replace(
+    /\b(close[sd]?|fix(?:e[sd])?|resolve[sd]?)(\s+)(#\d+)\b/giu,
+    "`$1$2$3`",
+  );
+}
+
+/**
+ * Build the draft-PR body for a promoted plan. The body is the self-contained
+ * spec-of-record: it references the committed plan doc path (the PR→plan link)
+ * and carries the FULL Acceptance criteria + Definition of done extracted from
+ * the refined plan, so the PR alone fully specifies the work.
+ *
+ * Deliberately no `Closes #N` / issue reference: PR-FIRST promotion never mints
+ * an issue, and the committed plan doc — not a tracker artifact — is the
+ * authority. Issue-closing keywords inside the embedded AC/DoD are neutralized
+ * so untrusted plan content cannot smuggle one in.
+ *
+ * @param {object} params
+ * @param {string} params.planDocPath  repo-relative path of the committed plan doc
+ * @param {string} params.acceptanceCriteria  full Acceptance criteria section body
+ * @param {string} params.definitionOfDone  full Definition of done section body
+ * @returns {string}
+ */
+export function buildPromotionPrBody({ planDocPath, acceptanceCriteria, definitionOfDone } = {}) {
+  const docPath = String(planDocPath ?? "").trim();
+  const ac = String(acceptanceCriteria ?? "").trim();
+  const dod = String(definitionOfDone ?? "").trim();
+  if (docPath.length === 0) {
+    throw new Error("buildPromotionPrBody requires a planDocPath");
+  }
+  if (ac.length === 0) {
+    throw new Error("buildPromotionPrBody requires acceptanceCriteria");
+  }
+  if (dod.length === 0) {
+    throw new Error("buildPromotionPrBody requires definitionOfDone");
+  }
+  const safeAc = neutralizeIssueCloseKeywords(ac);
+  const safeDod = neutralizeIssueCloseKeywords(dod);
+  return [
+    `Spec-of-record: the committed plan doc \`${docPath}\` is the authority for this work.`,
+    "This PR was opened by PR-FIRST promotion; no tracker issue exists.",
+    "",
+    "## Acceptance criteria",
+    "",
+    safeAc,
+    "",
+    "## Definition of done",
+    "",
+    safeDod,
+    "",
+  ].join("\n");
+}

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

@@ -0,0 +1,229 @@
+/**
+ * Local-planning plan-file refine + human-review checkpoint (off-tracker).
+ *
+ * This is the P3 core noise-reduction step. It generalizes the proposal-first
+ * intake pattern (emit a local artifact, human-gate it, make zero tracker
+ * mutation, stop and ask) to plan files: the refined plan is written in-place to
+ * the single canonical plan file, the autonomous docs-grill runs as a step
+ * within refinement, and the loop stops at a local human-review checkpoint with
+ * the intake state advanced to `plan_refined_ready_for_promotion`.
+ *
+ * This module is pure: it transforms markdown text and reports a disposition. It
+ * performs no GitHub mutation, no network calls, and no filesystem I/O. The
+ * caller supplies the section-presence facts it already read (mirroring the
+ * `evaluatePlanFileIntakeState` precedent) and the refiner-produced payload, and
+ * writes the returned markdown back. That keeps the zero-tracker-mutation
+ * guarantee structural: there is no gh/network surface to reach from here.
+ *
+ * It composes the already-shipped contracts: P2 `evaluatePlanFileIntakeState` +
+ * `PLAN_FILE_REFINEMENT_SECTIONS` (this step acts on `new_plan_needs_refinement`
+ * and drives the transition to `plan_refined_ready_for_promotion`) and #948's
+ * docs-grill: the caller classifies each finding with `classifyDocsGrillFinding`
+ * and passes the dispositions in, and this module validates and records them.
+ */
+
+import {
+  evaluatePlanFileIntakeState,
+  PLAN_FILE_INTAKE_STATE,
+  PLAN_FILE_REFINEMENT_SECTIONS,
+} from "./plan-file-intake-contract.mjs";
+
+/** The local human-review checkpoint surface the loop stops at on success. */
+export const PLAN_FILE_REFINE_STOP = Object.freeze({
+  /** Refinement wrote the plan in-place; stop for local human review before any promotion. */
+  LOCAL_HUMAN_REVIEW: "local_human_review",
+});
+
+/** The heading the recorded docs-grill findings live under in the plan file. */
+export const DOCS_GRILL_FINDINGS_HEADING = "Docs-grill findings";
+
+/** The heading the refiner coverage matrix lives under in the plan file. */
+export const COVERAGE_MATRIX_HEADING = "Coverage matrix";
+
+/**
+ * Remove an existing `## <heading>` section (heading + body up to the next H2)
+ * from markdown so a refine re-run replaces it rather than appending a duplicate.
+ * Returns the markdown unchanged when the heading is absent.
+ */
+function stripSection(markdownText, headingText) {
+  const escapedHeading = headingText.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+  const headingPattern = new RegExp(`^##\\s+${escapedHeading}\\s*$`, "imu");
+  const match = headingPattern.exec(markdownText);
+  if (!match || match.index === undefined) return markdownText;
+  const start = match.index;
+  const afterHeading = start + match[0].length;
+  const remaining = markdownText.slice(afterHeading);
+  const nextHeadingMatch = /^##\s+/imu.exec(remaining);
+  const end = nextHeadingMatch && nextHeadingMatch.index !== undefined
+    ? afterHeading + nextHeadingMatch.index
+    : markdownText.length;
+  // Drop the section and collapse the blank-line gap it leaves behind.
+  return `${markdownText.slice(0, start)}${markdownText.slice(end)}`.replace(/\n{3,}/gu, "\n\n");
+}
+
+/**
+ * Whether markdown carries a `## <heading>` section marker. Used to re-derive
+ * the section-presence facts from the freshly-written text so the end-state
+ * check verifies the append actually happened (rather than re-asserting the
+ * inputs). ponytail: local copy of the section-detect regex; the shared section
+ * helper belongs in core once extractSection is lifted out of scripts/.
+ */
+function hasSection(markdownText, headingText) {
+  const escaped = headingText.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+  return new RegExp(`^##\\s+${escaped}\\s*$`, "imu").test(markdownText);
+}
+
+/** Append a `## <heading>` section with the given body to markdown. */
+function appendSection(markdownText, headingText, body) {
+  const trimmed = markdownText.replace(/\s+$/u, "");
+  return `${trimmed}\n\n## ${headingText}\n\n${String(body).trim()}\n`;
+}
+
+/**
+ * Render recorded docs-grill findings as a markdown body. Each finding lists the
+ * disposition `classifyDocsGrillFinding` assigned it. When the grill produced no
+ * findings, an explicit "none recorded" line keeps the section idempotent and
+ * non-empty so the plan file always carries the grill evidence.
+ */
+function renderGrillFindings(classified) {
+  if (classified.length === 0) {
+    return "- None recorded; the docs-grill step ran and surfaced no findings.";
+  }
+  return classified
+    .map((entry) => {
+      const summary = String(entry.summary ?? "").trim() || "(no summary)";
+      return `- [${entry.disposition}] (${entry.kind}) ${summary}`;
+    })
+    .join("\n");
+}
+
+/**
+ * Refine a plan file in-place and advance its intake state, then stop at the
+ * local human-review checkpoint.
+ *
+ * The caller reads the plan file and supplies the section-presence facts plus
+ * the refiner payload. On success it writes `refinedMarkdown` back to the same
+ * path (the single canonical artifact) and stops; it never promotes here.
+ *
+ * @param {object} params
+ * @param {string} params.markdownText  current plan-file markdown
+ * @param {boolean} params.baseSectionsValid  whether the plan passes the base-section validator
+ * @param {boolean} params.hasAcceptanceCriteria  whether the plan already carries a non-empty Acceptance criteria section marker (per the intake contract)
+ * @param {boolean} params.hasDefinitionOfDone  whether the plan already carries a non-empty Definition of done section marker (per the intake contract)
+ * @param {object} params.payload  refiner-produced refinement output
+ * @param {string} params.payload.acceptanceCriteria  Acceptance criteria section body
+ * @param {string} params.payload.definitionOfDone  Definition of done section body
+ * @param {string} params.payload.coverageMatrix  AC/DoD/Non-goal coverage matrix (markdown table)
+ * @param {object[]} [params.payload.grillDispositions]  docs-grill dispositions the caller pre-classified via #948's `classifyDocsGrillFinding`; each entry is `{ kind, summary, disposition }` and a null/invalid `disposition` fails the grill closed
+ * @returns {{
+ *   ok: boolean,
+ *   reason?: string,
+ *   planFileIntakeState?: string,
+ *   refinedMarkdown?: string,
+ *   grillDispositions?: object[],
+ *   stop?: { kind: string },
+ * }}
+ */
+export function refinePlanFileInPlace({
+  markdownText,
+  baseSectionsValid,
+  hasAcceptanceCriteria,
+  hasDefinitionOfDone,
+  payload,
+} = {}) {
+  if (typeof markdownText !== "string" || markdownText.length === 0) {
+    return { ok: false, reason: "missing_plan_markdown" };
+  }
+
+  // Gate on the starting intake state: this step only acts on a base-valid plan
+  // that has not yet been refined. A plan already carrying refinement markers, a
+  // partially-refined plan, or one failing the base contract is ambiguous here;
+  // fail closed without writing or advancing.
+  const startState = evaluatePlanFileIntakeState({
+    baseSectionsValid,
+    hasAcceptanceCriteria,
+    hasDefinitionOfDone,
+  }).state;
+  if (startState !== PLAN_FILE_INTAKE_STATE.NEW_PLAN_NEEDS_REFINEMENT) {
+    return { ok: false, reason: "not_in_new_plan_needs_refinement", planFileIntakeState: startState };
+  }
+
+  // The refiner payload must carry the refinement contract: AC, DoD, and the
+  // coverage matrix. A missing/empty piece is a failed refine; fail closed.
+  if (!payload || typeof payload !== "object") {
+    return { ok: false, reason: "missing_refinement_payload", planFileIntakeState: startState };
+  }
+  const acceptanceCriteria = String(payload.acceptanceCriteria ?? "").trim();
+  const definitionOfDone = String(payload.definitionOfDone ?? "").trim();
+  const coverageMatrix = String(payload.coverageMatrix ?? "").trim();
+  if (!acceptanceCriteria) {
+    return { ok: false, reason: "missing_acceptance_criteria", planFileIntakeState: startState };
+  }
+  if (!definitionOfDone) {
+    return { ok: false, reason: "missing_definition_of_done", planFileIntakeState: startState };
+  }
+  if (!coverageMatrix) {
+    return { ok: false, reason: "missing_coverage_matrix", planFileIntakeState: startState };
+  }
+
+  // The docs-grill runs as a step of refinement. The caller (the CLI, which owns
+  // I/O and the scripts/ boundary) classifies each finding with #948's
+  // `classifyDocsGrillFinding` and passes the dispositions in. This core module
+  // validates and renders them but does NOT import the classifier — keeping it
+  // free of any scripts/ import so the published @dev-loops/core package does not
+  // break for consumers. A missing or invalid disposition fails the grill closed
+  // so a malformed grill cannot advance the state.
+  const grillDispositions = Array.isArray(payload.grillDispositions) ? payload.grillDispositions : [];
+  for (const d of grillDispositions) {
+    if (!d || typeof d.disposition !== "string" || d.disposition.length === 0) {
+      return { ok: false, reason: "docs_grill_failed", planFileIntakeState: startState };
+    }
+  }
+
+  // A managed section body must not contain a top-level `## ` heading: stripSection
+  // finds a section's end by scanning to the next `## `, so an embedded H2 in a body
+  // would break the strip-then-append idempotency on a re-run (the inner heading and
+  // its text would orphan into the document body). Fail closed on such a payload.
+  const grillBody = renderGrillFindings(grillDispositions);
+  if ([acceptanceCriteria, definitionOfDone, coverageMatrix, grillBody].some((b) => /^##\s/mu.test(String(b)))) {
+    return { ok: false, reason: "section_body_contains_heading", planFileIntakeState: startState };
+  }
+
+  // Write the refinement sections in-place. Strip any prior copy first so a
+  // re-run replaces rather than duplicates (idempotency), then append the fresh
+  // sections in a stable order.
+  const [acHeading, dodHeading] = PLAN_FILE_REFINEMENT_SECTIONS;
+  let refinedMarkdown = markdownText;
+  for (const heading of [acHeading, dodHeading, COVERAGE_MATRIX_HEADING, DOCS_GRILL_FINDINGS_HEADING]) {
+    refinedMarkdown = stripSection(refinedMarkdown, heading);
+  }
+  refinedMarkdown = appendSection(refinedMarkdown, acHeading, acceptanceCriteria);
+  refinedMarkdown = appendSection(refinedMarkdown, dodHeading, definitionOfDone);
+  refinedMarkdown = appendSection(refinedMarkdown, COVERAGE_MATRIX_HEADING, coverageMatrix);
+  refinedMarkdown = appendSection(refinedMarkdown, DOCS_GRILL_FINDINGS_HEADING, grillBody);
+
+  // Re-derive the section-presence facts from the text the write just produced
+  // (not from the inputs) so this check actually verifies the append landed: a
+  // correct refine carries the base sections forward and adds both refinement
+  // markers, flipping the intake state to ready. A buggy rewrite that dropped a
+  // section is caught here and fails closed rather than advancing the state.
+  const endState = evaluatePlanFileIntakeState({
+    baseSectionsValid,
+    hasAcceptanceCriteria: hasSection(refinedMarkdown, acHeading),
+    hasDefinitionOfDone: hasSection(refinedMarkdown, dodHeading),
+  }).state;
+  if (endState !== PLAN_FILE_INTAKE_STATE.PLAN_REFINED_READY_FOR_PROMOTION) {
+    return { ok: false, reason: "refine_did_not_reach_ready", planFileIntakeState: endState };
+  }
+
+  return {
+    ok: true,
+    planFileIntakeState: endState,
+    refinedMarkdown,
+    grillDispositions,
+    // Generalized proposal-first stop: the refined plan is the local artifact,
+    // it is written in-place, and the loop stops here for human review before
+    // any promotion. No tracker artifact is created or mutated.
+    stop: { kind: PLAN_FILE_REFINE_STOP.LOCAL_HUMAN_REVIEW },
+  };
+}

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

@@ -119,6 +119,19 @@ function normalizeMergeStateStatus(value) {
   return value.trim().toUpperCase();
 }
 
+function normalizeMergeable(value) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    return null;
+  }
+
+  const upper = value.trim().toUpperCase();
+  if (upper === "MERGEABLE" || upper === "CONFLICTING" || upper === "UNKNOWN") {
+    return upper;
+  }
+
+  return null;
+}
+
 function normalizeConflictFiles(value) {
   if (!Array.isArray(value)) {
     return [];
@@ -142,14 +155,18 @@ function hasBlockedMergeStatus(mergeStateStatus) {
   return mergeStateStatus !== null && BLOCKED_MERGE_STATE_STATUSES.has(mergeStateStatus);
 }
 
-function formatBlockedMergeReason(mergeStateStatus, conflictFiles) {
+function formatBlockedMergeReason(mergeStateStatus, conflictFiles, mergeable = null) {
   if (mergeStateStatus === "BEHIND") {
     let reason = "Branch must be updated from base before entering any gate.";
     reason += ` GitHub mergeStateStatus: ${mergeStateStatus}.`;
     return reason;
   }
 
-  let reason = "The current branch conflicts with the base branch, so resolve the conflict locally on the PR branch, rerun validation, rerun gate detection, and only then resume the normal gate path.";
+  let reason = "The current branch conflicts with the base branch, so resolve the conflict locally on the PR branch (run `node scripts/loop/resolve-pr-conflicts.mjs --push` for the safe additive-CHANGELOG case), rerun validation, rerun gate detection, and only then resume the normal gate path.";
+
+  if (mergeable === "CONFLICTING") {
+    reason += " GitHub mergeable: CONFLICTING.";
+  }
 
   if (mergeStateStatus !== null) {
     reason += ` GitHub mergeStateStatus: ${mergeStateStatus}.`;
@@ -218,7 +235,23 @@ function buildRoundExhaustionGateEvidenceNote({ copilotReviewRoundCount, maxCopi
   return `Copilot review rounds exhausted (${copilotReviewRoundCount}/${maxCopilotRounds}); current head has zero unresolved threads and green or credibly green CI, so pre_approval_gate fallback is allowed without another Copilot re-request.`;
 }
 
-function evaluateRetrospectiveMergeApproval(checkpoint) {
+/**
+ * Render the (user-authored) rawCallViolations array into a bounded, single-line
+ * fragment for the gate failure reason. Collapses whitespace/newlines per entry,
+ * caps per-entry length, and caps the number of entries shown so a large or
+ * garbled checkpoint cannot bloat or break gate output. Still fails closed —
+ * this only formats the reason; the violation count above does the gating.
+ */
+function summarizeRawCallViolations(violations, { maxEntries = 10, maxEntryLen = 200 } = {}) {
+  const shown = violations.slice(0, maxEntries).map((v) => {
+    const flat = String(v).replace(/\s+/g, " ").trim();
+    return flat.length > maxEntryLen ? `${flat.slice(0, maxEntryLen)}…` : flat;
+  });
+  const more = violations.length - shown.length;
+  return more > 0 ? `${shown.join("; ")}; …(+${more} more)` : shown.join("; ");
+}
+
+function evaluateRetrospectiveMergeApproval(checkpoint, { developerMode = false } = {}) {
   if (!checkpoint || typeof checkpoint !== "object") {
     return { approved: false, reason: "No retrospective checkpoint was found." };
   }
@@ -278,6 +311,37 @@ function evaluateRetrospectiveMergeApproval(checkpoint) {
     return { approved: false, reason: "Retrospective is missing explicit `mergeRecommendation`." };
   }
 
+  // internalToolingOnly: the loop's own execution must have used internal dev-loops
+  // tooling only — no agent-level raw `gh`/`python`/`python3`/`node -e` (issue #982).
+  // This is a DEVELOPER-MODE retro step: it enforces the dev-loops maintainers'
+  // own dogfooding discipline and is opt-in via `workflow.requireRetrospectiveInternalTooling`
+  // (default OFF). CONSUMERS of the extension are never blocked by it — they may
+  // legitimately use raw gh/python/node -e in their own workflow — so when the flag
+  // is OFF these fields are neither required nor enforced (a complete checkpoint
+  // without them passes exactly as it did before #982). When ON it fails closed:
+  // a complete checkpoint must explicitly attest a clean tooling record, and an OLD
+  // checkpoint missing `internalToolingOnly` fails (not a silent pass). Re-record the
+  // retrospective with the new fields to clear it.
+  if (developerMode) {
+    const internalToolingOnly = br !== null ? br.internalToolingOnly : checkpoint.internalToolingOnly;
+    if (internalToolingOnly !== true) {
+      return {
+        approved: false,
+        reason: "Retrospective does not attest internal-tooling-only execution (`internalToolingOnly: true` is required in developer mode; agent-level raw gh/python/node -e is a violation). — re-record the retrospective with internalToolingOnly + rawCallViolations.",
+      };
+    }
+    const rawCallViolations = br !== null ? br.rawCallViolations : checkpoint.rawCallViolations;
+    if (!Array.isArray(rawCallViolations)) {
+      return { approved: false, reason: "Retrospective is missing `rawCallViolations` (array; empty when clean). — re-record the retrospective with internalToolingOnly + rawCallViolations." };
+    }
+    if (rawCallViolations.length > 0) {
+      return {
+        approved: false,
+        reason: `Retrospective records ${rawCallViolations.length} raw-call violation(s) (agent-level gh/python/node -e): ${summarizeRawCallViolations(rawCallViolations)}.`,
+      };
+    }
+  }
+
   return { approved: true, reason: null };
 }
 
@@ -610,6 +674,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
     ? "internal_only"
     : (typeof input.reviewMode === "string" ? input.reviewMode.trim().toLowerCase() : null);
   const mergeStateStatus = normalizeMergeStateStatus(input.mergeStateStatus);
+  const mergeable = normalizeMergeable(input.mergeable);
   const conflictFiles = normalizeConflictFiles(input.conflictFiles);
   const ciStatus = normalizeCiStatus(input.ciStatus);
   const draftGateRequireCi = input.draftGateRequireCi !== false;
@@ -617,6 +682,9 @@ function evaluatePrGateCoordinationCore(input = {}) {
   const maxCopilotRounds = normalizePositiveInteger(input.maxCopilotRounds);
   const roundCapReached = maxCopilotRounds !== null && copilotReviewRoundCount >= maxCopilotRounds;
   const requireRetrospectiveGate = input.requireRetrospectiveGate === true;
+  // Developer-mode flag (#982): only the dev-loops repo dogfooding itself enforces the
+  // internal-tooling-only retro discipline. Default OFF so consumer state changes pass.
+  const requireRetrospectiveInternalTooling = input.requireRetrospectiveInternalTooling === true;
   const retrospectiveCheckpoint = input.retrospectiveCheckpoint;
   const prTitle = typeof input.prTitle === "string" ? input.prTitle : "";
   const refinementArtifact = input.refinementArtifact && typeof input.refinementArtifact === "object"
@@ -694,7 +762,44 @@ function evaluatePrGateCoordinationCore(input = {}) {
     });
   }
 
-  if (hasBlockedMergeStatus(mergeStateStatus) || conflictFiles.length > 0) {
+  // Mergeability is a required precondition at every gate (issue #980). GitHub
+  // computes `mergeable` asynchronously, so an unsettled UNKNOWN must fail closed
+  // to a recheck — never a pass. The detect layer already re-polls a bounded
+  // number of times; if it still reads UNKNOWN here, hold gate progression and
+  // recheck rather than guess.
+  if (mergeable === "UNKNOWN") {
+    pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.WAIT_FOR_CI]);
+    pushUnique(forbiddenActions, [
+      PR_CHECKPOINT_ACTION.RUN_DRAFT_GATE,
+      PR_CHECKPOINT_ACTION.RECONCILE_DRAFT_GATE,
+      PR_CHECKPOINT_ACTION.MARK_READY_FOR_REVIEW,
+      PR_CHECKPOINT_ACTION.REQUEST_COPILOT_REVIEW,
+      PR_CHECKPOINT_ACTION.RUN_PRE_APPROVAL_GATE,
+      PR_CHECKPOINT_ACTION.AWAIT_FINAL_HUMAN_APPROVAL,
+      PR_CHECKPOINT_ACTION.DECLARE_MERGE_READY,
+    ]);
+    return buildResult({
+      repo: input.repo ?? null,
+      pr: Number.isInteger(input.pr) ? input.pr : null,
+      currentHeadSha,
+      lifecycleState: effectiveLifecycleState,
+      loopDisposition: DISPOSITION.PENDING,
+      gateBoundary: PR_CHECKPOINT.CONFLICT_RESOLUTION,
+      draftGateAlreadySatisfied,
+      draftGate,
+      preApprovalGate,
+      allowedNextActions,
+      forbiddenActions,
+      nextAction: PR_CHECKPOINT_ACTION.WAIT_FOR_CI,
+      reason: "GitHub has not yet computed mergeability (mergeable=UNKNOWN), so gate progression is held: recheck before proceeding rather than treating an unsettled merge state as clean.",
+      mergeStateStatus,
+      conflictFiles,
+      refinementArtifact,
+      copilotReviewRoundCount,
+    });
+  }
+
+  if (hasBlockedMergeStatus(mergeStateStatus) || mergeable === "CONFLICTING" || conflictFiles.length > 0) {
     pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.RESOLVE_MERGE_CONFLICTS]);
     pushUnique(forbiddenActions, [
       PR_CHECKPOINT_ACTION.RUN_DRAFT_GATE,
@@ -723,7 +828,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
       allowedNextActions,
       forbiddenActions,
       nextAction: PR_CHECKPOINT_ACTION.RESOLVE_MERGE_CONFLICTS,
-      reason: formatBlockedMergeReason(mergeStateStatus, conflictFiles),
+      reason: formatBlockedMergeReason(mergeStateStatus, conflictFiles, mergeable),
       mergeStateStatus,
       conflictFiles,
         refinementArtifact,
@@ -911,7 +1016,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
           });
         }
         if (requireRetrospectiveGate) {
-          const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint);
+          const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint, { developerMode: requireRetrospectiveInternalTooling });
           if (!retrospectiveGate.approved) {
             return buildRetrospectiveGatePendingResult({
               input,
@@ -1183,7 +1288,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         });
       }
       if (requireRetrospectiveGate) {
-        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint);
+        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint, { developerMode: requireRetrospectiveInternalTooling });
         if (!retrospectiveGate.approved) {
           return buildRetrospectiveGatePendingResult({
             input,
@@ -1349,7 +1454,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         });
       }
       if (requireRetrospectiveGate) {
-        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint);
+        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint, { developerMode: requireRetrospectiveInternalTooling });
         if (!retrospectiveGate.approved) {
           return buildRetrospectiveGatePendingResult({
             input,
@@ -1509,7 +1614,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         });
       }
       if (requireRetrospectiveGate) {
-        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint);
+        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint, { developerMode: requireRetrospectiveInternalTooling });
         if (!retrospectiveGate.approved) {
           return buildRetrospectiveGatePendingResult({
             input,

package/src/loop/spike-exit-contract.mjs

@@ -0,0 +1,138 @@
+/**
+ * Spike-mode exit (P2 of the spike-mode track #965).
+ *
+ * Phase 1 (#964) shipped the spike intake state machine
+ * (`evaluateSpikeIntakeState` → SPIKE_INTAKE_STATE). A spike becomes exitable
+ * only once it carries a Recommendation (`spike_ready_for_exit`). This module is
+ * the exit decision: from that ready state, the operator picks a disposition —
+ *   - DISCARD  — the recommendation is "don't pursue"; drop the spike with ZERO
+ *                tracker artifacts (the findings doc is the whole record).
+ *   - GRADUATE — promote the exploration into a #947-consumable plan file
+ *                (Status/Objective/In scope/Explicit non-goals) built from the
+ *                spike's Question/Approach/Findings/Recommendation, which then
+ *                enters the existing local-first plan→PR promotion path (#952).
+ *
+ * Pure: no fs/network/gh, no `scripts/` import (mirrors spike-intake-contract
+ * and plan-file-promote-contract). The CLI (`scripts/refine/exit-spike.mjs`)
+ * owns all I/O. Fail-closed on an unknown disposition or a non-ready state so
+ * the CLI makes zero mutation on those paths.
+ */
+
+import { SPIKE_INTAKE_STATE } from "./spike-intake-contract.mjs";
+
+/** Dispositions the operator can choose at a ready spike's exit. */
+export const SPIKE_EXIT_DISPOSITION = Object.freeze({
+  /** Drop the spike with no tracker artifact (recommendation: don't pursue). */
+  DISCARD: "discard",
+  /** Promote into a plan file consumable by the #947 local-first flow. */
+  GRADUATE: "graduate",
+});
+
+/** Actions the exit decision can return (1:1 with the eligible dispositions). */
+export const SPIKE_EXIT_ACTION = Object.freeze({
+  DISCARD: "discard",
+  GRADUATE: "graduate",
+});
+
+const DISPOSITION_TO_ACTION = Object.freeze({
+  [SPIKE_EXIT_DISPOSITION.DISCARD]: SPIKE_EXIT_ACTION.DISCARD,
+  [SPIKE_EXIT_DISPOSITION.GRADUATE]: SPIKE_EXIT_ACTION.GRADUATE,
+});
+
+/**
+ * Pure exit-eligibility decision.
+ *
+ * Eligible ONLY from `spike_ready_for_exit` (a Recommendation has been reached).
+ * Any other state — in-progress or ambiguous — fails closed with
+ * `not_ready_for_exit` and no action; the CLI must make zero tracker mutation.
+ * An unrecognized disposition fails closed with `unknown_disposition`.
+ *
+ * @param {object} facts
+ * @param {string} facts.spikeIntakeState  one of SPIKE_INTAKE_STATE values (from evaluateSpikeIntakeState)
+ * @param {string} facts.disposition  one of SPIKE_EXIT_DISPOSITION values
+ * @returns {{ ok: boolean, action?: string, reason?: string, spikeIntakeState?: string | null }}
+ */
+export function evaluateSpikeExit({ spikeIntakeState, disposition } = {}) {
+  // The ready gate: an exit decision is only meaningful once a recommendation
+  // exists. Fail closed otherwise — never guess an exit for an in-progress or
+  // malformed spike.
+  if (spikeIntakeState !== SPIKE_INTAKE_STATE.SPIKE_READY_FOR_EXIT) {
+    return { ok: false, reason: "not_ready_for_exit", spikeIntakeState: spikeIntakeState ?? null };
+  }
+
+  // Own-property check: a bare index lookup would also match inherited
+  // Object.prototype keys (`toString`, `__proto__`, `constructor`), letting an
+  // unknown disposition resolve to a truthy value and bypass the fail-closed
+  // contract. Require a string that is an own key of the map.
+  if (typeof disposition !== "string" || !Object.hasOwn(DISPOSITION_TO_ACTION, disposition)) {
+    return { ok: false, reason: "unknown_disposition", spikeIntakeState };
+  }
+  const action = DISPOSITION_TO_ACTION[disposition];
+
+  return { ok: true, action, spikeIntakeState };
+}
+
+/**
+ * Build a #947-consumable plan-file body from a ready spike's sections.
+ *
+ * The emitted body carries the four base authoring sections the plan-file
+ * format requires (Status / Objective / In scope / Explicit non-goals — see
+ * scripts/refine/validate-plan-file.mjs), so it passes `validatePlanFile` and
+ * enters the existing local-first plan→PR promotion path (#952) unchanged.
+ *
+ * The spike sections map onto the plan as: the Question + Approach become the
+ * Objective's context, the Recommendation becomes the In-scope work, the
+ * Findings record the evidence, and a fixed non-goal keeps the plan from
+ * re-opening the (now-concluded) exploration. Status starts as Draft.
+ *
+ * Idempotent and pure: same input → identical output, no side effects. Fails
+ * closed (throws) on an empty required section so a graduate exit cannot emit a
+ * plan that the validator would reject.
+ *
+ * @param {object} sections
+ * @param {string} sections.question
+ * @param {string} sections.approach
+ * @param {string} sections.findings
+ * @param {string} sections.recommendation
+ * @returns {string} markdown plan-file body
+ */
+export function buildGraduatedPlanBody({ question, approach, findings, recommendation } = {}) {
+  const q = String(question ?? "").trim();
+  const a = String(approach ?? "").trim();
+  const f = String(findings ?? "").trim();
+  const r = String(recommendation ?? "").trim();
+  if (q.length === 0) throw new Error("buildGraduatedPlanBody requires a non-empty question");
+  if (a.length === 0) throw new Error("buildGraduatedPlanBody requires a non-empty approach");
+  if (f.length === 0) throw new Error("buildGraduatedPlanBody requires non-empty findings");
+  if (r.length === 0) throw new Error("buildGraduatedPlanBody requires a non-empty recommendation");
+
+  return [
+    "# Graduated spike plan",
+    "",
+    "## Status",
+    "",
+    "Draft (graduated from a spike). Needs refinement before promotion.",
+    "",
+    "## Objective",
+    "",
+    `Act on the spike's recommendation. The spike asked: ${q}`,
+    "",
+    "Approach explored:",
+    "",
+    a,
+    "",
+    "## In scope",
+    "",
+    r,
+    "",
+    "Supporting findings from the spike:",
+    "",
+    f,
+    "",
+    "## Explicit non-goals",
+    "",
+    "- Re-running the spike's exploration; that question is concluded.",
+    "- Work beyond the recommendation above.",
+    "",
+  ].join("\n");
+}

package/src/loop/spike-intake-contract.mjs

@@ -0,0 +1,52 @@
+/**
+ * Spike-mode intake state machine.
+ *
+ * A `--spike` startup hands the dev-loop a time-boxed, exploratory artifact that
+ * lives outside the tracker — startable from a local question with no GitHub
+ * issue. A spike is NOT a plan-needing-refinement, so its states are distinct
+ * from PLAN_FILE_INTAKE_STATE: it classifies how far the exploration has
+ * progressed toward an exit decision, not how far a plan has progressed toward
+ * promotion.
+ *
+ * This evaluator mirrors `evaluatePlanFileIntakeState`: a frozen enum plus a
+ * pure, deterministic function with no GitHub or filesystem side effects — the
+ * caller supplies the section-presence facts it has already read.
+ *
+ * The two non-ambiguous states are the seam phase 2 (#965) consumes for its
+ * discard/graduate exits:
+ *   - SPIKE_IN_PROGRESS    — exploration ongoing (no recommendation yet); a
+ *                            discard exit can drop it with no artifact.
+ *   - SPIKE_READY_FOR_EXIT — a recommendation has been reached; phase 2 routes
+ *                            this to graduate (promote into a plan/PR) or
+ *                            discard (recommendation is "don't pursue").
+ */
+
+export const SPIKE_INTAKE_STATE = Object.freeze({
+  /** Valid spike artifact; the Recommendation is not yet reached. */
+  SPIKE_IN_PROGRESS: "spike_in_progress",
+  /** Valid spike artifact carrying a Recommendation; an exit decision can be made. */
+  SPIKE_READY_FOR_EXIT: "spike_ready_for_exit",
+  /** Inputs are malformed or unusable; fail closed. */
+  AMBIGUOUS_FAIL_CLOSED: "ambiguous_fail_closed",
+});
+
+/**
+ * Pure intake-state classifier.
+ *
+ * @param {object} facts
+ * @param {boolean} facts.baseSectionsValid  whether the spike's exploration scaffold (Question/Approach/Findings) is present and non-empty. Recommendation is NOT part of this fact — it is the separate exit-marker carried by `hasRecommendation`, so that a scaffold-valid spike without a Recommendation classifies as in-progress rather than failing closed.
+ * @param {boolean} facts.hasRecommendation  whether a non-empty Recommendation section is present (the exit-marker that flips in-progress → ready-for-exit)
+ * @returns {{ state: string }} one of SPIKE_INTAKE_STATE values
+ */
+export function evaluateSpikeIntakeState({ baseSectionsValid, hasRecommendation } = {}) {
+  // A malformed spike artifact (missing/empty base sections) is unusable intake
+  // input; fail closed instead of guessing an exit.
+  if (baseSectionsValid !== true) {
+    return { state: SPIKE_INTAKE_STATE.AMBIGUOUS_FAIL_CLOSED };
+  }
+  return {
+    state: hasRecommendation === true
+      ? SPIKE_INTAKE_STATE.SPIKE_READY_FOR_EXIT
+      : SPIKE_INTAKE_STATE.SPIKE_IN_PROGRESS,
+  };
+}