@aragon-agent/cli 0.6.44 → 0.6.45

package/dist/governance/roles.js

@@ -0,0 +1,142 @@
+/**
+ * Identities, roster sizing and work-package assignment (governance-mode 5.2).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Pure: no I/O, no clock, no randomness, so a
+ * resumed run recomputes exactly the same roster.
+ *
+ * IDENTITIES ARE LEDGER ENTITIES, NOT PROCESSES (5.2). Every dispatch builds a fresh
+ * `Agent`; continuity comes from the ledger and the artifact store. The id is also the
+ * subagent `label`, so it must satisfy the label rule `[a-z0-9-]{1,12}` AND must never be
+ * the reserved aggregate label `team` (a child labelled `team` would be addressed by
+ * `team_send {to:"team"}` as a broadcast). Ids here are `<prefix><slot>` and
+ * `<id>-r<generation>`, which cannot spell `team` by construction.
+ *
+ * "THE WRITER NEVER REVIEWS THEMSELF" IS STRUCTURAL: DEV, REV and TEST ids come from three
+ * disjoint prefixes, so no assignment function can hand a work package's author the review
+ * of it.
+ */
+/** The subagent label rule every identity satisfies. */
+export const IDENTITY_ID_PATTERN = /^[a-z0-9-]{1,12}$/;
+/** The single inspector's id. Never scored, never respawned. */
+export const INSPECTOR_ID = 'insp';
+const ROLE_PREFIX = { DEV: 'dev', REV: 'rev', TEST: 'tst' };
+const PREFIX_ROLE = { dev: 'DEV', rev: 'REV', tst: 'TEST' };
+/** REV / TEST roster is `clamp(ceil(K / 2), 1, 3)` (5.2). */
+const REVIEW_ROSTER_MIN = 1;
+const REVIEW_ROSTER_MAX = 3;
+/** Highest slot / generation an id can carry and still fit 12 characters. */
+const MAX_SLOT = 999;
+const MAX_GENERATION = 99;
+/** The roster id of slot `slot` (1-based) of a scored role: `dev1`, `rev2`, `tst1`. */
+export function makeIdentityId(role, slot) {
+    if (!Number.isInteger(slot) || slot < 1 || slot > MAX_SLOT) {
+        throw new Error(`makeIdentityId: slot must be an integer in 1..${MAX_SLOT}, got ${slot}`);
+    }
+    return `${ROLE_PREFIX[role]}${slot}`;
+}
+/** `dev2` -> `dev2-r1`; `dev2-r1` -> `dev2-r2`. The base slot never changes. */
+export function respawnIdentityId(predecessorId) {
+    const parsed = parseIdentityId(predecessorId);
+    if (!parsed || parsed.role === 'INSP') {
+        throw new Error(`respawnIdentityId: "${predecessorId}" is not a respawnable identity`);
+    }
+    const generation = parsed.generation + 1;
+    if (generation > MAX_GENERATION) {
+        throw new Error(`respawnIdentityId: generation ${generation} exceeds ${MAX_GENERATION}`);
+    }
+    return `${ROLE_PREFIX[parsed.role]}${parsed.slot}-r${generation}`;
+}
+/** Inverse of `makeIdentityId` / `respawnIdentityId`; `null` for anything else. */
+export function parseIdentityId(id) {
+    if (id === INSPECTOR_ID)
+        return { role: 'INSP', slot: 0, generation: 0 };
+    const m = /^(dev|rev|tst)([1-9][0-9]{0,2})(?:-r([1-9][0-9]?))?$/.exec(id);
+    if (!m)
+        return null;
+    const role = PREFIX_ROLE[m[1]];
+    if (!role)
+        return null;
+    return { role, slot: Number(m[2]), generation: m[3] ? Number(m[3]) : 0 };
+}
+/** The ids `dev1..devN` for `count` slots of `role`. */
+export function rosterIds(role, count) {
+    return Array.from({ length: Math.max(0, count) }, (_, i) => makeIdentityId(role, i + 1));
+}
+/**
+ * Roster size for `wpCount` work packages (5.2): `DEV = K`, `REV = TEST =
+ * clamp(ceil(K/2), 1, 3)`. `stageWidthCap` (the user's `team.maxSubagents`, D-24) bounds the
+ * REV / TEST counts, because those are exactly the identities that run side by side in one
+ * review / test stage. DEV is NOT bounded: the engine splits a wide dev stage into chunks
+ * (the `NEXT` it prints is already chunked), so the roster may exceed one dispatch.
+ */
+export function rosterSizes(wpCount, stageWidthCap) {
+    const k = Math.max(1, Math.floor(wpCount));
+    const cap = Math.max(1, Math.floor(stageWidthCap));
+    const reviewers = Math.min(cap, Math.min(REVIEW_ROSTER_MAX, Math.max(REVIEW_ROSTER_MIN, Math.ceil(k / 2))));
+    return { dev: k, rev: reviewers, test: reviewers };
+}
+/** Follow `takeover` links to the identity that now owns `id`'s work; cycle-safe. */
+function resolveSuccessor(id, takeover) {
+    const seen = new Set();
+    let current = id;
+    while (takeover[current] !== undefined && !seen.has(current)) {
+        seen.add(current);
+        current = takeover[current];
+    }
+    return current;
+}
+/**
+ * Assign work packages to identities.
+ *
+ * 1. A WP with a sticky preference goes to that identity - or to its successor if it was
+ *    replaced - as long as the result is an active identity.
+ * 2. Every other WP goes to the identity with the fewest WPs so far, ties broken by roster
+ *    order. With no stickiness this is exactly "WP i goes to identity i mod M" (5.2); with
+ *    stickiness it keeps the load level instead of piling every new WP on the identity that
+ *    happens to come next in a fixed rotation.
+ *
+ * Identities that receive nothing are omitted, so the caller dispatches no idle child.
+ * Deterministic: the same input always yields the same output.
+ */
+export function assignRoundRobin(options) {
+    const { wpIds, identities, sticky = {}, takeover = {} } = options;
+    if (identities.length === 0) {
+        throw new Error('assignRoundRobin: at least one active identity is required');
+    }
+    const active = new Set(identities);
+    const buckets = new Map(identities.map((id) => [id, []]));
+    const pinned = new Map();
+    for (const wpId of wpIds) {
+        const preferred = sticky[wpId];
+        if (preferred === undefined)
+            continue;
+        const owner = resolveSuccessor(preferred, takeover);
+        if (active.has(owner))
+            pinned.set(wpId, owner);
+    }
+    for (const wpId of wpIds) {
+        const owner = pinned.get(wpId);
+        if (owner !== undefined)
+            buckets.get(owner).push(wpId);
+    }
+    for (const wpId of wpIds) {
+        if (pinned.has(wpId))
+            continue;
+        buckets.get(leastLoaded(identities, buckets)).push(wpId);
+    }
+    const order = new Map(wpIds.map((id, i) => [id, i]));
+    return identities
+        .map((identity) => ({
+        identity,
+        wpIds: buckets.get(identity).sort((a, b) => order.get(a) - order.get(b)),
+    }))
+        .filter((a) => a.wpIds.length > 0);
+}
+function leastLoaded(identities, buckets) {
+    let best = identities[0];
+    for (const id of identities) {
+        if (buckets.get(id).length < buckets.get(best).length)
+            best = id;
+    }
+    return best;
+}

package/dist/governance/rules/claims.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Claims and finding fingerprints (governance-mode 5.5 / 5.6).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * A CLAIM is an accusation that books NOTHING when it is raised: a tester who says "the
+ * reviewer missed this" earns +10 only if the inspector upholds it in the settle stage, and
+ * pays -10 if it is rejected. Deferring the booking is what keeps claims from being a
+ * score farm ("accuse everyone, collect T2").
+ *
+ * FINGERPRINTS decide "the same problem rejected twice" (D8) WITHOUT a language model:
+ * `normalized file + sorted keyword set of the issue text`. Two findings count as the same
+ * when they name the same file and share most of their keywords. Deterministic, so the
+ * result is reproducible from the event log and pinned by fixed examples in the tests.
+ */
+import type { Claim, LedgerState, ReviewSubmission, TestSubmission } from '../types.js';
+import type { LedgerEvent } from './ledger.js';
+/** Lower-case, forward slashes, no leading `./`: so `.\\Src\\A.ts` and `src/a.ts` agree. */
+export declare function normalizeFindingPath(file: string): string;
+/**
+ * The sorted, de-duplicated keyword set of an issue text: lower-cased, punctuation
+ * stripped, stop-words and bare numbers (line numbers drift between rounds) dropped.
+ * Falls back to the unfiltered tokens, then to `_`, so an issue never fingerprints to an
+ * empty set that would match every other finding on the same file.
+ */
+export declare function issueKeywords(issue: string): string[];
+export interface FingerprintInput {
+    file: string;
+    issue: string;
+}
+/** `file#kw1+kw2+...`. Deterministic; the unit tests pin fixed examples. */
+export declare function fingerprintFinding(finding: FingerprintInput): string;
+/**
+ * D8 test: does any new finding repeat a previously rejected one? Same file AND a keyword
+ * overlap of at least 60 percent of the smaller set (and at least two shared keywords
+ * unless the smaller set has one).
+ */
+export declare function findingsIntersect(a: readonly string[], b: readonly string[]): boolean;
+export interface ClaimContext {
+    wpId: string;
+    phase: number;
+    /** The DEV holding the WP. */
+    developer: string | null;
+    /** The REV assigned to the WP. */
+    reviewer: string | null;
+}
+/**
+ * Claims implied by a test submission: one per kind, never one per issue (a tester cannot
+ * multiply T2 by splitting one defect into five lines). Explicit `claims[]` come first
+ * and win over an implied claim of the same kind. Ids are deterministic
+ * (`cl-<wp>-t<attempt>-<n>`) so replay and tests need no id generator.
+ */
+export declare function claimsFromTest(ctx: ClaimContext, submission: TestSubmission): Claim[];
+/** A reviewer's `securityFinding` becomes a security claim against the developer. */
+export declare function claimsFromReview(ctx: ClaimContext, submission: ReviewSubmission): Claim[];
+export interface RuleClaimInput {
+    /** Ledger state: only used to look up the roles of the parties. */
+    state: LedgerState;
+    claim: Claim;
+    decision: 'upheld' | 'rejected';
+    ruling: string;
+    at: number;
+    /** The inspector's identity, e.g. `insp`. */
+    inspectorId: string;
+}
+export interface RuleClaimResult {
+    claim: Claim;
+    events: LedgerEvent[];
+    notes: string[];
+}
+/**
+ * Expand an inspector ruling into ledger events (5.6 L2):
+ *
+ *  - upheld missed_by_review: R4 against the reviewer, T2 for the tester.
+ *  - upheld incomplete_impl:  R7 against the reviewer, T7 for the tester.
+ *  - upheld security: D6 against the developer. upheld same_issue: D8 against the developer.
+ *  - upheld false_positive: R5 / T5 against the party whose finding was wrong.
+ *  - ANY rejected claim: T5 (tester) or R5 (reviewer) against the CLAIMANT.
+ *
+ * Idempotent: a claim that is no longer `open` yields no events, so a repeated
+ * `ledger_rule` call cannot pay twice.
+ */
+export declare function ruleClaim(input: RuleClaimInput): RuleClaimResult;

package/dist/governance/rules/claims.js

@@ -0,0 +1,250 @@
+/**
+ * Claims and finding fingerprints (governance-mode 5.5 / 5.6).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * A CLAIM is an accusation that books NOTHING when it is raised: a tester who says "the
+ * reviewer missed this" earns +10 only if the inspector upholds it in the settle stage, and
+ * pays -10 if it is rejected. Deferring the booking is what keeps claims from being a
+ * score farm ("accuse everyone, collect T2").
+ *
+ * FINGERPRINTS decide "the same problem rejected twice" (D8) WITHOUT a language model:
+ * `normalized file + sorted keyword set of the issue text`. Two findings count as the same
+ * when they name the same file and share most of their keywords. Deterministic, so the
+ * result is reproducible from the event log and pinned by fixed examples in the tests.
+ */
+import { eventDef } from './events-table.js';
+// ---------------------------------------------------------------------------
+// Fingerprints
+// ---------------------------------------------------------------------------
+const STOP_WORDS = new Set([
+    'a', 'an', 'the', 'is', 'are', 'was', 'were', 'be', 'been', 'being', 'am',
+    'of', 'in', 'on', 'at', 'to', 'for', 'from', 'by', 'with', 'without', 'within',
+    'and', 'or', 'but', 'nor', 'not', 'no', 'this', 'that', 'these', 'those',
+    'it', 'its', 'as', 'if', 'then', 'than', 'so', 'do', 'does', 'did', 'done',
+    'has', 'have', 'had', 'should', 'must', 'can', 'could', 'would', 'will', 'shall',
+    'may', 'might', 'there', 'here', 'which', 'when', 'where', 'while', 'into',
+    'onto', 'over', 'under', 'also', 'only', 'very', 'too', 'any', 'all', 'some',
+    'each', 'every', 'more', 'most', 'less', 'such', 'per', 'via', 'about',
+    'because', 'however', 'currently', 'still', 'just', 'line', 'lines',
+]);
+/** Separator between the file part and the keyword part of a fingerprint. */
+const FP_SEPARATOR = '#';
+/** Lower-case, forward slashes, no leading `./`: so `.\\Src\\A.ts` and `src/a.ts` agree. */
+export function normalizeFindingPath(file) {
+    return file.trim().replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/{2,}/g, '/').toLowerCase();
+}
+/** Plural `s` only: enough to unify "handles"/"handle"; anything cleverer breeds collisions. */
+function stem(word) {
+    if (word.length > 3 && word.endsWith('s') && !/(ss|us|is)$/.test(word))
+        return word.slice(0, -1);
+    return word;
+}
+/**
+ * The sorted, de-duplicated keyword set of an issue text: lower-cased, punctuation
+ * stripped, stop-words and bare numbers (line numbers drift between rounds) dropped.
+ * Falls back to the unfiltered tokens, then to `_`, so an issue never fingerprints to an
+ * empty set that would match every other finding on the same file.
+ */
+export function issueKeywords(issue) {
+    const tokens = issue
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, ' ')
+        .split(' ')
+        .filter((t) => t.length > 0);
+    const meaningful = tokens.filter((t) => !STOP_WORDS.has(t) && !/^\d+$/.test(t)).map(stem);
+    const chosen = meaningful.length > 0 ? meaningful : tokens;
+    const unique = [...new Set(chosen)].sort();
+    return unique.length > 0 ? unique : ['_'];
+}
+/** `file#kw1+kw2+...`. Deterministic; the unit tests pin fixed examples. */
+export function fingerprintFinding(finding) {
+    const file = normalizeFindingPath(finding.file);
+    return `${file}${FP_SEPARATOR}${issueKeywords(finding.issue).join('+')}`;
+}
+function parseFingerprint(fingerprint) {
+    const at = fingerprint.lastIndexOf(FP_SEPARATOR);
+    if (at < 0)
+        return { file: fingerprint, keywords: [] };
+    return {
+        file: fingerprint.slice(0, at),
+        keywords: fingerprint.slice(at + 1).split('+').filter((k) => k.length > 0),
+    };
+}
+function sameProblem(a, b) {
+    if (a === b)
+        return true;
+    const left = parseFingerprint(a);
+    const right = parseFingerprint(b);
+    if (left.file !== right.file)
+        return false;
+    const rightSet = new Set(right.keywords);
+    const shared = left.keywords.filter((k) => rightSet.has(k)).length;
+    const smaller = Math.min(left.keywords.length, right.keywords.length);
+    if (smaller === 0)
+        return false;
+    return shared >= Math.min(2, smaller) && shared / smaller >= 0.6;
+}
+/**
+ * D8 test: does any new finding repeat a previously rejected one? Same file AND a keyword
+ * overlap of at least 60 percent of the smaller set (and at least two shared keywords
+ * unless the smaller set has one).
+ */
+export function findingsIntersect(a, b) {
+    return a.some((x) => b.some((y) => sameProblem(x, y)));
+}
+function finishClaim(ctx, id, draft) {
+    return {
+        id,
+        kind: draft.kind,
+        raisedBy: draft.raisedBy,
+        against: draft.against,
+        wpId: ctx.wpId,
+        justification: draft.justification,
+        status: 'open',
+        phase: ctx.phase,
+    };
+}
+/** Who a claim of `kind` accuses when the claimant did not say. */
+function defaultAgainst(kind, ctx) {
+    switch (kind) {
+        case 'security':
+        case 'same_issue':
+            return ctx.developer;
+        case 'missed_by_review':
+        case 'incomplete_impl':
+        case 'false_positive':
+            return ctx.reviewer;
+    }
+}
+/** First `max` justifications joined, so one claim can carry several flagged issues. */
+function joinJustifications(parts, max) {
+    const kept = parts.filter((p) => p.trim().length > 0).slice(0, max);
+    return kept.join(' | ');
+}
+function flaggedIssueClaim(ctx, submission) {
+    const flagged = submission.issues.filter((i) => i.missedByReview === true);
+    if (flagged.length === 0 || ctx.reviewer === null)
+        return null;
+    const kind = submission.verdict === 'INCOMPLETE_IMPL' ? 'incomplete_impl' : 'missed_by_review';
+    const justification = joinJustifications(flagged.map((i) => i.reviewMissJustification ?? i.description), 3);
+    return { kind, raisedBy: submission.identity, against: ctx.reviewer, justification };
+}
+/**
+ * Claims implied by a test submission: one per kind, never one per issue (a tester cannot
+ * multiply T2 by splitting one defect into five lines). Explicit `claims[]` come first
+ * and win over an implied claim of the same kind. Ids are deterministic
+ * (`cl-<wp>-t<attempt>-<n>`) so replay and tests need no id generator.
+ */
+export function claimsFromTest(ctx, submission) {
+    const drafts = [];
+    for (const c of submission.claims) {
+        const against = c.against ?? defaultAgainst(c.kind, ctx);
+        if (against === null || drafts.some((d) => d.kind === c.kind))
+            continue;
+        drafts.push({
+            kind: c.kind,
+            raisedBy: submission.identity,
+            against,
+            justification: c.justification,
+        });
+    }
+    const implied = flaggedIssueClaim(ctx, submission);
+    if (implied !== null && !drafts.some((d) => d.kind === implied.kind))
+        drafts.push(implied);
+    return drafts.map((d, i) => finishClaim(ctx, `cl-${ctx.wpId}-t${submission.attempt}-${i + 1}`, d));
+}
+/** A reviewer's `securityFinding` becomes a security claim against the developer. */
+export function claimsFromReview(ctx, submission) {
+    const finding = submission.securityFinding;
+    if (finding === undefined || ctx.developer === null)
+        return [];
+    return [
+        finishClaim(ctx, `cl-${ctx.wpId}-r${submission.attempt}-1`, {
+            kind: 'security',
+            raisedBy: submission.identity,
+            against: ctx.developer,
+            justification: joinJustifications([finding.description, finding.evidence], 2),
+        }),
+    ];
+}
+function roleOf(state, agentId) {
+    return state.agents[agentId]?.role;
+}
+/** The "you were wrong" event for an agent of `role` (T5 tester, R5 reviewer). */
+function falsePositiveCode(role) {
+    if (role === 'TEST')
+        return 'T5';
+    if (role === 'REV')
+        return 'R5';
+    return null;
+}
+const UPHELD_CODES = {
+    missed_by_review: { against: 'R4', raisedBy: 'T2' },
+    incomplete_impl: { against: 'R7', raisedBy: 'T7' },
+    security: { against: 'D6', raisedBy: null },
+    same_issue: { against: 'D8', raisedBy: null },
+    false_positive: { against: null, raisedBy: null },
+};
+function claimEvent(input, code, agentId) {
+    const { claim } = input;
+    return {
+        code,
+        agentId,
+        at: input.at,
+        phase: claim.phase,
+        by: `inspector:${input.inspectorId}`,
+        reason: `Claim ${claim.id} ${input.decision}: ${eventDef(code).title}`,
+        evidence: input.ruling,
+        wpId: claim.wpId,
+    };
+}
+function upheldEvents(input, notes) {
+    const { claim, state } = input;
+    const events = [];
+    const codes = UPHELD_CODES[claim.kind];
+    if (claim.kind === 'false_positive') {
+        const code = falsePositiveCode(roleOf(state, claim.against));
+        if (code === null)
+            notes.push(`No false-positive event exists for ${claim.against}.`);
+        else
+            events.push(claimEvent(input, code, claim.against));
+        return events;
+    }
+    if (codes.against !== null)
+        events.push(claimEvent(input, codes.against, claim.against));
+    if (codes.raisedBy !== null)
+        events.push(claimEvent(input, codes.raisedBy, claim.raisedBy));
+    return events;
+}
+function rejectedEvents(input, notes) {
+    const { claim, state } = input;
+    const code = falsePositiveCode(roleOf(state, claim.raisedBy));
+    if (code === null) {
+        notes.push(`Rejected claim ${claim.id}: no penalty event exists for ${claim.raisedBy}.`);
+        return [];
+    }
+    return [claimEvent(input, code, claim.raisedBy)];
+}
+/**
+ * Expand an inspector ruling into ledger events (5.6 L2):
+ *
+ *  - upheld missed_by_review: R4 against the reviewer, T2 for the tester.
+ *  - upheld incomplete_impl:  R7 against the reviewer, T7 for the tester.
+ *  - upheld security: D6 against the developer. upheld same_issue: D8 against the developer.
+ *  - upheld false_positive: R5 / T5 against the party whose finding was wrong.
+ *  - ANY rejected claim: T5 (tester) or R5 (reviewer) against the CLAIMANT.
+ *
+ * Idempotent: a claim that is no longer `open` yields no events, so a repeated
+ * `ledger_rule` call cannot pay twice.
+ */
+export function ruleClaim(input) {
+    const notes = [];
+    if (input.claim.status !== 'open') {
+        notes.push(`Claim ${input.claim.id} was already ${input.claim.status}; nothing booked.`);
+        return { claim: input.claim, events: [], notes };
+    }
+    const events = input.decision === 'upheld' ? upheldEvents(input, notes) : rejectedEvents(input, notes);
+    const claim = { ...input.claim, status: input.decision, rulingText: input.ruling };
+    return { claim, events, notes };
+}

package/dist/governance/rules/elimination.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Elimination rules and team health (governance-mode 5.8).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * TWO WAYS OUT, BOTH READ `confirmed` ONLY (I-G3):
+ *
+ *  - KILL: `confirmed <= 0`, immediate, no appeal. `apply()` performs it inside the
+ *    booking that depleted the balance; `killDepleted` is the sweep the engine runs after
+ *    a batch as a safety net (and for a state loaded from an older checkpoint).
+ *  - TAIL: a role with at least three active members drops its lowest member when that
+ *    member is BOTH the unique lowest and below 60 for two phase ends in a row. The first
+ *    time is a warning. A tie for the lowest place eliminates nobody (a coin toss between
+ *    equals would be arbitrary) and is reported as `tie_skip`.
+ *
+ * Provisional escrow never saves or condemns an agent: a clawback can slash an agent's
+ * total without touching survival.
+ */
+import type { LedgerState, ScoredRole } from '../types.js';
+export { AVOID_ADVICE, FAILURE_ANALYSIS_TOP_PENALTIES, buildFailureAnalysis, negativeEventCodes, } from './failure-analysis.js';
+export interface KillSweepResult {
+    state: LedgerState;
+    eliminated: string[];
+}
+/** Eliminate every active agent whose `confirmed` is <= 0. Idempotent. */
+export declare function killDepleted(state: LedgerState, at: number): KillSweepResult;
+export interface TailWarning {
+    agentId: string;
+    role: ScoredRole;
+    strikes: number;
+}
+export interface TailTie {
+    role: ScoredRole;
+    agentIds: string[];
+    confirmed: number;
+}
+export interface TailResult {
+    state: LedgerState;
+    /** First (or later, not yet fatal) strike: the agent is told it is in the tail. */
+    warnings: TailWarning[];
+    eliminated: string[];
+    /** Ties for the lowest place: nobody is eliminated (`tie_skip`). */
+    tieSkips: TailTie[];
+    notes: string[];
+}
+export interface TailRequest {
+    phase: number;
+    at: number;
+    /** Stored-event seq to stamp on any elimination. */
+    seq?: number;
+}
+/**
+ * Phase-end tail check for every role. Order is fixed (DEV, REV, TEST) so the result and
+ * any seq stamping are reproducible on replay.
+ */
+export declare function evaluateTail(state: LedgerState, request: TailRequest): TailResult;
+export type TeamHealthLabel = 'UNKNOWN' | 'HEALTHY' | 'CHECKPOINT_ADVISED';
+export interface TeamHealthStatus {
+    /** Mean `confirmed` over active agents; null before any agent exists. */
+    health: number | null;
+    label: TeamHealthLabel;
+    /** Text for the status / settle brief when a coordination checkpoint is advised. */
+    advisory: string | null;
+}
+/** `< 70` advises a coordination checkpoint (and a focused interface check at settle). */
+export declare function teamHealthStatus(state: LedgerState): TeamHealthStatus;

package/dist/governance/rules/elimination.js

@@ -0,0 +1,105 @@
+/**
+ * Elimination rules and team health (governance-mode 5.8).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * TWO WAYS OUT, BOTH READ `confirmed` ONLY (I-G3):
+ *
+ *  - KILL: `confirmed <= 0`, immediate, no appeal. `apply()` performs it inside the
+ *    booking that depleted the balance; `killDepleted` is the sweep the engine runs after
+ *    a batch as a safety net (and for a state loaded from an older checkpoint).
+ *  - TAIL: a role with at least three active members drops its lowest member when that
+ *    member is BOTH the unique lowest and below 60 for two phase ends in a row. The first
+ *    time is a warning. A tie for the lowest place eliminates nobody (a coin toss between
+ *    equals would be arbitrary) and is reported as `tie_skip`.
+ *
+ * Provisional escrow never saves or condemns an agent: a clawback can slash an agent's
+ * total without touching survival.
+ */
+import { GOV_LIMITS } from '../limits.js';
+import { eliminate } from './ledger.js';
+import { activeAgents, teamHealth } from './ledger-state.js';
+export { AVOID_ADVICE, FAILURE_ANALYSIS_TOP_PENALTIES, buildFailureAnalysis, negativeEventCodes, } from './failure-analysis.js';
+const SCORED_ROLES = ['DEV', 'REV', 'TEST'];
+/** Eliminate every active agent whose `confirmed` is <= 0. Idempotent. */
+export function killDepleted(state, at) {
+    let current = state;
+    const eliminated = [];
+    for (const agent of activeAgents(state)) {
+        if (agent.confirmed > 0)
+            continue;
+        const outcome = eliminate(current, { agentId: agent.id, reason: 'depleted', at });
+        current = outcome.state;
+        if (outcome.eliminated)
+            eliminated.push(agent.id);
+    }
+    return { state: current, eliminated };
+}
+function withStrikes(state, agent, strikes) {
+    if (agent.tailStrikes === strikes)
+        return state;
+    return { ...state, agents: { ...state.agents, [agent.id]: { ...agent, tailStrikes: strikes } } };
+}
+/** Clear strikes: the streak must be CONSECUTIVE phase ends. */
+function resetStrikes(state, agents) {
+    return agents.reduce((s, a) => withStrikes(s, s.agents[a.id], 0), state);
+}
+function evaluateRole(state, role, request, out) {
+    const members = activeAgents(state, role);
+    if (members.length < GOV_LIMITS.tailEliminationMinRoleSize) {
+        return resetStrikes(state, members);
+    }
+    const lowest = Math.min(...members.map((m) => m.confirmed));
+    if (lowest >= GOV_LIMITS.tailEliminationThreshold)
+        return resetStrikes(state, members);
+    const tied = members.filter((m) => m.confirmed === lowest);
+    if (tied.length > 1) {
+        out.tieSkips.push({ role, agentIds: tied.map((m) => m.id), confirmed: lowest });
+        out.notes.push(`tie_skip: ${role} ${tied.map((m) => m.id).join(', ')} tie at ${lowest}.`);
+        return resetStrikes(state, members);
+    }
+    const target = tied[0];
+    let current = resetStrikes(state, members.filter((m) => m.id !== target.id));
+    const strikes = target.tailStrikes + 1;
+    current = withStrikes(current, current.agents[target.id], strikes);
+    if (strikes < 2) {
+        out.warnings.push({ agentId: target.id, role, strikes });
+        out.notes.push(`Tail warning: ${target.id} is lowest in ${role} at ${lowest}.`);
+        return current;
+    }
+    const outcome = eliminate(current, {
+        agentId: target.id,
+        reason: 'tail',
+        at: request.at,
+        ...(request.seq === undefined ? {} : { seq: request.seq }),
+    });
+    if (outcome.eliminated)
+        out.eliminated.push(target.id);
+    return outcome.state;
+}
+/**
+ * Phase-end tail check for every role. Order is fixed (DEV, REV, TEST) so the result and
+ * any seq stamping are reproducible on replay.
+ */
+export function evaluateTail(state, request) {
+    const out = { state, warnings: [], eliminated: [], tieSkips: [], notes: [] };
+    let current = state;
+    for (const role of SCORED_ROLES)
+        current = evaluateRole(current, role, request, out);
+    out.state = current;
+    return out;
+}
+/** `< 70` advises a coordination checkpoint (and a focused interface check at settle). */
+export function teamHealthStatus(state) {
+    const health = teamHealth(state);
+    if (health === null)
+        return { health, label: 'UNKNOWN', advisory: null };
+    if (health >= GOV_LIMITS.healthWarnThreshold)
+        return { health, label: 'HEALTHY', advisory: null };
+    return {
+        health,
+        label: 'CHECKPOINT_ADVISED',
+        advisory: `Team health ${health.toFixed(1)} is below ${GOV_LIMITS.healthWarnThreshold}: ` +
+            'a coordination checkpoint is advised; the next settle checks interface conflicts.',
+    };
+}