@event4u/agent-config 14.13.0 → 14.14.0

package/src/scripts/_lib/promotion_review.ts

@@ -0,0 +1,294 @@
+/**
+ * The lifecycle AFTER promotion — `road-to-harness-promotion-bridge` steps 7.6
+ * and 7.7.
+ *
+ * ## 7.6 — a promoted artefact is not immortal
+ *
+ * > *post-promotion re-evaluation with `KEEP / REVISE / MERGE / SPLIT / RETIRE`.
+ * > The master's promotion phase ends at the evidence package plus a cooldown,
+ * > so nothing reopens a promoted artefact and the lifecycle is manual-only at
+ * > exactly the point where growth accumulates.*
+ * > verify: **a promoted artefact reaching its review trigger produces one of
+ * > the five verdicts, and at least one `RETIRE` path is exercised in a
+ * > fixture.**
+ *
+ * Two halves were already in the tree and one was missing. Four of the five
+ * verdicts are E6 curator ops (`_lib/curator_ops.ts`) — `REVISE` is not — and
+ * `promoted -> retired` is already the one legal retirement edge
+ * (`_lib/candidate_record.ts:210-219`). What did not exist was the REVIEW
+ * TRIGGER: nothing decided that a promoted artefact was due, and nothing turned
+ * that into a verdict. {@link reviewPromoted} is that.
+ *
+ * **The verdict set is NOT a subset of `CURATOR_OPS`, and finding that out is
+ * part of what this step buys.** E6 argued for seven curator ops on the ground
+ * that 7.6 specifies five verdicts a four-op curator could not execute — and the
+ * shipped seven still cannot execute one of them, because `REVISE` is not among
+ * them. The relationship is pinned by a test in both directions rather than
+ * papered over with a mapping nobody chose; see {@link POST_PROMOTION_VERDICTS}.
+ *
+ * ## 7.7 — best-known-state reference on regression
+ *
+ * > *Roll back to the recorded best-known state; lineage, not endless append.*
+ * > verify: **an injected regression triggers the rollback path in a fixture.**
+ *
+ * {@link BestKnownState} is the record, {@link planRollback} is the decision.
+ * "Lineage, not endless append" is carried in the type: a rollback names the
+ * state it returns to and the state it leaves, so the history is a chain rather
+ * than a pile of snapshots nobody can order.
+ *
+ * ## This module promotes nothing
+ *
+ * It reads promoted artefacts and it can RETIRE one — the only transition it
+ * expresses is `promoted -> retired`, which `assertTransition` accepts without
+ * an approver because retirement is the direction that shrinks the estate.
+ * There is no path here that moves anything INTO `promoted`; that stays behind
+ * `_lib/promotion_capability.ts`, and `lint_promotion_paths.ts` is what proves
+ * this file did not grow one.
+ */
+import { ACCEPTED_STATE, type LifecycleState, assertTransition } from './candidate_record.js';
+import { CURATOR_OPS, type CuratorOp } from './curator_ops.js';
+
+/**
+ * The five verdicts step 7.6 names, verbatim.
+ *
+ * **Four of the five are E6 curator ops. `REVISE` is not, and that is a finding
+ * rather than a detail.** `_lib/curator_ops.ts:48-56` is `KEEP · ADD · MERGE ·
+ * REPLACE · SPLIT · RETIRE · SKIP`, and its own header argues for seven ops on
+ * the ground that *"step 7.6 of the same roadmap already specifies the verdict
+ * set KEEP / REVISE / MERGE / SPLIT / RETIRE, so a four-op curator would emit
+ * verdicts it cannot execute"*. Measured against the shipped set: `REVISE` is
+ * still a verdict the curator cannot execute — `REPLACE` is the nearest op and
+ * it is not the same thing, since `REPLACE` is 1→1 with a new artefact while
+ * `REVISE` edits the one in place and keeps its identity.
+ *
+ * The list is therefore written out rather than derived, because deriving it
+ * would require inventing the mapping the two sets do not have. What IS pinned,
+ * by `tests/scripts/promotion_review.test.ts`, is the relationship in both
+ * directions: the four shared verdicts really are curator ops, and `REVISE`
+ * really is not — so a later change that adds `REVISE` to `CURATOR_OPS`, or
+ * drops one of the four, fails a test instead of drifting.
+ */
+export const POST_PROMOTION_VERDICTS = ['KEEP', 'REVISE', 'MERGE', 'SPLIT', 'RETIRE'] as const;
+
+/** The four verdicts the curator can actually execute today. */
+export const VERDICTS_EXECUTABLE_BY_CURATOR: readonly CuratorOp[] = CURATOR_OPS.filter(
+    (op) => (POST_PROMOTION_VERDICTS as readonly string[]).includes(op),
+);
+
+export type PostPromotionVerdict = (typeof POST_PROMOTION_VERDICTS)[number];
+
+/** Why a promoted artefact came up for review. Absent means it is not due. */
+export const REVIEW_TRIGGERS = [
+    'regression',
+    'usage-floor',
+    'duplicate-detected',
+    'scope-overgrown',
+    'age',
+] as const;
+export type ReviewTrigger = (typeof REVIEW_TRIGGERS)[number];
+
+/** What a review reads. Every field is an observation, not a judgement. */
+export interface PromotedArtefactState {
+    readonly id: string;
+    readonly lifecycle: LifecycleState;
+    /** Measured effect now, in the same units as the promotion evidence's delta. */
+    readonly currentDeltaPercent: number;
+    /** The delta recorded at promotion. The regression test is `current < promoted`. */
+    readonly promotedDeltaPercent: number;
+    /** How many times the artefact was actually reached since promotion. */
+    readonly invocations: number;
+    /** Ids of promoted artefacts whose text this one now duplicates. */
+    readonly duplicates: readonly string[];
+    /** Distinct responsibilities the artefact has accumulated. */
+    readonly responsibilities: number;
+    readonly daysSincePromotion: number;
+}
+
+export class NotPromotedError extends Error {
+    constructor(id: string, lifecycle: LifecycleState) {
+        super(
+            `'${id}' is '${lifecycle}', not '${ACCEPTED_STATE}' — post-promotion review acts on a ` +
+                'PROMOTED artefact. A candidate that never landed is rejected, not retired, and ' +
+                'reviewing one here would report a lifecycle event that did not happen.',
+        );
+        this.name = 'NotPromotedError';
+    }
+}
+
+export interface ReviewOutcome {
+    readonly id: string;
+    readonly trigger: ReviewTrigger;
+    readonly verdict: PostPromotionVerdict;
+    readonly reason: string;
+}
+
+/** The floors the review reads. Stated defaults; each carries its own revisit-if. */
+export const REVIEW_THRESHOLDS = {
+    /** Below this many invocations the artefact is not earning its place. `revisit-if` a
+     *  legitimately rare artefact is retired for being rare. */
+    usageFloor: 1,
+    /** Distinct responsibilities above which the artefact should be SPLIT. `revisit-if` a
+     *  cohesive artefact with several facets is split for having them. */
+    responsibilityCeiling: 2,
+    /** Days after which an unreviewed artefact is due. `revisit-if` the cadence is noise. */
+    ageDays: 180,
+} as const;
+
+/**
+ * Is this artefact due for review, and why? `null` means not due.
+ *
+ * Order is precedence: a regression outranks a usage question, which outranks a
+ * duplicate, which outranks overgrowth, which outranks mere age. Without a fixed
+ * order two triggers firing at once would make the verdict depend on evaluation
+ * order, which is how a review becomes irreproducible.
+ */
+export function reviewTriggerFor(state: PromotedArtefactState): ReviewTrigger | null {
+    if (state.currentDeltaPercent < state.promotedDeltaPercent) return 'regression';
+    if (state.invocations < REVIEW_THRESHOLDS.usageFloor) return 'usage-floor';
+    if (state.duplicates.length > 0) return 'duplicate-detected';
+    if (state.responsibilities > REVIEW_THRESHOLDS.responsibilityCeiling) return 'scope-overgrown';
+    if (state.daysSincePromotion >= REVIEW_THRESHOLDS.ageDays) return 'age';
+    return null;
+}
+
+/**
+ * Produce exactly ONE of the five verdicts for a promoted artefact that reached
+ * its review trigger.
+ *
+ * @throws {NotPromotedError} when the artefact is not promoted.
+ */
+export function reviewPromoted(state: PromotedArtefactState, trigger: ReviewTrigger): ReviewOutcome {
+    if (state.lifecycle !== ACCEPTED_STATE) {
+        throw new NotPromotedError(state.id, state.lifecycle);
+    }
+    const outcome = (verdict: PostPromotionVerdict, reason: string): ReviewOutcome => ({
+        id: state.id,
+        trigger,
+        verdict,
+        reason,
+    });
+    switch (trigger) {
+        case 'regression':
+            // A measured effect that fell BELOW zero is not worth revising; it is
+            // now costing what it was promoted to save.
+            return state.currentDeltaPercent <= 0
+                ? outcome('RETIRE', `effect fell to ${String(state.currentDeltaPercent)} pp — it no longer earns its place`)
+                : outcome(
+                      'REVISE',
+                      `effect fell ${String(state.promotedDeltaPercent)} -> ${String(state.currentDeltaPercent)} pp ` +
+                          'but is still positive',
+                  );
+        case 'usage-floor':
+            return outcome('RETIRE', `reached ${String(state.invocations)} time(s) since promotion`);
+        case 'duplicate-detected':
+            return outcome('MERGE', `now duplicates ${state.duplicates.join(', ')}`);
+        case 'scope-overgrown':
+            return outcome('SPLIT', `carries ${String(state.responsibilities)} distinct responsibilities`);
+        case 'age':
+            return outcome('KEEP', `${String(state.daysSincePromotion)} days since promotion, effect held`);
+    }
+}
+
+/**
+ * Execute the RETIRE verdict.
+ *
+ * Routes through `assertTransition`, so the ONE legal retirement edge is the one
+ * this takes and a caller cannot retire something that never landed. Returns the
+ * next lifecycle state rather than writing anything — nothing in this module
+ * touches the filesystem.
+ *
+ * @throws {LifecycleTransitionError} from `assertTransition`.
+ */
+export function retirePromoted(state: PromotedArtefactState): LifecycleState {
+    assertTransition(state.lifecycle, 'retired');
+    return 'retired';
+}
+
+// --- 7.7 — best-known state and rollback ------------------------------------
+
+/** A recorded good state, and the state it came from. Lineage, not endless append. */
+export interface BestKnownState {
+    readonly artefactId: string;
+    /** The revision or bundle identifier this state is recoverable from. */
+    readonly reference: string;
+    readonly deltaPercent: number;
+    /** The best-known state this one replaced. `null` only for the first. */
+    readonly supersedes: string | null;
+    readonly recordedAt: string;
+}
+
+export interface RollbackPlan {
+    readonly artefactId: string;
+    readonly from: string;
+    readonly to: string;
+    readonly reason: string;
+    /** Oldest first. The chain that makes this a lineage rather than a pile. */
+    readonly lineage: readonly string[];
+}
+
+export class NoBestKnownStateError extends Error {
+    constructor(artefactId: string) {
+        super(
+            `'${artefactId}' regressed and has no recorded best-known state to return to. A rollback ` +
+                'target is recorded at promotion time, not reconstructed after the regression — by ' +
+                'then the state that worked is exactly what is missing.',
+        );
+        this.name = 'NoBestKnownStateError';
+    }
+}
+
+/**
+ * Walk the `supersedes` chain, oldest first.
+ *
+ * Cycle-guarded: a chain that points at itself is a corrupted lineage, and
+ * following it forever would hang the caller rather than report the corruption.
+ */
+export function lineageOf(head: BestKnownState, all: readonly BestKnownState[]): string[] {
+    const byRef = new Map(all.map((s) => [s.reference, s]));
+    const chain: string[] = [];
+    const seen = new Set<string>();
+    let cursor: BestKnownState | undefined = head;
+    while (cursor !== undefined && !seen.has(cursor.reference)) {
+        seen.add(cursor.reference);
+        chain.push(cursor.reference);
+        cursor = cursor.supersedes === null ? undefined : byRef.get(cursor.supersedes);
+    }
+    return chain.reverse();
+}
+
+/**
+ * Plan a rollback when the current state regressed against the best known one.
+ *
+ * `null` when there is no regression — the caller does not have to know the
+ * comparison, and a rollback that fires on an improvement is worse than none.
+ *
+ * @throws {NoBestKnownStateError} when a regression has nowhere to return to.
+ */
+export function planRollback(
+    artefactId: string,
+    currentReference: string,
+    currentDeltaPercent: number,
+    history: readonly BestKnownState[],
+): RollbackPlan | null {
+    const mine = history.filter((s) => s.artefactId === artefactId);
+    const best = mine.reduce<BestKnownState | null>(
+        (acc, s) => (acc === null || s.deltaPercent > acc.deltaPercent ? s : acc),
+        null,
+    );
+    if (best === null) {
+        if (currentDeltaPercent < 0) throw new NoBestKnownStateError(artefactId);
+        return null;
+    }
+    if (currentDeltaPercent >= best.deltaPercent) {
+        return null;
+    }
+    return {
+        artefactId,
+        from: currentReference,
+        to: best.reference,
+        reason:
+            `regressed ${String(best.deltaPercent)} -> ${String(currentDeltaPercent)} pp against the ` +
+            `best-known state '${best.reference}'`,
+        lineage: lineageOf(best, mine),
+    };
+}

package/src/scripts/_lib/prompt_shape.ts

@@ -86,3 +86,95 @@ export function humanAuthoredLead(text: string): string {
   }
   return kept.join("\n");
 }
+
+/** A line that is nothing but an opening tag, with the tag name captured. */
+const REGION_OPEN = /^\s*<([A-Za-z][\w-]*)>\s*$/;
+
+/**
+ * The host's own framing of an injected region — the sentence it writes ABOUT
+ * the block, not a sentence the user typed.
+ *
+ * Named literally, for the same reason `isSyntheticPrompt` names wrapper tags:
+ * this is host furniture, and furniture is identified by what it says about
+ * itself. It is deliberately NOT a language rule — the clauses describe the
+ * region's provenance and its data status, and a user who types one is quoting
+ * the host, which is exactly the case that should be dropped too.
+ */
+const REGION_NOTE =
+  /\b(content (above|below) is from|treat (it|this|that|the (content|text|above|following)) as data)\b/i;
+
+/**
+ * Remove host-injected wrapper regions — `<launch-selected-element>` and
+ * friends — leaving the text the human actually typed around them.
+ *
+ * MEASURED, from a 14.13.0 field report (2026-09-01) reproduced against this
+ * source. `DOCUMENT_HEAD` matches a bare `<tag>` line, and Claude Code PREPENDS
+ * exactly that when the user picks a DOM element in the browser pane. So
+ * `humanAuthoredLead` broke at line zero and returned `""` for every such
+ * prompt — the lead-first isolation was not degraded, it was OFF — and the
+ * whole-text fallback then scored ~4 KB of class-heavy markup plus the host's
+ * own advisory line. Four consecutive German turns pinned English, and the
+ * turn-end gate refused each one.
+ *
+ * Two things had to move, and both are visible in the reproduction:
+ *
+ *   1. A bare `<tag>` line that HAS a matching close is the START of a region
+ *      to skip, never the end of the human lead. That is this function.
+ *   2. It runs BEFORE `instructionText`. The block's indented lines arm that
+ *      filter's paste-state machine, and where no blank line separates the
+ *      block from the user's sentence, the sentence itself was deleted — the
+ *      German markers did not merely lose the count, they reached zero.
+ *
+ * Conservative by construction, in three ways. An UNBALANCED bare tag is left
+ * in place, so a pasted document opening with one still terminates the lead
+ * exactly as before. A prompt with no balanced region is returned untouched,
+ * so nothing outside this shape reclassifies. And the framing sentence is
+ * dropped LINE BY LINE against `REGION_NOTE` rather than as a paragraph: in the
+ * reported shape the advisory and the user's sentence share one unbroken run,
+ * so dropping the run would have taken the sentence with it.
+ *
+ * Not `isSyntheticPrompt`: that answers "is this whole turn machine-written",
+ * and these turns are not — a human sentence follows the block. The wrapper is
+ * removed; the turn is kept.
+ *
+ * Nested same-name regions resolve to the FIRST matching close tag. Host
+ * wrappers do not nest by name, and stopping early keeps more human text than
+ * scanning past the wrong close would.
+ */
+export function stripInjectedRegions(text: string): string {
+  const lines = text.split("\n");
+  const kept: string[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const open = REGION_OPEN.exec(line);
+    if (open === null) {
+      kept.push(line);
+      continue;
+    }
+    // The tag name comes from `[A-Za-z][\w-]*`, so it carries no regex
+    // metacharacter and needs no escaping.
+    const close = new RegExp(`^\\s*</${open[1] ?? ""}>\\s*$`);
+    let end = -1;
+    for (let j = i + 1; j < lines.length; j++) {
+      if (close.test(lines[j] ?? "")) {
+        end = j;
+        break;
+      }
+    }
+    if (end === -1) {
+      kept.push(line);
+      continue;
+    }
+    if (kept.length > 0 && REGION_NOTE.test(kept[kept.length - 1] ?? "")) {
+      kept.pop();
+    }
+    i = end;
+    while (i + 1 < lines.length && (lines[i + 1] ?? "").trim() !== "") {
+      if (!REGION_NOTE.test(lines[i + 1] ?? "")) {
+        break;
+      }
+      i++;
+    }
+  }
+  return kept.join("\n");
+}

package/src/scripts/_lib/release_highlights.ts

@@ -25,6 +25,8 @@
  */
 import { spawnSync } from 'node:child_process';
 
+import { CURATED_HEAD_INSTRUCTION } from './release_material.js';
+
 /** The five curated labels, in the order an operator reads them. */
 export const HEAD_LABELS: readonly string[] = [
     'Behaviour changes',
@@ -39,11 +41,27 @@ export const HEAD_NONE = '_none_';
 /**
  * Prefix marking a head line the generator derived rather than a human wrote.
  *
- * Machine-checkable so the gate can warn when one survives to merge, and
+ * Machine-checkable so the gate can REFUSE when one survives to merge, and
  * readable so the line still says something true to anyone who ships it
  * unedited. It is not a placeholder token: the line it introduces carries real
  * evidence (the reason plus the citing SHAs), so nothing here is
  * wrong-if-shipped — only unpolished-if-unedited.
+ *
+ * **REVERSED 2026-09-01 — "only unpolished-if-unedited" no longer implies
+ * "therefore advisory".** The clause above is kept because it is TRUE, and the
+ * conclusion that used to follow from it is the part that was falsified: the
+ * gate warned, and the marker shipped anyway in five consecutive released
+ * sections (14.9.0 through 14.13.0, eighteen lines, re-derived at
+ * `b50b27281`). `check_release_highlights` now exits non-zero on a marker in
+ * the section under release, and the sibling annotation in that file's header
+ * carries the full reversal.
+ *
+ * **Instructing authority:** the maintainer's closing instruction in the
+ * 2026-09-a inbox round, carried into
+ * `agents/roadmaps/archive/road-to-publication-integrity-hard-fail.md` § Phase 1.
+ *
+ * Nothing about the marker's own shape changes here — it is still one
+ * definition, still shared with the generator that writes it.
  */
 export const DERIVED_MARKER = '_auto-derived, rewrite before merge:_';
 
@@ -283,6 +301,57 @@ export function render_derived_head_values(
     return out;
 }
 
+/**
+ * Reasons the section under release must NOT be published, in the order a
+ * reader should act on them. Empty means nothing here blocks publication.
+ *
+ * Added 2026-09-01 for roadmap § 3.1. It exists because the two IRREVERSIBLE
+ * transitions — the annotated tag and the GitHub Release body — happen inside
+ * `release.ts` after the PR gate has already passed, and nothing re-read the
+ * section between them. `check_release_highlights` guards the PR; this guards
+ * the publish.
+ *
+ * **It takes a section body, never a path and never a repository.** A guard
+ * that reads a file decides for itself what it is guarding, and the two
+ * refused earlier attempts both died there: one placed the check inside a pure
+ * formatter, which has no idea whether it is publishing, and one read the live
+ * changelog from a drill fixture. The caller cuts the section and owns the
+ * decision to publish; this function only answers whether that text is
+ * publishable.
+ *
+ * **Two markers since 2026-09-01, and the second one had to wait for a writer
+ * change.** This function used to check `DERIVED_MARKER` only, and said so:
+ * the generator still wrote its authoring comment into every section it cut,
+ * so refusing on that comment would have redded every release on its first run
+ * — Risk 1 of the roadmap, reproduced exactly. Roadmap § Phase 2 Option A
+ * removed the emission (`render_release_head` in `release.ts`), which is what
+ * makes refusing on it safe. The order was forced and it is the reason the
+ * check arrives second rather than late.
+ *
+ * `CURATED_HEAD_INSTRUCTION` is a named sentinel imported from the module that
+ * defines it — never a shape match over comment prose, which would reject
+ * unrelated legitimate comments and miss this one after a reword.
+ */
+export function publication_blockers(sectionBody: string, version: string): string[] {
+    const out: string[] = [];
+    if (sectionBody.includes(DERIVED_MARKER)) {
+        out.push(
+            `the ${version} section still carries \`${DERIVED_MARKER}\` — the generator's ` +
+                'draft head, not a curated claim. Rewrite those line(s) on ' +
+                `${'`main`'} and re-run.`,
+        );
+    }
+    if (sectionBody.includes(CURATED_HEAD_INSTRUCTION)) {
+        out.push(
+            `the ${version} section still carries the authoring instruction ` +
+                `(\`${CURATED_HEAD_INSTRUCTION}\`) — a reminder to the releaser, not ` +
+                'release content, and `CHANGELOG.md` is published to npm. Delete that ' +
+                'comment line from the section and re-run.',
+        );
+    }
+    return out;
+}
+
 /** Labels whose curated value is still the generator's unedited draft. */
 export function stale_draft_labels(
     curated: Readonly<Record<string, string>>,

package/src/scripts/_lib/release_material.ts

@@ -61,6 +61,116 @@ export function extract_changelog_section(text: string, version: string): Change
     return { heading: m[0], body };
 }
 
+/**
+ * The generator's authoring instruction, identified by ONE named sentinel.
+ *
+ * Roadmap `road-to-publication-integrity-hard-fail` § Phase 2, Option A. Until
+ * 2026-09-01 `render_release_head` wrote this comment into every changelog
+ * section it cut, and nothing removed it at release time — so it shipped. At
+ * that commit `grep -c 'Curated head: fill before merge' CHANGELOG.md` read 2,
+ * and `package.json` `files` carries the bare `"CHANGELOG.md"`, which is the
+ * npm-published artifact. The instruction now lives in the release-PR body,
+ * which is never published, and the writer emits none.
+ *
+ * **A sentinel, deliberately not a shape match.** A council seat warned that a
+ * pattern such as `/<!-- .* should(?: only)? be .* -->/` is overbroad and
+ * under-specified: it rejects unrelated legitimate comments while missing the
+ * prohibited instruction after harmless rewording. This follows the discipline
+ * `DERIVED_MARKER` already follows — one definition, imported by every
+ * consumer, including the gates that refuse on it.
+ */
+export const CURATED_HEAD_INSTRUCTION = 'Curated head: fill before merge';
+
+/**
+ * The full authoring instruction as the release-PR body carries it.
+ *
+ * Parameterized rather than importing `RELEASE_HEAD_CAP_LINES` / `HEAD_NONE`,
+ * because this module has no imports and that is load-bearing: it is the one
+ * place the equality gate, the drill fixtures and the unit tests all reach, so
+ * a dependency here is a dependency in all three.
+ */
+/**
+ * Cap on curated-head lines, and the placeholder a label carries when the
+ * answer is genuinely nothing.
+ *
+ * Relocated here from `release.ts` on 2026-09-01 with the instruction text:
+ * this module builds the release-PR body, so the instruction and the two
+ * values it interpolates belong on the same side of the import boundary. The
+ * generator re-exports `RELEASE_HEAD_CAP_LINES` under its original name, so
+ * nothing that referenced it there has to change.
+ */
+export const RELEASE_HEAD_CAP_LINES = 10;
+
+/**
+ * The fallback value of a head line the span does not substantiate.
+ *
+ * `_none_` and not a placeholder token: where nothing was derived it is the
+ * **true** answer, and a release that genuinely changed no defaults should say
+ * so rather than carry an unfilled marker.
+ *
+ * It is a fallback and no longer a blanket default. Writing `_none_` into
+ * every field made the generator assert five things it had not checked, and
+ * `check_release_highlights` rejected exactly that assertion the moment the
+ * span contradicted it — which for this package is every release, because every
+ * release touches `src/rules/` or `src/scripts/schemas/`. Substantiated labels
+ * are now pre-filled from the span (`_derive_head_prefill`), so the tool states
+ * only what it can support and `_none_` means what it says.
+ */
+export const RELEASE_HEAD_DEFAULT = '_none_';
+
+export function render_curated_head_instruction(capLines: number, headDefault: string): string {
+    return (
+        `<!-- ${CURATED_HEAD_INSTRUCTION}, keep it under ${capLines} lines, and leave ` +
+        `\`${headDefault}\` where it is genuinely the answer. The generated log below is ` +
+        'unchanged. -->'
+    );
+}
+
+/** The instruction exactly as the release-PR body carries it. */
+export const CURATED_HEAD_INSTRUCTION_COMMENT = render_curated_head_instruction(
+    RELEASE_HEAD_CAP_LINES,
+    RELEASE_HEAD_DEFAULT,
+);
+
+/**
+ * Delimiters bounding the release-PR-only region.
+ *
+ * The region exists so the PR body can carry something the changelog must not,
+ * WITHOUT relaxing surface equality anywhere else. `strip_pr_wrapper` removes
+ * exactly what sits between these two markers and nothing else — never a prose
+ * match, never a whole-body relaxation. Relaxing equality wholesale would
+ * remove the release-truth guarantee that the PR body and the changelog say
+ * the same thing, which is a larger floor than the one this change
+ * strengthens.
+ *
+ * An UNTERMINATED region is deliberately left in place: it then surfaces as an
+ * ordinary divergence instead of silently swallowing the rest of the body.
+ */
+export const PR_ONLY_START = '<!-- release-pr-only:start -->';
+export const PR_ONLY_END = '<!-- release-pr-only:end -->';
+
+/** Remove every complete PR-only region. Delimiter-bounded, never a prose match. */
+export function strip_pr_only_regions(s: string): string {
+    const out: string[] = [];
+    let rest = s;
+    for (;;) {
+        const i = rest.indexOf(PR_ONLY_START);
+        if (i === -1) {
+            out.push(rest);
+            break;
+        }
+        const j = rest.indexOf(PR_ONLY_END, i + PR_ONLY_START.length);
+        if (j === -1) {
+            // Unterminated — leave it standing so equality reports it.
+            out.push(rest);
+            break;
+        }
+        out.push(rest.slice(0, i));
+        rest = rest.slice(j + PR_ONLY_END.length);
+    }
+    return out.join('');
+}
+
 /** Footer appended to the release-PR body; the strip helper accepts legacy variants. */
 export const PR_BODY_FOOTER = 'Created by `src/scripts/release.ts`.';
 const _LEGACY_PR_FOOTERS = ['Created by `scripts/release.py`.', PR_BODY_FOOTER];
@@ -68,9 +178,18 @@ const _LEGACY_PR_FOOTERS = ['Created by `scripts/release.py`.', PR_BODY_FOOTER];
 /** Marker `_cap_body` embeds when a surface was truncated to a GitHub limit. */
 export const TRUNCATION_MARKER = '_Changelog truncated to fit GitHub';
 
-/** Release-PR body derived from the (possibly capped) changelog-section body. */
+/**
+ * Release-PR body derived from the (possibly capped) changelog-section body.
+ *
+ * Carries the authoring instruction inside the PR-only region. The region is
+ * emitted unconditionally rather than passed in by each caller: there are two
+ * PR-creation paths (`release.ts` and `release_publication.ts`), and a caller
+ * that forgot the argument would silently ship a PR with no reminder — the
+ * failure this change exists to make impossible, reintroduced one level up.
+ */
 export function pr_body_from_section(cappedBody: string, version: string): string {
-    return `Release ${version}.\n\n${cappedBody}\n\n${PR_BODY_FOOTER}`;
+    const prOnly = `${PR_ONLY_START}\n${CURATED_HEAD_INSTRUCTION_COMMENT}\n${PR_ONLY_END}`;
+    return `Release ${version}.\n\n${prOnly}\n\n${cappedBody}\n\n${PR_BODY_FOOTER}`;
 }
 
 /** GitHub-release notes derived from the (possibly capped) changelog-section body. */
@@ -96,6 +215,10 @@ export function strip_pr_wrapper(prBody: string, version: string): string | null
         return null;
     }
     s = s.slice(prefix.length);
+    // Delimiter-bounded, before the footer walk: the region is PR-only material
+    // by construction, so it is removed from the comparison rather than
+    // compared. Everything outside it still has to match the changelog.
+    s = strip_pr_only_regions(s);
     for (const footer of _LEGACY_PR_FOOTERS) {
         if (s.trimEnd().endsWith(footer)) {
             s = s.trimEnd();