@event4u/agent-config 14.12.0 → 14.14.0

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();

package/src/scripts/_lib/repeated_failure.ts

@@ -0,0 +1,105 @@
+/**
+ * The repeated-failure rate — computed over the AMENDED view, by construction.
+ *
+ * This is the roadmap's single pre-registered core metric, and the reason it
+ * needed the amendment path first is arithmetic rather than aesthetic. A repeat
+ * is precisely the signal that surfaces AFTER an episode's terminal record is
+ * written: rework lands, a regression is found, a review comes back. A rate
+ * computed over unamended rows therefore undercounts the exact thing it exists
+ * to measure, and undercounts it in the flattering direction.
+ *
+ * The guarantee here is structural, not documentary: this module's input type
+ * is {@link EpisodeReconstruction}, which is the folded projection. It has no
+ * overload taking raw `JournalEvent[]`, so a caller CANNOT accidentally compute
+ * the rate over unamended rows — there is nothing to pass.
+ */
+
+import type { BasisTag } from './evidence_basis.js';
+import type { EpisodeReconstruction } from './runtime_journal.js';
+import { RUN_TERMINAL_STATES, type RunTerminalState } from './outcome_vocabularies.js';
+
+/**
+ * Terminal states that count as a failure for this metric.
+ *
+ * `clean-no-op` is deliberately NOT a failure: an episode that correctly
+ * determined there was nothing to do succeeded at the thing it was asked. And
+ * `approval-required` is not one either — it is the safety floor working, and
+ * counting a floor doing its job as a failure would make the metric fall every
+ * time governance fires.
+ */
+export const FAILURE_TERMINALS: ReadonlySet<RunTerminalState> = new Set([
+    'blocked',
+    'exhausted',
+    'stagnated',
+]);
+
+/** States that count as a success for the metric. */
+export const SUCCESS_TERMINALS: ReadonlySet<RunTerminalState> = new Set([
+    'success',
+    'clean-no-op',
+]);
+
+// Every terminal state is classified or deliberately excluded -- silence about
+// one is how a metric quietly changes meaning when the vocabulary grows.
+const CLASSIFIED = new Set<string>([...FAILURE_TERMINALS, ...SUCCESS_TERMINALS, 'approval-required']);
+const _unclassified = RUN_TERMINAL_STATES.filter((t) => !CLASSIFIED.has(t));
+if (_unclassified.length > 0) {
+    throw new Error(
+        `repeated_failure: terminal state(s) ${_unclassified.join(', ')} are neither a failure, ` +
+            'a success, nor explicitly excluded. Classify them or the rate silently changes meaning.',
+    );
+}
+
+export interface RepeatedFailureRate {
+    /** Episodes whose EFFECTIVE terminal state is a failure. */
+    failed: number;
+    /** Episodes with any classifiable effective terminal state. */
+    classified: number;
+    /** Episodes whose terminal state is absent or excluded. Its own share. */
+    unknown: number;
+    /** `failed / classified`, or `null` when nothing was classifiable. */
+    rate: number | null;
+    /** How many of the counted episodes carried at least one amendment. */
+    amended_episodes: number;
+    basis: BasisTag;
+}
+
+/**
+ * Compute the rate.
+ *
+ * `rate` is `null`, never `0`, when nothing classifiable was seen — the same
+ * rule the per-asset report follows, for the same reason: zero is a measurement
+ * and null is an absence, and a reader acts on the first while asking about the
+ * second.
+ */
+export function repeatedFailureRate(
+    episodes: readonly EpisodeReconstruction[],
+): RepeatedFailureRate {
+    let failed = 0;
+    let classified = 0;
+    let unknown = 0;
+    let amended_episodes = 0;
+
+    for (const ep of episodes) {
+        if (ep.amendment_count > 0) amended_episodes += 1;
+
+        // `ep.terminal_state` is already the AMENDED verdict: reconstructEpisode
+        // drops superseded rows and takes the LAST effective terminal state.
+        const t = ep.terminal_state;
+        if (t === null || !CLASSIFIED.has(t) || t === 'approval-required') {
+            unknown += 1;
+            continue;
+        }
+        classified += 1;
+        if (FAILURE_TERMINALS.has(t)) failed += 1;
+    }
+
+    return {
+        failed,
+        classified,
+        unknown,
+        rate: classified === 0 ? null : failed / classified,
+        amended_episodes,
+        basis: 'estimated:ratio-over-amended-episode-terminals',
+    };
+}

package/src/scripts/_lib/repo_root.ts

@@ -0,0 +1,111 @@
+/**
+ * Repository-root resolution that REFUSES rather than guesses.
+ *
+ * `road-to-skill-ecosystem-runtime-enforcement` Phase 2 Step 6. The trap class
+ * this closes is small to describe and has cost multiple sessions:
+ *
+ *   1. **An inherited `GIT_DIR`.** A git hook exports `GIT_DIR` (often `.git`,
+ *      relative) into every child process. A gate that resolves its root with
+ *      `git rev-parse --show-toplevel` then answers for whatever repository the
+ *      inherited variable points at — which inside a worktree hook is the parent
+ *      checkout, not the tree being committed. The gate runs, reads the wrong
+ *      files, and passes.
+ *   2. **A path walked one directory too far.** `path.resolve(__dirname, '..',
+ *      '..')` is correct until a file moves, and then it silently addresses a
+ *      parent directory that also exists. Nothing fails; the scan is simply
+ *      empty, which several gates report as a clean pass.
+ *
+ * Both are the same failure in the end: a resolver that always SUCCEEDS. So the
+ * contract here is the opposite — a root is returned only when the directory
+ * carries a **sentinel** proving it is the repository, and otherwise the call
+ * throws. A caller that cannot locate its own repository should stop, not scan
+ * an arbitrary directory.
+ *
+ * The sentinel is `package.json` carrying this package's `name`, not a bare
+ * `package.json`: every node_modules entry and every sibling project has one of
+ * those, and a resolver that accepts any of them has not narrowed anything.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** The package name that identifies THIS repository. */
+export const SENTINEL_PACKAGE_NAME = '@event4u/agent-config';
+
+/** Raised when no directory on the walk carries the sentinel. */
+export class RepoRootUnresolvedError extends Error {
+    readonly startedAt: string;
+
+    constructor(startedAt: string, message: string) {
+        super(message);
+        this.name = 'RepoRootUnresolvedError';
+        this.startedAt = startedAt;
+    }
+}
+
+/**
+ * True when `dir` is this repository's root.
+ *
+ * Reads `package.json` and compares `name`. A parse failure is `false`, never a
+ * throw: a malformed `package.json` somewhere up the walk must not stop the walk
+ * from reaching a valid root above it.
+ */
+export function hasSentinel(dir: string): boolean {
+    try {
+        const raw = fs.readFileSync(path.join(dir, 'package.json'), 'utf8');
+        return (JSON.parse(raw) as { name?: unknown }).name === SENTINEL_PACKAGE_NAME;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Walk upward from `from` and return the first directory carrying the sentinel.
+ *
+ * @throws {RepoRootUnresolvedError} when the walk reaches the filesystem root
+ * without finding one. Deliberately not a `null` return: an optional type
+ * invites `?? process.cwd()`, which is the guess this module exists to prevent.
+ */
+export function resolveRepoRoot(from: string = process.cwd()): string {
+    let dir = path.resolve(from);
+    const seen: string[] = [];
+    for (;;) {
+        seen.push(dir);
+        if (hasSentinel(dir)) return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+    }
+    throw new RepoRootUnresolvedError(
+        path.resolve(from),
+        `no repository root above ${path.resolve(from)} — no directory on the walk carries a ` +
+            `package.json named "${SENTINEL_PACKAGE_NAME}". Checked ${String(seen.length)} directory(ies). ` +
+            'This is a refusal, not a fallback: resolving to the working directory here is how a gate ' +
+            'ends up scanning an arbitrary tree and reporting a clean pass over it.',
+    );
+}
+
+/**
+ * The environment variables that override git's own discovery.
+ *
+ * `GIT_DIR` is the one that has actually bitten; the other three are listed
+ * because they fail the same way and a reader checking for one should see all
+ * four rather than believe the list is complete at one entry.
+ */
+export const GIT_DISCOVERY_OVERRIDES = [
+    'GIT_DIR',
+    'GIT_WORK_TREE',
+    'GIT_INDEX_FILE',
+    'GIT_COMMON_DIR',
+] as const;
+
+/** Any git discovery override present in `env`, with its value. */
+export function inheritedGitOverrides(
+    env: NodeJS.ProcessEnv = process.env,
+): { name: string; value: string }[] {
+    const out: { name: string; value: string }[] = [];
+    for (const name of GIT_DISCOVERY_OVERRIDES) {
+        const value = env[name];
+        if (typeof value === 'string' && value !== '') out.push({ name, value });
+    }
+    return out;
+}

package/src/scripts/_lib/review_skipped_record.ts

@@ -34,6 +34,17 @@
  */
 export type MutationMeasure = 'exact' | 'capped_approximation';
 
+import type { NoFreeForm } from './runtime_journal.js';
+import { type PrivacyClass } from './privacy_class.js';
+
+type Assert<T extends true> = T;
+
+/**
+ * What THIS producer's lines carry: counts (`diff_lines`), enums, and the
+ * `rules_applied` id array. `ids-only`, same as the orchestration producer.
+ */
+const PRODUCER_PRIVACY_CLASS: PrivacyClass = 'ids-only';
+
 export interface ReviewSkippedInput {
     /** Non-doc tracked-file mutation size that triggered the nudge (count only). */
     diff_lines: number;
@@ -92,6 +103,15 @@ export function buildReviewSkippedLine(input: ReviewSkippedInput): BuiltReviewSk
         memory: { asks: 0, hits: 0 },
         verify: { claims: 0, first_try_passes: 0 },
         rules_applied: ['delegation-policy'],
+        // 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.
+        // audit-log-v1 distinguishes an absent key ("not recorded") from `[]`
+        // ("recorded, none applied"), and this writer observes a review that
+        // did not happen -- it has no skill observation to offer in either
+        // direction. Emitting `[]` would assert "no skills applied" on evidence
+        // this producer never gathered, which is the exact fabrication the
+        // absent/empty split exists to make impossible.
         persona: null,
         input_kind: 'prompt',
         type: 'note',
@@ -100,3 +120,20 @@ export function buildReviewSkippedLine(input: ReviewSkippedInput): BuiltReviewSk
 
     return { line, errors: [] };
 }
+
+/**
+ * The SECOND producer's half of the compile-time privacy floor.
+ *
+ * `docs/contracts/audit-log-v1.md` states that the floor holds by construction
+ * "on two paths"; guarding only the first would leave that sentence half true
+ * while reading as fully true. Same mechanism as
+ * `orchestration_record.ts`: a free-form key on the input type makes this
+ * `Assert<false>` and stops the build.
+ *
+ * The negative direction is fixtured there rather than duplicated here — one
+ * proof that `NoFreeForm` still rejects is enough for both call sites, since
+ * they share the type.
+ */
+type _ReviewSkippedInputCarriesNoFreeFormField = Assert<
+    [NoFreeForm<ReviewSkippedInput>] extends [never] ? false : true
+>;