@milehimikey/em 1.14.2 → 1.16.0

package/dist/cli/defer.d.ts

@@ -1,5 +1,6 @@
 import { NormalizedModel } from "../model/model.js";
 import { RefsResult } from "../model/refs.js";
+import { QueuedItem } from "../catalog/deferQueue.js";
 /** `v<int>` → int, else null. */
 export declare function parseUntil(s: string): number | null;
 export interface DeferInput {
@@ -25,6 +26,12 @@ export type ApplyDeferResult = {
  * Already deferred to the same version → `{ok: true, changed: false}` (idempotent no-op).
  */
 export declare function applyDefer(raw: string, input: DeferInput): ApplyDeferResult;
+/** Appends `bullet` at the end of the section under `heading` (before the next `## ` heading or
+ *  EOF, after the section's last non-blank line) unless an identical bullet line exists. */
+export declare function appendBullet(lines: string[], heading: RegExp, bullet: string, eol: string): {
+    lines: string[];
+    changed: boolean;
+} | null;
 export interface StateMirrorInput {
     question: string;
     sliceKey: string;
@@ -36,20 +43,117 @@ export interface StateMirrorInput {
 }
 /** Pure: mirrors the deferral into the state file's parking lot and Decisions log. */
 export declare function applyDeferStateFile(raw: string, input: StateMirrorInput): ApplyDeferResult;
-/** Pure (reratify): re-opens every `- [x] … — v<old>: …; deferred to v<newVersion> (…)` item under
+/** Pure (revise): re-opens every `- [x] … — v<old>: …; deferred to v<newVersion> (…)` item under
  *  `## Open Questions` as `- [ ] <original text>`. Items deferred to a later version are untouched. */
 export declare function reopenDeferred(raw: string, newVersion: number): {
     content: string;
     count: number;
 };
+/** True when the doc's body is a signed spec that defer must not touch: `status: implemented`, or
+ *  `status: ready-to-implement` with a `ratifiedBy:`. A `draft`/`reviewed` doc — including the
+ *  next version of a shipped slice — is still being written, so defer edits it as ever. */
+export declare function isLockedDoc(raw: string): boolean;
+/** Pure: mirrors a QUEUED deferral into the state file — the queued parking-lot bullet and a
+ *  dated Decisions-log bullet. Idempotent on an identical bullet. */
+export declare function applyQueueStateFile(raw: string, input: StateMirrorInput): ApplyDeferResult;
+/** Pure (revise / mark-implemented): appends every queued item to `## Open Questions` of the
+ *  freshly opened draft (creating the section at EOF when the doc has none), skipping a line
+ *  already present. Returns how many items were written. */
+export declare function injectQueuedQuestions(raw: string, items: QueuedItem[]): {
+    content: string;
+    count: number;
+};
+/** Pure: "clears" the queue for `<sliceKey>@v<targetVersion>` in the state file — each queued
+ *  parking-lot bullet becomes the ordinary `- <q> (from slice <key>, deferred to v<until>)`
+ *  mirror a draft-doc defer writes. Other slices' and other versions' bullets are untouched. */
+export declare function drainQueueInState(raw: string, sliceKey: string, targetVersion: number): {
+    content: string;
+    count: number;
+};
+/** Reads the queue for `<sliceKey>@v<targetVersion>` from `<baseDir>/.event-modeling.md`; empty
+ *  when the file is absent. */
+export declare function readQueue(baseDir: string, sliceKey: string, targetVersion: number): {
+    items: QueuedItem[];
+    statePath: string;
+    stateRaw: string | null;
+};
+/** Writes the drained state file once the draft carrying the queue is on disk. */
+export declare function clearQueue(baseDir: string, sliceKey: string, targetVersion: number): void;
+/** An open `issue "..."` clause on one of the slice's own elements. */
+export interface IssueCandidate {
+    kind: string;
+    name: string;
+    /** The element's declaration line in the `.em` (1-based) — where the clause search starts. */
+    line: number;
+    issue: string;
+}
+/** Open issues on the slice's own elements whose text contains `text` (case-sensitive substring,
+ *  the same matching the positional path applies to Open Questions). An issue on a sibling
+ *  slice's element is never a candidate — the deferral lands on THIS slice's doc. */
+export declare function findIssueCandidates(model: NormalizedModel, sliceIndex: number, text: string): IssueCandidate[];
+export declare function formatIssueCandidate(c: IssueCandidate): string;
+export type RemoveIssueResult = {
+    ok: true;
+    content: string;
+    removedLine: number;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Pure: removes the one `issue "<issueText>"` clause that belongs to the element declared at
+ * `startLine` (1-based). The clause may sit on the declaration line or trail the element's
+ * `{ … }` field block (parser.ts's `extractClauses` accepts both), so the scan runs forward from
+ * `startLine` and stops at the first line carrying an `issue` clause that decodes to
+ * `issueText`. The clause span (plus the one whitespace run before it) is cut out of that line;
+ * when nothing but whitespace is left, the whole line goes, EOL included. Everything else —
+ * other clauses on the line, every other line, the file's EOL style — is copied through
+ * verbatim. The caller re-parses the result before accepting it (`runDeferFromIssue`).
+ */
+export declare function removeIssueClause(raw: string, startLine: number, issueText: string): RemoveIssueResult;
+/**
+ * Pure: records `issueText` on the doc as an already-deferred Open Question. If an unchecked
+ * item containing the text already exists (someone wrote it down by hand), that item is deferred
+ * in place via `applyDefer` — never a duplicate. Otherwise the `[x]` item is appended to
+ * `## Open Questions`, creating the section at EOF when the doc has none (a pre-template doc).
+ * An identical item already present → `changed: false`.
+ */
+export declare function applyDeferFromIssueDoc(raw: string, issueText: string, input: Omit<DeferInput, "question">): ApplyDeferResult;
 export type RunDeferResult = {
     ok: true;
     path: string;
     changed: boolean;
+    queued: QueuedNote | null;
 } | {
     ok: false;
     message: string;
 };
-/** Resolves `sliceKey` to its bound doc (same join as ratify/reratify), computes both edits, and
+/** GH #236: set when defer QUEUED the question (a ratified/shipped doc) instead of editing the
+ *  doc — `forVersion` is the draft that will carry it, `docVersion` the version left untouched. */
+export interface QueuedNote {
+    forVersion: number;
+    docVersion: number;
+}
+/** Resolves `sliceKey` to its bound doc (same join as ratify/revise), computes both edits, and
  *  writes only when every precondition holds (the state file is required and never created). */
 export declare function runDefer(model: NormalizedModel, refs: RefsResult, baseDir: string, sliceKey: string, input: Omit<DeferInput, "currentVersion">): RunDeferResult;
+export type RunDeferFromIssueResult = {
+    ok: true;
+    path: string;
+    changed: boolean;
+    issue: string;
+    modelLine: number | null;
+    queued: QueuedNote | null;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * `--from-issue <text>` (MIL-281): the single open `issue "..."` on one of the slice's own
+ * elements whose text contains `text` becomes a deferred Open Question on the doc, is mirrored
+ * into the state file, and its clause is removed from `modelFile`. All three edits are computed
+ * first; nothing is written unless every one succeeds. Zero candidates with the question already
+ * deferred on the doc → the idempotent no-op; zero otherwise → refuse; two or more → refuse
+ * naming each with its `.em` line.
+ */
+export declare function runDeferFromIssue(model: NormalizedModel, refs: RefsResult, baseDir: string, modelFile: string, sliceKey: string, text: string, input: Omit<DeferInput, "question" | "currentVersion">): RunDeferFromIssueResult;

package/dist/cli/defer.js

@@ -2,17 +2,41 @@
 // `em slice defer` (MIL-275): the missing verb behind docs/process.md's "resolved or explicitly
 // deferred". Rewrites ONE unchecked `## Open Questions` item as a checked, dated "deferred to
 // v<n>" item, and mirrors it into the model's `.event-modeling.md` (the `## Open questions /
-// parking lot` bullet and a dated `## Decisions log` bullet), idempotently. `em slice reratify`
-// reads the `deferred to v<n>` marker back and re-opens the item (`reopenDeferred`, below).
+// parking lot` bullet and a dated `## Decisions log` bullet), idempotently. `em slice revise`
+// (and `mark-implemented`'s auto-open, MIL-283) reads the `deferred to v<n>` marker back and re-opens the item (`reopenDeferred`, below).
 //
-// Write strategy: surgical line edits (the same discipline as ratify.ts/reratify.ts) — every
+// Write strategy: surgical line edits (the same discipline as ratify.ts/revise.ts) — every
 // byte outside the edited line / appended bullet, including the file's own EOL style, is copied
 // through verbatim. Pure `apply*` functions here; the fs orchestration (`runDefer`) is thin.
+//
+// MIL-281 — `--from-issue`: the question a review session actually produces is an `issue "..."`
+// clause in the `.em` (what the walkthrough captures live, what `em validate --list-issues`
+// lists), not an item under the doc's `## Open Questions`; defer could only see the latter, so a
+// room-raised question took a hand edit of the doc before it could be deferred. `--from-issue
+// <text>` promotes the single matching open issue on the slice's own elements into the doc as an
+// already-deferred `[x]` item, mirrors it into the state file exactly like the positional path,
+// and REMOVES the `issue` clause from the `.em` — the deferral record replaces the red note, so
+// the diagram stops flagging a question the doc now tracks with a return path. Three files, all
+// computed before any is written; the `.em` edit is a single clause span (or the whole line when
+// the clause was alone on it), re-parsed before it is accepted. Not a generic "move issue to doc"
+// verb: the only thing a promoted issue can become is a deferred question.
+//
+// GH #236 — a RATIFIED or SHIPPED doc is never edited by defer. Its body is the signed spec
+// (`ratifiedHash`), so on `status: ready-to-implement` + `ratifiedBy:` or `status: implemented`
+// both paths QUEUE the question instead: one bullet in the state file's parking lot plus the dated
+// Decisions-log bullet, the doc untouched (catalog/deferQueue.ts has the bullet format).
+// `revise`/`mark-implemented` inject the queue into the v<N+1> draft they open
+// (`injectQueuedQuestions`) and `drainQueueInState` turns the bullets back into ordinary
+// deferral mirrors. `draft`/`reviewed` docs behave exactly as before.
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { continuationOf } from "../model/continuation.js";
 import { resolveSliceDocJoin } from "../catalog/docJoin.js";
+import { decodeQuoted, matchQuote } from "../parser/lexer.js";
+import { compile } from "../pipeline.js";
 import { STATE_FILE_NAME } from "./stateFile.js";
+import { fieldLineRegex, locateFrontmatterInner, normalizeFieldValue } from "./frontmatterSurgery.js";
+import { parseQueuedBullet, queuedBullet, queuedItems } from "../catalog/deferQueue.js";
 const OPEN_QUESTIONS_HEADING = /^##\s+Open Questions\s*$/i;
 const TASK_ITEM = /^([ \t]*[-*]\s*)\[([ xX])\](.*)$/;
 const PARKING_LOT_HEADING = /^##\s+Open questions \/ parking lot\s*$/i;
@@ -115,7 +139,7 @@ export function applyDefer(raw, input) {
 }
 /** Appends `bullet` at the end of the section under `heading` (before the next `## ` heading or
  *  EOF, after the section's last non-blank line) unless an identical bullet line exists. */
-function appendBullet(lines, heading, bullet, eol) {
+export function appendBullet(lines, heading, bullet, eol) {
     const start = lines.findIndex((l) => heading.test(stripEol(l).body));
     if (start === -1)
         return null;
@@ -135,7 +159,9 @@ function appendBullet(lines, heading, bullet, eol) {
     const out = lines.slice();
     if (out[last] !== undefined && !/\n$/.test(out[last]))
         out[last] = out[last] + eol;
-    out.splice(last + 1, 0, bullet + eol);
+    // An empty section (nothing but the heading) keeps a blank line between heading and first
+    // item — the shape the slice-doc template and every hand-written section use.
+    out.splice(last + 1, 0, ...(last === start ? [eol, bullet + eol] : [bullet + eol]));
     return { lines: out, changed: true };
 }
 /** Pure: mirrors the deferral into the state file's parking lot and Decisions log. */
@@ -154,7 +180,7 @@ export function applyDeferStateFile(raw, input) {
         return { ok: false, message: `${STATE_FILE_NAME} has no "## Decisions log" heading` };
     return { ok: true, content: b.lines.join(""), changed: a.changed || b.changed };
 }
-/** Pure (reratify): re-opens every `- [x] … — v<old>: …; deferred to v<newVersion> (…)` item under
+/** Pure (revise): re-opens every `- [x] … — v<old>: …; deferred to v<newVersion> (…)` item under
  *  `## Open Questions` as `- [ ] <original text>`. Items deferred to a later version are untouched. */
 export function reopenDeferred(raw, newVersion) {
     const lines = splitKeepEol(raw);
@@ -182,9 +208,204 @@ export function reopenDeferred(raw, newVersion) {
     }
     return { content: lines.join(""), count };
 }
-/** Resolves `sliceKey` to its bound doc (same join as ratify/reratify), computes both edits, and
- *  writes only when every precondition holds (the state file is required and never created). */
-export function runDefer(model, refs, baseDir, sliceKey, input) {
+// ---- GH #236: the queue for a ratified / shipped doc --------------------------------------
+/** True when the doc's body is a signed spec that defer must not touch: `status: implemented`, or
+ *  `status: ready-to-implement` with a `ratifiedBy:`. A `draft`/`reviewed` doc — including the
+ *  next version of a shipped slice — is still being written, so defer edits it as ever. */
+export function isLockedDoc(raw) {
+    const range = locateFrontmatterInner(raw);
+    if (!range)
+        return false;
+    const inner = raw.slice(range.innerStart, range.innerEnd);
+    const statusMatch = fieldLineRegex("status").exec(inner);
+    const status = statusMatch ? normalizeFieldValue(statusMatch[2])?.toLowerCase() : null;
+    if (status === "implemented")
+        return true;
+    if (status !== "ready-to-implement")
+        return false;
+    const by = fieldLineRegex("ratifiedBy").exec(inner);
+    return by !== null && normalizeFieldValue(by[2]) !== null;
+}
+/** Pure: mirrors a QUEUED deferral into the state file — the queued parking-lot bullet and a
+ *  dated Decisions-log bullet. Idempotent on an identical bullet. */
+export function applyQueueStateFile(raw, input) {
+    const eol = raw.includes("\r\n") ? "\r\n" : "\n";
+    const target = input.currentVersion + 1;
+    const parking = queuedBullet({
+        question: input.question,
+        sliceKey: input.sliceKey,
+        targetVersion: target,
+        until: input.until,
+        on: input.on,
+        ...(input.by !== undefined ? { by: input.by.trim() } : {}),
+        decision: input.decision.trim(),
+    });
+    const decision = `- ${input.on}: queued "${input.question}" on ${input.sliceKey} for ${input.sliceKey}@v${target} (until v${input.until}) — ` +
+        `v${input.currentVersion}: ${input.decision.trim()}${input.by !== undefined ? ` — by ${input.by.trim()}` : ""}`;
+    let lines = splitKeepEol(raw);
+    const a = appendBullet(lines, PARKING_LOT_HEADING, parking, eol);
+    if (!a)
+        return { ok: false, message: `${STATE_FILE_NAME} has no "## Open questions / parking lot" heading` };
+    lines = a.lines;
+    const b = appendBullet(lines, DECISIONS_HEADING, decision, eol);
+    if (!b)
+        return { ok: false, message: `${STATE_FILE_NAME} has no "## Decisions log" heading` };
+    return { ok: true, content: b.lines.join(""), changed: a.changed || b.changed };
+}
+/** Pure: the Open Questions line a queued item becomes in the v<target> draft. Aimed at the
+ *  draft's own version it is an unchecked `- [ ]` carrying its decision; aimed further out
+ *  (`--until` beyond it) it is the ordinary checked deferral, so the draft is not asked to
+ *  answer what the room already pushed past it. */
+function injectedLine(item) {
+    const prior = item.targetVersion - 1;
+    const who = `${item.on}${item.by !== undefined ? `, ${item.by}` : ""}`;
+    return item.until > item.targetVersion
+        ? `- [x] ${item.question} — v${prior}: ${item.decision}; deferred to v${item.until} (${who})`
+        : `- [ ] ${item.question} — v${prior}: ${item.decision} (queued ${who})`;
+}
+/** Pure (revise / mark-implemented): appends every queued item to `## Open Questions` of the
+ *  freshly opened draft (creating the section at EOF when the doc has none), skipping a line
+ *  already present. Returns how many items were written. */
+export function injectQueuedQuestions(raw, items) {
+    const eol = raw.includes("\r\n") ? "\r\n" : "\n";
+    let content = raw;
+    let count = 0;
+    for (const item of items) {
+        const bullet = injectedLine(item);
+        const appended = appendBullet(splitKeepEol(content), OPEN_QUESTIONS_HEADING, bullet, eol);
+        if (appended) {
+            if (appended.changed)
+                count++;
+            content = appended.lines.join("");
+            continue;
+        }
+        if (content.length > 0 && !/\r?\n$/.test(content))
+            content += eol;
+        if (content.length > 0 && !/(\r?\n){2}$/.test(content))
+            content += eol;
+        content += `## Open Questions${eol}${eol}${bullet}${eol}`;
+        count++;
+    }
+    return { content, count };
+}
+/** Pure: "clears" the queue for `<sliceKey>@v<targetVersion>` in the state file — each queued
+ *  parking-lot bullet becomes the ordinary `- <q> (from slice <key>, deferred to v<until>)`
+ *  mirror a draft-doc defer writes. Other slices' and other versions' bullets are untouched. */
+export function drainQueueInState(raw, sliceKey, targetVersion) {
+    const lines = splitKeepEol(raw);
+    let count = 0;
+    for (let j = 0; j < lines.length; j++) {
+        const { body, eol } = stripEol(lines[j]);
+        const item = parseQueuedBullet(body);
+        if (!item || item.sliceKey !== sliceKey || item.targetVersion !== targetVersion)
+            continue;
+        lines[j] = `- ${item.question} (from slice ${item.sliceKey}, deferred to v${item.until})${eol}`;
+        count++;
+    }
+    return { content: lines.join(""), count };
+}
+/** Reads the queue for `<sliceKey>@v<targetVersion>` from `<baseDir>/.event-modeling.md`; empty
+ *  when the file is absent. */
+export function readQueue(baseDir, sliceKey, targetVersion) {
+    const statePath = join(baseDir, STATE_FILE_NAME);
+    if (!existsSync(statePath))
+        return { items: [], statePath, stateRaw: null };
+    const stateRaw = readFileSync(statePath, "utf8");
+    return { items: queuedItems(stateRaw, sliceKey, targetVersion), statePath, stateRaw };
+}
+/** Writes the drained state file once the draft carrying the queue is on disk. */
+export function clearQueue(baseDir, sliceKey, targetVersion) {
+    const { stateRaw, statePath } = readQueue(baseDir, sliceKey, targetVersion);
+    if (stateRaw === null)
+        return;
+    const drained = drainQueueInState(stateRaw, sliceKey, targetVersion);
+    if (drained.count > 0)
+        writeFileSync(statePath, drained.content, "utf8");
+}
+/** Open issues on the slice's own elements whose text contains `text` (case-sensitive substring,
+ *  the same matching the positional path applies to Open Questions). An issue on a sibling
+ *  slice's element is never a candidate — the deferral lands on THIS slice's doc. */
+export function findIssueCandidates(model, sliceIndex, text) {
+    return model.elements
+        .filter((el) => el.sliceIndex === sliceIndex && el.issue !== undefined && el.issue.includes(text))
+        .map((el) => ({ kind: el.kind, name: el.name, line: el.line, issue: el.issue }));
+}
+export function formatIssueCandidate(c) {
+    return `${c.kind} "${c.name}" :${c.line} issue "${c.issue}"`;
+}
+/**
+ * Pure: removes the one `issue "<issueText>"` clause that belongs to the element declared at
+ * `startLine` (1-based). The clause may sit on the declaration line or trail the element's
+ * `{ … }` field block (parser.ts's `extractClauses` accepts both), so the scan runs forward from
+ * `startLine` and stops at the first line carrying an `issue` clause that decodes to
+ * `issueText`. The clause span (plus the one whitespace run before it) is cut out of that line;
+ * when nothing but whitespace is left, the whole line goes, EOL included. Everything else —
+ * other clauses on the line, every other line, the file's EOL style — is copied through
+ * verbatim. The caller re-parses the result before accepting it (`runDeferFromIssue`).
+ */
+export function removeIssueClause(raw, startLine, issueText) {
+    const lines = splitKeepEol(raw);
+    const keyword = /(?:^|\s)issue\s+(?=")/gi;
+    for (let j = Math.max(0, startLine - 1); j < lines.length; j++) {
+        const { body, eol } = stripEol(lines[j]);
+        keyword.lastIndex = 0;
+        let m;
+        while ((m = keyword.exec(body)) !== null) {
+            const openIdx = m.index + m[0].length;
+            const closeIdx = matchQuote(body, openIdx);
+            if (closeIdx < 0)
+                break; // unterminated — the parser already refused this file
+            if (decodeQuoted(body.slice(openIdx + 1, closeIdx)) !== issueText)
+                continue;
+            const before = body.slice(0, m.index);
+            const after = body.slice(closeIdx + 1);
+            const rest = (before + after).replace(/[ \t]+$/, "");
+            const out = lines.slice();
+            if (rest.trim() === "")
+                out.splice(j, 1);
+            else
+                out[j] = rest + eol;
+            return { ok: true, content: out.join(""), removedLine: j + 1 };
+        }
+    }
+    return { ok: false, message: `no \`issue "${issueText}"\` clause found at or after line ${startLine}` };
+}
+/**
+ * Pure: records `issueText` on the doc as an already-deferred Open Question. If an unchecked
+ * item containing the text already exists (someone wrote it down by hand), that item is deferred
+ * in place via `applyDefer` — never a duplicate. Otherwise the `[x]` item is appended to
+ * `## Open Questions`, creating the section at EOF when the doc has none (a pre-template doc).
+ * An identical item already present → `changed: false`.
+ */
+export function applyDeferFromIssueDoc(raw, issueText, input) {
+    const full = { ...input, question: issueText };
+    const v = validateInput(full);
+    if (!v.ok)
+        return v;
+    const existing = applyDefer(raw, full);
+    if (existing.ok)
+        return existing;
+    if (!existing.message.startsWith("no unchecked Open Question matching"))
+        return existing; // ambiguous / already checked
+    const eol = raw.includes("\r\n") ? "\r\n" : "\n";
+    const bullet = `- [x] ${issueText} — v${input.currentVersion}: ${input.decision.trim()}; deferred to v${v.until} ` +
+        `(${input.on}${input.by !== undefined ? `, ${input.by.trim()}` : ""})`;
+    const lines = splitKeepEol(raw);
+    const appended = appendBullet(lines, OPEN_QUESTIONS_HEADING, bullet, eol);
+    if (appended)
+        return { ok: true, content: appended.lines.join(""), changed: appended.changed };
+    // No `## Open Questions` section at all: open one at the end of the doc.
+    let content = raw;
+    if (content.length > 0 && !/\r?\n$/.test(content))
+        content += eol;
+    if (content.length > 0 && !/(\r?\n){2}$/.test(content))
+        content += eol;
+    content += `## Open Questions${eol}${eol}${bullet}${eol}`;
+    return { ok: true, content, changed: true };
+}
+/** The doc resolution both paths share (same join as ratify/revise): continuation and
+ *  binding refusals, frontmatter validity, the doc's current version. */
+function resolveDeferDoc(model, refs, baseDir, sliceKey) {
     const sliceIndex = refs.sliceKeys.indexOf(sliceKey);
     if (sliceIndex === -1)
         return { ok: false, message: `no slice with export key "${sliceKey}" in this model` };
@@ -214,31 +435,143 @@ export function runDefer(model, refs, baseDir, sliceKey, input) {
             message: `slice doc "${doc.path}" has missing or invalid frontmatter — run \`em validate\` for details`,
         };
     }
-    const full = { ...input, currentVersion: doc.version };
-    const absDoc = join(baseDir, doc.path);
-    const result = applyDefer(readFileSync(absDoc, "utf8"), full);
-    if (!result.ok)
-        return { ok: false, message: `${doc.path}: ${result.message}` };
+    return { ok: true, sliceIndex, path: doc.path, version: doc.version };
+}
+/** The state-file mirror both paths share; refuses (never creates) when the file is absent. */
+function mirrorIntoStateFile(baseDir, sliceKey, question, input, currentVersion, queue = false) {
     const statePath = join(baseDir, STATE_FILE_NAME);
     if (!existsSync(statePath)) {
         return { ok: false, message: `no ${STATE_FILE_NAME} beside the model — defer mirrors into it and never creates it` };
     }
-    const until = parseUntil(input.until);
-    const stateResult = applyDeferStateFile(readFileSync(statePath, "utf8"), {
-        question: input.question,
+    const r = (queue ? applyQueueStateFile : applyDeferStateFile)(readFileSync(statePath, "utf8"), {
+        question,
         sliceKey,
-        until,
+        until: parseUntil(input.until),
         decision: input.decision,
         by: input.by,
         on: input.on,
-        currentVersion: doc.version,
+        currentVersion,
     });
-    if (!stateResult.ok)
-        return stateResult;
+    if (!r.ok)
+        return r;
+    return { ok: true, path: statePath, content: r.content, changed: r.changed };
+}
+/** Resolves `sliceKey` to its bound doc (same join as ratify/revise), computes both edits, and
+ *  writes only when every precondition holds (the state file is required and never created). */
+export function runDefer(model, refs, baseDir, sliceKey, input) {
+    const doc = resolveDeferDoc(model, refs, baseDir, sliceKey);
+    if (!doc.ok)
+        return doc;
+    const absDoc = join(baseDir, doc.path);
+    const docRaw = readFileSync(absDoc, "utf8");
+    // GH #236: a ratified / shipped doc is not edited — the question is queued for v<N+1>.
+    if (isLockedDoc(docRaw)) {
+        const v = validateInput({ ...input, currentVersion: doc.version });
+        if (!v.ok)
+            return { ok: false, message: `${doc.path}: ${v.message}` };
+        const state = mirrorIntoStateFile(baseDir, sliceKey, input.question, input, doc.version, true);
+        if (!state.ok)
+            return state;
+        if (state.changed)
+            writeFileSync(state.path, state.content, "utf8");
+        return { ok: true, path: doc.path, changed: state.changed, queued: { forVersion: doc.version + 1, docVersion: doc.version } };
+    }
+    const result = applyDefer(docRaw, { ...input, currentVersion: doc.version });
+    if (!result.ok)
+        return { ok: false, message: `${doc.path}: ${result.message}` };
+    const state = mirrorIntoStateFile(baseDir, sliceKey, input.question, input, doc.version);
+    if (!state.ok)
+        return state;
     if (result.changed)
         writeFileSync(absDoc, result.content, "utf8");
-    if (stateResult.changed)
-        writeFileSync(statePath, stateResult.content, "utf8");
-    return { ok: true, path: doc.path, changed: result.changed || stateResult.changed };
+    if (state.changed)
+        writeFileSync(state.path, state.content, "utf8");
+    return { ok: true, path: doc.path, changed: result.changed || state.changed, queued: null };
+}
+/**
+ * `--from-issue <text>` (MIL-281): the single open `issue "..."` on one of the slice's own
+ * elements whose text contains `text` becomes a deferred Open Question on the doc, is mirrored
+ * into the state file, and its clause is removed from `modelFile`. All three edits are computed
+ * first; nothing is written unless every one succeeds. Zero candidates with the question already
+ * deferred on the doc → the idempotent no-op; zero otherwise → refuse; two or more → refuse
+ * naming each with its `.em` line.
+ */
+export function runDeferFromIssue(model, refs, baseDir, modelFile, sliceKey, text, input) {
+    if (text.trim() === "")
+        return { ok: false, message: "--from-issue needs the issue's text (a case-sensitive substring)" };
+    const doc = resolveDeferDoc(model, refs, baseDir, sliceKey);
+    if (!doc.ok)
+        return doc;
+    const absDoc = join(baseDir, doc.path);
+    const docRaw = readFileSync(absDoc, "utf8");
+    const locked = isLockedDoc(docRaw);
+    const queued = locked ? { forVersion: doc.version + 1, docVersion: doc.version } : null;
+    const candidates = findIssueCandidates(model, doc.sliceIndex, text);
+    if (candidates.length === 0) {
+        // Already promoted on an earlier run? Then the doc carries it as deferred to this version —
+        // or, on a ratified/shipped doc (GH #236), the state file carries it as queued.
+        if (locked) {
+            if (readQueue(baseDir, sliceKey, doc.version + 1).items.some((q) => q.question.includes(text))) {
+                return { ok: true, path: doc.path, changed: false, issue: text, modelLine: null, queued };
+            }
+            return { ok: false, message: `no open issue matching "${text}" on slice "${sliceKey}" (see \`em validate --list-issues\`)` };
+        }
+        const probe = applyDefer(docRaw, { ...input, question: text, currentVersion: doc.version });
+        if (probe.ok && !probe.changed)
+            return { ok: true, path: doc.path, changed: false, issue: text, modelLine: null, queued: null };
+        if (probe.ok) {
+            // The question is on the doc as a hand-written `- [ ]` item, never on the diagram: that is
+            // the positional form's job.
+            return {
+                ok: false,
+                message: `no open issue matching "${text}" on slice "${sliceKey}" — but ${doc.path} has an unchecked Open Question ` +
+                    `containing it; defer that with the positional form: em slice defer <model> ${sliceKey} "${text}" --until ${input.until} --decision "..."`,
+            };
+        }
+        return { ok: false, message: `no open issue matching "${text}" on slice "${sliceKey}" (see \`em validate --list-issues\`)` };
+    }
+    if (candidates.length > 1) {
+        return { ok: false, message: `ambiguous — matches: ${candidates.map(formatIssueCandidate).join(" | ")}` };
+    }
+    const [cand] = candidates;
+    // GH #236: on a ratified/shipped doc the promoted issue is queued, not written into the body.
+    const docResult = locked
+        ? (() => {
+            const v = validateInput({ ...input, question: cand.issue, currentVersion: doc.version });
+            return v.ok ? { ok: true, content: docRaw, changed: false } : v;
+        })()
+        : applyDeferFromIssueDoc(docRaw, cand.issue, { ...input, currentVersion: doc.version });
+    if (!docResult.ok)
+        return { ok: false, message: `${doc.path}: ${docResult.message}` };
+    const state = mirrorIntoStateFile(baseDir, sliceKey, cand.issue, input, doc.version, locked);
+    if (!state.ok)
+        return state;
+    const emRaw = readFileSync(modelFile, "utf8");
+    const removed = removeIssueClause(emRaw, cand.line, cand.issue);
+    if (!removed.ok)
+        return { ok: false, message: `${modelFile}: ${removed.message}` };
+    // Verify before write: the edited model must still compile, and this issue must be gone from
+    // the slice — the same discipline `em migrate` holds for its own `.em` rewrite. (The candidate
+    // was the slice's only issue containing its own text — a second one would have been ambiguous
+    // above — so "gone" is simply "no element of the slice still carries it".)
+    let clean;
+    try {
+        const after = compile(removed.content);
+        clean =
+            !after.diagnostics.some((d) => d.severity === "error") &&
+                !after.model.elements.some((el) => el.sliceIndex === doc.sliceIndex && el.issue === cand.issue);
+    }
+    catch {
+        clean = false;
+    }
+    if (!clean) {
+        return { ok: false, message: `${modelFile}: removing the issue clause at line ${removed.removedLine} would not leave a clean model — nothing written` };
+    }
+    if (docResult.changed)
+        writeFileSync(absDoc, docResult.content, "utf8");
+    if (state.changed)
+        writeFileSync(state.path, state.content, "utf8");
+    writeFileSync(modelFile, removed.content, "utf8");
+    return { ok: true, path: doc.path, changed: true, issue: cand.issue, modelLine: removed.removedLine, queued };
 }
 //# sourceMappingURL=defer.js.map