@event4u/agent-config 14.18.0 → 14.20.0

package/src/scripts/_lib/mcp_consent_residual.ts

@@ -0,0 +1,173 @@
+/**
+ * Per-host MCP consent residuals (roadmap step 3.2).
+ *
+ * A RESIDUAL is what remains non-automatic after this package has installed:
+ * the step the human still has to take before the MCP server actually runs.
+ * The step's own framing is the design constraint — "a checklist of things that
+ * did work is noise, a named residual is actionable" — so this module models
+ * only what is left, and the surfaces that print it print nothing else.
+ *
+ * Provenance is carried, not assumed.
+ *
+ * Every residual says where its text came from, and the surfaces print it:
+ *
+ * - `vendor-doc` — the host's own documentation says so. Nobody here watched it
+ *   happen. Vendor documentation drifts, so this is a starting value, never a
+ *   fact about the machine the reader is on.
+ * - `observed` — a session on that host recorded it. Only an observation may
+ *   replace a documented value, and only in that direction.
+ *
+ * An absent host is UNRECORDED, never "no residual".
+ *
+ * A host with no entry here has not been looked at. `residualFor` returns
+ * `null` and the callers say so in words, because printing nothing would make
+ * "this host needs no step" and "nobody checked this host" the same line — the
+ * exact confusion the capability manifest's own `default` provenance exists to
+ * prevent.
+ */
+
+import { describeHostCapabilities } from './host_capability.js';
+
+/** Where a residual's text came from. Only an observation may replace a doc. */
+export type ResidualSource = 'vendor-doc' | 'observed';
+
+export interface ConsentResidual {
+    /** Capability-manifest host id (`claude`), not the installer tool id. */
+    hostId: string;
+    /** The step the human still has to take. One sentence, imperative. */
+    residual: string;
+    source: ResidualSource;
+    /** Why we believe it — a doc reference, or the session that observed it. */
+    cite: string;
+}
+
+/**
+ * Seeded residuals.
+ *
+ * DELIBERATELY SHORT. Only hosts whose residual is establishable today appear;
+ * a row invented for a host nobody checked would be the "vendor-doc residuals
+ * harden into asserted facts" risk this roadmap's own register names, arriving
+ * one step earlier than predicted. Absence here is the honest state, and the
+ * callers render it as such.
+ */
+const SEEDED: Readonly<Record<string, ConsentResidual>> = {
+    claude: {
+        hostId: 'claude',
+        residual:
+            'Approve the project-scoped `agent-config` server the first time the host '
+            + 'prompts — the installer writes `.mcp.json` but does not pre-approve it.',
+        source: 'vendor-doc',
+        cite:
+            'Host documentation: a project-scope MCP server requires explicit approval, '
+            + 'suppressible only through the user-global `enabledMcpjsonServers` key, '
+            + 'which this package deliberately does not write '
+            + '(blocker `mcp-user-scope-approval-consent`).',
+    },
+};
+
+/** Installer `--tools` id → capability-manifest host id, for the report. */
+export const TOOL_TO_HOST: Readonly<Record<string, string>> = {
+    'claude-code': 'claude',
+    cursor: 'cursor',
+    'gemini-cli': 'gemini',
+    windsurf: 'windsurf',
+    cline: 'cline',
+    copilot: 'copilot',
+    augment: 'augment',
+};
+
+/**
+ * The residual for one host, or `null` when none is recorded.
+ *
+ * An OBSERVATION outranks the documented value, and in one direction only: a
+ * host whose capability row explicitly records `mcp_needs_manual_activation:
+ * false` — an observation, since the field's provenance reads `registry` only
+ * when the row wrote it — has no residual left, and that clearance is itself
+ * reported as `observed`. The reverse never happens: a documented residual is
+ * not upgraded to `observed` by anything short of a session.
+ */
+export function residualFor(hostId: string): ConsentResidual | null {
+    const { manifest, sources } = describeHostCapabilities(hostId);
+    if (sources.mcp_needs_manual_activation === 'registry' && !manifest.mcp_needs_manual_activation) {
+        return null;
+    }
+    return SEEDED[hostId] ?? null;
+}
+
+/** Was this host looked at at all? Distinguishes "cleared" from "unrecorded". */
+export function isRecorded(hostId: string): boolean {
+    const { sources } = describeHostCapabilities(hostId);
+    return hostId in SEEDED || sources.mcp_needs_manual_activation === 'registry';
+}
+
+/** One rendered line per host, for the doctor check and the installer report. */
+export interface ResidualLine {
+    hostId: string;
+    /** `residual` · `cleared` · `unrecorded` — the three honest states. */
+    state: 'residual' | 'cleared' | 'unrecorded';
+    text: string;
+}
+
+/** Render the state of one host. Never silent, in any of the three states. */
+export function residualLine(hostId: string): ResidualLine {
+    const r = residualFor(hostId);
+    if (r !== null) {
+        return {
+            hostId,
+            state: 'residual',
+            text: `${hostId}: ${r.residual} (source: ${r.source} — not observed here)`,
+        };
+    }
+    if (isRecorded(hostId)) {
+        return {
+            hostId,
+            state: 'cleared',
+            text: `${hostId}: nothing left to do (source: observed)`,
+        };
+    }
+    return {
+        hostId,
+        state: 'unrecorded',
+        text: `${hostId}: no residual recorded — nobody checked this host, which is not the same as nothing to do`,
+    };
+}
+
+/**
+ * The lines an installer run should print, for the tools it selected.
+ *
+ * Only hosts with a real residual OR an unrecorded state are returned: a host
+ * whose residual was observed away has nothing actionable to say, and the step
+ * asks for exactly the actionable set.
+ */
+export function residualReport(toolIds: Iterable<string>): ResidualLine[] {
+    const seen = new Set<string>();
+    const out: ResidualLine[] = [];
+    for (const toolId of toolIds) {
+        const hostId = TOOL_TO_HOST[toolId];
+        if (hostId === undefined || seen.has(hostId)) continue;
+        seen.add(hostId);
+        const line = residualLine(hostId);
+        if (line.state !== 'cleared') out.push(line);
+    }
+    return out;
+}
+
+/**
+ * Print the residuals for one install's selected tools, or nothing.
+ *
+ * Lives here rather than inline in the installer's closing block for the same
+ * reason `registerMcpHosts` does: `install.ts` sits far over the source-size
+ * ratchet's ceiling, and the rendering belongs beside the table it renders.
+ */
+export function printResiduals(
+    toolIds: Iterable<string>,
+    quiet: boolean,
+    write: (s: string) => void = (s) => process.stdout.write(s),
+): void {
+    if (quiet) return;
+    const lines = residualReport(toolIds);
+    if (lines.length === 0) return;
+    write('  Still needs you (MCP):\n');
+    for (const line of lines) write(`    \u2022 ${line.text}\n`);
+    write('\n');
+}

package/src/scripts/_lib/model_tier.ts

@@ -11,7 +11,7 @@
  * - the repo generator (`condense.py generate_claude_skills`), which
  *   builds the package's own `.claude/skills/` tree, and
  * - the consumer install finalizer
- *   (`install.py finalize_claude_model_tiers`), which rewrites the
+ *   (the installer's `finalize_claude_model_tiers`), which rewrites the
  *   installed `.claude/skills/` tree so Claude Code performs the
  *   per-turn model switch on a consumer with `model.auto_switch: auto`.
  *

package/src/scripts/_lib/obligation_frequency.ts

@@ -275,7 +275,7 @@ export function slot_frequency(platform: string, slot: Slot): Frequency {
 }
 
 /**
- * Platforms with no hook surface at all.
+ * Platforms this package binds nothing on.
  *
  * Copilot declares `fallback_only: true` in the manifest — concerns route
  * through rule-only fallback and the dispatcher no-ops. Every hook-declared
@@ -294,7 +294,7 @@ export function is_hook_capable(platform_block: Record<string, unknown>): boolea
 export interface PlatformBinding {
     /** Platform id → slot → concern ids bound in that slot. */
     slots: Map<string, Map<Slot, string[]>>;
-    /** Platform ids that carry no hook surface at all. */
+    /** Platform ids declared `fallback_only` — this package binds nothing there. */
     fallback_only: Set<string>;
 }
 

package/src/scripts/_lib/orchestration_record.ts

@@ -16,6 +16,7 @@
  * add one. (Mirrors `domain-safety-pii` § Surface 2 / artifact-engagement.)
  */
 
+import { appliedIds } from './audit_field_provenance.js';
 import type { LookupClass } from './auto_dispatch.js';
 import type { EvidenceBasis } from './evidence_basis.js';
 // TYPE-ONLY on purpose. `runtime_journal.ts` imports `node:sqlite` at runtime,
@@ -104,6 +105,24 @@ export interface RecordInput {
      * the rules bound in the contract.
      */
     skills_applied?: string[] | null | undefined;
+    /**
+     * Stable rule ids the run ACTUALLY carried, as an observation.
+     *
+     * Until 2026-09-07 this producer wrote the literal `['delegation-policy']`
+     * on every line, and so did `review_skipped_record.ts`. Mining the real
+     * stream with `extract_audit_patterns --min-count 2` therefore minted
+     * exactly ONE pattern at count 1074 over 1104 lines: not a regularity, just
+     * arithmetic over a constant. Every per-asset reader downstream was
+     * aggregating over the writer rather than over the work.
+     *
+     * ABSENT now means an EMPTY list, not a fabricated one. An empty list is an
+     * honest absence — the same answer `activation_receipt_producer.ts` has
+     * always given — and it is what makes the field's variation, when a caller
+     * does supply ids, evidence about the run.
+     *
+     * Ids only, never bodies. Bounded to <= 32, mirroring the contract.
+     */
+    rules_applied?: string[] | null | undefined;
     /**
      * What this dispatch was supposed to produce. Drives the anti-forgery gate
      * in `envelopeOutcome`. Absent or `unknown` disables the gate for this
@@ -253,6 +272,7 @@ const ORIGIN_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
  */
 const MAX_APPLIED_IDS = 32;
 
+
 /**
  * What THIS producer's lines carry. `ids-only` and not `counts-only` because
  * every line carries `rules_applied`, and some carry `skills_applied`.
@@ -626,7 +646,9 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
         risk_class: risk,
         memory: { asks: 0, hits: 0 },
         verify: { claims: 0, first_try_passes: 0 },
-        rules_applied: ['delegation-policy'],
+        // COMPUTED, never a producer constant. See `rules_applied` on the input
+        // interface for the measurement that retired the constant.
+        rules_applied: appliedIds(input.rules_applied),
         // MANDATORY, never optional and never derived by the reader. This line
         // carries `rules_applied` and may carry `skills_applied`, both of which
         // are stable artefact ids, so the class it declares is `ids-only`

package/src/scripts/_lib/recycle_envelope_paths.ts

@@ -5,8 +5,11 @@
  * when it is stale. A second copy of any of these values is the drift seam
  * Risk 6 warns about.
  */
+import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { safe_stem } from './session_register.js';
+
 /** Where `session:recycle` writes the pending envelope (gitignored runtime state). */
 export const RECYCLE_ENVELOPE_REL = path.join('agents', 'runtime', 'state', 'recycle-envelope.json');
 
@@ -33,3 +36,190 @@ export const RECYCLE_MAX_AGE_HOURS = 48;
  * for the wrapper block and a co-pending handoff.
  */
 export const RECYCLE_ENVELOPE_MAX_BYTES = 6144;
+
+// ---------------------------------------------------------------------
+// Per-SESSION keying (road-to-one-continuity-record Phase 2.1)
+// ---------------------------------------------------------------------
+
+/** State directory the two constants above live in. */
+const _STATE_REL = path.join('agents', 'runtime', 'state');
+
+/**
+ * Per-SESSION record path. The two constants above name **one file per
+ * workspace**, and the session register in the same tree models concurrent
+ * sessions per checkout — so the continuity artifact and the identity model
+ * disagreed, and the artifact lost. Two sessions in one checkout overwrite
+ * each other's record and each resumes from whichever wrote last.
+ *
+ * This is the same defect `roadmap_claim_rel` (`session_register_hook.ts:105`)
+ * was repaired for, and it is deliberately repaired the same way rather than a
+ * better way: one shape for "state keyed by session", so a reader who has seen
+ * one recognises the other. `safe_stem` is imported from the register rather
+ * than re-implemented — a second sanitiser is a second traversal guard to keep
+ * correct.
+ *
+ * **No `latest` index, by decision.** A pointer file naming the newest record
+ * would restore the shared write target one layer up and re-create the same
+ * race with an extra indirection. Resolution is by register identity,
+ * workspace and branch — never by recency.
+ *
+ * When no session id is resolvable the legacy shared path is returned, so an
+ * older record keeps working and the fallback degrades to the previous
+ * behaviour instead of losing the record. The reader's ambiguity rule
+ * (`resolveContinuityRecord`) is what keeps that fallback from becoming a
+ * cross-session read.
+ */
+export function recycle_envelope_rel(session_id: string | null | undefined): string {
+    return _sessionKeyed(session_id, RECYCLE_ENVELOPE_REL, 'recycle-envelope', '.json');
+}
+
+/** Consumed sibling of {@link recycle_envelope_rel}, same keying. */
+export function recycle_consumed_rel(session_id: string | null | undefined): string {
+    return _sessionKeyed(session_id, RECYCLE_CONSUMED_REL, 'recycle-envelope', '.consumed.json');
+}
+
+/**
+ * Shared builder. Containment is asserted locally rather than trusted from
+ * `safe_stem`: a guarantee living in another module's implementation is one
+ * refactor away from being untrue here, and the failure mode of being wrong is
+ * a write outside the state directory.
+ */
+function _sessionKeyed(
+    session_id: string | null | undefined,
+    legacy: string,
+    stem: string,
+    suffix: string,
+): string {
+    const id = String(session_id ?? '').trim();
+    if (id === '') {
+        return legacy;
+    }
+    const rel = path.join(_STATE_REL, `${stem}-${safe_stem(id)}${suffix}`);
+    const norm = path.normalize(rel);
+    if (!norm.startsWith(`${_STATE_REL}${path.sep}`) || norm.includes('..')) {
+        return legacy;
+    }
+    return norm;
+}
+
+/** Every session-keyed record present in a workspace, plus the legacy file. */
+export function listContinuityRecords(workspace_root: string): string[] {
+    const dir = path.join(workspace_root, _STATE_REL);
+    let names: string[];
+    try {
+        names = fs.readdirSync(dir);
+    } catch {
+        return [];
+    }
+    return names
+        .filter(
+            (n) =>
+                n.startsWith('recycle-envelope') &&
+                n.endsWith('.json') &&
+                !n.endsWith('.consumed.json'),
+        )
+        .sort()
+        .map((n) => path.join(dir, n));
+}
+
+/** What {@link resolveContinuityRecord} decided, and why — the reason is emitted, never dropped. */
+export interface ContinuityResolution {
+    /** Absolute path to read, or `null` when the reader must start clean. */
+    file: string | null;
+    /** One line, always present. On `file === null` this is what the reader says out loud. */
+    reason: string;
+}
+
+/**
+ * Which record THIS session may read.
+ *
+ * Three cases, and the third is the one the per-session key exists for:
+ *
+ * 1. **Own id resolves.** Read the record keyed to it, and nothing else. A peer
+ *    session's record is not a candidate at any point, so "neither observes the
+ *    other's" holds by construction rather than by a comparison that could be
+ *    skipped.
+ * 2. **No id, one candidate.** Read it. A single record in a checkout with no
+ *    resolvable identity is the pre-key situation and is unchanged.
+ * 3. **No id, several candidates.** START CLEAN and say so. Picking the newest
+ *    is precisely the recency resolution the no-index rule forbids: it would
+ *    hand this session a stranger's state and look like a successful resume.
+ */
+export function resolveContinuityRecord(
+    workspace_root: string,
+    session_id: string | null | undefined,
+): ContinuityResolution {
+    const id = String(session_id ?? '').trim();
+    if (id !== '') {
+        const own = path.join(workspace_root, recycle_envelope_rel(id));
+        return fs.existsSync(own)
+            ? { file: own, reason: `continuity record for this session (${safe_stem(id)})` }
+            : { file: null, reason: `no continuity record for this session (${safe_stem(id)})` };
+    }
+    const candidates = listContinuityRecords(workspace_root);
+    if (candidates.length === 0) {
+        return { file: null, reason: 'no continuity record present' };
+    }
+    if (candidates.length === 1) {
+        return { file: candidates[0] as string, reason: 'one continuity record, no session id to key on' };
+    }
+    return {
+        file: null,
+        reason:
+            `starting clean: ${candidates.length} continuity records in this workspace and no session id ` +
+            'to tell them apart — resuming from the newest would resume a peer session, not this one',
+    };
+}
+
+/**
+ * Is there any trace in this workspace of the session a record names as its
+ * predecessor?
+ *
+ * The normal case resolves through the consumed sibling: when this session
+ * started, its reader consumed the predecessor's record and moved it to this
+ * session's consumed path, so that file carries `session_id === predecessor`.
+ * A live record under the predecessor's own key also counts — that is the
+ * shape when the chain has not been walked yet.
+ *
+ * **A `false` here is a refusal, not a repair.** The reader discards the record
+ * and says why. The alternative — injecting a record whose stated lineage
+ * cannot be corroborated — is the guess this check exists to prevent, and it is
+ * the expensive direction: a refused resume costs one session's context, a
+ * wrong resume costs a session working from a stranger's state without knowing
+ * it.
+ *
+ * **Known false-refusal, stated rather than hidden:** the janitor prunes old
+ * state, so a long-idle chain can lose its consumed sibling and be refused
+ * although it was genuine. That is the same cost as the record having expired,
+ * which at {@link RECYCLE_MAX_AGE_HOURS} it very likely has.
+ */
+export function predecessorTracePresent(workspace_root: string, predecessor: string): boolean {
+    const id = String(predecessor ?? '').trim();
+    if (id === '' || id === 'none') {
+        return true;
+    }
+    if (fs.existsSync(path.join(workspace_root, recycle_envelope_rel(id)))) {
+        return true;
+    }
+    const dir = path.join(workspace_root, _STATE_REL);
+    let names: string[];
+    try {
+        names = fs.readdirSync(dir);
+    } catch {
+        return false;
+    }
+    for (const n of names) {
+        if (!n.startsWith('recycle-envelope') || !n.endsWith('.json')) continue;
+        try {
+            const raw = JSON.parse(fs.readFileSync(path.join(dir, n), 'utf-8')) as {
+                session_id?: unknown;
+            };
+            if (String(raw.session_id ?? '').trim() === id) {
+                return true;
+            }
+        } catch {
+            // unreadable file proves nothing in either direction
+        }
+    }
+    return false;
+}

package/src/scripts/_lib/release_highlights.ts

@@ -29,6 +29,10 @@ import {
     CURATED_HEAD_INSTRUCTION,
     MIX_RESPONSE_MARKER,
     MIX_RESPONSE_PLACEHOLDERS,
+    PROMISE_OUTCOMES,
+    PROMISE_PHRASE,
+    PROMISE_READBACK_MARKER,
+    extract_changelog_section,
 } from './release_material.js';
 
 /** The five curated labels, in the order an operator reads them. */
@@ -546,6 +550,95 @@ export function mix_response_blockers(
     return [];
 }
 
+/**
+ * The promise the PREVIOUS release head made, or null when it made none.
+ *
+ * Scoped to that section's governance-response block, not to its whole body: a
+ * product line that happens to contain the phrase is not a promise the project
+ * made about the next cycle.
+ */
+export function previous_promise(changelogText: string, previousVersion: string): string | null {
+    const section = extract_changelog_section(changelogText, previousVersion);
+    if (section === null) return null;
+    const idx = section.body.indexOf(MIX_RESPONSE_MARKER);
+    if (idx === -1) return null;
+    const block = mix_response_block(section.body, idx);
+    return block.includes(PROMISE_PHRASE) ? block : null;
+}
+
+/**
+ * The ONE predicate for "did this head answer the previous head's promise?".
+ *
+ * The defect: `_lib/release_material.ts` generates a `Next cycle ships …` line
+ * and nothing has ever read the previous one back, so an unmet promise can be
+ * restated indefinitely at zero cost — the debt is booked and never called. A
+ * promise nobody reads is not a commitment, it is a sentence.
+ *
+ * Three outcomes are accepted and one of them must be chosen, which is the
+ * whole mechanism: it does not require the promise to have been KEPT, and no
+ * ratio, deadline or count is enforced here. Refusing an unkept promise would
+ * make the honest answer the expensive one and teach an author to promise less
+ * rather than to answer truthfully.
+ *
+ * Length floor and placeholder scan reuse the governance-response discipline
+ * for the same reason it exists there: a bare marker, or the writer's own
+ * scaffolding, is not an answer a human wrote.
+ */
+export function promise_readback_blockers(
+    sectionBody: string,
+    version: string,
+    previousVersion: string,
+    promise: string | null,
+    where = '`main`',
+): string[] {
+    if (promise === null) return [];
+    const idx = sectionBody.indexOf(PROMISE_READBACK_MARKER);
+    if (idx === -1) {
+        return [
+            `the ${version} section does not answer the ${previousVersion} head's ` +
+                `\`${PROMISE_PHRASE}\` promise. Add one \`> ${PROMISE_READBACK_MARKER}\` line ` +
+                `immediately under the curated head on ${where}, naming the promise and whether ` +
+                `it ${PROMISE_OUTCOMES.join(', ')} (the last one with its reason).`,
+        ];
+    }
+    const block = mix_response_block(sectionBody, idx);
+    const left = MIX_RESPONSE_PLACEHOLDERS.filter((t) => block.includes(t));
+    if (left.length > 0) {
+        return [
+            `the ${version} previous-cycle answer still carries the writer's placeholder(s) ` +
+                `(${left.map((t) => `\`${t}\``).join(', ')}). \`CHANGELOG.md\` is published to npm. ` +
+                `Write the outcome on ${where} and re-run.`,
+        ];
+    }
+    const lower = block.toLowerCase();
+    const named = PROMISE_OUTCOMES.filter((o) => lower.includes(o));
+    if (named.length === 0) {
+        return [
+            `the ${version} previous-cycle answer names no outcome. It has to say which of ` +
+                `${PROMISE_OUTCOMES.join(', ')} applies to the ${previousVersion} promise — an ` +
+                'answer that restates the promise without resolving it is the failure this reads ' +
+                'back for.',
+        ];
+    }
+    if (readback_answer(block).length < MIX_RESPONSE_MIN_CHARS) {
+        return [
+            `the ${version} previous-cycle answer is shorter than a written answer ` +
+                `(${String(MIX_RESPONSE_MIN_CHARS)} characters after the marker). Name what was ` +
+                `promised and what became of it on ${where}, not the outcome word alone.`,
+        ];
+    }
+    return [];
+}
+
+/** What the author wrote under the read-back marker, marker and quoting removed. */
+export function readback_answer(block: string): string {
+    return block
+        .replace(PROMISE_READBACK_MARKER, '')
+        .replace(/^[>\s.]+|[>\s.]+$/gu, '')
+        .replace(/[>\s]+/gu, ' ')
+        .trim();
+}
+
 /**
  * The whole response block: the marker's line plus every blockquote line under it.
  *

package/src/scripts/_lib/release_material.ts

@@ -351,6 +351,69 @@ export const MIX_RESPONSE_PLACEHOLDERS: readonly string[] = [
 export function render_mix_response(level: string): string[] {
     return [
         `> ${MIX_RESPONSE_MARKER} ${level}.`,
-        `> Next cycle ships ${MIX_RESPONSE_PLACEHOLDER}, tracked in <roadmap or issue>.`,
+        `> ${PROMISE_PHRASE} ${MIX_RESPONSE_PLACEHOLDER}, tracked in <roadmap or issue>.`,
     ];
 }
+
+/**
+ * The words that turn a governance response into a PROMISE about a later cycle.
+ *
+ * Named rather than inlined because two sides now read it: the writer emits it,
+ * and the next release reads the previous section for it to decide whether a
+ * read-back is owed. A promise nothing reads back costs nothing to restate, so
+ * it can be restated for as many cycles as there are cycles — the defect this
+ * constant exists to make addressable.
+ */
+export const PROMISE_PHRASE = 'Next cycle ships';
+
+/**
+ * The marker under which a release head answers the PREVIOUS head's promise.
+ *
+ * A named sentinel, on the same discipline as `MIX_RESPONSE_MARKER` and
+ * `DERIVED_MARKER`: a shape match over prose would accept a sentence that
+ * happens to mention last cycle and reject a reworded answer.
+ */
+export const PROMISE_READBACK_MARKER = '**Previous cycle:**';
+
+/**
+ * The three outcomes a read-back may report, and the reason there are exactly
+ * three.
+ *
+ * `shipped` and `did not ship` are the honest halves of the fact. `withdrawn`
+ * exists because a promise the project decided not to keep is a legitimate
+ * third state — but only WITH a reason, which is why the answer also has to
+ * clear a written-length floor rather than being one of these three words on
+ * its own. Without the third state the mechanism would push an author toward
+ * restating a dead promise as still-outstanding, which is the failure it is
+ * built to stop.
+ */
+export const PROMISE_OUTCOMES: readonly string[] = ['shipped', 'did not ship', 'withdrawn'];
+
+/** Every `## X.Y.Z` release version in the file, in document order (newest first). */
+export function changelog_versions(text: string): string[] {
+    const out: string[] = [];
+    for (const m of text.matchAll(/^##\s+\[?(\d+\.\d+\.\d+)\b/gmu)) {
+        out.push(m[1] as string);
+    }
+    return out;
+}
+
+/**
+ * The release published immediately before `version`, or null when there is none.
+ *
+ * Read from the CHANGELOG rather than from git tags on purpose: the promise
+ * being read back is a property of the SECTION, and a tag can exist for a
+ * version whose section was archived into `docs/archive/` under an era split —
+ * in which case there is no previous promise reachable in this file and the
+ * honest answer is that none is owed.
+ *
+ * `version` itself need not be present: a section still under authoring is
+ * named `[Unreleased]`, so the caller passes the version it is releasing and
+ * gets the newest RELEASED version that is not it.
+ */
+export function previous_changelog_version(text: string, version: string): string | null {
+    const versions = changelog_versions(text);
+    const idx = versions.indexOf(version);
+    if (idx !== -1) return versions[idx + 1] ?? null;
+    return versions[0] ?? null;
+}