@codedology/code-forge 0.3.1 → 0.4.0

package/src/review/session-retry.mjs

@@ -0,0 +1,69 @@
+/**
+ * One review session with ONE automatic retry on `timeout` (block B30, issue #2).
+ *
+ * Field data: a reviewer CLI can hang for the whole `review.session_timeout_s` with almost no
+ * output, while the same packet reviews in seconds on a second try. So a session whose status is
+ * `timeout` is spawned once more with the SAME options (same packet file, same level, same lens);
+ * only when the second attempt times out too does the review report `unavailable: timeout`. Any
+ * other failure (exit, schema, unavailable…) is never retried here.
+ *
+ * Both attempts are recorded: `spawnSession` writes one ledger `session` row per spawn as always,
+ * and every timed-out attempt adds a `review.session_timeout` note `{lens, role, level, provider,
+ * model, attempt, retried, duration_ms, stderr_tail, tail_note?, stdout_bytes, stdout_events}`:
+ * the last 4 KB of the session's stderr, packet-free and redacted (`stderrTail`; null with a
+ * `tail_note` when withheld), and stdout only as its byte count and last event types
+ * (`stdoutEvents`) — never stdout text. The helper never throws: a throwing spawn is returned as
+ * `res: null` and a failed note is ignored. `onAttempt(n)` is told each attempt as it starts.
+ */
+
+import { logWarning } from '../util/error-log.mjs';
+
+/** How many times a timed-out session is spawned again. */
+export const TIMEOUT_RETRIES = 1;
+
+/**
+ * @param {(opts: Record<string, any>) => Promise<Record<string, any>>} spawn
+ * @param {Record<string, any>} opts - the spawn options; passed unchanged to every attempt.
+ * @param {(row: Record<string, any>) => Promise<unknown>} note - best-effort ledger note.
+ * @param {(attempt: number) => void} [onAttempt] - told the attempt number as each one starts.
+ * @returns {Promise<{res: Record<string, any> | null, attempts: number}>} the last attempt's result
+ *   (`null` when the spawn threw) and how many attempts ran.
+ */
+export async function spawnWithTimeoutRetry(spawn, opts, note, onAttempt = () => {}) {
+  let attempts = 0;
+  for (;;) {
+    attempts += 1;
+    onAttempt(attempts);
+    /** @type {Record<string, any> | null} */
+    let res;
+    try {
+      res = await spawn(opts);
+    } catch {
+      return { res: null, attempts }; // a throw is an `exit` failure, never retried
+    }
+    if (res?.status !== 'timeout') return { res, attempts };
+    const retried = attempts <= TIMEOUT_RETRIES;
+    try {
+      await note({
+        event: 'review.session_timeout',
+        lens: opts?.rowExtra?.lens ?? null,
+        role: opts?.role ?? null,
+        level: opts?.level ?? null,
+        provider: res.provider ?? null,
+        model: res.model ?? null,
+        attempt: attempts,
+        retried,
+        duration_ms: typeof res.duration_ms === 'number' ? res.duration_ms : null,
+        stderr_tail: typeof res.stderr_tail === 'string' ? res.stderr_tail : null,
+        ...(typeof res.tail_note === 'string' ? { tail_note: res.tail_note } : {}),
+        stdout_bytes: typeof res.stdout_bytes === 'number' ? res.stdout_bytes : null,
+        stdout_events: Array.isArray(res.stdout_events) ? res.stdout_events : [],
+      });
+    } catch {
+      // a failed note never stops the retry or the result
+    }
+    if (!retried) return { res, attempts };
+    // B37: the retry is a recoverable problem: one warning line in the local error log
+    await logWarning({ warning: 'review_retry', message: 'a review session timed out; it was retried once' }).catch(() => null);
+  }
+}

package/src/review/triage.mjs

@@ -18,6 +18,7 @@
 import { buildQuestionPayload, isQuestionDisabled } from '../decide/questions.mjs';
 import { bandFinding, bandResolved } from '../decide/thresholds.mjs';
 import { alwaysResidue } from '../decide/fallback-rules.mjs';
+import { logWarning } from '../util/error-log.mjs';
 
 /**
  * @typedef {{id: string, file?: string, line_start: number, line_end: number, severity: 'critical' | 'warning' | 'nit', category?: string, claim?: string, evidence?: string, fix?: string}} Finding
@@ -37,6 +38,27 @@ async function note(writeRow, row) {
   }
 }
 
+/**
+ * The reasons a fallback warning may name: Jev client failure kinds (`jev-client.mjs`) plus
+ * `error` (the call threw) and `invalid_answer` (ok, but no probability). Anything else is `other`.
+ */
+const FALLBACK_REASONS = new Set(['unauthorized', 'invalid_request', 'rate_limited', 'unavailable', 'network', 'timeout', 'unexpected_status', 'invalid_response', 'error', 'invalid_answer']);
+
+/**
+ * B37: Jev was asked and gave no usable answer, so §3.5's fallback decides: one warning line in the
+ * local error log (once per reason per process). The reason is a word from a fixed list, never
+ * Jev's text. Never throws: a logging failure cannot change the fallback.
+ * @param {unknown} reason
+ */
+async function fellBack(reason) {
+  const word = typeof reason === 'string' && FALLBACK_REASONS.has(reason) ? reason : 'other';
+  try {
+    await logWarning({ warning: 's1_fallback', message: `System 1 (Jev) gave no answer (${word}); fell back to the rules` }).catch(() => null);
+  } catch {
+    // the fallback stands without its warning line
+  }
+}
+
 /** @param {Finding} f @returns {'fix_now' | 'nit'} the verdict a judge's severity means. */
 export const severityVerdict = (f) => (f.severity === 'nit' ? 'nit' : 'fix_now');
 
@@ -53,10 +75,13 @@ export async function askNoul(id, state, { jev, cfg = {} }) {
   try {
     res = await jev({ state, questions: buildQuestionPayload([id], cfg) });
   } catch {
+    await fellBack('error');
     return null;
   }
   const p = res?.ok === true ? res.answers?.[id]?.noul : undefined;
-  return typeof p === 'number' && Number.isFinite(p) && p >= 0 && p <= 1 ? p : null;
+  if (typeof p === 'number' && Number.isFinite(p) && p >= 0 && p <= 1) return p;
+  await fellBack(res?.ok === true ? 'invalid_answer' : res?.kind);
+  return null;
 }
 
 /**

package/src/review/validate-review.mjs

@@ -7,17 +7,27 @@
  *  3. `reviewed_hunks` equals the packet's hunk headers EXACTLY and IN ORDER;
  *  4. `tokens_out ≥ review.min_tokens_out` (120).
  * Anything else is `unavailable` with one reason — `timeout`, `exit`, `schema`,
- * `hunks_mismatch`, `too_short` — and is never approval. There is no "approve on missing output":
+ * `hunks_mismatch`, `too_short`, or `budget` (B33: the spawner refused at `budget.usd`) — and is
+ * never approval. There is no "approve on missing output":
  * no answer is a `schema` failure, no session is an `exit` failure.
  */
 
 import { readFileSync } from 'node:fs';
 import { Ajv2020 } from 'ajv/dist/2020.js';
 
-export const UNAVAILABLE_REASONS = Object.freeze(['exit', 'schema', 'hunks_mismatch', 'too_short', 'timeout']);
+export const UNAVAILABLE_REASONS = Object.freeze(['exit', 'schema', 'hunks_mismatch', 'too_short', 'timeout', 'budget']);
 
 export const DEFAULT_MIN_TOKENS_OUT = 120;
 
+/**
+ * A clean pass (`passed: true`, no findings, every hunk acknowledged) on a SMALL diff legitimately
+ * needs few words: a 3-line placeholder reviewed by GPT-6 Astra produced 108 tokens and was refused
+ * as `too_short`. For such answers the floor drops to this value; any finding keeps the full floor.
+ */
+export const CLEAN_PASS_MIN_TOKENS_OUT = 40;
+/** A diff with at most this many added lines is "small" for the clean-pass floor. */
+export const SMALL_DIFF_ADDED_LINES = 20;
+
 /** The source answer schema (compiled per provider by the spawner). */
 export const FINDING_SCHEMA = Object.freeze(JSON.parse(readFileSync(new URL('./finding.schema.json', import.meta.url), 'utf8')));
 
@@ -39,18 +49,20 @@ export function minTokensOut(cfg) {
  * @property {boolean} ok
  * @property {Record<string, any>} [review]
  * @property {number} [tokens_out]
- * @property {'exit' | 'schema' | 'hunks_mismatch' | 'too_short' | 'timeout'} [reason]
+ * @property {'exit' | 'schema' | 'hunks_mismatch' | 'too_short' | 'timeout' | 'budget'} [reason]
  * @property {string} [detail]
  */
 
 /**
  * @param {Record<string, any> | null | undefined} session - a `spawnSession` result.
- * @param {{hunkHeaders: ReadonlyArray<string>, minTokensOut?: number}} expect
+ * @param {{hunkHeaders: ReadonlyArray<string>, minTokensOut?: number, smallDiff?: boolean}} expect - `smallDiff` lowers the floor to `CLEAN_PASS_MIN_TOKENS_OUT` for a clean pass only
  * @returns {Verdict}
  */
-export function validateReview(session, { hunkHeaders, minTokensOut: min = DEFAULT_MIN_TOKENS_OUT }) {
+export function validateReview(session, { hunkHeaders, minTokensOut: min = DEFAULT_MIN_TOKENS_OUT, smallDiff = false }) {
   if (!session || typeof session !== 'object') return { ok: false, reason: 'exit', detail: 'no session result' };
   if (session.status === 'timeout') return { ok: false, reason: 'timeout', detail: 'killed at the session timeout' };
+  // B33: the spawner refused the session because the run reached `budget.usd` — nothing ran
+  if (session.status === 'unavailable' && session.reason === 'budget') return { ok: false, reason: 'budget', detail: String(session.message ?? 'budget.usd reached') };
   const exitCode = session.exit_code;
   if (session.status === 'failed' || session.status === 'unavailable' || (exitCode !== undefined && exitCode !== 0)) {
     return { ok: false, reason: 'exit', detail: `session ${session.status}${exitCode === undefined ? '' : ` (exit ${exitCode})`}` };
@@ -65,6 +77,9 @@ export function validateReview(session, { hunkHeaders, minTokensOut: min = DEFAU
     return { ok: false, reason: 'hunks_mismatch', detail: `reviewed_hunks has ${got.length} entries; the packet has ${hunkHeaders.length} hunks` };
   }
   const tokensOut = Number(session.usage?.tokens_out ?? session.row?.tokens_out ?? 0);
-  if (!(tokensOut >= min)) return { ok: false, reason: 'too_short', detail: `tokens_out ${tokensOut} < ${min}` };
+  const review = /** @type {{passed: boolean, findings: unknown[]}} */ (session.answer);
+  const cleanPass = review.passed === true && Array.isArray(review.findings) && review.findings.length === 0;
+  const floor = smallDiff && cleanPass ? Math.min(min, CLEAN_PASS_MIN_TOKENS_OUT) : min;
+  if (!(tokensOut >= floor)) return { ok: false, reason: 'too_short', detail: `tokens_out ${tokensOut} < ${floor}` };
   return { ok: true, review: session.answer, tokens_out: tokensOut };
 }

package/src/session/author.mjs

@@ -20,6 +20,7 @@ import { estimateCostUsd } from '../ledger/prices.mjs';
 import { writeSafe } from '../util/redact.mjs';
 import { currentRunRoot } from '../util/tmp.mjs';
 import { checkSheetFresh } from './facts.mjs';
+import { authorHeadingRules } from './plan-sections.mjs';
 import { spawnSession } from './spawn.mjs';
 
 export const JOBS = Object.freeze(['plan', 'harden']);
@@ -58,8 +59,11 @@ export const AUTHOR_LENS =
 const JOB_RULES = {
   plan: [
     'Write the plan draft in markdown. Its §0 is the facts sheet below, VERBATIM (header lines included).',
-    'Include a section titled "Acceptance clauses the facts sheet cannot back": every clause that cites a claim the sheet',
-    'marks NOT-FOUND or UNVERIFIABLE, each with a tolerance naming the block; write `none` when there is none.',
+    ...authorHeadingRules(),
+    'The level column of the block table is the lane recorded for each block by `forge jev ask lane --block <id> --plan <plan>`',
+    '(or `--rules`, the deterministic fallback, when Jev is unavailable): L0 trivial · L1 a plain feature following a pattern ·',
+    'L2 money, dates, tenancy, migrations, concurrency. It is never a block category. Leave it as `L?` when no lane is given in',
+    'the message; plan check refuses a level that differs from the recorded lane.',
   ],
   harden: [
     'Harden the draft: close every gap you can from the material given; for each decision only the human can make,',

package/src/session/plan-check.mjs

@@ -9,6 +9,10 @@
  *    VERIFIED is listed in the "… the facts sheet cannot back" section by a line that names the
  *    token, the block, and a tolerance — else `unbackable clause without tolerance: <block> <clause>`;
  *  - a caller map section exists and names every block (C9);
+ *  - the required sections are found by their exact headings (`plan-sections.mjs`); a near miss at
+ *    the expected position is accepted with a WARN naming the exact heading (B36);
+ *  - every block's level is the lane recorded for it in the ledger by `jev ask lane --block <id>`
+ *    (Jev, or `--rules`, the deterministic fallback) — none, or a different one, is refused (B36);
  *  - every block has a lane, owned files that pass B8's `assertOwned` (no `[ ] ( ) ! + @` in a
  *    glob, V6) and are disjoint from the other blocks of its wave (O26);
  *  - `depends_on` is acyclic and every path a block imports (`imports` column) that another block
@@ -24,6 +28,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { assertOwned, findOverlap, ownsFile } from '../state/registry.mjs';
 import { extractClaims, parseSheet, sha256 } from './facts.mjs';
+import { findSection, nearMissWarning, REQUIRED_SECTIONS } from './plan-sections.mjs';
 
 /** Limits used when the config does not set them (plan v1.3 §10.7, R10). */
 export const DEFAULT_LIMITS = Object.freeze({ coders: 2, blockCases: 80, blockLines: 2000 });
@@ -185,17 +190,57 @@ const listItems = (body) =>
     .filter((l) => /^\s*(?:[-*]|\d+\.)\s+/.test(l))
     .map((l) => l.trim());
 
+/** Where a lane may come from: Jev's `lane` answer, or the deterministic fallback rule (`--rules`). */
+export const LANE_SOURCES = Object.freeze(['jev', 'rules']);
+
+/**
+ * @typedef {{lane: string, source: string, decision_id: string | null}} RecordedLane
+ */
+
+/**
+ * A recorded lane answer, normalised: trimmed, upper-cased, the first `L0`–`L3` token (`" l1 "` ⇒
+ * `L1`); an answer with no such token stays as written, trimmed (`split`).
+ * @param {string} answer @returns {string}
+ */
+export function normaliseLane(answer) {
+  const token = /\bL[0-3]\b/.exec(answer.trim().toUpperCase());
+  return token ? token[0] : answer.trim();
+}
+
+/**
+ * The lane recorded per block by `forge jev ask lane --block <id>` (or `--rules`): the latest
+ * `decision` row for `lane` whose `block` is set and whose `source` is Jev or the fallback rules.
+ * A row that names a plan (`--plan`) counts only for the plan with that base name (both sides are
+ * compared as `path.basename`); with no plan name given, only untagged rows count.
+ * @param {Array<Record<string, any>>} rows - ledger rows, oldest first.
+ * @param {string} [planName] - the plan file's base name.
+ * @returns {Map<string, RecordedLane>}
+ */
+export function recordedLanes(rows, planName) {
+  /** @type {Map<string, RecordedLane>} */
+  const out = new Map();
+  for (const row of rows) {
+    if (row?.event !== 'decision' || row.question !== 'lane' || typeof row.block !== 'string') continue;
+    if (!LANE_SOURCES.includes(row.source) || typeof row.answer !== 'string') continue;
+    if (row.plan !== undefined && (planName === undefined || typeof row.plan !== 'string' || path.basename(row.plan) !== path.basename(planName))) continue;
+    out.set(row.block, { lane: normaliseLane(row.answer), source: row.source, decision_id: typeof row.decision_id === 'string' ? row.decision_id : null });
+  }
+  return out;
+}
+
 /**
  * @typedef {object} CheckOpts
  * @property {string} [planPath] - where the plan lives (resolves the sheet's brief reference).
  * @property {string} [factsText] @property {string} [factsPath] - a separate sheet (else the plan's own §0).
  * @property {Record<string, any>} [cfg] - `caps.coders`, `budget.block_cases`, `budget.block_lines`.
+ * @property {Array<Record<string, any>>} [decisions] - the project's ledger rows (the recorded lanes);
+ *   none given ⇒ no block has a recorded lane.
  */
 
 /**
  * @param {string} text - the plan.
  * @param {CheckOpts} [opts]
- * @returns {{ok: boolean, errors: string[], blocks: number}}
+ * @returns {{ok: boolean, errors: string[], warnings: string[], blocks: number, lanes: Array<{block: string, level: string | null, lane: string | null, source: string | null}>}}
  */
 export function checkPlan(text, opts = {}) {
   const limits = {
@@ -206,7 +251,7 @@ export function checkPlan(text, opts = {}) {
   const { blocks, sections, dispatch } = parsePlan(text);
   /** @type {string[]} */
   const errors = [];
-  if (blocks.length === 0) return { ok: false, errors: ['no block table found (a table with id, owned_files and acceptance columns)'], blocks: 0 };
+  if (blocks.length === 0) return { ok: false, errors: ['no block table found (a table with id, owned_files and acceptance columns)'], warnings: [], blocks: 0, lanes: [] };
 
   // facts sheet: present, fresh, and (when separate) pasted into the plan
   const sheetText = opts.factsText ?? text;
@@ -224,8 +269,18 @@ export function checkPlan(text, opts = {}) {
   }
   const verified = new Set((sheet?.facts ?? []).filter((f) => f.tag === 'VERIFIED').map((f) => f.claim));
 
+  // the required sections, by their exact headings (B36: a near miss at the expected position is a WARN)
+  /** @type {string[]} */
+  const warnings = [];
+  /** @param {import('./plan-sections.mjs').RequiredSection} spec */
+  const required = (spec) => {
+    const hit = findSection(sections, spec);
+    if (hit && !hit.exact) warnings.push(nearMissWarning(hit.section.title, spec));
+    return hit?.section;
+  };
+
   // unbackable clauses
-  const unbackable = sections.find((s) => /cannot back/i.test(s.title));
+  const unbackable = required(REQUIRED_SECTIONS.unbackable);
   if (!unbackable) errors.push('unbackable-clauses section missing (write "none" when there is none)');
   const tolerances = unbackable ? listItems(unbackable.body).filter((l) => /\btolerance\b/i.test(l)) : [];
   for (const b of blocks) {
@@ -237,13 +292,17 @@ export function checkPlan(text, opts = {}) {
   }
 
   // caller map
-  const callerMap = sections.find((s) => /caller map/i.test(s.title));
+  const callerMap = required(REQUIRED_SECTIONS.callerMap);
   if (!callerMap) errors.push('caller map missing');
   else for (const b of blocks) if (!idRe(b.id).test(callerMap.body)) errors.push(`caller map: block ${b.id} is absent`);
 
-  // lane, owned files, forecasts
+  // lane (B36: the level is the lane recorded for the block), owned files, forecasts
+  const lanes = recordedLanes(opts.decisions ?? [], opts.planPath === undefined ? undefined : path.basename(opts.planPath));
   for (const b of blocks) {
+    const recorded = lanes.get(b.id);
     if (b.level === null) errors.push(`block ${b.id}: no lane (level L0–L3)`);
+    else if (!recorded) errors.push(`block ${b.id}: level ${b.level} has no recorded lane decision — run forge jev ask lane --block ${b.id} --state <file> (or --rules when Jev is unavailable)`);
+    else if (recorded.lane !== b.level) errors.push(`block ${b.id}: level ${b.level} differs from the recorded lane ${recorded.lane} (${recorded.source})`);
     try {
       assertOwned(b.owned);
     } catch (err) {
@@ -290,5 +349,11 @@ export function checkPlan(text, opts = {}) {
     });
   }
 
-  return { ok: errors.length === 0, errors, blocks: blocks.length };
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings,
+    blocks: blocks.length,
+    lanes: blocks.map((b) => ({ block: b.id, level: b.level, lane: lanes.get(b.id)?.lane ?? null, source: lanes.get(b.id)?.source ?? null })),
+  };
 }

package/src/session/plan-sections.mjs

@@ -0,0 +1,98 @@
+/**
+ * The plan sections `forge plan check` requires, by their exact headings (B36). One source for
+ * the author's prompt (`author.mjs` lists these headings in the Plan job's rules), the check
+ * (`plan-check.mjs` finds the sections by them) and the template (`skill/templates/plan.md`
+ * carries them; a test keeps the three in step). Callers address a section by its id, never by
+ * its place in a list.
+ *
+ * A section is found by its exact heading: the heading's text after its number equals `heading`
+ * (case-insensitive, trimmed). A heading that misses the wording is accepted, with a WARN naming
+ * the exact heading, only when its number is the section's expected one (`position`), its text
+ * names one of the section's distinctive `keywords`, and its text is not another required
+ * section's heading. Anything else is a missing section.
+ */
+
+/**
+ * @typedef {'unbackable' | 'callerMap'} SectionId
+ * @typedef {object} RequiredSection
+ * @property {SectionId} id
+ * @property {string} heading - the exact heading text (without its number).
+ * @property {string} label - the expected position as the template numbers it.
+ * @property {RegExp} position - matches the heading's number (`§0.x`, `0.6` ⇒ `0.x`, `0.6`).
+ * @property {string[]} keywords - distinctive lowercase words a near-miss heading must name one of.
+ * @property {string} purpose - what the author writes under it (the prompt's one line per section).
+ */
+
+/** @type {Readonly<Record<SectionId, Readonly<RequiredSection>>>} */
+export const REQUIRED_SECTIONS = Object.freeze({
+  unbackable: Object.freeze({
+    id: 'unbackable',
+    heading: 'Acceptance clauses the facts sheet cannot back',
+    label: '§0.x',
+    position: /^0\.\w+$/,
+    // distinctive words only: a plain '§0.1 Facts sheet' heading must not pass as this section
+    keywords: ['unbackable', 'cannot back'],
+    purpose: 'every clause that cites a claim the sheet marks NOT-FOUND or UNVERIFIABLE, each with a tolerance naming the block; `none` when there is none',
+  }),
+  callerMap: Object.freeze({
+    id: 'callerMap',
+    heading: 'Caller map',
+    label: '§3',
+    position: /^3$/,
+    keywords: ['caller map', 'callers'],
+    purpose: 'mechanism → the block that ships it → the block that calls it; every block id appears',
+  }),
+});
+
+/** @returns {Readonly<RequiredSection>[]} every required section, in template order. */
+export const requiredSections = () => Object.values(REQUIRED_SECTIONS);
+
+/**
+ * @param {string} title - a heading's text (markdown emphasis already stripped).
+ * @returns {{number: string | null, text: string}} its leading number (`§0.x`, `0.6.`, `3.` ⇒
+ *   `0.x`, `0.6`, `3`) and the rest.
+ */
+export function splitHeading(title) {
+  const m = /^§?\s*(\d+(?:\.\w+)*)\.?\s+(.*)$/.exec(title.trim());
+  return m ? { number: m[1], text: m[2].trim() } : { number: null, text: title.trim() };
+}
+
+/**
+ * @template {{title: string}} S
+ * @param {S[]} sections - the plan's headings, in order.
+ * @param {RequiredSection} spec
+ * @returns {{section: S, exact: boolean} | null} the first exact match, else the first near miss
+ *   at the expected position, else null.
+ */
+export function findSection(sections, spec) {
+  const textOf = (/** @type {S} */ s) => splitHeading(s.title).text.toLowerCase();
+  const want = spec.heading.toLowerCase();
+  const exact = sections.find((s) => textOf(s) === want);
+  if (exact) return { section: exact, exact: true };
+  const others = requiredSections()
+    .filter((o) => o.id !== spec.id)
+    .map((o) => o.heading.toLowerCase());
+  const near = sections.find((s) => {
+    const { number } = splitHeading(s.title);
+    const text = textOf(s);
+    return number !== null && spec.position.test(number) && !others.includes(text) && spec.keywords.some((k) => text.includes(k));
+  });
+  return near ? { section: near, exact: false } : null;
+}
+
+/**
+ * @param {string} found - the near-miss heading as written.
+ * @param {RequiredSection} spec
+ * @returns {string} the WARN line `plan check` prints for it.
+ */
+export function nearMissWarning(found, spec) {
+  return `WARN section "${found}" at ${spec.label} read as "${spec.heading}" — use the exact heading "${spec.heading}"`;
+}
+
+/** @returns {string[]} the Plan job's section rule lines for the author packet: each heading once. */
+export function authorHeadingRules() {
+  return [
+    'Use these section headings exactly, word for word, at these positions (plan check finds the sections by them):',
+    ...requiredSections().map((s) => `- "${s.label} ${s.heading}" — ${s.purpose}.`),
+  ];
+}