@event4u/agent-config 15.0.0 → 16.1.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;
+}

package/src/scripts/_lib/turn_end_refusals.ts

@@ -41,15 +41,21 @@ import * as path from 'node:path';
 import { read_lockfile } from './installed_lock.js';
 
 /**
- * The four detectors, in the order the gate runs them.
+ * The five detectors, in the order the gate runs them.
  *
  * The roadmap's § 0 names three (A promissory, B language, C verification).
  * That was true of the draft and is not true of the tree: detector D
- * (`completion`) landed under round 7 § Phase 1 and runs in the same detector
- * list as the other three. Counting three would silently drop a detector's
+ * (`completion`) landed under round 7 § Phase 1, detector E
+ * (`pending-decision`) under road-to-a-question-that-survives-the-turn, and
+ * detector F (`untested`) on 2026-09-11 — all of which run in the same detector
+ * list as the first three. Counting three would silently drop a detector's
  * refusals, so the set is read off `DetectorId` in the gate rather than off the
  * prose.
  *
+ * F is the one that asks whether a change is TESTED rather than whether
+ * something ran: C is satisfied by `eslint`, which is how a feature with zero
+ * test lines passed every guard in that file.
+ *
  * This said "the same UNCONDITIONAL list" until 2026-08-18, which was wrong and
  * is worth naming rather than quietly rewording: `main()` runs A and D only when
  * no subagent dispatch is open. It does not change this set — every detector
@@ -63,6 +69,8 @@ export const DETECTOR_IDS = [
     'language',
     'verification',
     'completion',
+    'pending-decision',
+    'untested',
 ] as const;
 
 export type RefusalDetectorId = (typeof DETECTOR_IDS)[number];
@@ -138,10 +146,39 @@ export interface RefusalRecord {
     counts?: Partial<DetectorCounts>;
     /** Package version recorded at the most recent refusal, when readable. */
     agent_config_version?: string;
+    /**
+     * The host's own id for the prompt being processed at the most recent
+     * refusal, when the payload carries one.
+     *
+     * Recorded BESIDE `refused_turn`, never instead of it. The ordinal stays the
+     * re-entrancy key — its drift history is why both guard layers exist, and
+     * swapping the key of a wedge-critical guard on an axis nothing measures is
+     * a behaviour change dressed as a correction. What the pair buys is the
+     * measurement: two refusals carrying the same `refused_prompt_id` and
+     * different `refused_turn` are one prompt whose ordinal drifted, which is
+     * the failure this file's own header describes and which the ordinal alone
+     * cannot distinguish from two genuine turns.
+     */
+    refused_prompt_id?: string;
 }
 
+/**
+ * A zeroed counter per detector, DERIVED from `DETECTOR_IDS` rather than
+ * written out.
+ *
+ * It was an object literal of four keys until detector E landed, and the
+ * literal is what made adding a detector a silent arithmetic defect rather than
+ * a type error: `DetectorCounts` is `Record<RefusalDetectorId, number>`, the
+ * literal satisfied it for the union of the day, and a fifth id then read back
+ * as `undefined` — so every `+=` over it produced `NaN` and the whole rollup
+ * went quiet. The sibling test asserts that the id list and the gate's union
+ * agree; nothing asserted that the COUNTER covered the list, which is the half
+ * this construction removes the need to assert.
+ */
 export function emptyCounts(): DetectorCounts {
-    return { promissory: 0, language: 0, verification: 0, completion: 0 };
+    const out = {} as DetectorCounts;
+    for (const id of DETECTOR_IDS) out[id] = 0;
+    return out;
 }
 
 function isDetector(v: unknown): v is RefusalDetectorId {
@@ -174,6 +211,9 @@ export function parseRecord(raw: string): RefusalRecord | null {
     if (typeof o['agent_config_version'] === 'string') {
         rec.agent_config_version = o['agent_config_version'];
     }
+    if (typeof o['refused_prompt_id'] === 'string') {
+        rec.refused_prompt_id = o['refused_prompt_id'];
+    }
     const counts = o['counts'];
     if (typeof counts === 'object' && counts !== null && !Array.isArray(counts)) {
         const parsed: Partial<DetectorCounts> = {};
@@ -231,6 +271,7 @@ export function foldRefusal(
         turnOrdinal: number;
         at: string;
         version?: string | undefined;
+        promptId?: string | undefined;
     },
 ): RefusalRecord {
     const counts = prev === null ? emptyCounts() : countsOf(prev);
@@ -247,6 +288,12 @@ export function foldRefusal(
     else if (prev?.agent_config_version !== undefined) {
         rec.agent_config_version = prev.agent_config_version;
     }
+    // Not inherited from `prev` when this refusal carries none: the field
+    // describes THIS refusal's prompt, and carrying a previous one forward would
+    // read as an identity the payload never supplied.
+    if (input.promptId !== undefined && input.promptId !== '') {
+        rec.refused_prompt_id = input.promptId;
+    }
     return rec;
 }
 

package/src/scripts/_lib/typed_op_grant.ts

@@ -0,0 +1,246 @@
+/**
+ * Who may authorise a typed op — `road-to-adversarial-verification-and-long-runs`
+ * 7.3.
+ *
+ * Under a mission the sequence is: a council check that the op belongs to the
+ * mission → a native ask naming the exact object → execute. The council sits
+ * BEFORE the ask and can only subtract.
+ *
+ * ```
+ * THE COUNCIL MAY VETO A TYPED OP. IT MAY NEVER GRANT ONE.
+ * A COUNCIL VERDICT ALONE NEVER PRODUCES THE GRANT, HOWEVER UNANIMOUS.
+ * THE GRANT COMES FROM THE ASK, AND THE ASK NAMES THE EXACT OBJECT.
+ * THE ASK ALSO NAMES THE VERB AND THE TURN. A CONFIRMATION THAT CANNOT SAY
+ * WHICH TURN IT CAME FROM IS NOT A THIS-TURN CONFIRMATION.
+ * ```
+ *
+ * **Why the asymmetry is the whole design.** ADR-257: an unpaid route may
+ * propose and score, never decide. A council that could grant would be a second
+ * authorisation path around `non-destructive-by-default`'s this-turn
+ * confirmation — and it would be the cheaper one, so it would become the only
+ * one. Letting it VETO adds a refusal without adding an authority, which is the
+ * only direction that is safe to add for free.
+ *
+ * **An UNAVAILABLE council does not block the op**, and that is deliberate
+ * rather than lax: the council is a filter, so its absence removes a filter and
+ * leaves the ask exactly where it was. Treating unavailability as a veto would
+ * make an unconfigured council a silent kill switch on every typed op — the
+ * same-shaped wrong guess `council-availability` exists over.
+ *
+ * **What the exactness check is, and why it is two tiers.** It used to be a
+ * shape-free heuristic — eight characters, one of them not a letter — which
+ * accepted `!!!!!!!!` and `all-branches` alike, so the "exact object" guarantee
+ * the Hard Floor rests on was not real. It is now a universal floor that every
+ * op passes through, plus a per-op shape where one is declared. The floor is
+ * deliberately the weakest claim that cannot be wrong (an object with no
+ * alphanumeric run names nothing); the shape is where a category is actually
+ * refused. An op with NO declared shape keeps the old heuristic above the floor
+ * rather than being refused by default, because a Hard-Floor ask that can never
+ * be answered is worse than a loose one. The residual that leaves is real and
+ * bounded: a category still grants for an op OUTSIDE the declared set, and the
+ * declared set is drawn from the Hard Floor's own list of gated operations.
+ *
+ * Pure.
+ */
+
+/** What the council said about this op. `null` when it was not consulted. */
+export type CouncilVerdict = 'in-mission' | 'out-of-mission' | 'unavailable' | null;
+
+/** The ask, as `non-destructive-by-default` requires it: an exact object. */
+export interface ExactObjectAsk {
+    /** e.g. `force-push`. Blank is not a verb, and a blank verb never grants. */
+    readonly op: string;
+    /**
+     * The object, named concretely — a branch and SHA, a recipient and subject,
+     * an amount and card-last4. A CATEGORY is not an object.
+     */
+    readonly object: string;
+    /** True once a human answered this ask. */
+    readonly confirmed: boolean;
+    /**
+     * The turn the human answered in, compared against the caller's current
+     * turn. A bare boolean cannot express the Hard Floor's THIS-TURN wording:
+     * an ask persisted into a mission record and read back after a restart is
+     * otherwise indistinguishable from a confirmation given a second ago. That
+     * replay-across-restart case is the concrete threat, and the sibling module
+     * `mission_record` is what makes it concrete.
+     */
+    readonly confirmed_turn: string;
+}
+
+export type GrantState = 'vetoed' | 'ask-required' | 'granted';
+
+export interface GrantDecision {
+    readonly state: GrantState;
+    readonly reason: string;
+}
+
+/** Whitespace-separated parts of an object, empties dropped. */
+function parts(object: string): string[] {
+    return object.trim().split(/\s+/).filter((p) => p.length > 0);
+}
+
+/** A part with its surrounding punctuation removed, so `@abc123,` reads as `abc123`. */
+function bare(part: string): string {
+    return part.replace(/^[^0-9a-z]+/i, '').replace(/[^0-9a-z]+$/i, '');
+}
+
+/** Does this text name anything at all? The universal floor, and the weakest claim made here. */
+function namesSomething(object: string): boolean {
+    return /[0-9a-z]{2,}/i.test(object);
+}
+
+/** A 7-to-40 character hex run — the token that pins a push to one commit. */
+function isSha(part: string): boolean {
+    return /^[0-9a-f]{7,40}$/i.test(bare(part));
+}
+
+/** An address-shaped part — the token that pins a send to one recipient. */
+function isRecipient(part: string): boolean {
+    return /^[^\s@]+@[^\s@]+\.[a-z]{2,}$/i.test(bare(part));
+}
+
+/** A money-shaped part — a decimal amount, or digits carrying a currency marker. */
+function isAmount(part: string): boolean {
+    return /\d[.,]\d{2}\b/.test(part) || (/\d/.test(part) && /[€$£]|\b(?:EUR|USD|GBP)\b/i.test(part));
+}
+
+/** A four-digit run — the card suffix that pins a purchase to one instrument. */
+function isCardSuffix(part: string): boolean {
+    return /(?:^|\D)\d{4}$/.test(bare(part)) && !isAmount(part);
+}
+
+/** Is there a part that carries a name, other than the one already accounted for? */
+function hasQualifier(ps: string[], accountedFor: (p: string) => boolean): boolean {
+    return ps.some((p) => !accountedFor(p) && /[0-9a-z]{2,}/i.test(bare(p)));
+}
+
+/**
+ * The declared per-op object shapes.
+ *
+ * Keyed by the typed-op vocabulary, looked up case-insensitively on a trimmed
+ * op. Only the ops whose exact object this repository has actually seen or that
+ * the roadmap specifies are declared — inventing a shape for an op with no
+ * example risks refusing the first real one, which is the Risk-1 direction.
+ *
+ * `tag-or-release` is deliberately absent: a release object may legitimately be
+ * a bare version, so a SHA requirement would refuse a real one.
+ */
+const OBJECT_SHAPES: ReadonlyMap<string, (object: string) => boolean> = new Map([
+    // A push names WHERE and WHICH COMMIT. The remote is optional — the shipped
+    // object in the unit fixture names a ref and a SHA and no remote, so
+    // requiring one would refuse an object this repository already ships.
+    ...(['push', 'force-push', 'merge-to-trunk', 'history-rewrite'] as const).map(
+        (op) =>
+            [
+                op,
+                (object: string): boolean => {
+                    const ps = parts(object);
+                    return ps.some(isSha) && hasQualifier(ps, isSha);
+                },
+            ] as const,
+    ),
+    [
+        'send',
+        (object: string): boolean => {
+            const ps = parts(object);
+            return ps.some(isRecipient) && hasQualifier(ps, isRecipient);
+        },
+    ] as const,
+    [
+        'purchase',
+        (object: string): boolean => {
+            const ps = parts(object);
+            return ps.some(isAmount) && ps.some(isCardSuffix);
+        },
+    ] as const,
+]);
+
+/**
+ * A named object must be specific enough to be checkable.
+ *
+ * Exported so the two tiers are testable separately: a caller can ask whether an
+ * object would survive the floor without also asking which op it belongs to.
+ */
+export function objectIsExact(op: string, object: string): boolean {
+    if (!namesSomething(object)) return false;
+    const shape = OBJECT_SHAPES.get(op.trim().toLowerCase());
+    if (shape !== undefined) return shape(object);
+    // No declared shape: the pre-existing heuristic, above the floor.
+    return object.trim().length >= 8 && /[^a-z ]/i.test(object);
+}
+
+/** An op names what is about to happen. Blank names nothing. */
+function opIsNamed(op: string): boolean {
+    return op.trim().length > 0;
+}
+
+/**
+ * Decide whether a typed op may proceed.
+ *
+ * The order is fixed: veto first, then the verb, then the confirmation, then
+ * the turn, then the object. A confirmed ask after a veto is still a veto —
+ * otherwise the veto would be advisory, and an advisory veto is not one. The
+ * verb is read before the object because it decides which object shape applies.
+ *
+ * `currentTurn` is REQUIRED rather than optional. An optional turn would make
+ * the this-turn check something a caller opts into, and a security check that
+ * is off by default is not one.
+ */
+export function grantFor(
+    verdict: CouncilVerdict,
+    ask: ExactObjectAsk,
+    currentTurn: string,
+): GrantDecision {
+    if (verdict === 'out-of-mission') {
+        return {
+            state: 'vetoed',
+            reason: `the council found ${ask.op} outside this mission; a veto is not overridden by a later confirmation`,
+        };
+    }
+    if (!opIsNamed(ask.op)) {
+        return {
+            state: 'ask-required',
+            reason: 'the ask names no operation — the verb that says what is about to happen is blank',
+        };
+    }
+    if (!ask.confirmed) {
+        return {
+            state: 'ask-required',
+            reason:
+                verdict === 'in-mission'
+                    ? `the council cleared ${ask.op}, which is not a grant — the ask still has to happen`
+                    : `${ask.op} needs a this-turn confirmation naming the exact object`,
+        };
+    }
+    if (currentTurn.trim().length === 0 || ask.confirmed_turn.trim().length === 0) {
+        return {
+            state: 'ask-required',
+            reason: `the confirmation for ${ask.op} carries no turn, so it cannot be shown to be this turn`,
+        };
+    }
+    if (ask.confirmed_turn !== currentTurn) {
+        return {
+            state: 'ask-required',
+            reason: `the confirmation for ${ask.op} was given in turn ${ask.confirmed_turn}, not this turn (${currentTurn})`,
+        };
+    }
+    if (!objectIsExact(ask.op, ask.object)) {
+        return {
+            state: 'ask-required',
+            reason: `the confirmation named "${ask.object}", which is a category rather than an object — an approval must name the exact thing`,
+        };
+    }
+    return { state: 'granted', reason: `confirmed this turn for ${ask.op} on ${ask.object}` };
+}
+
+/**
+ * Could this verdict, on its own, produce a grant?
+ *
+ * Exists as its own function so the Iron Law is CHECKABLE rather than merely
+ * stated: it returns false for every verdict, including a unanimous one, and a
+ * test asserts that over the whole domain.
+ */
+export function verdictAloneGrants(_verdict: CouncilVerdict): boolean {
+    return false;
+}