@event4u/agent-config 16.2.0 → 16.4.0

package/src/scripts/_lib/minimality_tiebreak.ts

@@ -1,168 +0,0 @@
-/**
- * Minimality tie-break — the FOUR criteria of decision E5, in its committed order.
- *
- * `road-to-governed-harness-evolution` Phase 4, step 4.5.
- *
- * > *Order per E5: the FOUR criteria `tokens → artifacts → scope →
- * > precedence`. The fifth criterion the skipped parent added — simpler
- * > mechanism — is OUT.*
- * > verify: **two candidates with identical vectors resolve deterministically
- * > under the committed order.**
- *
- * ## Why four and not five
- *
- * E5 (decided 2026-08-30, AI council, anthropic + openai, 2/2) rejected
- * "simpler mechanism" on a timing argument rather than a taste one: by the time
- * this function runs, both candidates have survived selection evaluation and
- * every hygiene check, so there is **no outcome signal left to measure
- * simplicity against**. Admitting it converts a mechanical decision into a
- * reviewer's vote. The four that survive are all countable off candidate
- * metadata — token count, artifact count, a scope enum, a precedence rank —
- * which is what makes the result reproducible rather than argued.
- *
- * This module therefore has no place to put a fifth criterion:
- * {@link MINIMALITY_ORDER} is the whole list, {@link breakTie} walks exactly it,
- * and `tests/scripts/minimality_tiebreak.test.ts` pins both the order and its
- * arity. A future fifth criterion has to move E5 first.
- *
- * ## The order is load-bearing, which is why inverting it is tested
- *
- * The two source proposals ordered these criteria in opposite directions, so
- * the same pair of candidates resolves to different winners depending on the
- * choice. The test asserts a fixture whose winner FLIPS under the inverted
- * order — a tie-break whose order did not matter would not need a council
- * decision behind it.
- *
- * ## Identity is a stabiliser, not a criterion
- *
- * {@link breakTie} returns `winner: null` when all four criteria tie: that is
- * the honest answer, and it is deterministic. {@link orderByMinimality} needs a
- * TOTAL order to sort with, so it falls back to the candidate id — an arbitrary
- * but stable stabiliser that expresses no preference about the candidates and
- * is deliberately NOT a fifth criterion. A caller that needs to know whether a
- * decision was made reads {@link breakTie}, never the sort position.
- */
-
-/** The committed order. E5, option A. Walked left to right; first difference decides. */
-export const MINIMALITY_ORDER = ['tokens', 'artifacts', 'scope', 'precedence'] as const;
-
-export type MinimalityCriterion = (typeof MINIMALITY_ORDER)[number];
-
-/**
- * Blast-radius scope, narrowest first. Lower rank wins — a candidate that
- * touches one artifact is more minimal than one that touches a whole pack.
- */
-export const SCOPE_ORDER = ['single-artifact', 'module', 'pack', 'repo'] as const;
-export type CandidateScope = (typeof SCOPE_ORDER)[number];
-
-/**
- * Precedence rank, least binding first. Lower rank wins — a candidate that
- * lands as advisory guidance is more minimal than one that lands in the kernel,
- * because the kernel binds every session whether or not the change helps it.
- */
-export const PRECEDENCE_ORDER = ['advisory', 'auto', 'always', 'kernel'] as const;
-export type CandidatePrecedence = (typeof PRECEDENCE_ORDER)[number];
-
-/** Everything the tie-break reads. All four fields are counted, none is judged. */
-export interface MinimalityMetadata {
-    candidate_id: string;
-    /** Tokens the candidate adds to the surface it lands on. */
-    tokens: number;
-    /** Artifacts the candidate creates or edits. */
-    artifacts: number;
-    scope: CandidateScope;
-    precedence: CandidatePrecedence;
-}
-
-export interface TieBreakResult {
-    /** The winning candidate id, or `null` when all four criteria tie. */
-    winner: string | null;
-    /** Which criterion decided, or `null` when none did. */
-    decided_by: MinimalityCriterion | null;
-    /** One sentence a report can print verbatim. */
-    reason: string;
-}
-
-export class MinimalityMetadataError extends Error {
-    constructor(message: string) {
-        super(message);
-        this.name = 'MinimalityMetadataError';
-    }
-}
-
-function rankOf<T extends string>(order: readonly T[], value: T, field: string): number {
-    const i = order.indexOf(value);
-    if (i < 0) {
-        throw new MinimalityMetadataError(`unknown ${field}: '${String(value)}'`);
-    }
-    return i;
-}
-
-/** The four criterion values as comparable integers, lower being more minimal. */
-function costs(m: MinimalityMetadata): Record<MinimalityCriterion, number> {
-    if (!Number.isFinite(m.tokens) || !Number.isFinite(m.artifacts)) {
-        throw new MinimalityMetadataError(`${m.candidate_id}: tokens and artifacts must be finite`);
-    }
-    return {
-        tokens: m.tokens,
-        artifacts: m.artifacts,
-        scope: rankOf(SCOPE_ORDER, m.scope, 'scope'),
-        precedence: rankOf(PRECEDENCE_ORDER, m.precedence, 'precedence'),
-    };
-}
-
-/**
- * Walk {@link MINIMALITY_ORDER} and return at the first criterion that differs.
- *
- * `order` exists for the test that proves the order is load-bearing; production
- * callers pass nothing and get E5's committed order.
- */
-export function breakTie(
-    a: MinimalityMetadata,
-    b: MinimalityMetadata,
-    order: readonly MinimalityCriterion[] = MINIMALITY_ORDER,
-): TieBreakResult {
-    const ca = costs(a);
-    const cb = costs(b);
-    for (const criterion of order) {
-        if (ca[criterion] === cb[criterion]) continue;
-        const winner = ca[criterion] < cb[criterion] ? a : b;
-        return {
-            winner: winner.candidate_id,
-            decided_by: criterion,
-            reason:
-                `${winner.candidate_id} wins on ${criterion} ` +
-                `(${String(ca[criterion])} vs ${String(cb[criterion])}); ` +
-                `criteria before it tied under the committed order ${order.join(' -> ')}`,
-        };
-    }
-    return {
-        winner: null,
-        decided_by: null,
-        reason:
-            `${a.candidate_id} and ${b.candidate_id} tie on all ${String(order.length)} criteria ` +
-            `(${order.join(' -> ')}); E5 admits no further criterion, so this escalates rather than resolving`,
-    };
-}
-
-/**
- * A deterministic TOTAL order over candidates.
- *
- * Ties on all four criteria fall back to the candidate id — see the header:
- * that is a sort stabiliser, not a fifth criterion, and it never appears in a
- * {@link TieBreakResult}.
- */
-export function orderByMinimality(
-    candidates: readonly MinimalityMetadata[],
-): readonly MinimalityMetadata[] {
-    return [...candidates].sort((a, b) => {
-        const ca = costs(a);
-        const cb = costs(b);
-        for (const criterion of MINIMALITY_ORDER) {
-            if (ca[criterion] !== cb[criterion]) {
-                return ca[criterion] - cb[criterion];
-            }
-        }
-        return a.candidate_id < b.candidate_id ? -1 : a.candidate_id > b.candidate_id ? 1 : 0;
-    });
-}

package/src/scripts/_lib/overbuild_lens_contract.ts

@@ -1,196 +0,0 @@
-/**
- * Output-contract parser + scorer for `overbuild-review-lens`.
- *
- * The lens's own SKILL.md states an output contract. This is the half of that
- * contract a machine can check: tag grammar, the mandatory Chesterton's-Fence
- * line on every `delete:` finding, the honest-null form, and the sign of the
- * net-lines figure. Whether a live model *finds the plant* in a fixture is not
- * checkable here — that needs a scored eval run — and the split is stated in
- * `tests/fixtures/overbuild-lens/README.md` rather than blurred.
- *
- * Deliberately dependency-free and side-effect-free: parse a string, return a
- * verdict. Nothing reads the filesystem or the network.
- */
-
-/** The six tags the lens may emit. Anything else is a contract violation. */
-export const LENS_TAGS = ['delete', 'stdlib', 'native', 'yagni', 'shrink', 'flatten'] as const;
-export type LensTag = (typeof LENS_TAGS)[number];
-
-export const LENS_VERDICTS = ['lean', 'trim', 'overbuilt'] as const;
-export type LensVerdict = (typeof LENS_VERDICTS)[number];
-
-export interface LensFinding {
-    tag: LensTag;
-    location: string;
-    text: string;
-    /** Present only on `delete:` findings; the contract requires it there. */
-    fence?: { why: string; safe: string; covered: string };
-}
-
-export interface ParsedLensOutput {
-    verdict: LensVerdict | null;
-    findings: LensFinding[];
-    isNull: boolean;
-    netLines: number | null;
-    /** Contract violations found while parsing. Empty means the shape is legal. */
-    errors: string[];
-}
-
-const _TAG_RE = new RegExp(
-    String.raw`^\s*\d+\.\s+(` + LENS_TAGS.join('|') + String.raw`):\s+(\S+)\s+(.*\S)\s*$`,
-);
-const _FENCE_RE =
-    /^\s*Fence:\s*why=(.+?)\s+safe=(.+?)\s+covered=(yes|no|partial)\s*$/;
-const _VERDICT_RE = /^\s*Verdict:\s*(\S+)\s*$/;
-const _NET_RE = /^\s*Net:\s*([+-]?\d+)\s+lines?\s*$/;
-const _NULL_RE = /^\s*Findings:\s*none\b/;
-const _COVERED_VALUES = new Set(['yes', 'no', 'partial']);
-
-/**
- * Parse a lens verdict block. Never throws — a malformed block comes back with
- * a populated `errors` array, because a parser that throws on bad input cannot
- * report *how many* ways the input was bad.
- */
-export function parseLensOutput(raw: string): ParsedLensOutput {
-    const lines = raw.split('\n');
-    const errors: string[] = [];
-    const findings: LensFinding[] = [];
-    let verdict: LensVerdict | null = null;
-    let netLines: number | null = null;
-    let isNull = false;
-
-    for (let i = 0; i < lines.length; i += 1) {
-        const line: string = lines[i] ?? '';
-
-        const v = line.match(_VERDICT_RE);
-        if (v) {
-            if ((LENS_VERDICTS as readonly string[]).includes(v[1] ?? '')) {
-                verdict = v[1] as LensVerdict;
-            } else {
-                errors.push(`unknown verdict \`${v[1]}\` (allowed: ${LENS_VERDICTS.join('/')})`);
-            }
-            continue;
-        }
-
-        const n = line.match(_NET_RE);
-        if (n) {
-            netLines = Number.parseInt(n[1] ?? '0', 10);
-            continue;
-        }
-
-        if (_NULL_RE.test(line)) {
-            isNull = true;
-            continue;
-        }
-
-        const m = line.match(_TAG_RE);
-        if (!m) {
-            // An unrecognised numbered line is a finding the grammar rejects.
-            if (/^\s*\d+\.\s+\S+:/.test(line)) {
-                errors.push(`line ${i + 1}: not a legal tag — \`${line.trim()}\``);
-            }
-            continue;
-        }
-
-        const finding: LensFinding = {
-            tag: m[1] as LensTag,
-            location: m[2] ?? '',
-            text: m[3] ?? '',
-        };
-
-        if (finding.tag === 'delete') {
-            const fenceLine: string = lines[i + 1] ?? '';
-            const f = fenceLine.match(_FENCE_RE);
-            if (!f) {
-                errors.push(
-                    `line ${i + 1}: \`delete:\` finding at ${finding.location} has no valid ` +
-                        'Fence line (why= / safe= / covered=yes|no|partial)',
-                );
-            } else {
-                const covered = f[3] ?? '';
-                finding.fence = {
-                    why: (f[1] ?? '').trim(),
-                    safe: (f[2] ?? '').trim(),
-                    covered,
-                };
-                if (!_COVERED_VALUES.has(covered)) {
-                    errors.push(`line ${i + 2}: covered= must be yes|no|partial`);
-                }
-            }
-        }
-
-        findings.push(finding);
-    }
-
-    if (verdict === null) errors.push('no `Verdict:` line');
-    if (netLines === null) errors.push('no `Net: <n> lines` line');
-    if (isNull && findings.length > 0) {
-        errors.push('emitted the null AND findings — pick one');
-    }
-    if (!isNull && findings.length === 0) {
-        errors.push('no findings and no null block — the null is mandatory, not optional');
-    }
-    if (verdict === 'lean' && findings.length > 0) {
-        errors.push('`lean` verdict with findings — a lean diff has nothing to cut');
-    }
-    if (verdict !== 'lean' && isNull) {
-        errors.push('null block with a non-`lean` verdict');
-    }
-
-    return { verdict, findings, isNull, netLines, errors };
-}
-
-export interface ExpectedLabels {
-    verdict: string;
-    must_tags: string[];
-    forbidden_tags: string[];
-    must_be_null: boolean;
-    net_sign: 'negative' | 'zero' | 'positive';
-    requires_fence?: boolean;
-}
-
-/**
- * Score a parsed output against a fixture's expected labels. Returns the list
- * of failures — empty means the output is correct for that fixture.
- */
-export function scoreAgainstExpected(
-    parsed: ParsedLensOutput,
-    expected: ExpectedLabels,
-): string[] {
-    const failures = [...parsed.errors];
-
-    if (parsed.verdict !== expected.verdict) {
-        failures.push(`verdict ${parsed.verdict} ≠ expected ${expected.verdict}`);
-    }
-    if (parsed.isNull !== expected.must_be_null) {
-        failures.push(
-            expected.must_be_null
-                ? 'expected the honest null, got findings (invented a finding on a lean diff)'
-                : 'expected findings, got the null (missed the plant)',
-        );
-    }
-
-    const seen = new Set(parsed.findings.map((f) => f.tag));
-    for (const tag of expected.must_tags) {
-        if (!seen.has(tag as LensTag)) failures.push(`missing required tag \`${tag}:\``);
-    }
-    for (const tag of expected.forbidden_tags) {
-        if (seen.has(tag as LensTag)) failures.push(`emitted forbidden tag \`${tag}:\``);
-    }
-
-    if (expected.requires_fence) {
-        const unfenced = parsed.findings.filter((f) => f.tag === 'delete' && !f.fence);
-        if (unfenced.length > 0) failures.push('a `delete:` finding is missing its fence');
-    }
-
-    const sign =
-        parsed.netLines === null ? 'unknown'
-        : parsed.netLines < 0 ? 'negative'
-        : parsed.netLines > 0 ? 'positive'
-        : 'zero';
-    if (sign !== expected.net_sign) {
-        failures.push(`net-lines sign ${sign} ≠ expected ${expected.net_sign}`);
-    }
-
-    return failures;
-}