@dev-loops/core 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "0.4.0",
+  "version": "0.6.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,9 +51,12 @@
     "./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",
+    "./loop/ui-e2e-scoping": "./src/loop/ui-e2e-scoping.mjs",
     "./refinement/ac-dod-matrix": "./src/refinement/ac-dod-matrix.mjs",
     "./harness": "./src/harness/index.mjs",
     "./loop/worktree-guard": "./src/loop/worktree-guard.mjs",

package/src/claude/asset-generation.mjs

@@ -169,6 +169,32 @@ export function transformAgent({ source, raw, version = "latest" }) {
   return `${lines.join("\n")}\n${body}`;
 }
 
+/**
+ * Transform a canonical `commands/<name>.command.md` into a Claude `.claude/commands/<name>.md`
+ * slash command (#972). Commands are thin wrappers over the public dev-loop contract: the body
+ * is a prompt (with `$ARGUMENTS`) that invokes the existing entrypoint, so there is NO routing
+ * logic here. Frontmatter keeps Claude's command fields (`description`, `argument-hint`); the body
+ * is passed through `stripPiOnlyBlocks` + `rewriteCliInvocation` like agents/skills.
+ * @param {{ source: string, raw: string, version?: string }} input
+ * @returns {string} Full generated file content.
+ */
+export function transformCommand({ source, raw, version = "latest" }) {
+  const { frontmatter, body: rawBody } = splitFrontmatter(raw, source);
+  const body = rewriteCliInvocation(stripPiOnlyBlocks(rawBody), version);
+
+  const lines = ["---"];
+  if (frontmatter.description != null) {
+    lines.push(`description: ${JSON.stringify(String(frontmatter.description))}`);
+  }
+  if (frontmatter["argument-hint"] != null) {
+    lines.push(`argument-hint: ${JSON.stringify(String(frontmatter["argument-hint"]))}`);
+  }
+  lines.push("---");
+  lines.push(GENERATED_NOTE(source));
+  lines.push("");
+  return `${lines.join("\n")}\n${body}`;
+}
+
 /**
  * Transform a canonical `skills/<name>/SKILL.md` into a Claude `.claude/skills/<name>/SKILL.md`.
  * @param {{ source: string, raw: string, version?: string }} input

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/async-start-contract.mjs

@@ -13,6 +13,7 @@
  * Async context marker (required when workflow.asyncStartMode is `required`)
  * — see `@dev-loops/core/loop/run-context`:
  * - DEVLOOPS_RUN_ID env var (neutral, harness-agnostic)
+ * - PI_SUBAGENT_RUN_ID env var (the alias the Pi runtime injects)
  *
  * Allowed modes:
  * - workflow.asyncStartMode: required | allowed
@@ -159,14 +160,20 @@ export function validateAsyncStartContext({
     };
   }
 
-  // No marker found — fail closed
+  // No marker found — fail closed.
+  // Derive the marker hint from ASYNC_CONTEXT_MARKERS (primary first, aliases after)
+  // so the message never drifts from the recognized-marker list.
+  const [primaryMarker, ...aliasMarkers] = ASYNC_CONTEXT_MARKERS;
+  const markerHint = aliasMarkers.length
+    ? `Set ${primaryMarker} (or the ${aliasMarkers.join("/")} alias) to proceed. `
+    : `Set ${primaryMarker} to proceed. `;
   return {
     status: ASYNC_START_STATUS.REJECTED,
     reason:
       "No async context detected. " +
       "The dev-loop must run within a visible async subagent session, " +
       "not as a detached local process. " +
-      `Set ${ASYNC_CONTEXT_MARKERS[0]} to proceed. ` +
+      markerHint +
       "Repository-maintained workflow policy controls any exceptions.",
     detectedMarker: null,
   };

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");
+}