@event4u/agent-config 14.19.0 → 14.21.0

package/src/scripts/_lib/release_highlights.ts

@@ -25,15 +25,7 @@
  */
 import { spawnSync } from 'node:child_process';
 
-import {
-    CURATED_HEAD_INSTRUCTION,
-    MIX_RESPONSE_MARKER,
-    MIX_RESPONSE_PLACEHOLDERS,
-    PROMISE_OUTCOMES,
-    PROMISE_PHRASE,
-    PROMISE_READBACK_MARKER,
-    extract_changelog_section,
-} from './release_material.js';
+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[] = [
@@ -406,7 +398,6 @@ export function publication_blockers(
     sectionBody: string,
     version: string,
     where = '`main`',
-    mix: MixObligation | null = null,
 ): string[] {
     const out: string[] = [];
     if (sectionBody.includes(DERIVED_MARKER)) {
@@ -423,13 +414,15 @@ export function publication_blockers(
                 'comment line from the section and re-run.',
         );
     }
-    out.push(...mix_response_blockers(sectionBody, version, where, mix));
     return out;
 }
 
 /**
  * Everything that makes a whole SECTION unpublishable — the head-level
- * blockers above plus the two obligations that only exist for a full section.
+ * blockers above plus the tests footer, which only exists for a full section.
+ *
+ * It was "the two obligations" until 2026-09-07: the governance-versus-product
+ * written answer was the other, and ADR-261 deleted it. One remains.
  *
  * Two levels and not one, because `publication_blockers` is legitimately called
  * with a bare curated head (the prefill tests do exactly that), and a head
@@ -450,9 +443,8 @@ export function section_publication_blockers(
     sectionBody: string,
     version: string,
     where = '`main`',
-    mix: MixObligation | null = null,
 ): string[] {
-    const out = publication_blockers(sectionBody, version, where, mix);
+    const out = publication_blockers(sectionBody, version, where);
     if (!TEST_FOOTER_RE.test(sectionBody)) {
         out.push(
             `the ${version} section carries no \`Tests: N (+M since PREV)\` footer. ` +
@@ -479,208 +471,24 @@ export function section_publication_blockers(
 const TEST_FOOTER_RE = /^Tests: \d+/mu;
 
 /**
- * The measured governance-versus-product level, as the writer and the guards
- * both receive it.
- *
- * A plain record and not the measurement itself: this module is reached by the
- * push guard, the pre-commit ask and the CI gate, and only the callers have git
- * to measure with. Passing the reading in keeps the predicate pure and keeps
- * `measure_release_mix`'s git access out of a module three guards import.
+ * The measured governance-versus-product level, as the writer receives it.
+ *
+ * A plain record and not the measurement itself: only the callers have git to
+ * measure with, and keeping `measure_release_mix`'s git access out of this
+ * module keeps it importable by the guards.
+ *
+ * It carried a `triggered` boolean until ADR-261, when the obligation that
+ * boolean gated was deleted. It was removed rather than kept with a rationale:
+ * the first attempt at this docblock claimed a reader of the published line
+ * could see the verdict, and a neutral review falsified that — `triggered` was
+ * set once and read nowhere, and `render_mix_response` never received it. The
+ * two counts in `level` are what the line publishes, and the taxonomy's own
+ * verdict stays where it is computed and printed, in `measure_release_mix`.
  */
 export interface MixObligation {
-    triggered: boolean;
     level: string;
 }
 
-/** Minimum written characters after the marker — a bare marker is not an answer. */
-export const MIX_RESPONSE_MIN_CHARS = 40;
-
-/**
- * The ONE predicate for the governance-versus-product obligation.
- *
- * `check_release_highlights` refuses this from the CI side and
- * `guard_release_branch_push` from the local side, and until 2026-09-05 only
- * the first of the two knew the obligation existed. That asymmetry is what the
- * contract itself recorded — *"the earliest refusal for this one obligation is
- * the PR, not the push"* (`docs/contracts/CHANGELOG-conventions.md`) — and what
- * cost 14.17.0 a red release PR. Both sides now read this function, so a change
- * to the obligation cannot reach one guard and miss the other.
- *
- * `null` means the measurement did not run (shallow clone, missing tag). That
- * degrades to no blocker, matching the gate's documented stance: this is a
- * governance signal, not a correctness control, and an environment fact must
- * not block a release.
- */
-export function mix_response_blockers(
-    sectionBody: string,
-    version: string,
-    where = '`main`',
-    mix: MixObligation | null = null,
-): string[] {
-    if (!mix || !mix.triggered) {
-        return [];
-    }
-    const idx = sectionBody.indexOf(MIX_RESPONSE_MARKER);
-    if (idx === -1) {
-        return [
-            `the ${version} section owes a governance-versus-product response ` +
-                `(${mix.level}) and carries none. Add one \`> ${MIX_RESPONSE_MARKER}\` line ` +
-                `immediately under the curated head on ${where}, naming the next cycle's ` +
-                'consumer work or a maintainer justification.',
-        ];
-    }
-    const block = mix_response_block(sectionBody, idx);
-    const left = MIX_RESPONSE_PLACEHOLDERS.filter((t) => block.includes(t));
-    if (left.length > 0) {
-        return [
-            `the ${version} governance-versus-product response still carries the writer's ` +
-                `placeholder(s) (${left.map((t) => `\`${t}\``).join(', ')}) — the measured level ` +
-                'is the generator\'s, the answer is not, and `CHANGELOG.md` is published to npm. ' +
-                `Name the next cycle's consumer work (or the justification) on ${where} and re-run.`,
-        ];
-    }
-    if (human_answer(block, mix.level).length < MIX_RESPONSE_MIN_CHARS) {
-        return [
-            `the ${version} governance-versus-product response carries no written answer ` +
-                `beyond the measured level (${mix.level}). The level is the generator's; the ` +
-                `response has to name the next cycle's consumer work or a maintainer ` +
-                `justification. Write it on ${where}, in the \`> \` block under the marker.`,
-        ];
-    }
-    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.
- *
- * Reading only the FIRST line after the marker was wrong in both directions, and
- * both were reproduced before this was written. It **accepted** a section whose
- * placeholder line had simply been deleted, because the machine-written level
- * alone is 54 characters and cleared the floor — the smuggled auto-approval the
- * placeholder exists to prevent. And it **refused** the writer's own two-line
- * template, where the level sits on line 1 and the answer on line 2.
- *
- * Scoping to the block also fixes the placeholder scan, which searched the
- * entire section body: a legitimate changelog line containing
- * `<roadmap or issue>` blocked the release.
- */
-export function mix_response_block(sectionBody: string, markerIdx: number): string {
-    const lines = sectionBody.slice(markerIdx).split('\n');
-    const out: string[] = [lines[0] ?? ''];
-    for (const line of lines.slice(1)) {
-        if (!line.trimStart().startsWith('>')) break;
-        out.push(line);
-    }
-    return out.join('\n');
-}
-
-/**
- * What is left of the response block once the generator's own contribution is
- * removed — i.e. the part a human had to write.
- *
- * The measured level is stripped because the writer emitted it; a floor that
- * counted it would be satisfied by the tool on the author's behalf, which is
- * the whole failure this obligation guards against.
- */
-export function human_answer(block: string, level: string): string {
-    return block
-        .replace(MIX_RESPONSE_MARKER, '')
-        .split(level)
-        .join('')
-        .replace(/^[>\s.]+|[>\s.]+$/gu, '')
-        .replace(/[>\s]+/gu, ' ')
-        .trim();
-}
-
 /** 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

@@ -300,95 +300,45 @@ function _first_diff(a: string, b: string): string {
  * a branch, a PR and a CI run — the exact cost `guard_release_branch_push` was
  * added to avoid for the sibling obligation two releases earlier.
  *
- * This module has no imports on purpose (see `CURATED_HEAD_INSTRUCTION`), which
- * is what lets the writer, the local push guard and the CI gate all reach one
- * definition instead of three copies.
+ * This module has no imports on purpose (see `CURATED_HEAD_INSTRUCTION`).
+ *
+ * **One reader left, as of ADR-261 (2026-09-07).** This paragraph used to say
+ * the definition was shared by "the writer, the local push guard and the CI
+ * gate", which was true while `mix_response_blockers` and
+ * `check_governance_mix_response` scanned a section for this marker. Both are
+ * deleted, and with them every search for it: the only consumer now is
+ * `render_mix_response` in this same file, which WRITES the line. Nothing reads
+ * a changelog looking for it, so do not assume a guard notices when it is
+ * missing — none does.
  */
 export const MIX_RESPONSE_MARKER = '**Governance mix:**';
 
 /**
- * The sentinel that marks an EMITTED-BUT-UNANSWERED response.
- *
- * A generator that emits the measured level alone would satisfy the gate's
- * length floor (`MIX_RESPONSE_MIN_CHARS`, 40) with a number the machine
- * produced, turning a written-answer obligation into a formality the tool
- * discharges for itself. That is a smuggled auto-approval, not a fix.
+ * Render the measured governance-versus-product line the writer emits.
  *
- * So the writer emits the level AND this sentinel, and every gate refuses the
- * sentinel — the same discipline `CURATED_HEAD_INSTRUCTION` and
- * `DERIVED_MARKER` already follow. The net effect is only that the obligation
- * moves from CI to the moment the section is written, where the fix is an edit
- * to a file already open in the working tree.
- */
-export const MIX_RESPONSE_PLACEHOLDER = '<the consumer work>';
-
-/**
- * Every placeholder token the writer emits, so none of them can ship.
+ * ONE line, and machine-written end to end. It reports what the span measured
+ * and asks the releaser for nothing.
  *
- * The block carries two, and refusing only the first would leave
- * `<roadmap or issue>` publishable — `CHANGELOG.md` is in `package.json`
- * `files`, so that is the same "the generator's own scaffolding reached npm"
- * failure `CURATED_HEAD_INSTRUCTION` exists for, one token to the right.
+ * The written-answer obligation is gone (ADR-261). This used to emit a second line — `Next cycle ships <the consumer work>,
+ * tracked in <roadmap or issue>.` — a placeholder no generator was allowed to
+ * fill, backed by four refusals, an interactive prompt, a staging channel under
+ * `## [Unreleased]` and a read-back obligation on the following release. The
+ * releaser had to type prose into a running pipeline to get a version out.
  *
- * A named list rather than a shape match over angle brackets, for the reason
- * that constant already states: a pattern such as `/<[a-z ]+>/` rejects
- * unrelated legitimate prose and misses a reworded placeholder. Adding a token
- * to `render_mix_response` means adding it here.
- */
-export const MIX_RESPONSE_PLACEHOLDERS: readonly string[] = [
-    MIX_RESPONSE_PLACEHOLDER,
-    '<roadmap or issue>',
-];
-
-/**
- * Render the response block the writer emits when the obligation triggers.
+ * The owner ended it: this package exists to make the maintainer's work
+ * cheaper, and a release gate that stops a green pipeline until a human writes
+ * a sentence about a FUTURE cycle is the opposite. The measurement stays
+ * because it is free and true; the homework does not.
  *
- * Two blockquote lines, immediately under the curated head and outside it, per
- * `docs/contracts/CHANGELOG-conventions.md` § Governance-versus-product
- * response — the head's ten-line cap is for product lines, and a sixth label
- * would make every historical section retroactively incomplete.
+ * The removed placeholder constants (`MIX_RESPONSE_PLACEHOLDER(S)`) and promise
+ * sentinels (`PROMISE_PHRASE`, `PROMISE_READBACK_MARKER`, `PROMISE_OUTCOMES`)
+ * are deleted rather than deprecated — a sentinel nothing writes and nothing
+ * refuses is dead weight that reads as live policy.
  */
 export function render_mix_response(level: string): string[] {
-    return [
-        `> ${MIX_RESPONSE_MARKER} ${level}.`,
-        `> ${PROMISE_PHRASE} ${MIX_RESPONSE_PLACEHOLDER}, tracked in <roadmap or issue>.`,
-    ];
+    return [`> ${MIX_RESPONSE_MARKER} ${level}.`];
 }
 
-/**
- * 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[] = [];

package/src/scripts/_lib/release_position.ts

@@ -0,0 +1,96 @@
+/**
+ * Where a release may START — the branch it may run from, and whether a dirty
+ * working tree is tolerated there.
+ *
+ * Its own module because `release.ts` sits 456 lines over the 1500-line source
+ * ratchet, so growing it is a gate failure by construction. `_lib/` is where
+ * `release_highlights.ts` and `release_material.ts` already put the predicates
+ * the pipeline and its gates share.
+ */
+
+export interface PositionVerdict {
+    proceed: boolean;
+    /** Printed before the run continues. Never a refusal. */
+    notice?: string;
+    /** Printed on refusal (no trailing newline). */
+    message?: string;
+}
+
+/**
+ * Where a release may START, resolved as a pure verdict (no I/O, so it is
+ * unit-testable — same shape as `confirmGate`).
+ *
+ * THE DEADLOCK THIS REMOVES.
+ *
+ * `guard_release_curation` refuses BETWEEN step 2 and step 3: step 1 has
+ * already created and checked out `release/{target}`, step 2 has already
+ * written the bump, the changelog section and every regenerated derived file,
+ * and nothing is committed yet. Its message says to curate the head and re-run
+ * `task release`. Measured on 14.19.0, neither re-run reached step 1:
+ *
+ *   - `task release`            → `release must run from 'main'` (this check)
+ *   - `task release --resume`   → `working tree is not clean` (this check)
+ *
+ * So the guard prescribed a remedy the preflight refused, in both spellings,
+ * and the only way through was to hand-craft the `release: X.Y.Z` commit the
+ * pipeline makes for itself one step later.
+ *
+ * `docs/release-runbook.md` already claimed this was closed on 2026-09-03 and
+ * the drill pins `plain-run-reuses-an-existing-branch` for it. Both were true
+ * of the fix that landed — in `checkout_release_branch`, which is STEP 1. The
+ * preflight runs before step 1, so from the release branch the run never
+ * arrived at the code that had been repaired. The claim was not wrong about
+ * step 1; it was wrong that step 1 was reachable from that position.
+ *
+ * Why `release/{target}` is a legitimate start, with or without `--resume`:
+ *
+ * It is the position the pipeline itself leaves behind. `--resume` remains
+ * meaningful for what it was always for — skipping a COMMIT, a PR, a tag or a
+ * Release that already exists — and the `!resume` tag-exists check in
+ * `preflight` still refuses a plain re-run of an already-tagged version.
+ *
+ * Why a dirty tree is accepted THERE and nowhere else:
+ *
+ * On `release/{target}` the dirt is this pipeline's own step-2 output, and
+ * step 3 sweeps it with `git add -A` regardless. Refusing it can therefore
+ * only ever fire against the tool's own state. On `main` the same tree is an
+ * operator's unrelated work about to be swept into a release commit, so the
+ * refusal stays exactly as it was. The accepted files are PRINTED rather than
+ * absorbed silently, and `check_release_pr_shape` still refuses anything
+ * outside the version-bump allowlist on the resulting PR — two nets under the
+ * one place this relaxes.
+ */
+export function preflightPosition(opts: {
+    branch: string;
+    mainBranch: string;
+    releaseBranch: string;
+    porcelain: string;
+}): PositionVerdict {
+    const { branch, mainBranch, releaseBranch, porcelain } = opts;
+    if (branch !== mainBranch && branch !== releaseBranch) {
+        return {
+            proceed: false,
+            message:
+                `release must run from '${mainBranch}' or '${releaseBranch}', ` +
+                `currently on '${branch}'`,
+        };
+    }
+    if (!porcelain.trim()) {
+        return { proceed: true };
+    }
+    if (branch === mainBranch) {
+        return { proceed: false, message: 'working tree is not clean; commit or stash first' };
+    }
+    return {
+        proceed: true,
+        notice:
+            `working tree is not clean, and on '${releaseBranch}' that is this pipeline's own ` +
+            'step-2 output — step 3 commits it with `git add -A`. Files that will be swept ' +
+            'into the release commit:\n' +
+            porcelain
+                .split('\n')
+                .filter((l) => l.trim())
+                .map((l) => `      ${l}`)
+                .join('\n'),
+    };
+}

package/src/scripts/_lib/review_skipped_record.ts

@@ -34,6 +34,7 @@
  */
 export type MutationMeasure = 'exact' | 'capped_approximation';
 
+import { appliedIds } from './audit_field_provenance.js';
 import type { NoFreeForm } from './runtime_journal.js';
 import { type PrivacyClass } from './privacy_class.js';
 
@@ -55,6 +56,20 @@ export interface ReviewSkippedInput {
     /** Stable id (ULID, UUID, or content hash); caller supplies. */
     id: string;
     work_id?: string | undefined;
+    /**
+     * Stable rule ids the run ACTUALLY carried. Absent means `[]`, an honest
+     * absence — this writer observes a review that did NOT happen, so it
+     * usually has no rules observation to offer in either direction.
+     *
+     * It wrote the literal `['delegation-policy']` on every line until
+     * 2026-09-07, which made the whole audit stream's most frequent "pattern" a
+     * property of the writer. See `_lib/audit_field_provenance.ts` for the
+     * measurement, and note the difference from `skills_applied` below: that
+     * field is OMITTED because audit-log-v1 lets absence mean "not recorded",
+     * while `rules_applied` is mandatory on every line and `[]` is how absence
+     * is spelled there.
+     */
+    rules_applied?: string[] | null | undefined;
 }
 
 export interface BuiltReviewSkippedLine {
@@ -102,7 +117,8 @@ export function buildReviewSkippedLine(input: ReviewSkippedInput): BuiltReviewSk
         risk_class: input.diff_lines >= HIGH_RISK_DIFF_LINES ? 'high' : 'medium',
         memory: { asks: 0, hits: 0 },
         verify: { claims: 0, first_try_passes: 0 },
-        rules_applied: ['delegation-policy'],
+        // COMPUTED, never a producer constant.
+        rules_applied: appliedIds(input.rules_applied),
         // MANDATORY on every audit line, same as the orchestration producer.
         privacy_class: PRODUCER_PRIVACY_CLASS,
         // `skills_applied` is OMITTED here, deliberately and not by oversight.