@aragon-agent/cli 0.6.43 → 0.6.45

package/dist/governance/engine/state-machine.js

@@ -0,0 +1,586 @@
+/**
+ * Stage legality, `NEXT` generation and escalation handling (governance-mode 8.2, I-G6).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Pure apart from the explicitly named
+ * mutators (`recordRework`, `markBlocked`, `openEscalation`, `closeEscalation`,
+ * `applyResolveDisposition`), which edit the `RunState` they are handed IN PLACE and do
+ * no I/O, so the engine can replay or persist around them.
+ *
+ * WHY A TABLE AND NOT TRUST. The orchestrator is an LLM; "do not skip review" in a prompt
+ * drifts over a multi-hour run. Here the stage order is a hard fact: `checkStage` is the
+ * only gate `gov_dispatch` passes through, and every refusal teaches (it names the
+ * blocking WPs and ends with the legal next calls) so a refused call is one cheap
+ * correction, not a dead end. Refusals are plain text, never errors (D-15).
+ *
+ * The current phase is the FIRST phase with `integrated === false`; stages only ever act
+ * on it. `dropped` and `integrated` WPs never block anything.
+ */
+import { TEAM_LIMITS } from '../../team/limits.js';
+import { GOV_LIMITS } from '../limits.js';
+import { STAGE_KINDS, } from '../types.js';
+export const NOT_ACCEPTED = 'NOT ACCEPTED:';
+// ---------------------------------------------------------------------------
+// Basic queries
+// ---------------------------------------------------------------------------
+/** Index of the first phase that is not integrated, or null when all are. */
+export function currentPhaseIndex(run) {
+    const found = run.phases.find((phase) => !phase.integrated);
+    return found ? found.index : null;
+}
+export function currentPhase(run) {
+    const index = currentPhaseIndex(run);
+    return index === null ? null : (run.phases[index] ?? null);
+}
+export function wpsInPhase(run, phase) {
+    return phase.wpIds
+        .map((id) => run.workPackages[id])
+        .filter((wp) => wp !== undefined);
+}
+/** `maxRework` plus L3 grants for one WP, never above the structural ceiling. */
+export function reworkLimit(run, wp) {
+    return Math.min(run.limits.maxRework + wp.reworkGrants, GOV_LIMITS.hardMaxRework);
+}
+/** Fix cycles allowed in a phase: `maxFixCycles + extraFixGrants`, capped structurally. */
+export function fixCycleLimit(run, phase) {
+    return Math.min(run.limits.maxFixCycles + phase.extraFixGrants, GOV_LIMITS.hardMaxFixCycles);
+}
+/**
+ * The last integrate failed, every allowed fix has been spent, and no newer integrate
+ * attempt is pending: the engine must open an `integration_exhausted` escalation.
+ */
+export function isIntegrationExhausted(run, phase) {
+    return (phase.lastIntegrationFailed &&
+        phase.fixCycles >= fixCycleLimit(run, phase) &&
+        phase.fixCycles < phase.integrationAttempts);
+}
+/** `gov_run close` precondition: every phase integrated (accepted failing counts). */
+export function canClose(run) {
+    return run.phases.length > 0 && run.phases.every((phase) => phase.integrated);
+}
+// ---------------------------------------------------------------------------
+// Per-stage eligibility
+// ---------------------------------------------------------------------------
+function dependenciesIntegrated(run, wp) {
+    return wp.dependsOn.every((id) => run.workPackages[id]?.status === 'integrated');
+}
+function isEligible(run, wp, stage) {
+    switch (stage) {
+        case 'dev':
+            return ((wp.status === 'pending' && dependenciesIntegrated(run, wp)) ||
+                wp.status === 'rework' ||
+                (wp.status === 'blocked' && wp.blockedAt === 'dev'));
+        case 'review':
+            return (wp.status === 'awaiting_review' || (wp.status === 'blocked' && wp.blockedAt === 'review'));
+        case 'test':
+            return wp.status === 'awaiting_test' || (wp.status === 'blocked' && wp.blockedAt === 'test');
+    }
+}
+const SETTLE_BLOCKING = new Set([
+    'pending',
+    'dev_running',
+    'awaiting_review',
+    'review_running',
+    'awaiting_test',
+    'test_running',
+    'rework',
+    'blocked',
+]);
+const STATUS_LABEL = {
+    pending: 'pending',
+    dev_running: 'in development',
+    awaiting_review: 'awaiting review',
+    review_running: 'in review',
+    awaiting_test: 'awaiting test',
+    test_running: 'in testing',
+    rework: 'in rework',
+    tested_ok: 'tested ok',
+    integrated: 'integrated',
+    blocked: 'blocked',
+    dropped: 'dropped',
+};
+function labelOf(wp) {
+    if (wp.status === 'blocked' && wp.blockedAt)
+        return `blocked at ${wp.blockedAt}`;
+    return STATUS_LABEL[wp.status];
+}
+/** "WPs awaiting review: a, b; pending: c" over the not-yet-finished WPs of a phase. */
+export function describePhaseStatus(run, phase) {
+    const groups = new Map();
+    for (const wp of wpsInPhase(run, phase)) {
+        if (wp.status === 'integrated' || wp.status === 'dropped')
+            continue;
+        const label = labelOf(wp);
+        groups.set(label, [...(groups.get(label) ?? []), wp.id]);
+    }
+    return [...groups.entries()].map(([label, ids]) => `WPs ${label}: ${ids.join(', ')}`).join('; ');
+}
+function settleIssue(run, phase) {
+    if (phase.settled)
+        return 'this phase is already settled';
+    const wps = wpsInPhase(run, phase);
+    const blockers = wps.filter((wp) => SETTLE_BLOCKING.has(wp.status));
+    if (blockers.length > 0) {
+        return `settle needs every WP finished: ${describePhaseStatus(run, phase)}`;
+    }
+    if (!wps.some((wp) => wp.status === 'tested_ok'))
+        return 'no work package has passed testing';
+    return null;
+}
+function integrateIssue(run, phase) {
+    if (!phase.settled)
+        return 'the phase is not settled yet';
+    if (phase.lastIntegrationFailed && phase.fixCycles < phase.integrationAttempts) {
+        return isIntegrationExhausted(run, phase)
+            ? `the last integration failed and all ${fixCycleLimit(run, phase)} fix cycles are spent`
+            : 'the last integration failed; run a fix stage first';
+    }
+    return null;
+}
+function fixIssue(run, phase) {
+    if (!phase.lastIntegrationFailed)
+        return 'there is no failed integration to fix';
+    if (phase.fixCycles >= phase.integrationAttempts) {
+        return 'a fix already ran since the last failure; integrate again';
+    }
+    const limit = fixCycleLimit(run, phase);
+    if (phase.fixCycles >= limit)
+        return `fix cycles are exhausted (${phase.fixCycles}/${limit})`;
+    return null;
+}
+function evaluateWpStage(run, phase, stage, requested) {
+    const eligible = wpsInPhase(run, phase).filter((wp) => isEligible(run, wp, stage));
+    if (requested === undefined) {
+        if (eligible.length > 0)
+            return { ok: true, phase, wpIds: eligible.map((wp) => wp.id) };
+        return { ok: false, reason: describePhaseStatus(run, phase) || 'no work package is eligible' };
+    }
+    const problems = requested.flatMap((id) => requestedProblem(run, phase, id, eligible));
+    if (problems.length > 0)
+        return { ok: false, reason: problems.join('; ') };
+    return { ok: true, phase, wpIds: [...new Set(requested)] };
+}
+function requestedProblem(run, phase, id, eligible) {
+    const wp = run.workPackages[id];
+    if (!wp)
+        return [`unknown work package '${id}'`];
+    if (wp.phase !== phase.index) {
+        return [`'${id}' belongs to phase ${wp.phase + 1}, the current phase is ${phase.index + 1}`];
+    }
+    if (eligible.some((candidate) => candidate.id === id))
+        return [];
+    return [`'${id}' is ${labelOf(wp)}`];
+}
+function evaluateStage(run, stage, requested) {
+    const phase = currentPhase(run);
+    if (!phase)
+        return { ok: false, reason: 'every phase is already integrated' };
+    if (stage === 'dev' || stage === 'review' || stage === 'test') {
+        return evaluateWpStage(run, phase, stage, requested);
+    }
+    const issue = stage === 'settle'
+        ? settleIssue(run, phase)
+        : stage === 'integrate'
+            ? integrateIssue(run, phase)
+            : fixIssue(run, phase);
+    if (issue)
+        return { ok: false, reason: issue };
+    // `fix` defaults to no WPs: the engine picks the DEVs the RCA attributes, and counting
+    // every WP of the phase here would inflate the stage width past the team ceiling.
+    const live = wpsInPhase(run, phase).filter((wp) => wp.status !== 'dropped');
+    const defaults = stage === 'fix' ? [] : live.map((wp) => wp.id);
+    return { ok: true, phase, wpIds: (requested ?? defaults).slice() };
+}
+// ---------------------------------------------------------------------------
+// Stage width and chunking (D-24)
+// ---------------------------------------------------------------------------
+/** Number of children a stage over `wpCount` WPs launches. */
+export function stageWidth(stage, wpCount) {
+    switch (stage) {
+        case 'dev':
+            return wpCount;
+        case 'fix':
+            return Math.max(1, wpCount);
+        case 'review':
+        case 'test':
+            return Math.min(3, Math.max(1, Math.ceil(wpCount / 2)));
+        case 'settle':
+        case 'integrate':
+            return 1;
+    }
+}
+/** Most WPs one call may carry so that `stageWidth` stays within `ceiling`. */
+export function stageChunkSize(stage, ceiling) {
+    const c = Math.max(1, Math.floor(ceiling));
+    switch (stage) {
+        case 'dev':
+        case 'fix':
+            return c;
+        case 'review':
+        case 'test':
+            return c >= 3 ? Number.POSITIVE_INFINITY : c * 2;
+        case 'settle':
+        case 'integrate':
+            return Number.POSITIVE_INFINITY;
+    }
+}
+function chunk(items, size) {
+    if (!Number.isFinite(size) || size >= items.length)
+        return [items.slice()];
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}
+function ceilingOf(options) {
+    return options?.teamCeiling ?? TEAM_LIMITS.hardMaxSubagents;
+}
+// ---------------------------------------------------------------------------
+// NEXT generation
+// ---------------------------------------------------------------------------
+/** `gov_dispatch {"stage":"dev","wps":["a","b"]}` */
+export function dispatchCall(stage, wps) {
+    const body = { stage };
+    if (wps && wps.length > 0)
+        body.wps = [...wps];
+    return `gov_dispatch ${JSON.stringify(body)}`;
+}
+/** Render actions as the trailing `NEXT:` block every `gov_*` result ends with (D-16). */
+export function formatNext(actions) {
+    if (actions.length === 0)
+        return 'NEXT: (none)';
+    return `NEXT:\n${actions.map((action) => `- ${action}`).join('\n')}`;
+}
+const DISPOSITIONS_BY_KIND = {
+    wp_rework_cap: ['retry', 'accept_as_is', 'drop'],
+    integration_exhausted: ['retry', 'accept_failing'],
+    dispute: [],
+};
+function escalationActions(escalations) {
+    const actions = [];
+    for (const esc of escalations.filter((e) => e.status === 'open')) {
+        const allowed = DISPOSITIONS_BY_KIND[esc.kind];
+        const disposition = allowed.length > 0 ? `,"disposition":"${allowed.join('|')}"` : '';
+        actions.push(`ask_user: put ${esc.id} (${esc.kind}) to the user: ${esc.topic}`);
+        const ruling = '"ruling":"<user ruling>"';
+        actions.push(`gov_run {"action":"resolve","escalationId":"${esc.id}",${ruling}${disposition}}`);
+    }
+    return actions;
+}
+function stageCalls(run, stage, ceiling) {
+    const evaluation = evaluateStage(run, stage, undefined);
+    if (!evaluation.ok)
+        return [];
+    if (stage === 'settle' || stage === 'integrate' || stage === 'fix')
+        return [dispatchCall(stage)];
+    const groups = chunk(evaluation.wpIds, stageChunkSize(stage, ceiling));
+    return groups.map((ids) => dispatchCall(stage, ids));
+}
+function dropHints(run) {
+    const phase = currentPhase(run);
+    if (!phase)
+        return [];
+    const stuck = wpsInPhase(run, phase).filter((wp) => wp.status === 'pending' &&
+        wp.dependsOn.some((id) => run.workPackages[id]?.status === 'dropped'));
+    if (stuck.length === 0)
+        return [];
+    return [
+        `WPs ${stuck.map((wp) => wp.id).join(', ')} depend on a dropped WP and cannot start: ` +
+            'gov_run {"action":"abandon","reason":"..."} and restart with a revised plan',
+    ];
+}
+function executingActions(run, ceiling) {
+    if (canClose(run))
+        return ['gov_run {"action":"close","summary":"<what was delivered>"}'];
+    const calls = STAGE_KINDS.flatMap((stage) => stageCalls(run, stage, ceiling));
+    const phase = currentPhase(run);
+    if (calls.length === 0 && phase && isIntegrationExhausted(run, phase)) {
+        return [
+            'integration fix cycles are exhausted: gov_run {"action":"status"} ' +
+                '(an escalation is opened)',
+        ];
+    }
+    const hints = dropHints(run);
+    if (calls.length === 0 && hints.length === 0)
+        return ['gov_run {"action":"status"}'];
+    return [...calls, ...hints];
+}
+/**
+ * Ordered legal next calls for the run's current state. Pure. Stage width beyond
+ * `teamCeiling` is split into chunk calls (D-24), each independently legal.
+ */
+export function nextActions(run, options) {
+    const ceiling = ceilingOf(options);
+    switch (run.status) {
+        case 'closed':
+        case 'abandoned':
+            return ['gov_run {"action":"start","goal":"...","spec":"...","workPackages":[...]}'];
+        case 'paused':
+            return ['gov_run {"action":"resume"}'];
+        case 'escalated':
+            return escalationActions(run.escalations);
+        case 'executing':
+            return run.stage?.status === 'running'
+                ? ['a stage is running; wait for it to finish, then gov_run {"action":"status"}']
+                : executingActions(run, ceiling);
+    }
+}
+// ---------------------------------------------------------------------------
+// checkStage
+// ---------------------------------------------------------------------------
+function refuse(run, reason, options, head) {
+    const first = head ?? reason;
+    const next = formatNext(nextActions(run, options));
+    return { ok: false, message: `${NOT_ACCEPTED} ${first}\n${next}` };
+}
+function runLevelRefusal(run) {
+    switch (run.status) {
+        case 'closed':
+            return 'the run is closed.';
+        case 'abandoned':
+            return 'the run was abandoned.';
+        case 'paused':
+            return 'the run is paused; resume it before dispatching.';
+        case 'escalated': {
+            const open = run.escalations.filter((e) => e.status === 'open').map((e) => e.id);
+            const ids = open.join(', ') || 'open escalation';
+            return `the run is escalated (${ids}); the user must rule first.`;
+        }
+        case 'executing':
+            break;
+    }
+    if (run.stage?.status === 'running')
+        return `a ${run.stage.kind} stage is already running.`;
+    if (run.dispatches >= GOV_LIMITS.hardMaxDispatches) {
+        return `the dispatch limit of ${GOV_LIMITS.hardMaxDispatches} per run is reached.`;
+    }
+    return null;
+}
+/**
+ * The single legality gate for `gov_dispatch` (I-G6). `wps` omitted means "every eligible
+ * WP of the current phase". On success `wpIds` is the validated list the stage will run.
+ */
+export function checkStage(run, stage, wps, options) {
+    const blocked = runLevelRefusal(run);
+    if (blocked)
+        return refuse(run, blocked, options);
+    const evaluation = evaluateStage(run, stage, wps);
+    if (!evaluation.ok) {
+        const head = `stage '${stage}' is not legal now (${evaluation.reason}).`;
+        return refuse(run, evaluation.reason, options, head);
+    }
+    const ceiling = ceilingOf(options);
+    const width = stageWidth(stage, evaluation.wpIds.length);
+    if (width > ceiling) {
+        const size = stageChunkSize(stage, ceiling);
+        const calls = chunk(evaluation.wpIds, size).map((ids) => dispatchCall(stage, ids));
+        return {
+            ok: false,
+            message: `${NOT_ACCEPTED} stage width ${width} exceeds team.maxSubagents (${ceiling}); ` +
+                `dispatch at most ${size} WPs per call.\n${formatNext(calls)}`,
+        };
+    }
+    return { ok: true, phase: evaluation.phase.index, wpIds: evaluation.wpIds };
+}
+/** Stages that are legal right now (ignores `teamCeiling`; chunking is not legality). */
+export function legalStages(run) {
+    return STAGE_KINDS.filter((stage) => checkStage(run, stage).ok);
+}
+// ---------------------------------------------------------------------------
+// Rework, blocking and escalations (mutators)
+// ---------------------------------------------------------------------------
+export function nextEscalationId(run) {
+    return `ESC-${run.escalations.length + 1}`;
+}
+/**
+ * Count one rejection against `wpId`. Beyond `maxRework + reworkGrants` the WP becomes
+ * `blocked` (retry stage `dev`, where the rework would have run) and an L3 escalation is
+ * proposed; otherwise it goes to `rework`.
+ */
+export function recordRework(run, wpId) {
+    const wp = run.workPackages[wpId];
+    if (!wp)
+        throw new Error(`recordRework: unknown work package '${wpId}'`);
+    wp.reworkCount += 1;
+    const limit = reworkLimit(run, wp);
+    if (wp.reworkCount <= limit) {
+        wp.status = 'rework';
+        return { outcome: 'rework', reworkCount: wp.reworkCount, limit, escalation: null };
+    }
+    wp.status = 'blocked';
+    wp.blockedAt = 'dev';
+    const escalation = {
+        id: nextEscalationId(run),
+        level: 'L3',
+        kind: 'wp_rework_cap',
+        wpId,
+        phase: wp.phase,
+        topic: `Work package '${wpId}' was sent back ${wp.reworkCount} times (limit ${limit}).`,
+        positions: [],
+        status: 'open',
+    };
+    return { outcome: 'blocked', reworkCount: wp.reworkCount, limit, escalation };
+}
+/** A stage produced no submission for this WP: block it at that stage, no penalty. */
+export function markBlocked(run, wpId, stage) {
+    const wp = run.workPackages[wpId];
+    if (!wp)
+        throw new Error(`markBlocked: unknown work package '${wpId}'`);
+    wp.status = 'blocked';
+    wp.blockedAt = stage;
+}
+export function openEscalation(run, escalation) {
+    run.escalations.push(escalation);
+    run.status = 'escalated';
+}
+/** Mark resolved; the run leaves `escalated` once no escalation remains open. */
+export function closeEscalation(run, escalation, ruling) {
+    escalation.status = 'resolved';
+    escalation.ruling = ruling;
+    const stillOpen = run.escalations.some((e) => e.status === 'open');
+    if (!stillOpen && run.status === 'escalated')
+        run.status = 'executing';
+}
+function resolveFailure(message) {
+    return { ok: false, message: `${NOT_ACCEPTED} ${message}` };
+}
+/** Not-yet-delivered WPs that depend (transitively) on `wpId`. */
+function dependentsOf(run, wpId) {
+    const hit = new Set();
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const wp of Object.values(run.workPackages)) {
+            if (hit.has(wp.id) || wp.status === 'integrated' || wp.status === 'dropped')
+                continue;
+            if (wp.dependsOn.some((dep) => dep === wpId || hit.has(dep))) {
+                hit.add(wp.id);
+                grew = true;
+            }
+        }
+    }
+    return run.wpOrder.filter((id) => hit.has(id));
+}
+function applyReworkDisposition(run, escalation, disposition) {
+    const wp = escalation.wpId ? run.workPackages[escalation.wpId] : undefined;
+    if (!wp)
+        return resolveFailure(`escalation ${escalation.id} names no known work package.`);
+    if (disposition === 'retry')
+        return grantRework(run, wp);
+    if (disposition === 'accept_as_is')
+        return acceptAsIs(wp);
+    return dropWorkPackage(run, wp);
+}
+function grantRework(run, wp) {
+    if (wp.reworkGrants >= GOV_LIMITS.maxReworkGrantsPerWp) {
+        return resolveFailure(`'${wp.id}' already used its ${GOV_LIMITS.maxReworkGrantsPerWp} rework grants; ` +
+            'choose accept_as_is or drop.');
+    }
+    if (run.limits.maxRework + wp.reworkGrants + 1 > GOV_LIMITS.hardMaxRework) {
+        return resolveFailure(`one more rework would exceed the structural limit of ${GOV_LIMITS.hardMaxRework}; ` +
+            'choose accept_as_is or drop.');
+    }
+    wp.reworkGrants += 1;
+    wp.status = 'rework';
+    delete wp.blockedAt;
+    return {
+        ok: true,
+        message: `'${wp.id}' gets one more rework (limit now ${reworkLimit(run, wp)}).`,
+        affectedDependents: [],
+    };
+}
+function acceptAsIs(wp) {
+    if (wp.submissions.review.length < 1) {
+        return resolveFailure(`'${wp.id}' has no review on record; accept_as_is needs at least one.`);
+    }
+    wp.status = 'tested_ok';
+    wp.acceptedWithIssues = true;
+    delete wp.blockedAt;
+    return {
+        ok: true,
+        message: `'${wp.id}' accepted as is; its unresolved required changes go into the final report.`,
+        affectedDependents: [],
+    };
+}
+function dropWorkPackage(run, wp) {
+    wp.status = 'dropped';
+    delete wp.blockedAt;
+    const voided = [];
+    for (const contract of run.contracts) {
+        const consumersGone = contract.consumers.every((id) => run.workPackages[id]?.status === 'dropped');
+        if (!contract.voided && (contract.producer === wp.id || consumersGone)) {
+            contract.voided = true;
+            voided.push(contract.id);
+        }
+    }
+    const phase = run.phases[wp.phase];
+    const skipped = phase !== undefined && wpsInPhase(run, phase).every((w) => w.status === 'dropped');
+    if (phase && skipped) {
+        phase.settled = true;
+        phase.integrated = true;
+    }
+    const dependents = dependentsOf(run, wp.id);
+    const parts = [`'${wp.id}' dropped; it is excluded from settle and integrate.`];
+    if (voided.length > 0)
+        parts.push(`Voided contracts: ${voided.join(', ')}.`);
+    if (skipped)
+        parts.push(`Phase ${wp.phase + 1} has no work left and is skipped.`);
+    if (dependents.length > 0) {
+        parts.push(`Affected work packages: ${dependents.join(', ')}. ` +
+            'Decide: drop them as well or abandon the run.');
+    }
+    return { ok: true, message: parts.join(' '), affectedDependents: dependents };
+}
+function applyIntegrationDisposition(run, escalation, disposition) {
+    const index = escalation.phase ?? currentPhaseIndex(run);
+    const phase = index === null ? undefined : run.phases[index];
+    if (!phase)
+        return resolveFailure(`escalation ${escalation.id} names no known phase.`);
+    if (disposition === 'retry') {
+        if (phase.extraFixGrants >= GOV_LIMITS.maxFixGrantsPerPhase) {
+            return resolveFailure('this phase already received its extra fix cycle; choose accept_failing.');
+        }
+        if (run.limits.maxFixCycles + phase.extraFixGrants + 1 > GOV_LIMITS.hardMaxFixCycles) {
+            return resolveFailure(`one more fix cycle would exceed the structural limit of ${GOV_LIMITS.hardMaxFixCycles}; ` +
+                'choose accept_failing.');
+        }
+        phase.extraFixGrants += 1;
+        return { ok: true, message: 'one extra fix cycle granted.', affectedDependents: [] };
+    }
+    phase.integrated = true;
+    phase.integrationAccepted = false;
+    phase.lastIntegrationFailed = false;
+    for (const wp of wpsInPhase(run, phase))
+        if (wp.status === 'tested_ok')
+            wp.status = 'integrated';
+    return {
+        ok: true,
+        message: `phase ${phase.index + 1} accepted although integration failed (reported in red).`,
+        affectedDependents: [],
+    };
+}
+/**
+ * Apply the user's `disposition` for an escalation (spec 7.2 table). Mismatched or
+ * over-cap dispositions are refused with a reason; no disposition changes nothing.
+ * Mutates `run`; does NOT mark the escalation resolved (`closeEscalation` does).
+ */
+export function applyResolveDisposition(run, escalation, disposition) {
+    if (escalation.status === 'resolved') {
+        return resolveFailure(`escalation ${escalation.id} is already resolved.`);
+    }
+    if (disposition === undefined) {
+        return {
+            ok: true,
+            message: 'ruling recorded; no work package or phase was changed.',
+            affectedDependents: [],
+        };
+    }
+    const allowed = DISPOSITIONS_BY_KIND[escalation.kind];
+    if (!allowed.includes(disposition)) {
+        const list = allowed.length > 0 ? allowed.join(', ') : 'none';
+        return resolveFailure(`disposition '${disposition}' does not apply to a ${escalation.kind} escalation ` +
+            `(allowed: ${list}).`);
+    }
+    return escalation.kind === 'wp_rework_cap'
+        ? applyReworkDisposition(run, escalation, disposition)
+        : applyIntegrationDisposition(run, escalation, disposition);
+}

package/dist/governance/engine/submission-queries.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Read-only queries over the accepted-submission cache (governance-mode 8.3).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * The stage runner builds briefs from these, and the adjudication half uses them to find
+ * "the previous review of this WP". Everything is derived from `core.submissionCache`
+ * (artifact id -> submission), which the resume path repopulates from the artifact store, so
+ * nothing here needs a second copy of state that could drift (a "pending rework" list kept
+ * beside the submissions would have to be persisted AND rebuilt; deriving it cannot).
+ */
+import { type RequiredChange } from '../rules/settlement.js';
+import type { ReviewSubmission, ReviewVerdict, Submission, TestSubmission, WorkSubmission } from '../types.js';
+import type { EngineCore } from './engine-core.js';
+type Kind = Submission['kind'];
+/** All cached submissions of one kind for a WP, oldest first. */
+export declare function submissionsOf<K extends Kind>(core: EngineCore, wpId: string, kind: K): Array<Extract<Submission, {
+    kind: K;
+}>>;
+export declare function latestWork(core: EngineCore, wpId: string): WorkSubmission | undefined;
+export declare function latestReview(core: EngineCore, wpId: string): ReviewSubmission | undefined;
+export declare function latestTest(core: EngineCore, wpId: string): TestSubmission | undefined;
+/** The review CONCLUSION a tester may see (never the comments, D-7). */
+export declare function reviewConclusion(core: EngineCore, wpId: string): ReviewVerdict | undefined;
+/** Files the developer reported changing in the latest work submission. */
+export declare function changeListOf(core: EngineCore, wpId: string): string[];
+/**
+ * The developer's open appeal, if the latest work submission appealed and no review has
+ * answered it yet. Reviewers MUST answer each finding id (L1, 5.6).
+ */
+export declare function pendingAppeal(core: EngineCore, wpId: string): {
+    findingIds: string[];
+    argument: string;
+} | undefined;
+/**
+ * The rework items a developer must address: derived from whichever REJECTION came last,
+ * a review (its `requiredChanges`, the only feedback surface a DEV sees) or a test (the
+ * defect or gap descriptions). Empty when the WP has not been rejected since its last
+ * work submission.
+ */
+export declare function reworkItemsFor(core: EngineCore, wpId: string): RequiredChange[];
+export {};