@sabaiway/agent-workflow-kit 14.5.0 → 14.6.0

package/tools/profile-gaps.mjs

@@ -0,0 +1,90 @@
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  RULES_REGIONS,
+  extractRegionBy,
+  readTemplateSpan,
+  planInsert,
+  frontmatterMaxLines,
+  decodeUtf8Strict,
+} from './rules-regions.mjs';
+
+const GAP_ID = 'story-sessions-section';
+const STORY_ID = 'story-sessions';
+const TEMPLATE_CANON = 'template';
+const ENCODING = 'utf8';
+const MISSING_FILE_CODE = 'ENOENT';
+const SINGLE_HEADING = 1;
+const TARGET_PATH = 'docs/ai/agent_rules.md';
+const TEMPLATE_PATH = fileURLToPath(new URL('../references/templates/agent_rules.md', import.meta.url));
+const INSERT_PATH = fileURLToPath(new URL('./rules-insert.mjs', import.meta.url));
+const COMMAND_PREFIX = 'node ';
+const CWD_FLAG = ' --cwd ';
+const VERDICTS = Object.freeze({
+  present: 'present',
+  absent: 'absent',
+  undecidable: 'undecidable',
+});
+const REASONS = Object.freeze({
+  template: 'template',
+  fileAbsent: 'file-absent',
+  fileSymlink: 'file-symlink',
+  fileUnreadable: 'file-unreadable',
+});
+const TEMPLATE_REGIONS = RULES_REGIONS.filter(({ canon }) => canon === TEMPLATE_CANON);
+const STORY_REGION = RULES_REGIONS.find(({ id }) => id === STORY_ID);
+
+const reportUndecidable = (reason) => ({ verdict: VERDICTS.undecidable, reason });
+
+const readSpans = (deps) => {
+  try {
+    const template = deps.readFileSync(TEMPLATE_PATH, ENCODING);
+    const entries = TEMPLATE_REGIONS.map(({ id, headingRe }) => [
+      id, readTemplateSpan(template, headingRe),
+    ]);
+    const spans = Object.fromEntries(entries);
+    if (Object.values(spans).some(({ defect }) => defect)) {
+      return reportUndecidable(REASONS.template);
+    }
+    return { spans };
+  } catch {
+    return reportUndecidable(REASONS.template);
+  }
+};
+
+const readTarget = (root, deps) => {
+  const target = resolve(root, TARGET_PATH);
+  try {
+    const stat = deps.lstatSync(target);
+    if (stat.isSymbolicLink()) return reportUndecidable(REASONS.fileSymlink);
+    if (!stat.isFile()) return reportUndecidable(REASONS.fileUnreadable);
+  } catch (error) {
+    const reason = error?.code === MISSING_FILE_CODE ? REASONS.fileAbsent : REASONS.fileUnreadable;
+    return reportUndecidable(reason);
+  }
+  try {
+    return { text: decodeUtf8Strict(deps.readFileSync(target)) };
+  } catch {
+    return reportUndecidable(REASONS.fileUnreadable);
+  }
+};
+
+const detectStorySessions = ({ root, deps }) => {
+  const template = readSpans(deps);
+  if (template.verdict) return template;
+  const target = readTarget(root, deps);
+  if (target.verdict) return target;
+  const { text } = target;
+  if (extractRegionBy(text, STORY_REGION.headingRe).count === SINGLE_HEADING) {
+    return { verdict: VERDICTS.present };
+  }
+  const result = planInsert({ text, spans: template.spans, cap: frontmatterMaxLines(text) });
+  if (result.refusal) return reportUndecidable(result.refusal);
+  return { verdict: VERDICTS.absent };
+};
+
+const buildInsertPreview = (root) => COMMAND_PREFIX + INSERT_PATH + CWD_FLAG + root;
+
+export const PROFILE_GAPS = Object.freeze([
+  Object.freeze({ id: GAP_ID, detect: detectStorySessions, apply: buildInsertPreview }),
+]);

package/tools/rules-insert.mjs

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+import { lstatSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { writeContainedFileAtomic } from './atomic-write.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { OUTCOME_LINES as LENS_OUTCOME_LINES } from './lens-region.mjs';
+import {
+  RULES_REGIONS, readTemplateSpan, planInsert, frontmatterMaxLines, decodeUtf8Strict,
+} from './rules-regions.mjs';
+
+const LF = String.fromCharCode(10);
+const BACKSLASH = String.fromCharCode(92);
+const BACKTICK = String.fromCharCode(96);
+const JSON_RADIX = 16;
+const JSON_ESCAPE_WIDTH = 4;
+const JSON_ESCAPE_PAD = '0';
+const FIRST_CODE_POINT = 0;
+const ARGV_OFFSET = 2;
+const UTF8 = 'utf8';
+const ABSENT_CODE = 'ENOENT';
+const EXIT_SUCCESS = 0;
+const EXIT_REFUSAL = 1;
+const EXIT_USAGE = 2;
+const FLAG_PREFIX = '--';
+const CWD_FLAG = '--cwd';
+const APPLY_FLAG = '--apply';
+const FLAGS = Object.freeze({ [CWD_FLAG]: 'cwd', [APPLY_FLAG]: 'apply' });
+const TEMPLATE_CANON = 'template';
+const REGIONS = RULES_REGIONS.filter(({ canon }) => canon === TEMPLATE_CANON);
+const TARGET_RELATIVE = 'docs/ai/agent_rules.md';
+const TEMPLATE_PATH = resolve(
+  dirname(fileURLToPath(import.meta.url)), '..', 'references', 'templates', 'agent_rules.md',
+);
+const REINSTALL = 'npx @sabaiway/agent-workflow-kit@latest init';
+const USAGE = 'usage: rules-insert.mjs --cwd <project> [--apply]';
+const NON_REGULAR_CAUSE = 'Target is not a regular file';
+const REFUSALS = Object.freeze({
+  fileAbsent: 'file-absent',
+  fileSymlink: 'file-symlink',
+  fileUnreadable: 'file-unreadable',
+  templateDefect: 'template',
+  headingTwice: 'heading-twice',
+  anchorAbsent: 'anchor-absent',
+  capRefused: 'cap',
+  writeFailed: 'write-failed',
+});
+const COMPOSERS = Object.fromEntries(Object.entries(REFUSALS).map(([key, name]) => [name, key]));
+const DIAGNOSTIC_REFUSALS = new Set([
+  REFUSALS.templateDefect, REFUSALS.fileUnreadable, REFUSALS.writeFailed,
+]);
+const UNICODE_UNSAFE_RANGE = BACKSLASH + 'u007f-' + BACKSLASH + 'u009f'
+  + BACKSLASH + 'u2028' + BACKSLASH + 'u2029';
+const LINE_UNSAFE = new RegExp('[' + UNICODE_UNSAFE_RANGE + ']', 'g');
+const HUMAN_UNSAFE = new RegExp(
+  '[' + BACKSLASH + 'u0000-' + BACKSLASH + 'u001f' + UNICODE_UNSAFE_RANGE + ']+', 'g',
+);
+
+const escapeUnsafe = (character) => BACKSLASH + 'u'
+  + character.codePointAt(FIRST_CODE_POINT).toString(JSON_RADIX).padStart(JSON_ESCAPE_WIDTH, JSON_ESCAPE_PAD);
+const renderOneLine = (value) => String(value).replace(HUMAN_UNSAFE, ' ');
+const readCause = (error) => String(error?.message ?? error);
+const makeResult = (code, stdout = '', stderr = '') => ({ code, stdout, stderr });
+
+export const OUTCOME_LINES = Object.freeze({
+  regionPresent: (id) => `${renderOneLine(id)}: present`,
+  regionPlanned: (id) => `${renderOneLine(id)}: planned`,
+  regionInserted: (id) => `${renderOneLine(id)}: inserted`,
+  fileAbsent: (target) => `${renderOneLine(target)} is absent; the file is seeded at bootstrap.`,
+  fileSymlink: (target) => `${renderOneLine(target)} is a symbolic link; no changes were made.`,
+  fileUnreadable: (target) => `${renderOneLine(target)} cannot be read as a regular file; no changes were made.`,
+  templateDefect: () => 'The bundled rules cannot be used; reinstall the kit with '
+    + BACKTICK + REINSTALL + BACKTICK + '.',
+  headingTwice: (label, target) => `The heading "${renderOneLine(label)}" occurs more than once in ${renderOneLine(target)}; no changes were made.`,
+  anchorAbsent: (target) => `${renderOneLine(target)} has no numbered section in part 2 to insert after; no changes were made.`,
+  capRefused: (target, count, cap) => `${renderOneLine(target)} would contain ${renderOneLine(count)} lines, exceeding its limit of ${renderOneLine(cap)}; trim the file and try again.`,
+  writeFailed: (target) => `${renderOneLine(target)} could not be replaced; its contents were not changed.`,
+  refusalLine: (name) => `[rules-insert] refusal=${renderOneLine(name)}`,
+  errorDetail: (raw) => `[rules-insert] error=${JSON.stringify(String(raw)).replace(LINE_UNSAFE, escapeUnsafe)}`,
+});
+
+const refuse = (name, args = [], cause) => {
+  const lines = [OUTCOME_LINES[COMPOSERS[name]](...args), OUTCOME_LINES.refusalLine(name)];
+  if (DIAGNOSTIC_REFUSALS.has(name)) lines.push(OUTCOME_LINES.errorDetail(cause));
+  return makeResult(EXIT_REFUSAL, '', lines.join(LF));
+};
+
+const parseArgs = (argv) => {
+  const parsed = argv.reduce((state, argument) => {
+    if (state.pending) {
+      if (!argument || argument.startsWith(FLAG_PREFIX)) {
+        throw new Error(`${state.pending} needs a value`);
+      }
+      return { options: { ...state.options, [FLAGS[state.pending]]: argument }, pending: null };
+    }
+    if (!Object.hasOwn(FLAGS, argument)) throw new Error(`unknown argument ${argument}`);
+    const key = FLAGS[argument];
+    if (Object.hasOwn(state.options, key)) throw new Error(`${argument} repeated`);
+    if (argument === APPLY_FLAG) return { options: { ...state.options, apply: true }, pending: null };
+    return { options: state.options, pending: argument };
+  }, { options: {}, pending: null });
+  if (parsed.pending) throw new Error(`${parsed.pending} needs a value`);
+  if (!parsed.options.cwd) throw new Error(`${CWD_FLAG} is required`);
+  return parsed.options;
+};
+
+const readTemplate = (deps) => {
+  try {
+    const read = deps.readFileSync ?? readFileSync;
+    const text = read(deps.templatePath ?? TEMPLATE_PATH, UTF8);
+    const spans = Object.fromEntries(REGIONS.map(({ id, headingRe }) => [
+      id, readTemplateSpan(text, headingRe),
+    ]));
+    const defective = REGIONS.find(({ id }) => spans[id].defect);
+    if (defective) {
+      return { error: refuse(REFUSALS.templateDefect, [], `${defective.id}: ${spans[defective.id].defect}`) };
+    }
+    return { spans };
+  } catch (error) {
+    return { error: refuse(REFUSALS.templateDefect, [], readCause(error)) };
+  }
+};
+
+const readDocument = (target, deps) => {
+  const probe = deps.lstatSync ?? lstatSync;
+  const read = deps.readFileSync ?? readFileSync;
+  const status = (() => {
+    try {
+      return { stat: probe(target) };
+    } catch (error) {
+      const name = error?.code === ABSENT_CODE ? REFUSALS.fileAbsent : REFUSALS.fileUnreadable;
+      return { error: refuse(name, [target], readCause(error)) };
+    }
+  })();
+  if (status.error) return status;
+  if (status.stat.isSymbolicLink()) return { error: refuse(REFUSALS.fileSymlink, [target]) };
+  if (!status.stat.isFile()) {
+    return { error: refuse(REFUSALS.fileUnreadable, [target], NON_REGULAR_CAUSE) };
+  }
+  try {
+    return { text: decodeUtf8Strict(read(target)) };
+  } catch (error) {
+    return { error: refuse(REFUSALS.fileUnreadable, [target], readCause(error)) };
+  }
+};
+
+const refusePlan = (plan, target) => {
+  if (plan.refusal === REFUSALS.headingTwice) {
+    const region = REGIONS.find(({ id }) => id === plan.region);
+    return refuse(plan.refusal, [region.label, target]);
+  }
+  if (plan.refusal === REFUSALS.capRefused) return refuse(plan.refusal, [target, plan.count, plan.cap]);
+  return refuse(plan.refusal, [target]);
+};
+
+const runInsert = (options, deps) => {
+  const template = readTemplate(deps);
+  if (template.error) return template.error;
+  const root = resolve(options.cwd);
+  const target = resolve(root, TARGET_RELATIVE);
+  const document = readDocument(target, deps);
+  if (document.error) return document.error;
+  const cap = frontmatterMaxLines(document.text);
+  const plan = planInsert({ text: document.text, spans: template.spans, cap });
+  if (plan.refusal) return refusePlan(plan, target);
+  const planned = new Set(plan.planned.map(({ id }) => id));
+  const hasPlanned = Boolean(planned.size);
+  if (options.apply && hasPlanned) {
+    try {
+      writeContainedFileAtomic(root, target, plan.text, {
+        writeFile: deps.writeFile,
+        rename: deps.rename,
+        rm: deps.rm,
+      });
+    } catch (error) {
+      return refuse(REFUSALS.writeFailed, [target], readCause(error));
+    }
+  }
+  const composePlanned = options.apply ? OUTCOME_LINES.regionInserted : OUTCOME_LINES.regionPlanned;
+  const stdout = REGIONS.map(({ id }) => (
+    planned.has(id) ? composePlanned(id) : OUTCOME_LINES.regionPresent(id)
+  )).join(LF);
+  const stderr = hasPlanned && cap === null ? LENS_OUTCOME_LINES.capSkipNote() : '';
+  return makeResult(EXIT_SUCCESS, stdout, stderr);
+};
+
+export const main = (argv, deps = {}) => {
+  const parsed = (() => {
+    try {
+      return { options: parseArgs(argv) };
+    } catch (error) {
+      return { error: makeResult(EXIT_USAGE, '', OUTCOME_LINES.errorDetail(`${USAGE}; ${readCause(error)}`)) };
+    }
+  })();
+  return parsed.error ?? runInsert(parsed.options, deps);
+};
+
+if (isDirectRun(import.meta.url)) {
+  const result = await main(process.argv.slice(ARGV_OFFSET));
+  if (result.stdout) console.log(result.stdout);
+  if (result.stderr) console.error(result.stderr);
+  process.exitCode = result.code;
+}

package/tools/rules-regions.mjs

@@ -0,0 +1,167 @@
+const LF = String.fromCharCode(10);
+const CR = String.fromCharCode(13);
+const CRLF = CR + LF;
+const BACKSLASH = String.fromCharCode(92);
+const FRONTMATTER_BOUNDARY = '---';
+const STRUCTURAL_HEADING_RE = /^#{2,3} /;
+const NUMBERED_HEADING_RE = /^### 2[.]([0-9]+)[.]/;
+const NUMBERED_HEADING_PREFIX = '### 2.';
+const MAX_LINES_RE = new RegExp('^maxLines:' + BACKSLASH + 's*([0-9]+)' + BACKSLASH + 's*$');
+const TEMPLATE_CANON = 'template';
+const HEADING_COUNT_DEFECT = 'heading-count';
+const HEADING_TWICE_REFUSAL = 'heading-twice';
+const ANCHOR_ABSENT_REFUSAL = 'anchor-absent';
+const CAP_REFUSAL = 'cap';
+const SINGLE_HEADING = 1;
+const NOT_FOUND = -1;
+const UTF8_LABEL = 'utf-8';
+const UTF8_ENCODING = 'utf8';
+const ROUND_TRIP_MESSAGE = 'the bytes read do not survive a UTF-8 round trip';
+const BOM_CHAR = String.fromCharCode(65279);
+
+// Append the OUTGOING canon here in the same release that changes the template
+// §2.5 region — the fragment-or-prior reconcile depends on it.
+const COMMS_PRIOR_PRE_AD054 = `### 2.x. Communication (user-facing messages)
+Apply this as part of §2 before any user-facing summary:
+- **Deliver the artifact IN the message** — paste the prompt / diff / version / command inline; never "see §X / open the file / run it and you'll see" as a *substitute* for showing what was asked.
+- **Lead with the result**, then the details; show exactly what was asked — no deflection, no "almost done" when the ask was the finished thing.
+- **No condescension, no filler.** Own a miss plainly and fix it in the same message.
+- **Large artifact (≈>100 lines):** deliver a real summary or the key excerpt inline **and** link the file — never flood the reader with a 2000-line paste, never hide the answer behind a bare pointer.`;
+const COMMS_PRIOR_AD054 = `${COMMS_PRIOR_PRE_AD054}
+- **Live host/session facts are tool-composed only.** Any claim about the current host or session state (prompts fired, sandbox scope, whether a bypass was needed, network reachability, approval counts) must trace to **live tool output** from **this session**; a memory/handover snapshot is **context, never report facts**, and a claim with no live signal is **omitted or explicitly marked unverified** — never asserted from recollection.`;
+const COMMS_PRIOR_PLAIN_LANGUAGE = `### 2.x. Communication (user-facing messages)
+Apply this as part of §2 before any user-facing summary:
+- **Plain language.** User-facing narration is short, clear, plain words of the dialogue language; when the dialogue language is not English, transliterated English jargon is banned — an English term survives only as the NAME of a thing (a flag / command / file / test), glossed in plain words when helpful; plain English stays plain for English-dialogue users.
+- **Deliver the artifact IN the message** — paste the prompt / diff / version / command inline; never "see §X / open the file / run it and you'll see" as a *substitute* for showing what was asked.
+- **Lead with the result**, then the details; show exactly what was asked — no deflection, no "almost done" when the ask was the finished thing.
+- **No condescension, no filler.** Own a miss plainly and fix it in the same message.
+- **Large artifact (≈>100 lines):** deliver a real summary or the key excerpt inline **and** link the file — never flood the reader with a 2000-line paste, never hide the answer behind a bare pointer.
+- **Live host/session facts are tool-composed only.** Any claim about the current host or session state (prompts fired, sandbox scope, whether a bypass was needed, network reachability, approval counts) must trace to **live tool output** from **this session**; a memory/handover snapshot is **context, never report facts**, and a claim with no live signal is **omitted or explicitly marked unverified** — never asserted from recollection.`;
+const COMMS_PRIOR_STATE_BLOCK = `${COMMS_PRIOR_PLAIN_LANGUAGE}
+- **The closing state block answers three DIFFERENT questions.** Close a user-facing message with three labelled slots — *now* · *what I need from you* · *what's next*. The slot LABELS stay ENGLISH — an English label is what lets a state-block checker FIND the block and its slots at all; everything written INTO a slot is in the project's dialogue language; when that language is not English, the checker's English phrase sets do not judge those values. **Now** = the state at this instant: what is RUNNING, or what the work is stopped on. It is **never a report of finished work** — what you completed goes in the message BODY, above the block. **From you** = the real unblocker, named; a turn that is ENDING always has one. **Next** = what follows. A *now* slot that opens with what was completed buries the one fact the reader opened the message for, and the three slots collapse into one restatement.`;
+const COMMS_PRIORS = [COMMS_PRIOR_PRE_AD054, COMMS_PRIOR_AD054, COMMS_PRIOR_PLAIN_LANGUAGE, COMMS_PRIOR_STATE_BLOCK];
+
+export const RULES_REGIONS = Object.freeze([
+  Object.freeze({
+    id: 'communication',
+    headingRe: /^### 2[.]([0-9]+)[.] Communication [(]user-facing messages[)]/,
+    label: '### 2.x. Communication (user-facing messages)',
+    canon: TEMPLATE_CANON,
+    priors: COMMS_PRIORS,
+  }),
+  Object.freeze({
+    id: 'story-sessions',
+    headingRe: /^### 2[.]([0-9]+)[.] Story sessions/,
+    label: '### 2.x. Story sessions',
+    canon: TEMPLATE_CANON,
+    priors: [],
+  }),
+  Object.freeze({
+    id: 'lens',
+    headingRe: /^### 2[.]([0-9]+)[.] Planning, review & process-fidelity/,
+    label: '### 2.x. Planning, review & process-fidelity invariants',
+    canon: 'engine',
+    priors: [],
+  }),
+]);
+const TEMPLATE_REGIONS = RULES_REGIONS.filter(({ canon }) => canon === TEMPLATE_CANON);
+
+const stripCr = (line) => (line.endsWith(CR) ? line.slice(0, -1) : line);
+const isBoundary = (line) => line === FRONTMATTER_BOUNDARY || STRUCTURAL_HEADING_RE.test(line);
+const lineCount = (text) => text.split(LF).length - (text.endsWith(LF) ? 1 : 0);
+const findHeadings = (lines, headingRe) => lines.flatMap((line, index) => {
+  const match = stripCr(line).match(headingRe);
+  return match ? [{ index, number: match[1] }] : [];
+});
+const regionEnd = (lines, start) => {
+  const afterHeading = start + 1;
+  const boundary = lines.slice(afterHeading).findIndex((line) => isBoundary(stripCr(line)));
+  return boundary === NOT_FOUND ? lines.length : afterHeading + boundary;
+};
+
+export const extractRegionBy = (text, headingRe) => {
+  const lines = String(text).split(LF);
+  const headings = findHeadings(lines, headingRe);
+  const count = headings.length;
+  if (count === 0) return { found: false, count: 0 };
+  const { index: start, number } = headings[0];
+  const end = regionEnd(lines, start);
+  const regionLines = lines.slice(start, end).map(stripCr);
+  const bodyEnd = regionLines.findLastIndex((line) => line.trim() !== '') + 1;
+  const body = regionLines.slice(0, bodyEnd).join(LF);
+  return { found: true, count, start, end, number, body };
+};
+
+export const readTemplateSpan = (text, headingRe) => {
+  const region = extractRegionBy(text, headingRe);
+  if (region.count !== SINGLE_HEADING) return { defect: HEADING_COUNT_DEFECT };
+  const span = String(text).split(LF).slice(region.start, region.end).map(stripCr).join(LF);
+  return { span, number: region.number };
+};
+
+// A reader that will WRITE the whole document back must not decode leniently: readFileSync(path,
+// 'utf8') turns an invalid byte into U+FFFD, and the rewrite would carry that substitution into
+// bytes nobody asked to change. The guarantee the callers need is not "the decoder is strict" but
+// "re-encoding gives back the bytes we read" — so it is asserted, not reasoned about: any decoder
+// asymmetry (a substitution, a stripped byte-order mark) fails here rather than in the written file.
+// Bytes in, text out, or one throw the caller answers by its own name.
+export const decodeUtf8Strict = (bytes) => {
+  const text = new TextDecoder(UTF8_LABEL, { fatal: true, ignoreBOM: true }).decode(bytes);
+  if (!Buffer.from(text, UTF8_ENCODING).equals(bytes)) throw new Error(ROUND_TRIP_MESSAGE);
+  return text;
+};
+
+// The decoded text KEEPS a leading byte-order mark, because the writer must give the bytes back
+// exactly; a structural reader must therefore look past it, or a file that declares maxLines reads
+// as one that declares none. Only judgement skips it — never the text any offset is computed over.
+export const frontmatterMaxLines = (text) => {
+  const lines = String(text).split(LF).map(stripCr);
+  const opening = lines[0]?.startsWith(BOM_CHAR) ? lines[0].slice(BOM_CHAR.length) : lines[0];
+  if (opening !== FRONTMATTER_BOUNDARY) return null;
+  for (const line of lines.slice(1)) {
+    if (line === FRONTMATTER_BOUNDARY) return null;
+    const match = line.match(MAX_LINES_RE);
+    if (match) return Number(match[1]);
+  }
+  return null;
+};
+
+export const exceedsCap = (text, cap) => {
+  const count = lineCount(text);
+  const skipped = cap === null;
+  return { over: !skipped && count > cap, count, skipped };
+};
+
+export const planInsert = ({ text, spans, cap }) => {
+  const regions = TEMPLATE_REGIONS.map(({ id, headingRe }) => ({
+    id,
+    region: extractRegionBy(text, headingRe),
+  }));
+  const doubled = regions.find(({ region }) => region.count > SINGLE_HEADING);
+  if (doubled) return { refusal: HEADING_TWICE_REFUSAL, region: doubled.id };
+  const missing = regions.filter(({ region }) => !region.found);
+  if (missing.length === 0) return { planned: [], text };
+  const lines = text.split(LF);
+  const headings = findHeadings(lines, NUMBERED_HEADING_RE);
+  if (headings.length === 0) return { refusal: ANCHOR_ABSENT_REFUSAL };
+  const insertAt = regionEnd(lines, headings.at(-1).index);
+  const highestNumber = Math.max(...headings.map(({ number }) => Number(number)));
+  const planned = missing.map(({ id }, index) => ({
+    id,
+    number: String(highestNumber + index + 1),
+    insertAt,
+  }));
+  const newline = text.includes(CRLF) ? CRLF : LF;
+  const offset = insertAt === lines.length
+    ? text.length
+    : lines.slice(0, insertAt).reduce((length, line) => length + line.length + LF.length, 0);
+  const prefix = offset === text.length && !text.endsWith(LF) ? newline : '';
+  const inserted = planned.map(({ id, number }) => {
+    const bound = spans[id].span.replace(NUMBERED_HEADING_RE, NUMBERED_HEADING_PREFIX + number + '.');
+    return bound.split(LF).map(stripCr).join(newline) + newline;
+  }).join('');
+  const resultText = text.slice(0, offset) + prefix + inserted + text.slice(offset);
+  const decision = exceedsCap(resultText, cap);
+  if (decision.over) return { refusal: CAP_REFUSAL, count: decision.count, cap };
+  return { planned, text: resultText };
+};