@dev-loops/core 0.3.0 → 0.5.0

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 },
+  };
+}