@event4u/agent-config 16.0.0 → 16.1.0

package/src/scripts/_lib/rides_along.ts

@@ -0,0 +1,102 @@
+/**
+ * What rides along during a mission — `road-to-adversarial-verification-and-long-runs`
+ * 6.1.
+ *
+ * `active-remediation`'s ladder is fix-now / note+ask / follow-up PR, and its
+ * middle rung is unavailable inside an autonomous mission: there is nobody to
+ * ask. Without a replacement the rung collapses in one of two bad directions —
+ * every spotted issue becomes a fix (scope creep, which `minimal-safe-diff`
+ * exists to stop) or every one becomes silence (which `active-remediation`
+ * exists to stop). So under a mission the middle rung becomes **emit a follow-up
+ * artefact**, and this module decides which rung a candidate lands on.
+ *
+ * **Six criteria, ALL of which must hold.** They are `AND`-ed rather than scored
+ * because a scored version lets a large change buy its way in with four cheap
+ * yeses, which is the shape that turns a boy-scout rule into a refactor licence.
+ *
+ * Pure: the caller characterises the change, this decides. The characterisation
+ * is a judgement and stays the agent's; the DECISION is mechanical so it is the
+ * same for the same inputs.
+ */
+
+/** What the agent observed about a candidate improvement. */
+export interface Candidate {
+    /** What it is. Used only in the rendered line. */
+    readonly what: string;
+    /** In the same request path / module the mission is already touching. */
+    readonly local: boolean;
+    /** Small: roughly a handful of lines in one production file. */
+    readonly small: boolean;
+    /** Low blast radius — nothing outside this module observes the change. */
+    readonly lowBlastRadius: boolean;
+    /** Clearly correct: a reviewer would not need to be persuaded. */
+    readonly clearlyCorrect: boolean;
+    /** Testable, and the test ships in the same commit. */
+    readonly testable: boolean;
+    /** Carries NO new product decision — nothing about what the thing should do. */
+    readonly noProductDecision: boolean;
+}
+
+/** The kinds of improvement a mission may take at all. */
+export const RIDE_ALONG_KINDS: readonly string[] = [
+    'characterization-test',
+    'regression-test',
+    'small-adjacent-bug',
+    'naming',
+    'types',
+    'robustness',
+    'local-dead-code',
+    'simplify-touched-code',
+    'testability',
+] as const;
+
+export type Disposition = 'ride-along' | 'follow-up-artefact';
+
+export interface Verdict {
+    readonly disposition: Disposition;
+    /** Every criterion that failed, in declaration order. Empty on ride-along. */
+    readonly failed: readonly string[];
+}
+
+const CRITERIA: readonly (readonly [keyof Candidate, string])[] = [
+    ['local', 'not local to the path this mission is already touching'],
+    ['small', 'not small — more than a handful of lines in one file'],
+    ['lowBlastRadius', 'blast radius reaches beyond this module'],
+    ['clearlyCorrect', 'not clearly correct — a reviewer would need persuading'],
+    ['testable', 'not testable in the same commit'],
+    ['noProductDecision', 'carries a new product decision'],
+];
+
+/**
+ * Which rung this candidate lands on.
+ *
+ * Returns EVERY failed criterion rather than the first, because the follow-up
+ * artefact has to say why the change was deferred, and "it failed one of six"
+ * is not a reason a later reader can act on.
+ */
+export function disposition(c: Candidate): Verdict {
+    const failed = CRITERIA.filter(([k]) => c[k] !== true).map(([, why]) => why);
+    return {
+        disposition: failed.length === 0 ? 'ride-along' : 'follow-up-artefact',
+        failed,
+    };
+}
+
+/**
+ * The follow-up artefact's body — what was seen, and why it did not ride along.
+ *
+ * A deferral with no reason is the note-and-forget `active-remediation` already
+ * forbids, one layer out: the artefact exists so the issue is still owed, and an
+ * artefact that does not say why it was deferred cannot be triaged later.
+ */
+export function followUpBody(c: Candidate, v: Verdict): string {
+    if (v.disposition === 'ride-along') return '';
+    return [
+        `Deferred adjacent improvement: ${c.what}`,
+        '',
+        'Did not ride along because:',
+        ...v.failed.map((f) => `  - ${f}`),
+        '',
+        'Spotted during a mission; the code was left alone deliberately.',
+    ].join('\n');
+}

package/src/scripts/_lib/settings_renamed_keys.ts

@@ -0,0 +1,82 @@
+/**
+ * Settings keys this package has RENAMED, old path -> new path.
+ *
+ * Distinct from `REMOVED_KEYS` in the one way that matters to a user: a
+ * removed key's value is DISCARDED, and a renamed key's value is CARRIED.
+ * Putting a rename in the removed map would silently return an installed
+ * `false` to the shipped default, which is the opposite of accepting the old
+ * key — so the two maps stay separate even though both warn once.
+ *
+ * An entry is dropped one minor after it lands. The new key always wins when
+ * one layer carries both: a reader who has already migrated is not overridden
+ * by a stale line they forgot to delete.
+ *
+ * Its own module rather than more lines in `agent_settings.ts`, which sits
+ * three lines under the 1500-line source ceiling — a sixty-line addition there
+ * is sixty units of ratchet, and here it is none.
+ */
+
+export type SettingsLayer = Record<string, unknown>;
+
+export const RENAMED_KEYS: ReadonlyMap<string, string> = new Map([
+    ['planning.challenge_on_create', 'planning.closure_pass'],
+]);
+
+/** Keys already warned about in THIS process — the "once per run" dedupe. */
+const _warned = new Set<string>();
+
+/** Read a dotted path out of a settings tree. `undefined` when absent. */
+function _read(tree: SettingsLayer, dotted: string): unknown {
+    let cur: unknown = tree;
+    for (const part of dotted.split('.')) {
+        if (cur === null || typeof cur !== 'object' || Array.isArray(cur)) return undefined;
+        cur = (cur as SettingsLayer)[part];
+    }
+    return cur;
+}
+
+/** Write a dotted path into a settings tree, creating the intermediate maps. */
+function _write(tree: SettingsLayer, dotted: string, value: unknown): void {
+    const parts = dotted.split('.');
+    let cur: SettingsLayer = tree;
+    for (const part of parts.slice(0, -1)) {
+        const next = cur[part];
+        if (next === null || typeof next !== 'object' || Array.isArray(next)) cur[part] = {};
+        cur = cur[part] as SettingsLayer;
+    }
+    cur[parts[parts.length - 1] as string] = value;
+}
+
+/**
+ * Carry every renamed key's value onto its new path within ONE layer, and
+ * return that layer.
+ *
+ * Per LAYER, before the merge, and that ordering is the whole contract: the
+ * shipped template already carries the new key, so a rename applied to the
+ * MERGED tree would always find the target "already set" and drop the user's
+ * value on the floor. Applied per layer, the old key becomes the new key
+ * inside the layer that wrote it, and ordinary precedence does the rest.
+ *
+ * Mutates and returns `layer` so it can wrap an existing merge call without
+ * adding a statement. Never throws: a layer that cannot be walked is a layer
+ * with nothing to migrate.
+ */
+export function applyRenamedKeys<T extends SettingsLayer>(layer: T): T {
+    for (const [oldKey, newKey] of RENAMED_KEYS) {
+        const oldValue = _read(layer, oldKey);
+        if (oldValue === undefined) continue;
+        if (_read(layer, newKey) === undefined) _write(layer, newKey, oldValue);
+        if (_warned.has(oldKey)) continue;
+        _warned.add(oldKey);
+        process.stderr.write(
+            `⚠️  settings: \`${oldKey}\` was renamed to \`${newKey}\`. The old key still ` +
+                `works for one minor; rename it in your .agent-settings.yml.\n`,
+        );
+    }
+    return layer;
+}
+
+/** Test seam — the once-per-process warning dedupe is process state. */
+export function _resetRenameWarnings(): void {
+    _warned.clear();
+}

package/src/scripts/_lib/test_delta.ts

@@ -0,0 +1,166 @@
+/**
+ * Shared classification for the two test gates —
+ * `road-to-adversarial-verification-and-long-runs` Phase 2.4.
+ *
+ * `check_test_delta` and `check_test_weakening` ask different questions about
+ * the same diff, and both need the same answer to "is this path code?" and "is
+ * this path a test?". Two copies of that answer is how one gate starts counting
+ * a file the other does not, so the predicates live here once.
+ *
+ * Pure, and `node:`-free, so either gate and their tests may import it.
+ */
+
+/** A changed path that is production code this repository ships or runs. */
+export function isCodePath(p: string): boolean {
+    const f = p.replace(/\\/g, '/');
+    if (isTestPath(f)) return false;
+    if (!/\.(ts|tsx|js|mjs|cjs)$/.test(f)) return false;
+    if (f.endsWith('.d.ts')) return false;
+    // Generated trees are projections of `src/`, never an independent change.
+    if (/^(dist|\.augment|\.claude|\.cursor|node_modules)\//.test(f)) return false;
+    return /^(src|scripts)\//.test(f);
+}
+
+/** A changed path that carries tests. */
+export function isTestPath(p: string): boolean {
+    const f = p.replace(/\\/g, '/');
+    if (/^tests\//.test(f)) return true;
+    return /\.(test|spec)\.(ts|tsx|js|mjs|cjs)$/.test(f);
+}
+
+/**
+ * An independent-verdict artefact — the thing that makes a weakening legitimate.
+ *
+ * Deliberately a PATH test and not a content test. Whether the artefact actually
+ * contains an independent verdict is exactly the judgement `evaluator-independence`
+ * says no gate can make, so this gate checks that one was COMMITTED and leaves
+ * its quality to the review. Claiming more would be the coverage inflation that
+ * rule was written over.
+ */
+export function isVerdictArtefact(p: string): boolean {
+    const f = p.replace(/\\/g, '/');
+    return /^agents\/evidence\/reviews\//.test(f) && f.endsWith('.md');
+}
+
+/** One file's hunks, as a unified diff splits them. */
+export interface FileDiff {
+    readonly path: string;
+    readonly added: readonly string[];
+    readonly removed: readonly string[];
+}
+
+/**
+ * Split a unified diff into per-file added/removed line lists.
+ *
+ * Tolerant by construction: an unparseable header is skipped rather than thrown
+ * on, because a gate that crashes on an unusual diff blocks the fix for the
+ * diff that produced it. `+++ b/<path>` is the authority for the path — a rename
+ * shows the destination, which is the file whose assertions now count.
+ */
+export function parseUnifiedDiff(diff: string): FileDiff[] {
+    const out: FileDiff[] = [];
+    let path: string | null = null;
+    let oldPath: string | null = null;
+    let added: string[] = [];
+    let removed: string[] = [];
+    const flush = (): void => {
+        if (path !== null) out.push({ path, added, removed });
+        added = [];
+        removed = [];
+    };
+    for (const line of diff.split('\n')) {
+        if (line.startsWith('diff --git ')) {
+            flush();
+            path = null;
+            oldPath = null;
+            continue;
+        }
+        if (line.startsWith('--- ')) {
+            const p = line.slice(4).trim();
+            oldPath = p === '/dev/null' ? null : p.replace(/^a\//, '');
+            continue;
+        }
+        if (line.startsWith('+++ ')) {
+            const p = line.slice(4).trim();
+            // A DELETION (`+++ /dev/null`) keeps the OLD path rather than
+            // dropping the file. Reported by an independent review of the change
+            // that introduced this parser: deleting a test file is the maximal
+            // form of the weakening this gate exists to see, and `git rm
+            // tests/x.test.ts` was the cheapest way past it — the deletion even
+            // counted as a `tests/` path for the sibling delta gate. A file whose
+            // every assertion is removed at once is not zero signal.
+            path = p === '/dev/null' ? oldPath : p.replace(/^b\//, '');
+            continue;
+        }
+        if (line.startsWith('@@')) continue;
+        if (path === null) continue;
+        if (line.startsWith('+')) added.push(line.slice(1));
+        else if (line.startsWith('-')) removed.push(line.slice(1));
+    }
+    flush();
+    return out;
+}
+
+/**
+ * Lines that assert something.
+ *
+ * Framework-spread on purpose — this suite runs vitest, and the rule it enforces
+ * ships to consumers running pytest, PHPUnit and Go. A gate that only recognises
+ * one framework reports every other project as assertion-free, which is a false
+ * green and worse than no gate.
+ */
+const ASSERTION = /\b(expect|assert|assertThat|self\.assert|should\.|\.toBe|\.toEqual|\.toMatch|assertEquals|assertTrue|require\.(New|Equal|NoError))/;
+
+/** Lines that disable a test rather than assert with it. */
+const SUPPRESSION =
+    /(\b(it|test|describe|context)\s*\.\s*(skip|todo|failing)\b|\bxit\b|\bxdescribe\b|@pytest\.mark\.(skip|xfail)|\bt\.Skip\(|->markTestSkipped\(|@group\s+skip)/;
+
+/**
+ * A line whose match is DATA, not code — a diff line held inside a string.
+ *
+ * Found by this gate reporting its own test file: a suite that tests a
+ * suppression detector necessarily contains suppression-shaped strings as
+ * fixtures (`'+@pytest.mark.skip\n'`), and counting those made the gate report
+ * the one file whose job is to prove it works. Generalised rather than
+ * special-cased to that path — every gate that reads diffs will have a test
+ * suite shaped exactly this way, and "the gate exempts its own tests" is the
+ * carve-out that makes a detector unfalsifiable.
+ *
+ * The discriminator is a quote immediately followed by a diff marker: a string
+ * literal whose content begins `+` or `-`. Real test code does not open a string
+ * with a diff marker; a diff fixture does nothing else.
+ */
+const DIFF_LINE_AS_DATA = /['"`][+-]/;
+
+/** Counted evidence about one test file's diff. */
+export interface WeakeningSignal {
+    readonly path: string;
+    /** Assertions removed minus assertions added. Positive means a net loss. */
+    readonly assertionsLost: number;
+    /** Suppressions added minus suppressions removed. Positive means new skips. */
+    readonly suppressionsGained: number;
+}
+
+/**
+ * Measure a test file's diff as NET counts, never as raw removals.
+ *
+ * This is the discriminator the gate lives or dies on. Editing an assertion
+ * removes one line and adds another, so a gate counting raw removals reds every
+ * legitimate test edit — and a gate that reds every PR gets its exemption widened
+ * until it finds nothing, which is Risk 4 of the roadmap that commissioned it.
+ * A NET loss is a different claim: the file asserts less than it did.
+ */
+export function weakeningSignal(file: FileDiff): WeakeningSignal {
+    const count = (lines: readonly string[], re: RegExp): number =>
+        lines.filter((l) => re.test(l) && !DIFF_LINE_AS_DATA.test(l)).length;
+    return {
+        path: file.path,
+        assertionsLost: count(file.removed, ASSERTION) - count(file.added, ASSERTION),
+        suppressionsGained: count(file.added, SUPPRESSION) - count(file.removed, SUPPRESSION),
+    };
+}
+
+/** True when a signal is worth reporting at all. */
+export function isWeakening(s: WeakeningSignal): boolean {
+    return s.assertionsLost > 0 || s.suppressionsGained > 0;
+}

package/src/scripts/_lib/test_provenance.ts

@@ -0,0 +1,171 @@
+/**
+ * Per-test independence provenance — `road-to-adversarial-verification-and-long-runs` AC-2.
+ *
+ * `evaluator-independence` § Tests are evaluators states the five levels and
+ * says critical behaviour targets L3 or L4 wherever two providers are
+ * configured. It states no place to WRITE that down, so before this module the
+ * level a given test actually reached was unrecorded and therefore uncheckable —
+ * which is the same shape as the recorded failure that rule exists over: a
+ * verdict nobody could trace back to the prompt that produced it.
+ *
+ * The record is a comment line directly above a `describe(`:
+ *
+ * ```
+ * // provenance: level=L4 | critical=yes | evidence=ac2-authorship-run-a
+ * describe('T9 — a typed op reaches an exact-object ask', () => {
+ * ```
+ *
+ * **Three decisions worth reading, because each has a plausible opposite.**
+ *
+ * An unmarked group is `ungoverned`, never defaulted to L0. Defaulting would
+ * make "provenance is recorded per test" true by construction, and a claim that
+ * cannot be false is not a record.
+ *
+ * The provider count is a PARAMETER, not a probe. `agent-config council:status`
+ * resolves from a user-global file that a CI runner does not have, so probing
+ * it would make the floor depend on the machine and read "no providers, no
+ * obligation" exactly where the obligation matters. The caller supplies the
+ * count it is asserting about, and a repository with two configured providers
+ * pins 2.
+ *
+ * `evidence` is required at L3 and L4 and ignored below. An unattributed claim
+ * of independence cannot be checked for the independence it claims; at L0-L2
+ * there is no cross-provider claim to attribute, so demanding an artefact there
+ * would be ceremony.
+ *
+ * Pure — a string in, findings out. No filesystem, so both polarities are
+ * testable without a fixture tree.
+ */
+
+/** The five levels of `evaluator-independence` § Tests are evaluators. */
+export const INDEPENDENCE_LEVELS = ['L0', 'L1', 'L2', 'L3', 'L4'] as const;
+export type IndependenceLevel = (typeof INDEPENDENCE_LEVELS)[number];
+
+/** What critical behaviour targets where two providers are configured. */
+export const CRITICAL_FLOOR: IndependenceLevel = 'L3';
+
+/**
+ * The honest ceiling below two providers.
+ *
+ * With one provider, L3 ("another provider") is unreachable by definition, so
+ * the floor relaxes rather than demanding a level the install cannot produce. A
+ * floor nobody can clear gets deleted rather than met.
+ */
+export const SINGLE_PROVIDER_FLOOR: IndependenceLevel = 'L2';
+
+/** One group's recorded independence. */
+export interface ProvenanceRecord {
+    /** The `describe` title this record governs. */
+    readonly group: string;
+    readonly level: IndependenceLevel;
+    /** Security, authority, data loss or merge control. */
+    readonly critical: boolean;
+    /** The artefact the level came from. Empty is legal below L3. */
+    readonly evidence: string;
+    /** 1-based line of the marker, so a finding can point at it. */
+    readonly line: number;
+}
+
+export interface ProvenanceScan {
+    readonly records: readonly ProvenanceRecord[];
+    /** Titles of `describe`s carrying no valid marker. */
+    readonly ungoverned: readonly string[];
+}
+
+/** Rank within the ordered vocabulary. L0 is 0. */
+export function levelRank(level: IndependenceLevel): number {
+    return INDEPENDENCE_LEVELS.indexOf(level);
+}
+
+const MARKER = /^\s*\/\/\s*provenance:\s*(.*)$/;
+const DESCRIBE = /^\s*describe\(\s*(['"`])(.*?)\1/;
+
+function isLevel(v: string): v is IndependenceLevel {
+    return (INDEPENDENCE_LEVELS as readonly string[]).includes(v);
+}
+
+/** Parse `key=value | key=value` into a map. Unknown keys are ignored. */
+function fields(rest: string): Map<string, string> {
+    const out = new Map<string, string>();
+    for (const part of rest.split('|')) {
+        const eq = part.indexOf('=');
+        if (eq < 0) continue;
+        out.set(part.slice(0, eq).trim(), part.slice(eq + 1).trim());
+    }
+    return out;
+}
+
+/**
+ * Scan a test file's source for provenance records.
+ *
+ * A marker governs the `describe` it sits directly above — blank lines between
+ * them are tolerated, any other statement is not. Without that adjacency rule a
+ * marker anywhere in the file would appear to cover the next group, which is how
+ * one record silently becomes a claim about several.
+ */
+export function parseProvenance(source: string): ProvenanceScan {
+    const lines = source.split('\n');
+    const records: ProvenanceRecord[] = [];
+    const ungoverned: string[] = [];
+
+    for (let i = 0; i < lines.length; i += 1) {
+        const d = DESCRIBE.exec(lines[i] ?? '');
+        if (d === null) continue;
+        const group = d[2] ?? '';
+
+        // Walk back over blank lines to the candidate marker.
+        let j = i - 1;
+        while (j >= 0 && (lines[j] ?? '').trim() === '') j -= 1;
+        const m = j >= 0 ? MARKER.exec(lines[j] ?? '') : null;
+        if (m === null) {
+            ungoverned.push(group);
+            continue;
+        }
+        const f = fields(m[1] ?? '');
+        const level = f.get('level') ?? '';
+        if (!isLevel(level)) {
+            ungoverned.push(group);
+            continue;
+        }
+        records.push({
+            group,
+            level,
+            critical: f.get('critical') === 'yes',
+            evidence: f.get('evidence') ?? '',
+            line: j + 1,
+        });
+    }
+    return { records, ungoverned };
+}
+
+/**
+ * Critical groups that do not clear the floor for this provider count.
+ *
+ * Returns one human-readable finding per gap, naming the group, the level it
+ * records and what it owed — a caller reading the list should not have to open
+ * the file to know what to change.
+ */
+export function criticalGaps(
+    records: readonly ProvenanceRecord[],
+    providerCount: number,
+): string[] {
+    const floor = providerCount >= 2 ? CRITICAL_FLOOR : SINGLE_PROVIDER_FLOOR;
+    const gaps: string[] = [];
+    for (const r of records) {
+        if (!r.critical) continue;
+        if (levelRank(r.level) < levelRank(floor)) {
+            gaps.push(
+                `${r.group} (line ${String(r.line)}) records ${r.level}; critical behaviour ` +
+                    `needs ${floor} or above with ${String(providerCount)} provider(s) configured`,
+            );
+            continue;
+        }
+        if (levelRank(r.level) >= levelRank(CRITICAL_FLOOR) && r.evidence === '') {
+            gaps.push(
+                `${r.group} (line ${String(r.line)}) claims ${r.level} with no evidence; an ` +
+                    `unattributed claim of independence cannot be checked for the independence it claims`,
+            );
+        }
+    }
+    return gaps;
+}