@aragon-agent/cli 0.6.44 → 0.6.46

package/dist/governance/engine/submission-queries.js

@@ -0,0 +1,97 @@
+/**
+ * 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 { settleTest } from '../rules/settlement.js';
+/** All cached submissions of one kind for a WP, oldest first. */
+export function submissionsOf(core, wpId, kind) {
+    const out = [];
+    for (const item of core.submissionCache.values()) {
+        if (item.kind === kind && 'wpId' in item && item.wpId === wpId) {
+            out.push(item);
+        }
+    }
+    return out.sort((a, b) => a.at - b.at || a.id.localeCompare(b.id));
+}
+export function latestWork(core, wpId) {
+    return submissionsOf(core, wpId, 'work').at(-1);
+}
+export function latestReview(core, wpId) {
+    return submissionsOf(core, wpId, 'review').at(-1);
+}
+export function latestTest(core, wpId) {
+    return submissionsOf(core, wpId, 'test').at(-1);
+}
+/** The review CONCLUSION a tester may see (never the comments, D-7). */
+export function reviewConclusion(core, wpId) {
+    return latestReview(core, wpId)?.verdict;
+}
+/** Files the developer reported changing in the latest work submission. */
+export function changeListOf(core, wpId) {
+    return latestWork(core, wpId)?.filesChanged ?? [];
+}
+/**
+ * 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 function pendingAppeal(core, wpId) {
+    const work = latestWork(core, wpId);
+    if (work?.appeal === undefined)
+        return undefined;
+    const review = latestReview(core, wpId);
+    if (review !== undefined && review.at >= work.at)
+        return undefined;
+    return work.appeal;
+}
+/**
+ * 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 function reworkItemsFor(core, wpId) {
+    const run = core.run;
+    const wp = run?.workPackages[wpId];
+    if (run === null || wp === undefined)
+        return [];
+    const work = latestWork(core, wpId);
+    const review = latestReview(core, wpId);
+    const test = latestTest(core, wpId);
+    const since = work?.at ?? 0;
+    const reviewRejected = review?.verdict === 'NEEDS_REWORK' && review.at >= since;
+    const testRejected = test !== undefined && test.verdict !== 'ALL_PASS' && test.at >= since;
+    if (reviewRejected && testRejected) {
+        return review.at >= test.at ? review.requiredChanges : testItems(core, wpId, test);
+    }
+    if (reviewRejected)
+        return review.requiredChanges;
+    if (testRejected)
+        return testItems(core, wpId, test);
+    return [];
+}
+function testItems(core, wpId, test) {
+    const wp = core.run?.workPackages[wpId];
+    if (wp === undefined)
+        return [];
+    const result = settleTest({
+        wp: {
+            id: wp.id,
+            assignee: wp.assignee ?? 'dev',
+            reviewer: wp.reviewer,
+            tester: wp.tester,
+            rejections: wp.rejections,
+            files: wp.files,
+        },
+        contracts: [],
+        phase: wp.phase,
+        at: test.at,
+    }, test);
+    return result.route?.to === 'dev' ? result.route.requiredChanges : [];
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Human-readable renderings of accepted submissions (written beside the JSON artifact, and
+ * what `gov_read` shows a role that is allowed to see them).
+ *
+ * ASCII ONLY in this source (`governance/` is glyph-scanned); the TEXT it renders is
+ * whatever the agent wrote, in whatever language the request used.
+ */
+import type { InspectorReport, ReviewSubmission, TestSubmission, WorkSubmission } from '../types.js';
+export declare function renderWorkMarkdown(sub: WorkSubmission): string;
+export declare function renderReviewMarkdown(sub: ReviewSubmission): string;
+export declare function renderTestMarkdown(sub: TestSubmission): string;
+export declare function renderInspectorMarkdown(report: InspectorReport): string;

package/dist/governance/engine/submission-render.js

@@ -0,0 +1,92 @@
+/**
+ * Human-readable renderings of accepted submissions (written beside the JSON artifact, and
+ * what `gov_read` shows a role that is allowed to see them).
+ *
+ * ASCII ONLY in this source (`governance/` is glyph-scanned); the TEXT it renders is
+ * whatever the agent wrote, in whatever language the request used.
+ */
+function list(items) {
+    return items.length === 0 ? '- (none)' : items.map((i) => `- ${i}`).join('\n');
+}
+export function renderWorkMarkdown(sub) {
+    const lines = [
+        `# Work submission - ${sub.wpId} by ${sub.identity} (attempt ${sub.attempt}, ${sub.stage})`,
+        '',
+        sub.summary,
+        '',
+        '## Files changed',
+        list(sub.filesChanged),
+        '',
+        '## Interface contracts',
+        list(sub.interfaceContracts.map((c) => `${c.interface} [${c.role}] verified=${c.verified} peer=${c.peer || '-'}: ${c.method}`)),
+        '',
+        '## Verification',
+        list(sub.verification.commands.map((c) => `${c.cmd} -> ${c.result}${c.note ? ` (${c.note})` : ''}`)),
+    ];
+    if (sub.appeal) {
+        lines.push('', '## Appeal', `Findings: ${sub.appeal.findingIds.join(', ')}`, sub.appeal.argument);
+    }
+    return `${lines.join('\n')}\n`;
+}
+export function renderReviewMarkdown(sub) {
+    const check = Object.entries(sub.checklist).map(([name, item]) => `${name}: ${item.status} - ${item.evidence}`);
+    const lines = [
+        `# Review - ${sub.wpId} by ${sub.identity} (attempt ${sub.attempt}): ${sub.verdict}`,
+        '',
+        '## Checklist',
+        list(check),
+        '',
+        '## Findings',
+        list(sub.findings.map((f) => `[${f.id}] ${f.severity}${f.mustFix ? ' MUST FIX' : ''} ${f.file}${f.line ? `:${f.line}` : ''}: ${f.issue} => ${f.requiredChange}`)),
+        '',
+        '## Fixes applied by the reviewer',
+        list(sub.fixesApplied.map((f) => `${f.file}: ${f.rationale}`)),
+        '',
+        '## Integration assessment',
+        sub.integrationAssessment,
+    ];
+    if (sub.appealResponses.length > 0) {
+        lines.push('', '## Appeal responses', list(sub.appealResponses.map((r) => `${r.findingId}: ${r.decision}${r.note ? ` - ${r.note}` : ''}`)));
+    }
+    return `${lines.join('\n')}\n`;
+}
+export function renderTestMarkdown(sub) {
+    const lines = [
+        `# Test report - ${sub.wpId} by ${sub.identity} (attempt ${sub.attempt}): ${sub.verdict}`,
+        '',
+        '## Traceability',
+        list(sub.traceability.map((t) => `[${t.status}] ${t.requirement} - ${t.evidence}`)),
+        '',
+        '## Commands',
+        list(sub.commands.map((c) => `${c.cmd} (exit ${c.exit}): ${c.summary}`)),
+        '',
+        '## Issues',
+        list(sub.issues.map((i) => `${i.severity}: ${i.description}`)),
+        '',
+        `Boundary tests written: ${sub.boundaryTestsWritten ? 'yes' : 'no'}`,
+    ];
+    if (sub.skeletonRatio !== undefined) {
+        lines.push(`Skeleton ratio: ${sub.skeletonRatio} (${sub.skeletonEvidence ?? 'no evidence'})`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+export function renderInspectorMarkdown(report) {
+    const lines = [
+        `# Inspector report - phase ${report.phase + 1} ${report.stage}`,
+        '',
+        report.summary,
+        '',
+        '## Contract checks',
+        list(report.contractChecks.map((c) => `${c.contractId}: ${c.status} - ${c.note}`)),
+    ];
+    if (report.integration) {
+        lines.push('', `## Integration: ${report.integration.result}`, list(report.integration.commands.map((c) => `${c.cmd} (exit ${c.exit}): ${c.summary}`)));
+    }
+    if (report.rca) {
+        lines.push('', '## Root cause analysis', `boundary=${report.rca.boundary} systemic=${report.rca.systemic}`, list(report.rca.failingChecks.map((f) => `${f.name}: ${f.files.join(', ')}`)), list(report.rca.attributions.map((a) => `${a.agentId} ${a.level} ${a.contract}: ${a.note}`)));
+    }
+    if (report.escalations.length > 0) {
+        lines.push('', '## Escalations', list(report.escalations.map((e) => `${e.kind}: ${e.topic}`)));
+    }
+    return `${lines.join('\n')}\n`;
+}

package/dist/governance/engine/submissions.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `gov_submit_work` / `gov_submit_review` / `gov_submit_test` - the engine side
+ * (governance-mode 5.5, 7.1, 7.3, 8.4).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THE TOOL LAYER NORMALIZES AND THIS MODULE RE-CHECKS. A tool that is mocked, replaced or
+ * called by a future code path must not be able to push an unvalidated object into the
+ * ledger; re-running the (pure, cheap) normalizer here makes that a property of the engine
+ * and not of the caller.
+ *
+ * EVERY REFUSAL IS TEXT, NEVER AN ERROR, NEVER A PENALTY (D-15). A malformed submission is
+ * a tool-layer mistake, not a character flaw: `errorResult` would invite an identical
+ * retry loop, and a deduction would punish an agent for a typo. Refusals are counted per
+ * (identity, wp); past `GOV_LIMITS.maxValidationFailures` the submission is treated as
+ * absent (the stage runner then re-dispatches once, then blocks the WP - still no penalty).
+ *
+ * ALL STATE CHANGES ARE SYNCHRONOUS. The model's tool call returns text; persistence is
+ * queued behind `EngineCore`'s write chain.
+ */
+import type { Identity } from '../types.js';
+import type { EngineCore } from './engine-core.js';
+export declare function handleSubmitWork(core: EngineCore, identity: Identity, input: unknown): string;
+export declare function handleSubmitReview(core: EngineCore, identity: Identity, input: unknown): string;
+export declare function handleSubmitTest(core: EngineCore, identity: Identity, input: unknown): string;
+/** For tests and the stage runner: every accepted submission of one WP, any kind. */
+export declare function acceptedSubmissionIds(core: EngineCore, wpId: string): string[];

package/dist/governance/engine/submissions.js

@@ -0,0 +1,455 @@
+/**
+ * `gov_submit_work` / `gov_submit_review` / `gov_submit_test` - the engine side
+ * (governance-mode 5.5, 7.1, 7.3, 8.4).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THE TOOL LAYER NORMALIZES AND THIS MODULE RE-CHECKS. A tool that is mocked, replaced or
+ * called by a future code path must not be able to push an unvalidated object into the
+ * ledger; re-running the (pure, cheap) normalizer here makes that a property of the engine
+ * and not of the caller.
+ *
+ * EVERY REFUSAL IS TEXT, NEVER AN ERROR, NEVER A PENALTY (D-15). A malformed submission is
+ * a tool-layer mistake, not a character flaw: `errorResult` would invite an identical
+ * retry loop, and a deduction would punish an agent for a typo. Refusals are counted per
+ * (identity, wp); past `GOV_LIMITS.maxValidationFailures` the submission is treated as
+ * absent (the stage runner then re-dispatches once, then blocks the WP - still no penalty).
+ *
+ * ALL STATE CHANGES ARE SYNCHRONOUS. The model's tool call returns text; persistence is
+ * queued behind `EngineCore`'s write chain.
+ */
+import { getLogger } from '../../logging/logger.js';
+import { GOV_LIMITS } from '../limits.js';
+import { settleReview, settleTest, settleWork } from '../rules/settlement.js';
+import { detectOwnershipViolations } from '../rules/suspicion.js';
+import { formatNotAccepted } from '../tools/normalize-util.js';
+import { normalizeReviewSubmission, normalizeTestSubmission, normalizeWorkSubmission, } from '../tools/submit-normalizers.js';
+import { applyEvents, emitLedger } from './aftermath.js';
+import { artifactIdFor, nextAttempt, persistArtifact, STORAGE_EXHAUSTED_TEXT, } from './artifact-persist.js';
+import { escalationCard } from './cards.js';
+import { renderReviewMarkdown, renderTestMarkdown, renderWorkMarkdown, } from './submission-render.js';
+import { latestReview, pendingAppeal, submissionsOf } from './submission-queries.js';
+import { openEscalation, recordRework } from './state-machine.js';
+const TOOL = {
+    work: 'gov_submit_work',
+    review: 'gov_submit_review',
+    test: 'gov_submit_test',
+};
+const ROLE_OF = { work: 'DEV', review: 'REV', test: 'TEST' };
+const STAGES_OF = {
+    work: ['dev', 'fix'],
+    review: ['review'],
+    test: ['test'],
+};
+const NOT_ACCEPTED = 'NOT ACCEPTED:';
+const NOT_ACCEPTED_ALREADY_TEXT = `${NOT_ACCEPTED} already submitted:`;
+function ownerOf(wp, kind) {
+    if (kind === 'work')
+        return wp.assignee;
+    return kind === 'review' ? wp.reviewer : wp.tester;
+}
+function failureKey(identity, wpId) {
+    return `${identity.id}|${wpId}`;
+}
+/** Record one refusal and append the running count; never books anything. */
+function refuse(core, identity, wpId, text) {
+    const key = failureKey(identity, wpId);
+    const count = (core.validationFailures.get(key) ?? 0) + 1;
+    core.validationFailures.set(key, count);
+    const left = GOV_LIMITS.maxValidationFailures - count;
+    const tail = left > 0
+        ? `(${left} correction attempt(s) left for ${wpId || 'this call'}; nothing was recorded ` +
+            `and no GT was deducted.)`
+        : `Too many invalid submissions for ${wpId || 'this call'}: it is now treated as NOT ` +
+            `submitted ` +
+            '(no GT was deducted).';
+    return `${text}\n${tail}`;
+}
+/** Refusals that are not the agent's mistake and so do not burn a correction attempt. */
+function uncounted(text) {
+    return text.startsWith(NOT_ACCEPTED_ALREADY_TEXT) || text === STORAGE_EXHAUSTED_TEXT;
+}
+function tooManyFailures(core, identity, wpId) {
+    return ((core.validationFailures.get(failureKey(identity, wpId)) ?? 0) >=
+        GOV_LIMITS.maxValidationFailures);
+}
+function resolveWpId(run, raw) {
+    if (run.workPackages[raw] !== undefined)
+        return raw;
+    const lower = raw.toLowerCase();
+    return run.workPackages[lower] !== undefined ? lower : undefined;
+}
+/** The legality gate shared by all three tools. Returns the context or a refusal text. */
+function admit(core, identity, kind, rawWpId) {
+    const run = core.run;
+    if (run === null)
+        return `${NOT_ACCEPTED} no governance run is active.`;
+    if (identity.role !== ROLE_OF[kind]) {
+        return (`${NOT_ACCEPTED} ${TOOL[kind]} is for ${ROLE_OF[kind]} agents; you are ` + `${identity.role}.`);
+    }
+    if (core.storageExhausted)
+        return STORAGE_EXHAUSTED_TEXT;
+    const stage = run.stage;
+    if (stage === null || stage.status !== 'running' || !STAGES_OF[kind].includes(stage.kind)) {
+        const now = stage ? `${stage.kind} (${stage.status})` : 'none';
+        return (`${NOT_ACCEPTED} no ${STAGES_OF[kind].join('/')} stage is running (current stage: ` +
+            `${now}).`);
+    }
+    const wpId = resolveWpId(run, rawWpId);
+    const wp = wpId === undefined ? undefined : run.workPackages[wpId];
+    if (wp === undefined) {
+        return (`${NOT_ACCEPTED} unknown work package "${rawWpId}". Yours: ` +
+            `${assignedTo(run, identity, kind)}.`);
+    }
+    if (!stage.wpIds.includes(wp.id)) {
+        return (`${NOT_ACCEPTED} work package ${wp.id} is not part of this stage. Yours: ` +
+            `${assignedTo(run, identity, kind)}.`);
+    }
+    if (ownerOf(wp, kind) !== identity.id) {
+        return (`${NOT_ACCEPTED} work package ${wp.id} is not assigned to you. Yours: ` +
+            `${assignedTo(run, identity, kind)}.`);
+    }
+    if (core.stageSubmitted.has(wp.id)) {
+        return `${NOT_ACCEPTED_ALREADY_TEXT} ${wp.id} (one submission per work package per stage).`;
+    }
+    return { run, wp, stage: stage.kind };
+}
+function assignedTo(run, identity, kind) {
+    const ids = (run.stage?.wpIds ?? []).filter((id) => ownerOf(run.workPackages[id], kind) === identity.id);
+    return ids.length > 0 ? ids.join(', ') : '(none)';
+}
+/** `OK:` tail telling a multi-WP agent what is still owed. */
+function remainingText(core, identity, kind) {
+    const run = core.requireRun();
+    const mine = (run.stage?.wpIds ?? []).filter((id) => ownerOf(run.workPackages[id], kind) === identity.id);
+    const owed = mine.filter((id) => !core.stageSubmitted.has(id));
+    if (owed.length === 0) {
+        core.setAgentState(identity.id, 'submitted');
+        return `All ${mine.length} of your work package(s) are submitted. You are done.`;
+    }
+    return (`${mine.length - owed.length} of ${mine.length} submitted. Still owed: ` + `${owed.join(', ')}.`);
+}
+function ctxFor(run, wp, at, appeal) {
+    return {
+        wp: {
+            id: wp.id,
+            assignee: wp.assignee,
+            reviewer: wp.reviewer,
+            tester: wp.tester,
+            rejections: wp.rejections,
+            files: wp.files,
+        },
+        contracts: run.contracts,
+        phase: wp.phase,
+        at,
+        ...(appeal !== undefined ? { appealFindingIds: appeal } : {}),
+    };
+}
+function bookedFor(booked, agentId) {
+    if (agentId === null)
+        return '';
+    const parts = booked
+        .filter((b) => b.agentId === agentId && typeof b.entry.code === 'string' && b.entry.delta !== 0)
+        .map((b) => {
+        const sign = b.entry.delta > 0 ? '+' : '';
+        const pool = b.entry.settlement === 'provisional' ? 'P' : '';
+        return `${sign}${b.entry.delta}${pool} ${b.entry.code}`;
+    });
+    return parts.join(' ');
+}
+/** Apply a settlement's side effects that are common to all three kinds. */
+function applySettlement(core, wp, result, at) {
+    const run = core.requireRun();
+    const booked = applyEvents(core, result.events, { phase: wp.phase });
+    for (const r of result.reversals) {
+        const op = core.ledgerOp({
+            op: 'reverse',
+            request: { agentId: r.agentId, code: r.code, wpId: r.wpId, at, reason: r.reason },
+        });
+        core.noteBooked(op.booked);
+        booked.push(...op.booked);
+    }
+    for (const fp of result.newRejections) {
+        if (!wp.rejections.includes(fp))
+            wp.rejections.push(fp);
+    }
+    for (const claim of result.claims) {
+        if (!run.claims.some((c) => c.id === claim.id)) {
+            run.claims.push(claim);
+            core.log('claim', claim.raisedBy, { claim });
+        }
+    }
+    return booked;
+}
+function openRework(core, run, wp) {
+    const outcome = recordRework(run, wp.id);
+    if (outcome.escalation === null)
+        return `rework ${outcome.reworkCount}/${outcome.limit}`;
+    openEscalation(run, outcome.escalation);
+    core.log('escalation', 'engine', { escalation: outcome.escalation });
+    core.stageWarnings.push(`ESCALATION ${outcome.escalation.id}: ${wp.id} reached the rework limit and is blocked; ` +
+        `ask the user, then gov_run resolve.`);
+    core.emit((snapshot) => ({
+        type: 'escalation',
+        snapshot,
+        escalation: outcome.escalation,
+        card: escalationCard(core, outcome.escalation),
+    }));
+    return `blocked: rework limit ${outcome.limit} exceeded`;
+}
+function checkOwnership(core, identity, wp) {
+    const touched = core.touchedFiles.get(identity.id);
+    if (touched === undefined || touched.length === 0)
+        return;
+    const stray = detectOwnershipViolations(touched, wp.files);
+    if (stray.length === 0)
+        return;
+    core.log('ownership_violation', identity.id, { wpId: wp.id, files: stray });
+    core.stageWarnings.push(`${identity.id} touched files outside ${wp.id}: ${stray.slice(0, 5).join(', ')}.`);
+}
+function finish(core, kind, identity, wpId) {
+    core.stageSubmitted.add(wpId);
+    core.log('submission', identity.id, { kind, wpId });
+    core.checkpoint();
+    core.emit((snapshot) => ({ type: 'submission', snapshot, identity: identity.id, wpId, kind }));
+    emitLedger(core);
+}
+/** Wrap a handler so a bug becomes a `NOT ACCEPTED` text and a log line, never a throw. */
+function guarded(tool, fn) {
+    try {
+        return fn();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        getLogger().warn('agent', 'governance.submission_internal_error', { tool, message });
+        return (`${NOT_ACCEPTED} internal error while recording ${tool} (${message}). Nothing was ` +
+            `recorded; try once more.`);
+    }
+}
+function normalizeOrRefuse(core, identity, kind, normalized, fallbackWpId) {
+    if (normalized.ok)
+        return normalized.value;
+    return refuse(core, identity, fallbackWpId, formatNotAccepted(TOOL[kind], normalized.errors));
+}
+/** Normalize, admit and rate-limit one call; a string result is the refusal to return. */
+function intake(core, identity, kind, input, normalized) {
+    const value = normalizeOrRefuse(core, identity, kind, normalized, rawWpId(input));
+    if (typeof value === 'string')
+        return value;
+    const admitted = admit(core, identity, kind, value.wpId);
+    if (typeof admitted === 'string') {
+        return uncounted(admitted) ? admitted : refuse(core, identity, value.wpId, admitted);
+    }
+    if (tooManyFailures(core, identity, admitted.wp.id)) {
+        return (`${NOT_ACCEPTED} too many invalid submissions for ${admitted.wp.id}; ` +
+            'it is treated as not submitted.');
+    }
+    return { value, ...admitted };
+}
+function rawWpId(input) {
+    if (input !== null && typeof input === 'object') {
+        const v = input.wpId;
+        if (typeof v === 'string')
+            return v;
+    }
+    return '';
+}
+// ---------------------------------------------------------------------------
+// Work
+// ---------------------------------------------------------------------------
+function validateAppeal(core, wp, sub) {
+    if (sub.appeal === undefined)
+        return null;
+    if (sub.stage === 'fix')
+        return (`${NOT_ACCEPTED} an appeal is only possible against a review rejection, not in a ` +
+            `fix stage.`);
+    if (wp.appealUsed)
+        return `${NOT_ACCEPTED} you already used your one appeal for ${wp.id}.`;
+    const review = latestReview(core, wp.id);
+    if (review === undefined || review.verdict !== 'NEEDS_REWORK') {
+        return `${NOT_ACCEPTED} there is no rejection of ${wp.id} to appeal.`;
+    }
+    const valid = new Set(review.findings.map((f) => f.id));
+    const unknown = sub.appeal.findingIds.filter((id) => !valid.has(id));
+    if (unknown.length > 0) {
+        return (`${NOT_ACCEPTED} unknown finding id(s) ${unknown.join(', ')}. Valid: ` +
+            `${[...valid].join(', ') || '(none)'}.`);
+    }
+    return null;
+}
+export function handleSubmitWork(core, identity, input) {
+    return guarded(TOOL.work, () => {
+        const got = intake(core, identity, 'work', input, normalizeWorkSubmission(input));
+        if (typeof got === 'string')
+            return got;
+        const { value: early, run, wp, stage } = got;
+        const at = core.now();
+        const target = { phase: wp.phase, wpId: wp.id, stage, identity: identity.id };
+        const sub = {
+            kind: 'work',
+            id: artifactIdFor(core, target),
+            identity: identity.id,
+            wpId: wp.id,
+            phase: wp.phase,
+            stage: stage === 'fix' ? 'fix' : 'dev',
+            attempt: nextAttempt(core, target),
+            at,
+            summary: early.summary,
+            filesChanged: early.filesChanged,
+            interfaceContracts: early.interfaceContracts,
+            verification: early.verification,
+            ...(early.appeal ? { appeal: early.appeal } : {}),
+            ...(early.escalate !== undefined ? { escalate: early.escalate } : {}),
+        };
+        const problem = validateAppeal(core, wp, sub);
+        if (problem !== null)
+            return refuse(core, identity, wp.id, problem);
+        const result = settleWork(ctxFor(run, wp, at), sub);
+        persistArtifact(core, target, sub.id, sub, renderWorkMarkdown(sub));
+        wp.submissions[stage].push(sub.id);
+        const booked = applySettlement(core, wp, result, at);
+        if (sub.appeal)
+            wp.appealUsed = true;
+        if (sub.escalate === true)
+            raiseDeveloperClaim(core, run, wp, sub);
+        if (stage === 'dev')
+            wp.status = 'awaiting_review';
+        checkOwnership(core, identity, wp);
+        core.stageResults.push(workResultLine(sub, booked));
+        finish(core, 'work', identity, wp.id);
+        const notes = result.notes.length > 0 ? `\n${result.notes.join('\n')}` : '';
+        return (`OK: work for ${wp.id} ` +
+            `recorded${stage === 'dev' ? '; it now goes to independent review' : ''}. ` +
+            `${remainingText(core, identity, 'work')}${notes}`);
+    });
+}
+function workResultLine(sub, booked) {
+    const what = sub.stage === 'fix' ? 'a fix' : 'work';
+    const files = `${sub.filesChanged.length} file(s)`;
+    const appeal = sub.appeal ? ', with an appeal' : '';
+    const delta = bookedFor(booked, sub.identity);
+    return `${sub.wpId}: ${sub.identity} submitted ${what} (${files})${appeal}${delta ? ` [${delta}]` : ''}`;
+}
+/** `escalate: true` after a lost appeal: the developer asks the inspector to arbitrate (L2). */
+function raiseDeveloperClaim(core, run, wp, sub) {
+    const reviewer = wp.reviewer;
+    if (reviewer === null)
+        return;
+    const id = `cl-${wp.id}-e${sub.attempt}`;
+    if (run.claims.some((c) => c.id === id))
+        return;
+    run.claims.push({
+        id,
+        kind: 'false_positive',
+        raisedBy: sub.identity,
+        against: reviewer,
+        wpId: wp.id,
+        justification: sub.appeal?.argument ?? sub.summary,
+        status: 'open',
+        phase: wp.phase,
+    });
+    core.log('claim', sub.identity, { claimId: id, kind: 'false_positive', wpId: wp.id });
+}
+export function handleSubmitReview(core, identity, input) {
+    return guarded(TOOL.review, () => {
+        const got = intake(core, identity, 'review', input, normalizeReviewSubmission(input));
+        if (typeof got === 'string')
+            return got;
+        const { value: early, run, wp } = got;
+        const at = core.now();
+        const target = {
+            phase: wp.phase,
+            wpId: wp.id,
+            stage: 'review',
+            identity: identity.id,
+        };
+        const sub = {
+            kind: 'review',
+            id: artifactIdFor(core, target),
+            identity: identity.id,
+            wpId: wp.id,
+            phase: wp.phase,
+            attempt: nextAttempt(core, target),
+            at,
+            verdict: early.verdict,
+            checklist: early.checklist,
+            findings: early.findings,
+            fixesApplied: early.fixesApplied,
+            integrationAssessment: early.integrationAssessment,
+            appealResponses: early.appealResponses,
+            requiredChanges: early.requiredChanges,
+            ...(early.excellence ? { excellence: early.excellence } : {}),
+            ...(early.securityFinding ? { securityFinding: early.securityFinding } : {}),
+        };
+        const appeal = pendingAppeal(core, wp.id);
+        const result = settleReview(ctxFor(run, wp, at, appeal?.findingIds), sub);
+        if (!result.ok)
+            return refuse(core, identity, wp.id, result.refusal ?? `${NOT_ACCEPTED} invalid review.`);
+        persistArtifact(core, target, sub.id, sub, renderReviewMarkdown(sub));
+        wp.submissions.review.push(sub.id);
+        const booked = applySettlement(core, wp, result, at);
+        let routed = 'to test';
+        if (result.route?.to === 'dev')
+            routed = openRework(core, run, wp);
+        else
+            wp.status = 'awaiting_test';
+        core.stageResults.push(`${wp.id}: ${identity.id} ${sub.verdict} -> ${routed}${bookedFor(booked, wp.assignee) ? ` (${wp.assignee} ${bookedFor(booked, wp.assignee)})` : ''}`);
+        finish(core, 'review', identity, wp.id);
+        const notes = result.notes.length > 0 ? `\n${result.notes.join('\n')}` : '';
+        return (`OK: review of ${wp.id} recorded (${sub.verdict}). ` +
+            `${remainingText(core, identity, 'review')}${notes}`);
+    });
+}
+export function handleSubmitTest(core, identity, input) {
+    return guarded(TOOL.test, () => {
+        const got = intake(core, identity, 'test', input, normalizeTestSubmission(input));
+        if (typeof got === 'string')
+            return got;
+        const { value: early, run, wp } = got;
+        const at = core.now();
+        const target = {
+            phase: wp.phase,
+            wpId: wp.id,
+            stage: 'test',
+            identity: identity.id,
+        };
+        const sub = {
+            kind: 'test',
+            id: artifactIdFor(core, target),
+            identity: identity.id,
+            wpId: wp.id,
+            phase: wp.phase,
+            attempt: nextAttempt(core, target),
+            at,
+            verdict: early.verdict,
+            traceability: early.traceability,
+            commands: early.commands,
+            issues: early.issues,
+            boundaryTestsWritten: early.boundaryTestsWritten,
+            claims: early.claims,
+            ...(early.skeletonRatio !== undefined ? { skeletonRatio: early.skeletonRatio } : {}),
+            ...(early.skeletonEvidence !== undefined ? { skeletonEvidence: early.skeletonEvidence } : {}),
+        };
+        const result = settleTest(ctxFor(run, wp, at), sub);
+        if (!result.ok)
+            return refuse(core, identity, wp.id, result.refusal ?? `${NOT_ACCEPTED} invalid test report.`);
+        persistArtifact(core, target, sub.id, sub, renderTestMarkdown(sub));
+        wp.submissions.test.push(sub.id);
+        const booked = applySettlement(core, wp, result, at);
+        let routed = 'passed';
+        if (result.route?.to === 'dev')
+            routed = openRework(core, run, wp);
+        else
+            wp.status = 'tested_ok';
+        checkOwnership(core, identity, wp);
+        core.stageResults.push(`${wp.id}: ${identity.id} ${sub.verdict} -> ${routed}${bookedFor(booked, wp.assignee) ? ` (${wp.assignee} ${bookedFor(booked, wp.assignee)})` : ''}`);
+        finish(core, 'test', identity, wp.id);
+        const notes = result.notes.length > 0 ? `\n${result.notes.join('\n')}` : '';
+        return (`OK: test report for ${wp.id} recorded (${sub.verdict}). ` +
+            `${remainingText(core, identity, 'test')}${notes}`);
+    });
+}
+/** For tests and the stage runner: every accepted submission of one WP, any kind. */
+export function acceptedSubmissionIds(core, wpId) {
+    return ['work', 'review', 'test'].flatMap((k) => submissionsOf(core, wpId, k).map((s) => s.id));
+}