@aragon-agent/cli 0.6.44 → 0.6.45

package/dist/governance/rules/rca.js

@@ -0,0 +1,220 @@
+/**
+ * Root-cause attribution -> ledger events (governance-mode 5.7).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * The inspector reports WHO and HOW (a structured `RcaInput`); the engine owns the
+ * ARITHMETIC. That split is the point: the model supplies judgement it can justify from
+ * the code, and cannot mistype a figure, forget the C2 relief or double-count a cap.
+ * `expandRca` is pure - it returns events plus clawback requests in priority order, and
+ * the caller books them through `applyIncident` so the single-incident -50 cap truncates
+ * the right row (D13 -> D14/D15 -> C2/C3/C4 -> clawback).
+ */
+import { eventDef } from './events-table.js';
+import { INSPECTOR_ID, activeAgents } from './ledger-state.js';
+/** Recorded in the report; contributing agents carry weight but no event of their own. */
+export const RCA_WEIGHTS = {
+    primary: 0.6,
+    contributing: 0.3,
+    oversight: 0.1,
+};
+/** Higher wins when one agent is attributed twice. */
+const LEVEL_RANK = { primary: 3, oversight: 2, contributing: 1 };
+const INDIVIDUAL_DEFECT_TEXT = 'Individual defect, no integration events: route the work back to its developer.';
+/** Validate attributions against the roster; one entry per agent, highest level wins. */
+function acceptAttributions(ctx, attributions, skipped) {
+    const byAgent = new Map();
+    for (const attribution of attributions) {
+        const id = attribution.agentId;
+        const agent = ctx.state.agents[id];
+        if (id === INSPECTOR_ID)
+            skipped.push(`${id}: the inspector is not scored (I-G5).`);
+        else if (agent === undefined)
+            skipped.push(`${id}: unknown agent.`);
+        else if (agent.status !== 'active')
+            skipped.push(`${id}: already eliminated.`);
+        else {
+            const known = byAgent.get(id);
+            const outranks = known !== undefined && LEVEL_RANK[attribution.level] > LEVEL_RANK[known.attribution.level];
+            if (known === undefined || outranks) {
+                byAgent.set(id, { attribution, role: agent.role });
+            }
+        }
+    }
+    return [...byAgent.values()];
+}
+function incidentEvent(ctx, code, agentId, note) {
+    const event = {
+        code,
+        agentId,
+        at: ctx.at,
+        phase: ctx.phase,
+        by: ctx.by,
+        reason: `RCA ${ctx.incidentId}: ${eventDef(code).title}${note === '' ? '' : ` - ${note}`}`,
+        incidentId: ctx.incidentId,
+    };
+    if (ctx.wpId !== undefined)
+        event.wpId = ctx.wpId;
+    return event;
+}
+/** Oversight code by the stated miss, defaulting by role (REV -> R9, TEST -> T10). */
+function oversightCode(attribution, role) {
+    switch (attribution.miss) {
+        case 'review_integration':
+            return role === 'REV' ? 'R9' : null;
+        case 'test_defect':
+            return role === 'TEST' ? 'T4' : null;
+        case 'test_boundary':
+            return role === 'TEST' ? 'T10' : null;
+        default:
+            if (role === 'REV')
+                return 'R9';
+            if (role === 'TEST')
+                return 'T10';
+            return null;
+    }
+}
+function primaryDevCodes(attribution) {
+    const codes = ['D13'];
+    if (attribution.contract === 'producer')
+        codes.push('D14');
+    if (attribution.contract === 'consumer_unverified')
+        codes.push('D15');
+    return codes;
+}
+/** Individual events for one accepted attribution; empty for report-only contributions. */
+function individualCodes(accepted, notes) {
+    const { attribution, role } = accepted;
+    if (attribution.level === 'contributing')
+        return [];
+    if (attribution.level === 'primary' && role === 'DEV')
+        return primaryDevCodes(attribution);
+    const code = oversightCode(attribution, role);
+    if (code === null) {
+        notes.push(`${attribution.agentId} (${role}): no ${attribution.level} event applies.`);
+        return [];
+    }
+    return [code];
+}
+function collectiveEvents(ctx, rca, primaryIds) {
+    const only = ctx.participants === undefined ? undefined : new Set(ctx.participants);
+    const members = activeAgents(ctx.state).filter((a) => only === undefined || only.has(a.id));
+    const events = [];
+    const first = rca.systemic ? 'C4' : 'C2';
+    for (const agent of members) {
+        const event = incidentEvent(ctx, first, agent.id, rca.systemic ? 'systemic failure' : '');
+        if (first === 'C2' && !primaryIds.has(agent.id))
+            event.relief = true;
+        events.push(event);
+    }
+    if (ctx.fixCycles >= 3) {
+        for (const agent of members) {
+            events.push(incidentEvent(ctx, 'C3', agent.id, `${ctx.fixCycles} fix cycles`));
+        }
+    }
+    return events;
+}
+function describeIndividual(accepted, codes) {
+    const { attribution } = accepted;
+    const weight = RCA_WEIGHTS[attribution.level];
+    const what = codes.length > 0
+        ? codes.map((c) => `${c} ${eventDef(c).delta}`).join(', ')
+        : 'report only (no event)';
+    return `${attribution.agentId} (${attribution.level}, weight ${weight}): ${what}`;
+}
+function describeCollective(rca, fixCycles, hasPrimary) {
+    const lines = [];
+    if (rca.systemic)
+        lines.push('Collective: C4 -15 for every active agent (replaces C2).');
+    else if (hasPrimary)
+        lines.push('Collective: C2 -5 for primary agents, -2 for everyone else.');
+    else
+        lines.push('Collective: C2 -2 for everyone (no primary attribution).');
+    if (fixCycles >= 3) {
+        lines.push(`Collective: C3 -10 for every active agent (${fixCycles} fix cycles).`);
+    }
+    return lines;
+}
+/**
+ * Expand a structured RCA into ledger events (5.7 step 3):
+ *
+ *  - primary DEV -> D13 -25, plus D14 -20 (producer) and/or D15 -10 (consumer_unverified);
+ *  - oversight -> R9 -20 (review_integration), T4 -15 (test_defect), T10 -15
+ *    (test_boundary); a missing `miss` defaults by role (REV R9, TEST T10);
+ *  - contributing -> reported with weight 0.3, no event of its own;
+ *  - everyone active -> C2 -5 (-2 for non-primary) or, when systemic, C4 -15 instead;
+ *  - fix cycles >= 3 -> C3 -10 for everyone;
+ *  - every primary has the phase's escrow clawed back.
+ *
+ * `boundary = false` is an individual bug: nothing is booked.
+ */
+export function expandRca(rca, ctx) {
+    const result = {
+        individualDefect: !rca.boundary,
+        events: [],
+        clawbacks: [],
+        weights: [],
+        skipped: [],
+        breakdown: [],
+    };
+    if (!rca.boundary) {
+        result.breakdown.push(INDIVIDUAL_DEFECT_TEXT);
+        return result;
+    }
+    const accepted = acceptAttributions(ctx, rca.attributions, result.skipped);
+    const primaryIds = new Set();
+    for (const item of accepted) {
+        const { agentId, level } = item.attribution;
+        result.weights.push({ agentId, level, weight: RCA_WEIGHTS[level] });
+        const codes = individualCodes(item, result.skipped);
+        for (const code of codes) {
+            result.events.push(incidentEvent(ctx, code, agentId, item.attribution.note));
+        }
+        if (level === 'primary') {
+            primaryIds.add(agentId);
+            result.clawbacks.push({
+                agentId,
+                phase: ctx.phase,
+                reason: `RCA ${ctx.incidentId}: primary cause, escrow clawed back`,
+                incidentId: ctx.incidentId,
+                at: ctx.at,
+                by: ctx.by,
+            });
+        }
+        result.breakdown.push(describeIndividual(item, codes));
+    }
+    result.events.push(...collectiveEvents(ctx, rca, primaryIds));
+    result.breakdown.push(...describeCollective(rca, ctx.fixCycles, primaryIds.size > 0));
+    if (primaryIds.size > 0) {
+        result.breakdown.push(`Clawback of phase escrow: ${[...primaryIds].join(', ')}.`);
+    }
+    for (const line of result.skipped)
+        result.breakdown.push(`Skipped - ${line}`);
+    return result;
+}
+/**
+ * Report lines AFTER booking: what the cap actually did. The inspector must state any
+ * `capped` row in the settle summary (AC-17), so the engine hands it ready-made text.
+ */
+export function summarizeIncident(outcome) {
+    const lines = [];
+    for (const o of outcome.outcomes) {
+        const entry = o.entry;
+        if (entry?.capped !== undefined) {
+            const { requested, applied } = entry.capped;
+            lines.push(`CAPPED ${entry.code}: requested ${requested}, applied ${applied}.`);
+        }
+        if (o.rejected !== undefined)
+            lines.push(`REJECTED: ${o.rejected.message}`);
+        if (o.eliminated)
+            lines.push('An agent was eliminated by this incident (confirmed reached 0).');
+    }
+    for (const c of outcome.clawbacks) {
+        if (c.requested > 0) {
+            lines.push(c.capped
+                ? `CAPPED CLAWBACK: ${c.clawed} of ${c.requested} reclaimed.`
+                : `Clawback: ${c.clawed} reclaimed.`);
+        }
+    }
+    return lines;
+}

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

@@ -0,0 +1,129 @@
+/**
+ * Mechanical settlement - structured verdicts -> automatic bookings and routing
+ * (governance-mode 5.5).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * Every function here is a PURE DECISION: it returns the events to book, the next route
+ * for the work package and any claims to open, and touches no state. The engine books the
+ * events through the ledger (I-G7: one accounting path) and applies the route.
+ *
+ * VALIDATION BEFORE ACCOUNTING (D-15). A submission that is incomplete or contradicts
+ * itself comes back as a `refusal` with NOTHING booked and no route - the child fixes the
+ * submission and tries again. A refusal text starts with `NOT ACCEPTED:` and says what is
+ * wrong and how to fix it; it is plain text, never an error, because an error would trip
+ * the model's retry loop. The tool layer decides how many refusals a child gets.
+ */
+import type { Claim, Contract, LedgerState, ReviewFinding, ReviewSubmission, TestSubmission, WorkPackage, WorkSubmission } from '../types.js';
+import { type EventCode } from './events-table.js';
+import { type LedgerEvent } from './ledger.js';
+export interface SettlementContext {
+    wp: Pick<WorkPackage, 'id' | 'assignee' | 'reviewer' | 'tester' | 'rejections' | 'files'>;
+    contracts: readonly Contract[];
+    phase: number;
+    /** Time of the submission; events carry it so replay never reads a clock. */
+    at: number;
+    /** Finding ids the DEV appealed last round: the reviewer MUST answer each (L1). */
+    appealFindingIds?: readonly string[];
+}
+export interface RequiredChange {
+    file: string;
+    issue: string;
+    change: string;
+}
+/** Where the work package goes next. */
+export type WpRoute = {
+    to: 'review';
+} | {
+    to: 'test';
+} | {
+    to: 'passed';
+} | {
+    to: 'dev';
+    requiredChanges: RequiredChange[];
+};
+/** Strike a previously booked deduction (an upheld-then-withdrawn D5). */
+export interface ReversalRequest {
+    agentId: string;
+    code: EventCode;
+    wpId: string;
+    reason: string;
+}
+/** One rejection (a NEEDS_REWORK review), kept so R2 can be paid at settle time. */
+export interface RejectionRecord {
+    id: string;
+    wpId: string;
+    reviewer: string;
+    hasBlockerOrMajor: boolean;
+    withdrawn: boolean;
+}
+export interface SettlementResult {
+    /** False => a validation refusal: nothing is booked, no route. */
+    ok: boolean;
+    refusal: string | null;
+    events: LedgerEvent[];
+    route: WpRoute | null;
+    claims: Claim[];
+    reversals: ReversalRequest[];
+    /** Fingerprints to append to `wp.rejections` (D8 detection on the next rejection). */
+    newRejections: string[];
+    rejection: RejectionRecord | null;
+    notes: string[];
+}
+/** The findings that make a rework mandatory: blocker, major or flagged `mustFix`. */
+export declare function blockingFindings(findings: readonly ReviewFinding[]): ReviewFinding[];
+/** The only feedback surface a DEV sees (D-7): one row per blocking finding. */
+export declare function deriveRequiredChanges(findings: readonly ReviewFinding[]): RequiredChange[];
+/**
+ * A DEV submission: route to review, flag D17 (scope narrowing) on the mechanical
+ * signature, and report files touched outside the WP's ownership (evidence only).
+ * D17 is appealable once; the booking carries that in its reason.
+ */
+export declare function settleWork(ctx: SettlementContext, submission: WorkSubmission): SettlementResult;
+/**
+ * A REVIEW submission. PASS -> D1 (+15 P) -> test; PASS_WITH_FIXES -> D2 (+5 P) -> test;
+ * NEEDS_REWORK -> D5 (-20) -> dev, plus D8 (-30) when a blocking finding repeats an
+ * earlier rejection. A withdrawn appeal finding books R5 on the reviewer and strikes the
+ * earlier D5 (one R5 per submission, not per finding, so withdrawing is not a punishment
+ * multiplier). R12 is checked on every verdict.
+ */
+export declare function settleReview(ctx: SettlementContext, sub: ReviewSubmission): SettlementResult;
+/** True when a traceability row names a real requirement (not a placeholder). */
+export declare function isConcreteRequirement(text: string): boolean;
+/**
+ * A TEST submission. ALL_PASS -> D3, and when every traceability row is covered D4 + T1;
+ * SPEC_MISMATCH -> D7 (needs a real `gap` row); INCOMPLETE_IMPL -> D9, or D11 instead when
+ * the skeleton ratio is above 0.30 with evidence; ISSUES_FOUND books nothing itself. Any
+ * `unverified` row books T6 on the tester. Claims are opened, never booked here.
+ */
+export declare function settleTest(ctx: SettlementContext, sub: TestSubmission): SettlementResult;
+export interface PhaseSettleInput {
+    /** Used only to make the stage idempotent (a re-run books nothing twice). */
+    state: LedgerState;
+    phase: number;
+    at: number;
+    /** WPs whose review passed, with the reviewer who passed them. */
+    reviewedWps: ReadonlyArray<{
+        wpId: string;
+        reviewer: string;
+    }>;
+    /** WPs that reached ALL_PASS. */
+    testedOkWpIds: readonly string[];
+    /** Every claim of the run; only this phase's are considered. */
+    claims: readonly Claim[];
+    rejections: readonly RejectionRecord[];
+}
+export interface PhaseSettleResult {
+    events: LedgerEvent[];
+    notes: string[];
+}
+/**
+ * R1 and R2, which can only be decided once the phase's claims are ruled.
+ *
+ *  - R1 +10 (P): a WP passed review and no missed-defect / incomplete-impl claim against
+ *    that review was upheld. A still-open claim defers R1 (never pay before the ruling).
+ *  - R2 +10: a rejection with a blocker/major finding that was not withdrawn or overturned,
+ *    and whose WP later reached ALL_PASS - rework confirmed the problem was real. Paid
+ *    once per rejection (`r2:<review id>`), which is what stops a reviewer farming it.
+ */
+export declare function settlePhaseR1R2(input: PhaseSettleInput): PhaseSettleResult;