@event4u/agent-config 14.17.0 → 14.19.0

package/src/scripts/_lib/tamper_vocabulary.ts

@@ -0,0 +1,242 @@
+/**
+ * The closed vocabulary the verification-tampering detector speaks.
+ *
+ * Declared in its own module, and declared BEFORE the detector, because the
+ * roadmap step that asks for it (`road-to-deterministic-defect-detectors` 1.1)
+ * asks for exactly that ordering: a detector that invents its ids while it is
+ * being written ends up with the ids its implementation found easy, not the
+ * ids the failure classes need. Every id below has a fixture in
+ * `tests/fixtures/tamper-corpus/`, committed one commit earlier.
+ *
+ * WHY THE OUTCOME TYPE EXTENDS `GateOutcome` INSTEAD OF REPLACING IT.
+ *
+ * `_lib/gate_result.ts` already separates "the check ran and found something"
+ * (`violations`) from "the check could not run" (`crashed`) from "the
+ * measurement is void" (`estate_invalid`). That distinction is the one a tamper
+ * detector most needs — a detector that crashed reporting `clean` is precisely
+ * the phantom green it exists to catch — so it is reused verbatim rather than
+ * re-spelled.
+ *
+ * Exactly ONE member is added, and only because `GateOutcome` cannot express
+ * it: `stale_verdict`. A runner that exited 0 before the last edit produces a
+ * green exit code over a tree that no longer exists. `clean` would launder it;
+ * `violations` would claim a finding nobody made; `crashed` would claim the
+ * runner failed when it succeeded — at the wrong time. The state is "it ran,
+ * it passed, and it is not evidence", and none of the four existing members
+ * says that. Adding a fifth member is a smaller change than a second
+ * vocabulary, which is what 1.1 forbids.
+ *
+ * SEVERITY, AND THE ONE CONTESTED CALL.
+ *
+ * Six ids are `block`. `verification-skipped` is `warn`, and that is not a
+ * confidence statement about the detection — an added `it.skip` is as
+ * mechanically certain as an added `.only`. It is a statement about the
+ * ACT: the source this roadmap came from is split on whether adding a skip
+ * on the way to green is tampering or triage, and this repository does not
+ * promote a class to blocking on a split. It ships `warn` with the corpus as
+ * the evidence a later promotion would need.
+ *
+ * THE ESCAPE HATCH IS SCOPED TO ONE ID, DELIBERATELY.
+ *
+ * A blanket `tamper-allow` in a commit message would suppress every detector at
+ * once, which turns one honest exception into a general amnesty. The grammar
+ * therefore names the id: `tamper-allow: <detector-id> — <reason>`. The reason
+ * floor mirrors `check_gate_completeness.MIN_REASON_CHARS` (20) and exists for
+ * the same reason stated there — it rejects `n/a`, and it cannot judge whether
+ * a reason is true, which stays a human read.
+ */
+import type { GateOutcome } from './gate_result.js';
+
+/** Every tampering class the detector can name. Closed set. */
+export type TamperDetectorId =
+    | 'assertion-removed'
+    | 'assertion-weakened'
+    | 'verification-skipped'
+    | 'expectation-rewritten'
+    | 'early-exit-injected'
+    | 'test-file-deleted'
+    | 'subject-mocked-away';
+
+export type TamperSeverity = 'block' | 'warn';
+
+export interface TamperDetectorSpec {
+    id: TamperDetectorId;
+    severity: TamperSeverity;
+    /** What shape in the diff fires this id. */
+    what: string;
+    /** Why that shape is a weakened verification rather than ordinary work. */
+    why: string;
+}
+
+export const TAMPER_DETECTORS: readonly TamperDetectorSpec[] = [
+    {
+        id: 'assertion-removed',
+        severity: 'block',
+        what: 'a removed assertion line with no assertion added in the same hunk',
+        why: 'the check that could fail is gone; what remains passes for a wider set of outputs',
+    },
+    {
+        id: 'assertion-weakened',
+        severity: 'block',
+        what: 'a removed assertion replaced in the same hunk by one lower on the strength ladder',
+        why: 'an exact-value check became an existence check, which passes for the broken output too',
+    },
+    {
+        id: 'verification-skipped',
+        severity: 'warn',
+        what: 'an added skip / xfail / only / ignore marker on a test',
+        why: 'the assertion survives the diff and stops running, which is the same thing at verdict time',
+    },
+    {
+        id: 'expectation-rewritten',
+        severity: 'block',
+        what: 'the same assertion call on both sides of a hunk with a different literal expected value',
+        why: 'the expectation moved onto whatever the code now emits, so the test can no longer disagree with it',
+    },
+    {
+        id: 'early-exit-injected',
+        severity: 'block',
+        what: 'an added unconditional return or exit above surviving assertions in a test body',
+        why: 'the test reports green having executed none of the verification below it',
+    },
+    {
+        id: 'test-file-deleted',
+        severity: 'block',
+        what: 'a test file deleted outright by the diff',
+        why: 'the fastest route to a green suite is the one that verifies nothing',
+    },
+    {
+        id: 'subject-mocked-away',
+        severity: 'block',
+        what: 'an added mock or stub whose target also appears on a removed line of the same file',
+        why: 'the function under test is replaced by a stub, so the test now asserts against its own fixture',
+    },
+] as const;
+
+/** Ids in declaration order — the canonical listing order for output. */
+export const TAMPER_DETECTOR_IDS: readonly TamperDetectorId[] = TAMPER_DETECTORS.map((d) => d.id);
+
+const BY_ID = new Map<string, TamperDetectorSpec>(TAMPER_DETECTORS.map((d) => [d.id, d]));
+
+/** True when `id` is a member of the closed set. */
+export function isTamperDetectorId(id: string): id is TamperDetectorId {
+    return BY_ID.has(id);
+}
+
+export function detectorSpec(id: TamperDetectorId): TamperDetectorSpec {
+    const spec = BY_ID.get(id);
+    /* c8 ignore next 3 -- unreachable while the map is built from the same array */
+    if (spec === undefined) {
+        throw new Error(`unknown tamper detector id: ${id}`);
+    }
+    return spec;
+}
+
+/**
+ * The loop's outcome vocabulary: `GateOutcome` plus the one state it cannot say.
+ *
+ * See the module header for why this is an extension of four members rather
+ * than a parallel set of five.
+ */
+export type LoopOutcome = GateOutcome | 'stale_verdict';
+
+/**
+ * One finding. `file` and `line` are mandatory and are checked at runtime by
+ * {@link assertWellFormed} — a finding without a location is a claim a reader
+ * cannot check, which is the shape of report this tree already refuses.
+ */
+export interface TamperFinding {
+    id: TamperDetectorId;
+    severity: TamperSeverity;
+    /** Repo-relative path as it appears in the diff header. */
+    file: string;
+    /** 1-based line number in the side of the diff the evidence lives on. */
+    line: number;
+    /** Which side `line` indexes — a removal has no post-image line. */
+    side: 'added' | 'removed';
+    /** The offending line, trimmed. Never empty. */
+    evidence: string;
+}
+
+/**
+ * Reject a finding that cannot be located.
+ *
+ * Deliberately a throw and not a filter: a detector that silently drops its own
+ * malformed findings under-reports, and under-reporting is the failure mode the
+ * whole detector exists to close.
+ */
+export function assertWellFormed(finding: TamperFinding): TamperFinding {
+    if (finding.file.trim() === '') {
+        throw new Error(`tamper finding ${finding.id} carries no file`);
+    }
+    if (!Number.isInteger(finding.line) || finding.line < 1) {
+        throw new Error(
+            `tamper finding ${finding.id} in ${finding.file} carries no usable line ` +
+                `(got ${String(finding.line)}); every finding must be locatable as file:line`,
+        );
+    }
+    if (finding.evidence.trim() === '') {
+        throw new Error(`tamper finding ${finding.id} at ${finding.file}:${String(finding.line)} carries no evidence text`);
+    }
+    return finding;
+}
+
+/** `path/to/file.ts:12` — the one location format the detector prints. */
+export function locate(finding: TamperFinding): string {
+    return `${finding.file}:${String(finding.line)}`;
+}
+
+/**
+ * Grammar of the scoped escape hatch, read from a commit message.
+ *
+ * Both an em dash and a plain hyphen are accepted as the separator: the
+ * repository writes em dashes in prose, and a contributor typing this into
+ * `git commit` will reach for `-`. Rejecting the hyphen would make the hatch
+ * fail in the direction that hides a legitimate change.
+ */
+export const TAMPER_ALLOW_RE = /^\s*tamper-allow:\s*([a-z-]+)\s*(?:—|--|-)\s*(.+)$/gim;
+
+/** Mirrors `check_gate_completeness.MIN_REASON_CHARS` — rejects `n/a`, judges nothing. */
+export const MIN_ALLOW_REASON_CHARS = 20;
+
+export interface AllowDeclaration {
+    id: TamperDetectorId;
+    reason: string;
+}
+
+export interface AllowParse {
+    allowed: Set<TamperDetectorId>;
+    /** Declarations that named an unknown id or gave too short a reason. */
+    malformed: string[];
+}
+
+/**
+ * Parse every `tamper-allow:` line out of a commit message.
+ *
+ * A malformed declaration does NOT suppress anything and is reported instead:
+ * a typo'd id that silently allowed nothing would read to its author as an
+ * accepted exception, and a typo'd id that silently allowed everything would be
+ * the amnesty this grammar exists to prevent.
+ */
+export function parseAllowDeclarations(message: string): AllowParse {
+    const allowed = new Set<TamperDetectorId>();
+    const malformed: string[] = [];
+    TAMPER_ALLOW_RE.lastIndex = 0;
+    for (const match of message.matchAll(TAMPER_ALLOW_RE)) {
+        const rawId = (match[1] ?? '').trim();
+        const reason = (match[2] ?? '').trim();
+        if (!isTamperDetectorId(rawId)) {
+            malformed.push(`tamper-allow names an unknown detector id: "${rawId}"`);
+            continue;
+        }
+        if (reason.length < MIN_ALLOW_REASON_CHARS) {
+            malformed.push(
+                `tamper-allow for "${rawId}" gives a ${String(reason.length)}-character reason; ` +
+                    `at least ${String(MIN_ALLOW_REASON_CHARS)} are required`,
+            );
+            continue;
+        }
+        allowed.add(rawId);
+    }
+    return { allowed, malformed };
+}

package/src/scripts/_lib/ui_authority.ts

@@ -341,3 +341,119 @@ export function operationConflicts(authority: UiAuthority, op: Operation): Confl
     }
     return out;
 }
+
+/* -------------------------------------------------------------------------- */
+/* Antipattern signal classes against the precedence list                      */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The five classes a `design-antipatterns.md` catalog row may claim.
+ *
+ * Kept here, beside the precedence list, rather than in the catalog gate: the
+ * question "may this signal overrule what the user supplied" is a precedence
+ * question, and precedence lives in exactly one module by construction.
+ */
+export type SignalClass =
+    | 'floor'
+    | 'invariant'
+    | 'craft-presumption'
+    | 'style-preference'
+    | 'reference-constraint';
+
+/** The two classes that are opinions rather than thresholds. */
+export const SOFT_CLASSES = ['craft-presumption', 'style-preference'] as const;
+
+export interface SignalVerdict {
+    /**
+     * `blocks` — refuse the surface. `flags` — surface it as a rebuttable
+     * presumption. `yields` — say nothing: something with more authority has
+     * already decided this.
+     */
+    outcome: 'blocks' | 'flags' | 'yields';
+    /** The precedence level that outranked it, numbered as in this file's header. */
+    outranked_by: { level: number; source: ProvenanceSource; detail: string } | null;
+    reason: string;
+}
+
+/**
+ * Where a soft signal sits against the precedence list.
+ *
+ * A craft presumption is a good default and nothing more. When the run has a
+ * supplied reference (4), a coherent incumbent (5), or a project `DESIGN.md`
+ * register (6), that artifact has already decided the question the presumption
+ * would re-open, and re-opening it is the redesign-by-taste failure
+ * `design-fidelity` exists to stop.
+ *
+ * A `floor` or an `invariant` is NOT a taste call — an accessibility threshold
+ * or a structural correctness rule — so nothing on the list releases it, and a
+ * reference artifact that violates one is a finding about the reference.
+ *
+ * LEVELS 1–3 ARE DELIBERATELY NOT MECHANISED HERE. Explicit user authority, a
+ * registered hard constraint, and the surface brief all outrank a presumption a
+ * fortiori, but `Signals` carries them only as whole-surface fields
+ * (`surface_mode`, `register`, `change_intent`) with no per-pattern statement.
+ * Reading a brief's mere presence as blanket permission for every antipattern
+ * would silence the catalog on every briefed surface, which is the opposite of
+ * what those levels mean. A per-pattern override is `DESIGN.md`'s declared
+ * suppression, which is level 6 and IS handled.
+ */
+export function resolveSignal(signalClass: SignalClass, signals: Signals = {}): SignalVerdict {
+    if (signalClass === 'floor' || signalClass === 'invariant') {
+        return {
+            outcome: 'blocks',
+            outranked_by: null,
+            reason:
+                `a ${signalClass} is a threshold, not a preference — no supplied artifact releases it, `
+                + 'and an artifact that violates one is a finding about the artifact',
+        };
+    }
+
+    if (signalClass === 'reference-constraint') {
+        const present = signals.reference !== undefined || signals.design_md?.present === true;
+        return present
+            ? {
+                outcome: 'blocks',
+                outranked_by: null,
+                reason: 'the reference or DESIGN.md this constraint is bound to is present in this run, so it carries that artifact\'s own authority',
+            }
+            : {
+                outcome: 'flags',
+                outranked_by: null,
+                reason: 'the reference this constraint is bound to is not present in this run, so it has no artifact behind it',
+            };
+    }
+
+    if (signals.reference !== undefined) {
+        return {
+            outcome: 'yields',
+            outranked_by: { level: 4, source: 'reference-artifact', detail: signals.reference.path ?? signals.reference.maturity },
+            reason: `a ${signalClass} never outranks a supplied reference artifact`,
+        };
+    }
+    if (signals.incumbent?.coherent === true) {
+        return {
+            outcome: 'yields',
+            outranked_by: { level: 5, source: 'incumbent-scan', detail: 'coherent incumbent' },
+            reason: `a ${signalClass} never outranks a coherent incumbent`,
+        };
+    }
+    if (signals.design_md?.present === true) {
+        return {
+            outcome: 'yields',
+            outranked_by: { level: 6, source: 'design-md', detail: signals.design_md.register ?? 'register unstated' },
+            reason: `a ${signalClass} never outranks a project DESIGN.md register`,
+        };
+    }
+    if (signals.product_md?.present === true) {
+        return {
+            outcome: 'yields',
+            outranked_by: { level: 6, source: 'product-md', detail: signals.product_md.register ?? 'register unstated' },
+            reason: `a ${signalClass} never outranks a project PRODUCT.md register`,
+        };
+    }
+    return {
+        outcome: 'flags',
+        outranked_by: null,
+        reason: `a ${signalClass} with nothing above it on the precedence list is a rebuttable presumption`,
+    };
+}

package/src/scripts/_lib/unified_diff.ts

@@ -0,0 +1,121 @@
+/**
+ * A minimal unified-diff reader.
+ *
+ * Written rather than pulled in: nothing in `src/scripts/_lib/` parses a diff
+ * (`grep -rl "diff --git" src/scripts/_lib/*.ts` returns nothing), and the two
+ * consumers here need three facts a full patch library would surround with
+ * fifty more — which side a line is on, what line number it lands on, and
+ * whether the file was deleted outright.
+ *
+ * Deliberately tolerant in one direction only: an unparseable line is skipped
+ * rather than thrown on, because a diff carrying an unexpected header must not
+ * make the detector crash into a green. Deliberately strict in the other: a
+ * hunk header that does not parse aborts the file, because line numbers that
+ * are wrong are worse than absent — every finding this feeds is a `file:line`
+ * claim a reader will try to open.
+ */
+
+export interface DiffLine {
+    side: 'added' | 'removed' | 'context';
+    /** 1-based line number on the side this line belongs to. */
+    line: number;
+    /** Line content with the leading +/-/space removed. */
+    text: string;
+}
+
+export interface DiffHunk {
+    header: string;
+    lines: DiffLine[];
+}
+
+export interface DiffFile {
+    /** Path as it appears after `b/`, or after `a/` for a deleted file. */
+    path: string;
+    /** True when the diff removes the file outright. */
+    deleted: boolean;
+    /** True when the diff creates the file. */
+    added: boolean;
+    hunks: DiffHunk[];
+}
+
+const HUNK_RE = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+const GIT_HEADER_RE = /^diff --git a\/(.+?) b\/(.+)$/;
+
+/** Parse a unified diff into files and hunks. Never throws on content. */
+export function parseUnifiedDiff(text: string): DiffFile[] {
+    const files: DiffFile[] = [];
+    let current: DiffFile | null = null;
+    let hunk: DiffHunk | null = null;
+    let oldNo = 0;
+    let newNo = 0;
+
+    for (const raw of text.split('\n')) {
+        const gitHeader = GIT_HEADER_RE.exec(raw);
+        if (gitHeader !== null) {
+            current = { path: gitHeader[2] ?? '', deleted: false, added: false, hunks: [] };
+            files.push(current);
+            hunk = null;
+            continue;
+        }
+        if (current === null) continue;
+
+        if (raw.startsWith('deleted file mode')) {
+            current.deleted = true;
+            continue;
+        }
+        if (raw.startsWith('new file mode')) {
+            current.added = true;
+            continue;
+        }
+        if (raw.startsWith('+++ ')) {
+            // `+++ /dev/null` is the other spelling of a deletion; some
+            // producers emit it without the `deleted file mode` line.
+            if (raw.slice(4).trim() === '/dev/null') current.deleted = true;
+            continue;
+        }
+        if (raw.startsWith('--- ')) {
+            if (raw.slice(4).trim() === '/dev/null') current.added = true;
+            continue;
+        }
+        if (raw.startsWith('index ') || raw.startsWith('similarity index') || raw.startsWith('rename ')) {
+            continue;
+        }
+
+        const hunkHeader = HUNK_RE.exec(raw);
+        if (hunkHeader !== null) {
+            oldNo = Number(hunkHeader[1]);
+            newNo = Number(hunkHeader[3]);
+            hunk = { header: raw, lines: [] };
+            current.hunks.push(hunk);
+            continue;
+        }
+        if (hunk === null) continue;
+
+        if (raw.startsWith('+')) {
+            hunk.lines.push({ side: 'added', line: newNo, text: raw.slice(1) });
+            newNo += 1;
+        } else if (raw.startsWith('-')) {
+            hunk.lines.push({ side: 'removed', line: oldNo, text: raw.slice(1) });
+            oldNo += 1;
+        } else if (raw.startsWith(' ') || raw === '') {
+            hunk.lines.push({ side: 'context', line: newNo, text: raw.slice(1) });
+            oldNo += 1;
+            newNo += 1;
+        }
+        // `` and anything else: skipped on purpose.
+    }
+    return files;
+}
+
+/** Every added line across the whole diff, with its file. */
+export function addedLines(files: readonly DiffFile[]): Array<{ file: DiffFile; line: DiffLine }> {
+    const out: Array<{ file: DiffFile; line: DiffLine }> = [];
+    for (const file of files) {
+        for (const h of file.hunks) {
+            for (const l of h.lines) {
+                if (l.side === 'added') out.push({ file, line: l });
+            }
+        }
+    }
+    return out;
+}

package/src/scripts/adr/regenerate_index.ts

@@ -16,7 +16,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { readAdrAxisCells, readAdrFrontmatterScalars } from '../_lib/adr_frontmatter.js';
+import { dated_trigger_day, readAdrAxisCells, readAdrFrontmatterScalars } from '../_lib/adr_frontmatter.js';
 import { generatedByItalic } from '../_lib/generated_by.js';
 
 // ^ADR-(\d{3})-([a-z0-9-]+)\.md$
@@ -262,6 +262,41 @@ export function scanOutside(repoRoot: string, roots: readonly string[] = OUTSIDE
     return out;
 }
 
+/**
+ * The rows whose `review_trigger` opens with a calendar date.
+ *
+ * WHY THIS SECTION CARRIES THE DATE AND NOT THE FIRED/NOT-FIRED STATE
+ * ------------------------------------------------------------------
+ * `regenerate_index --check` byte-compares this file in CI
+ * (`.github/workflows/rule-backstops.yml`), so anything rendered here has to be
+ * a function of the tree alone. A `fired` / `not-fired` column would be a
+ * function of the tree AND the day, which means the index would go stale on a
+ * calendar boundary nobody committed and red every open pull request until
+ * someone regenerated it. The date is the decidable half; the reader compares
+ * it to today, and `adr_cite_check` prints the comparison for a machine.
+ */
+export interface DatedTriggerRow {
+    label: string;
+    path: string;
+    day: string;
+    decision: string;
+}
+
+export function datedTriggerRows(rows: readonly Row[]): DatedTriggerRow[] {
+    const out: DatedTriggerRow[] = [];
+    for (const r of rows) {
+        const day = dated_trigger_day(r.review_trigger ?? '');
+        if (day === null) continue;
+        out.push({
+            label: 'num' in r ? `ADR-${r.num as string}` : (r.path as string).slice(0, -3),
+            path: r.path as string,
+            day,
+            decision: r.decision ?? r.slug ?? '—',
+        });
+    }
+    return out.sort((a, b) => a.day.localeCompare(b.day) || a.label.localeCompare(b.label));
+}
+
 /** Mirror `render(num, leg)`. */
 export function render(num: Row[], leg: Row[], outside: OutsideRow[] = []): string {
     const out = [
@@ -277,6 +312,24 @@ export function render(num: Row[], leg: Row[], outside: OutsideRow[] = []): stri
     if (leg.length > 0) {
         out.push('', '## Unnumbered (legacy)', '', HEAD, ...leg.map(row));
     }
+    const dated = datedTriggerRows([...num, ...leg]);
+    if (dated.length > 0) {
+        out.push(
+            '',
+            '## Dated review triggers',
+            '',
+            'A `review_trigger` that opens with a calendar date is the one reopen condition',
+            'this repository can decide without interpreting anything, so it is listed where a',
+            'reader meets it rather than only in a command they would have to know to run.',
+            'Compare the expiry to today; `./scripts-run src/scripts/adr_cite_check <ADR-NNN>`',
+            'prints `fired` or `not-fired` for the same date. Every other trigger is semantic',
+            'and reports `indeterminate` — a trigger that merely mentions a date is not listed.',
+            '',
+            '| Expiry | # | Decision |',
+            '|---|---|---|',
+            ...dated.map((d) => `| ${d.day} | [${d.label}](${d.path}) | ${d.decision} |`),
+        );
+    }
     if (outside.length > 0) {
         out.push(
             '',