@aragon-agent/cli 0.6.43 → 0.6.45

package/dist/governance/tools/submit-normalizers.js

@@ -0,0 +1,474 @@
+/**
+ * Normalizers for `gov_submit_work` / `gov_submit_review` / `gov_submit_test`
+ * (governance-mode 5.9, 7.1, 7.3).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Pure: no I/O, no clock.
+ *
+ * THE OUTPUT IS BUILT FROM KNOWN FIELDS ONLY. Each normalizer copies the keys it knows into
+ * a fresh object, so an `agentId` (or any other key) in the arguments can never reach the
+ * engine: identity is closed over by the tool factory, not argued by the model (5.9).
+ *
+ * EXPORTED FOR THE ENGINE. A submission that arrives by another path (resume, replay, a
+ * future REST surface) is validated by the same functions and gets the same verdict.
+ *
+ * CONTRADICTIONS ARE REJECTED, NOT GUESSED (D-15). A `PASS` verdict next to a blocker
+ * finding, or an `ALL_PASS` next to a `gap` row, is not repairable: either the verdict or
+ * the evidence is wrong and only the author knows which.
+ */
+import { GOV_LIMITS } from '../limits.js';
+import { Issues, SUBMIT_LIMITS as L, isRecord, readBool, readInteger, } from './normalize-util.js';
+const VERDICTS = ['PASS', 'PASS_WITH_FIXES', 'NEEDS_REWORK'];
+const TEST_VERDICTS = [
+    'ALL_PASS',
+    'ISSUES_FOUND',
+    'SPEC_MISMATCH',
+    'INCOMPLETE_IMPL',
+];
+const SEVERITIES = ['blocker', 'major', 'minor', 'nit'];
+const SEVERITY_ALIASES = {
+    critical: 'blocker',
+    high: 'major',
+    medium: 'minor',
+    low: 'nit',
+};
+const CHECK_STATUSES = ['pass', 'fail', 'na'];
+const CHECK_STATUS_ALIASES = {
+    ok: 'pass',
+    passed: 'pass',
+    yes: 'pass',
+    failed: 'fail',
+    no: 'fail',
+    n_a: 'na',
+    not_applicable: 'na',
+};
+const TRACE_STATUSES = ['covered', 'gap', 'unverified'];
+const TRACE_ALIASES = {
+    missing: 'gap',
+    not_verified: 'unverified',
+};
+const CLAIM_KINDS = [
+    'missed_by_review',
+    'security',
+    'false_positive',
+    'same_issue',
+    'incomplete_impl',
+];
+const VERIFIED_VALUES = ['YES', 'NOT_APPLICABLE'];
+const VERIFIED_ALIASES = {
+    true: 'YES',
+    y: 'YES',
+    n_a: 'NOT_APPLICABLE',
+    na: 'NOT_APPLICABLE',
+};
+const DECISIONS = ['uphold', 'withdraw'];
+const DECISION_ALIASES = {
+    upheld: 'uphold',
+    withdrawn: 'withdraw',
+};
+const CHECKLIST_KEYS = ['correctness', 'quality', 'security', 'integration', 'compliance'];
+/** The args object, or `{}` with an error recorded. */
+function argsOf(raw, issues, expected) {
+    if (isRecord(raw))
+        return raw;
+    issues.fail(`the arguments must be an object with ${expected}.`);
+    return {};
+}
+function readInterfaceContracts(raw, issues) {
+    const out = [];
+    issues.items(raw, 'interfaceContracts', L.contractsMax).forEach((item, i) => {
+        const at = `interfaceContracts[${i}]`;
+        if (!isRecord(item)) {
+            issues.fail(`${at} must be {interface, role, verified, method, peer}.`);
+            return;
+        }
+        const verified = issues.oneOf(item.verified, `${at}.verified`, VERIFIED_VALUES, {
+            aliases: VERIFIED_ALIASES,
+            required: true,
+        });
+        const role = issues.oneOf(item.role, `${at}.role`, ['PRODUCER', 'CONSUMER'], {
+            required: true,
+        });
+        out.push({
+            interface: issues.str(item.interface, `${at}.interface`, L.shortChars, true),
+            role: role ?? 'PRODUCER',
+            verified: verified ?? 'NOT_APPLICABLE',
+            method: issues.str(item.method, `${at}.method`, L.evidenceChars, verified === 'YES'),
+            peer: issues.str(item.peer, `${at}.peer`, L.shortChars),
+        });
+    });
+    return out;
+}
+function readVerification(raw, issues) {
+    const source = Array.isArray(raw) ? raw : isRecord(raw) ? raw.commands : undefined;
+    if (raw !== undefined && raw !== null && source === undefined) {
+        issues.fail('verification must be {commands: [{cmd, result, note?}]}.');
+    }
+    const commands = [];
+    issues.items(source, 'verification.commands', L.commandsMax).forEach((item, i) => {
+        const at = `verification.commands[${i}]`;
+        if (!isRecord(item)) {
+            issues.fail(`${at} must be {cmd, result, note?}.`);
+            return;
+        }
+        const note = issues.str(item.note, `${at}.note`, L.resultChars);
+        commands.push({
+            cmd: issues.str(item.cmd, `${at}.cmd`, L.commandChars, true),
+            result: issues.str(item.result, `${at}.result`, L.resultChars, true),
+            ...(note !== '' ? { note } : {}),
+        });
+    });
+    return { commands };
+}
+function readAppeal(raw, issues) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isRecord(raw)) {
+        issues.fail('appeal must be {findingIds: [..], argument}.');
+        return undefined;
+    }
+    const findingIds = issues.list(raw.findingIds, 'appeal.findingIds', L.findingIdsMax, L.idChars);
+    if (findingIds.length === 0)
+        issues.fail('appeal.findingIds must name at least one finding.');
+    const argument = issues.str(raw.argument, 'appeal.argument', L.argumentChars, true);
+    return { findingIds, argument };
+}
+/** Validate and repair a `gov_submit_work` argument object. Pure. */
+export function normalizeWorkSubmission(raw) {
+    const issues = new Issues();
+    const args = argsOf(raw, issues, 'wpId and summary');
+    const wpId = issues.wpId(args.wpId);
+    const summary = issues.str(args.summary, 'summary', L.summaryChars, true);
+    const filesChanged = issues.list(args.filesChanged, 'filesChanged', L.filesMax, L.pathChars);
+    if (filesChanged.length === 0) {
+        issues.note('filesChanged is empty: say in the summary why no file needed to change.');
+    }
+    const appeal = readAppeal(args.appeal, issues);
+    const escalate = readBool(args.escalate);
+    return issues.result({
+        wpId,
+        summary,
+        filesChanged,
+        interfaceContracts: readInterfaceContracts(args.interfaceContracts, issues),
+        verification: readVerification(args.verification, issues),
+        ...(appeal ? { appeal } : {}),
+        ...(escalate !== undefined ? { escalate } : {}),
+    });
+}
+function readChecklistItem(raw, at, issues) {
+    if (!isRecord(raw)) {
+        issues.fail(`${at} must be {status: pass | fail | na, evidence}.`);
+        return { status: 'na', evidence: '' };
+    }
+    const status = issues.oneOf(raw.status, `${at}.status`, CHECK_STATUSES, {
+        aliases: CHECK_STATUS_ALIASES,
+        required: true,
+    }) ?? 'na';
+    const evidence = issues.str(raw.evidence, `${at}.evidence`, L.evidenceChars, status !== 'na');
+    return { status, evidence: status === 'na' && evidence === '' ? 'not applicable' : evidence };
+}
+function readChecklist(raw, issues) {
+    if (!isRecord(raw)) {
+        issues.fail('checklist is required: an object with correctness, quality, security, integration and ' +
+            'compliance, each {status, evidence}.');
+    }
+    const source = isRecord(raw) ? raw : {};
+    const out = {};
+    for (const key of CHECKLIST_KEYS) {
+        out[key] = readChecklistItem(source[key], `checklist.${key}`, issues);
+    }
+    return out;
+}
+function readFindings(raw, issues) {
+    const used = new Set();
+    const out = [];
+    issues.items(raw, 'findings', L.findingsMax).forEach((item, i) => {
+        const at = `findings[${i}]`;
+        if (!isRecord(item)) {
+            issues.fail(`${at} must be {id, severity, file, line?, issue, requiredChange, mustFix?}.`);
+            return;
+        }
+        let id = issues.str(item.id, `${at}.id`, L.idChars);
+        if (id === '' || used.has(id)) {
+            id = `F${i + 1}`;
+            issues.note(`${at} was given the id ${id}.`);
+        }
+        used.add(id);
+        const line = readInteger(item.line);
+        const mustFix = readBool(item.mustFix);
+        const severity = issues.oneOf(item.severity, `${at}.severity`, SEVERITIES, {
+            aliases: SEVERITY_ALIASES,
+            required: true,
+        });
+        out.push({
+            id,
+            severity: severity ?? 'minor',
+            file: issues.str(item.file, `${at}.file`, L.pathChars, true),
+            ...(line !== undefined && line > 0 ? { line } : {}),
+            issue: issues.str(item.issue, `${at}.issue`, L.issueChars, true),
+            requiredChange: issues.str(item.requiredChange, `${at}.requiredChange`, L.issueChars, true),
+            ...(mustFix !== undefined ? { mustFix } : {}),
+        });
+    });
+    return out;
+}
+function readFixes(raw, issues) {
+    const out = [];
+    issues.items(raw, 'fixesApplied', L.fixesMax).forEach((item, i) => {
+        const at = `fixesApplied[${i}]`;
+        if (!isRecord(item)) {
+            issues.fail(`${at} must be {file, rationale}.`);
+            return;
+        }
+        out.push({
+            file: issues.str(item.file, `${at}.file`, L.pathChars, true),
+            rationale: issues.str(item.rationale, `${at}.rationale`, L.rationaleChars, true),
+        });
+    });
+    return out;
+}
+function readAppealResponses(raw, issues) {
+    const out = [];
+    issues.items(raw, 'appealResponses', L.responsesMax).forEach((item, i) => {
+        const at = `appealResponses[${i}]`;
+        if (!isRecord(item)) {
+            issues.fail(`${at} must be {findingId, decision: uphold | withdraw, note?}.`);
+            return;
+        }
+        const note = issues.str(item.note, `${at}.note`, L.rationaleChars);
+        const decision = issues.oneOf(item.decision, `${at}.decision`, DECISIONS, {
+            aliases: DECISION_ALIASES,
+            required: true,
+        });
+        out.push({
+            findingId: issues.str(item.findingId, `${at}.findingId`, L.idChars, true),
+            decision: decision ?? 'uphold',
+            ...(note !== '' ? { note } : {}),
+        });
+    });
+    return out;
+}
+/** `{a, b}` where both are required text, or `undefined` when the field is absent. */
+function readTextPair(raw, label, keys, issues) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isRecord(raw)) {
+        issues.fail(`${label} must be {${keys[0]}, ${keys[1]}}.`);
+        return undefined;
+    }
+    const field = (key) => issues.str(raw[key], `${label}.${key}`, L.evidenceChars, true);
+    return { [keys[0]]: field(keys[0]), [keys[1]]: field(keys[1]) };
+}
+/** The only feedback surface a developer sees (D-7): the findings that are binding. */
+function deriveRequiredChanges(findings) {
+    return findings
+        .filter((f) => f.mustFix === true || f.severity === 'blocker' || f.severity === 'major')
+        .map((f) => ({ file: f.file, issue: f.issue, change: f.requiredChange }));
+}
+/** Self-contradiction rules between the verdict and the rest of the review. */
+function crossCheckReview(value, issues) {
+    const hasBlocker = value.findings.some((f) => f.severity === 'blocker');
+    const hasFailedItem = CHECKLIST_KEYS.some((k) => value.checklist[k].status === 'fail');
+    switch (value.verdict) {
+        case 'PASS':
+            if (value.requiredChanges.length > 0 || hasFailedItem) {
+                issues.fail('verdict PASS contradicts the evidence (a failed checklist item or a blocker, ' +
+                    'major or mustFix finding). Use NEEDS_REWORK, or remove the finding.');
+            }
+            if (value.fixesApplied.length > 0) {
+                issues.fail('fixesApplied is not empty: a review that fixed files is PASS_WITH_FIXES.');
+            }
+            break;
+        case 'PASS_WITH_FIXES':
+            if (value.fixesApplied.length === 0) {
+                issues.fail('PASS_WITH_FIXES needs fixesApplied: one {file, rationale} per fixed file.');
+            }
+            if (hasBlocker) {
+                issues.fail('a blocker finding contradicts PASS_WITH_FIXES. Use NEEDS_REWORK.');
+            }
+            break;
+        case 'NEEDS_REWORK':
+            if (value.requiredChanges.length === 0) {
+                issues.fail('NEEDS_REWORK needs at least one finding with severity blocker or major, or ' +
+                    'mustFix:true, each with a concrete requiredChange.');
+            }
+            break;
+    }
+}
+/** Validate and repair a `gov_submit_review` argument object. Pure. */
+export function normalizeReviewSubmission(raw) {
+    const issues = new Issues();
+    const args = argsOf(raw, issues, 'wpId, verdict and checklist');
+    const wpId = issues.wpId(args.wpId);
+    const verdict = issues.oneOf(args.verdict, 'verdict', VERDICTS, {
+        aliases: { rework: 'NEEDS_REWORK' },
+        required: true,
+    });
+    const findings = readFindings(args.findings, issues);
+    const excellence = readTextPair(args.excellence, 'excellence', ['claim', 'evidence'], issues);
+    const security = readTextPair(args.securityFinding, 'securityFinding', ['description', 'evidence'], issues);
+    const value = {
+        wpId,
+        verdict: verdict ?? 'NEEDS_REWORK',
+        checklist: readChecklist(args.checklist, issues),
+        findings,
+        fixesApplied: readFixes(args.fixesApplied, issues),
+        integrationAssessment: issues.str(args.integrationAssessment, 'integrationAssessment', L.summaryChars, true),
+        appealResponses: readAppealResponses(args.appealResponses, issues),
+        requiredChanges: deriveRequiredChanges(findings),
+        ...(excellence ? { excellence } : {}),
+        ...(security ? { securityFinding: security } : {}),
+    };
+    if (verdict !== undefined)
+        crossCheckReview(value, issues);
+    return issues.result(value);
+}
+function readTraceability(raw, issues) {
+    const out = [];
+    issues.items(raw, 'traceability', L.traceMax).forEach((item, i) => {
+        const at = `traceability[${i}]`;
+        if (!isRecord(item)) {
+            issues.fail(`${at} must be {requirement, evidence, status: covered | gap | unverified}.`);
+            return;
+        }
+        const status = issues.oneOf(item.status, `${at}.status`, TRACE_STATUSES, {
+            aliases: TRACE_ALIASES,
+            required: true,
+        }) ?? 'unverified';
+        out.push({
+            requirement: issues.str(item.requirement, `${at}.requirement`, L.issueChars, true),
+            evidence: issues.str(item.evidence, `${at}.evidence`, L.evidenceChars, status === 'covered'),
+            status,
+        });
+    });
+    return out;
+}
+function readTestCommands(raw, issues) {
+    const out = [];
+    issues.items(raw, 'commands', L.commandsMax).forEach((item, i) => {
+        const at = `commands[${i}]`;
+        if (!isRecord(item)) {
+            issues.fail(`${at} must be {cmd, exit, summary}.`);
+            return;
+        }
+        const exit = readInteger(item.exit);
+        if (exit === undefined)
+            issues.fail(`${at}.exit must be the integer exit code.`);
+        out.push({
+            cmd: issues.str(item.cmd, `${at}.cmd`, L.commandChars, true),
+            exit: exit ?? -1,
+            summary: issues.str(item.summary, `${at}.summary`, L.resultChars),
+        });
+    });
+    return out;
+}
+function readTestIssues(raw, issues) {
+    const out = [];
+    issues.items(raw, 'issues', L.issuesMax).forEach((item, i) => {
+        const at = `issues[${i}]`;
+        if (!isRecord(item)) {
+            issues.fail(`${at} must be {severity, description, missedByReview?, ...}.`);
+            return;
+        }
+        const missed = readBool(item.missedByReview);
+        const justification = issues.str(item.reviewMissJustification, `${at}.reviewMissJustification`, L.rationaleChars, missed === true);
+        const severity = issues.oneOf(item.severity, `${at}.severity`, SEVERITIES, {
+            aliases: SEVERITY_ALIASES,
+            required: true,
+        });
+        out.push({
+            severity: severity ?? 'minor',
+            description: issues.str(item.description, `${at}.description`, L.issueChars, true),
+            ...(missed !== undefined ? { missedByReview: missed } : {}),
+            ...(justification !== '' ? { reviewMissJustification: justification } : {}),
+        });
+    });
+    return out;
+}
+function readClaims(raw, issues) {
+    const out = [];
+    issues.items(raw, 'claims', L.claimsMax).forEach((item, i) => {
+        const at = `claims[${i}]`;
+        if (!isRecord(item)) {
+            issues.fail(`${at} must be {kind, justification, against?}.`);
+            return;
+        }
+        const against = issues.str(item.against, `${at}.against`, L.idChars);
+        const kind = issues.oneOf(item.kind, `${at}.kind`, CLAIM_KINDS, { required: true });
+        out.push({
+            kind: kind ?? 'missed_by_review',
+            justification: issues.str(item.justification, `${at}.justification`, L.argumentChars, true),
+            ...(against !== '' ? { against } : {}),
+        });
+    });
+    return out;
+}
+/** A ratio in [0, 1]; a value in (1, 100] is read as a percentage and rescaled with a note. */
+function readSkeletonRatio(raw, issues) {
+    if (raw === undefined || raw === null || raw === '')
+        return undefined;
+    const n = typeof raw === 'number' ? raw : Number(String(raw).trim().replace(/%$/, ''));
+    if (!Number.isFinite(n) || n < 0 || n > 100) {
+        issues.fail('skeletonRatio must be a number between 0 and 1 (the gov_scan ratio).');
+        return undefined;
+    }
+    if (n > 1) {
+        issues.note(`skeletonRatio ${n} was read as a percentage and stored as ${n / 100}.`);
+        return n / 100;
+    }
+    return n;
+}
+/** Self-contradiction rules between the verdict and the rest of the test report. */
+function crossCheckTest(value, issues) {
+    const hasGap = value.traceability.some((r) => r.status === 'gap');
+    switch (value.verdict) {
+        case 'ALL_PASS':
+            checkAllPass(value, hasGap, issues);
+            break;
+        case 'SPEC_MISMATCH':
+            if (!hasGap) {
+                issues.fail('SPEC_MISMATCH needs a traceability row with status gap naming the need.');
+            }
+            break;
+        case 'ISSUES_FOUND':
+        case 'INCOMPLETE_IMPL':
+            if (value.issues.length === 0) {
+                issues.fail(`${value.verdict} needs at least one entry in issues.`);
+            }
+            break;
+    }
+    if ((value.skeletonRatio ?? 0) > GOV_LIMITS.skeletonRatioThreshold && !value.skeletonEvidence) {
+        issues.fail('skeletonRatio above the threshold needs skeletonEvidence (the gov_scan counts).');
+    }
+}
+function checkAllPass(value, hasGap, issues) {
+    const hasSerious = value.issues.some((x) => x.severity === 'blocker' || x.severity === 'major');
+    if (value.traceability.length === 0) {
+        issues.fail('ALL_PASS needs a traceability row for each requirement you verified.');
+    }
+    if (hasGap || hasSerious) {
+        issues.fail('ALL_PASS contradicts a gap row or a blocker/major issue. Use ISSUES_FOUND.');
+    }
+}
+/** Validate and repair a `gov_submit_test` argument object. Pure. */
+export function normalizeTestSubmission(raw) {
+    const issues = new Issues();
+    const args = argsOf(raw, issues, 'wpId and verdict');
+    const wpId = issues.wpId(args.wpId);
+    const verdict = issues.oneOf(args.verdict, 'verdict', TEST_VERDICTS, { required: true });
+    const skeletonRatio = readSkeletonRatio(args.skeletonRatio, issues);
+    const skeletonEvidence = issues.str(args.skeletonEvidence, 'skeletonEvidence', L.evidenceChars);
+    const value = {
+        wpId,
+        verdict: verdict ?? 'ISSUES_FOUND',
+        traceability: readTraceability(args.traceability, issues),
+        commands: readTestCommands(args.commands, issues),
+        issues: readTestIssues(args.issues, issues),
+        boundaryTestsWritten: readBool(args.boundaryTestsWritten) ?? false,
+        claims: readClaims(args.claims, issues),
+        ...(skeletonRatio !== undefined ? { skeletonRatio } : {}),
+        ...(skeletonEvidence !== '' ? { skeletonEvidence } : {}),
+    };
+    if (verdict !== undefined)
+        crossCheckTest(value, issues);
+    return issues.result(value);
+}

package/dist/governance/tools/submit-tools.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `gov_submit_work` / `gov_submit_review` / `gov_submit_test` (governance-mode 7.1, 7.3).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THE SCHEMAS DECLARE SHAPE, NOT POLICY (the `plan-tools.ts` P0-4 lesson): `type` and a
+ * minimal `required` stay; every bound lives in the `description` and is enforced by the
+ * normalizers in `submit-normalizers.ts`. `required` is kept to the one or two fields without
+ * which nothing can be routed (`wpId`, the verdict); everything else is checked by the
+ * normalizer so that a missing field produces a `NOT ACCEPTED:` text and not an executor
+ * validation ERROR (D-15: a tool-layer mistake is neither an error result nor a penalty).
+ *
+ * IDENTITY IS CLOSED OVER (5.9, 7.1 rule 4). Each factory binds the child's `Identity`; the
+ * model's arguments cannot name a different submitter because the normalizers copy only the
+ * fields they know and the engine call receives the bound identity.
+ */
+import { type AgentTool } from '@aragon-agent/core';
+import type { GovernanceEngineApi, Identity } from '../types.js';
+export * from './normalize-util.js';
+export * from './submit-normalizers.js';
+/** `gov_submit_work`: DEV (and the FIX developer). */
+export declare function makeSubmitWorkTool(engine: GovernanceEngineApi, identity: Identity): AgentTool;
+/** `gov_submit_review`: REV. One call per assigned work package. */
+export declare function makeSubmitReviewTool(engine: GovernanceEngineApi, identity: Identity): AgentTool;
+/** `gov_submit_test`: TEST. One call per assigned work package. */
+export declare function makeSubmitTestTool(engine: GovernanceEngineApi, identity: Identity): AgentTool;

package/dist/governance/tools/submit-tools.js

@@ -0,0 +1,171 @@
+/**
+ * `gov_submit_work` / `gov_submit_review` / `gov_submit_test` (governance-mode 7.1, 7.3).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THE SCHEMAS DECLARE SHAPE, NOT POLICY (the `plan-tools.ts` P0-4 lesson): `type` and a
+ * minimal `required` stay; every bound lives in the `description` and is enforced by the
+ * normalizers in `submit-normalizers.ts`. `required` is kept to the one or two fields without
+ * which nothing can be routed (`wpId`, the verdict); everything else is checked by the
+ * normalizer so that a missing field produces a `NOT ACCEPTED:` text and not an executor
+ * validation ERROR (D-15: a tool-layer mistake is neither an error result nor a penalty).
+ *
+ * IDENTITY IS CLOSED OVER (5.9, 7.1 rule 4). Each factory binds the child's `Identity`; the
+ * model's arguments cannot name a different submitter because the normalizers copy only the
+ * fields they know and the engine call receives the bound identity.
+ */
+import { textResult } from '@aragon-agent/core';
+import { formatNotAccepted, withNotes } from './normalize-util.js';
+import { normalizeReviewSubmission, normalizeTestSubmission, normalizeWorkSubmission, } from './submit-normalizers.js';
+export * from './normalize-util.js';
+export * from './submit-normalizers.js';
+const TEXT = { type: 'string' };
+const TEXT_LIST = { type: 'array', items: TEXT };
+function textWith(description) {
+    return { type: 'string', description };
+}
+function objectOf(properties, description) {
+    return { type: 'object', properties, ...(description ? { description } : {}) };
+}
+function listOf(items, description) {
+    return { type: 'array', items, ...(description ? { description } : {}) };
+}
+const WORK_DESCRIPTION = 'Submit your finished work for ONE work package (call once per work package). Give wpId, ' +
+    'a summary, filesChanged, interfaceContracts (every interface you produce or consume, with ' +
+    'how you verified it) and the verification commands you ran with their results. To ' +
+    'dispute a rejection use appeal {findingIds, argument} instead of reworking (once per ' +
+    'work package); escalate:true takes a lost appeal to the Inspector. Over-long fields are ' +
+    'truncated. A NOT ACCEPTED answer lists what to fix and costs nothing.';
+const REVIEW_DESCRIPTION = 'Submit your review of ONE work package (call once per work package). verdict: PASS, ' +
+    'PASS_WITH_FIXES (needs fixesApplied) or NEEDS_REWORK (needs a blocker or major finding, ' +
+    'or mustFix:true). checklist covers correctness, quality, security, integration and ' +
+    'compliance, each {status: pass | fail | na, evidence}. Each finding needs id, severity ' +
+    '(blocker | major | minor | nit), file, issue and a concrete requiredChange; the binding ' +
+    'ones are sent to the developer as the required changes. integrationAssessment must cite ' +
+    'contract names or signatures. A NOT ACCEPTED answer lists what to fix and costs nothing.';
+const TEST_DESCRIPTION = 'Submit your test report for ONE work package (call once per work package). verdict: ' +
+    'ALL_PASS, ISSUES_FOUND, SPEC_MISMATCH (needs a gap row in traceability) or ' +
+    'INCOMPLETE_IMPL. traceability has one {requirement, evidence, status: covered | gap | ' +
+    'unverified} row per requirement; commands lists what you ran as {cmd, exit, summary}; ' +
+    'boundaryTestsWritten says whether you wrote cross-module tests. For stubs report ' +
+    'skeletonRatio and skeletonEvidence from gov_scan. claims {kind, justification, against?} ' +
+    'raises a claim the Inspector will rule on. A NOT ACCEPTED answer lists what to fix and ' +
+    'costs nothing.';
+/** Run a normalizer, then forward the value to the engine exactly once on success. */
+function runSubmission(toolName, normalized, forward) {
+    if (!normalized.ok)
+        return textResult(formatNotAccepted(toolName, normalized.errors));
+    return textResult(withNotes(forward(normalized.value), normalized.notes));
+}
+/** `gov_submit_work`: DEV (and the FIX developer). */
+export function makeSubmitWorkTool(engine, identity) {
+    const contractItem = objectOf({
+        interface: TEXT,
+        role: textWith('PRODUCER | CONSUMER'),
+        verified: textWith('YES | NOT_APPLICABLE'),
+        method: textWith('How you verified it.'),
+        peer: textWith('The other side (work package or file).'),
+    });
+    return {
+        name: 'gov_submit_work',
+        label: 'Submit work',
+        description: WORK_DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                wpId: textWith('The work package this submission is for.'),
+                summary: textWith('What you built and how it meets the acceptance criteria.'),
+                filesChanged: { ...TEXT_LIST, description: 'Every file you created or changed.' },
+                interfaceContracts: listOf(contractItem, 'One entry per interface produced or consumed.'),
+                verification: objectOf({
+                    commands: listOf(objectOf({ cmd: TEXT, result: TEXT, note: TEXT })),
+                }),
+                appeal: objectOf({ findingIds: TEXT_LIST, argument: TEXT }, 'Dispute a rejection instead of reworking (once per work package).'),
+                escalate: { type: 'boolean', description: 'Take a lost appeal to the Inspector.' },
+            },
+            required: ['wpId', 'summary'],
+        },
+        async execute(_id, params) {
+            return runSubmission('gov_submit_work', normalizeWorkSubmission(params), (value) => engine.submitWork(identity, value));
+        },
+    };
+}
+/** `gov_submit_review`: REV. One call per assigned work package. */
+export function makeSubmitReviewTool(engine, identity) {
+    const checkItem = objectOf({ status: textWith('pass | fail | na'), evidence: TEXT });
+    const finding = objectOf({
+        id: TEXT,
+        severity: textWith('blocker | major | minor | nit'),
+        file: TEXT,
+        line: { type: 'number' },
+        issue: TEXT,
+        requiredChange: TEXT,
+        mustFix: { type: 'boolean' },
+    });
+    return {
+        name: 'gov_submit_review',
+        label: 'Submit review',
+        description: REVIEW_DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                wpId: textWith('The work package this review is for.'),
+                verdict: textWith('PASS | PASS_WITH_FIXES | NEEDS_REWORK'),
+                checklist: objectOf({
+                    correctness: checkItem,
+                    quality: checkItem,
+                    security: checkItem,
+                    integration: checkItem,
+                    compliance: checkItem,
+                }),
+                findings: listOf(finding),
+                fixesApplied: listOf(objectOf({ file: TEXT, rationale: TEXT })),
+                integrationAssessment: TEXT,
+                appealResponses: listOf(objectOf({ findingId: TEXT, decision: textWith('uphold | withdraw'), note: TEXT })),
+                excellence: objectOf({ claim: TEXT, evidence: TEXT }, 'Optional: proactive excellence you observed.'),
+                securityFinding: objectOf({ description: TEXT, evidence: TEXT }, 'Optional: a security flaw, with evidence.'),
+            },
+            required: ['wpId', 'verdict'],
+        },
+        async execute(_id, params) {
+            return runSubmission('gov_submit_review', normalizeReviewSubmission(params), (value) => engine.submitReview(identity, value));
+        },
+    };
+}
+/** `gov_submit_test`: TEST. One call per assigned work package. */
+export function makeSubmitTestTool(engine, identity) {
+    const trace = objectOf({
+        requirement: TEXT,
+        evidence: TEXT,
+        status: textWith('covered | gap | unverified'),
+    });
+    const issue = objectOf({
+        severity: textWith('blocker | major | minor | nit'),
+        description: TEXT,
+        missedByReview: { type: 'boolean' },
+        reviewMissJustification: TEXT,
+    });
+    return {
+        name: 'gov_submit_test',
+        label: 'Submit test report',
+        description: TEST_DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                wpId: textWith('The work package this report is for.'),
+                verdict: textWith('ALL_PASS | ISSUES_FOUND | SPEC_MISMATCH | INCOMPLETE_IMPL'),
+                traceability: listOf(trace),
+                commands: listOf(objectOf({ cmd: TEXT, exit: { type: 'number' }, summary: TEXT })),
+                issues: listOf(issue),
+                boundaryTestsWritten: { type: 'boolean' },
+                skeletonRatio: { type: 'number', description: 'From gov_scan (0 to 1).' },
+                skeletonEvidence: TEXT,
+                claims: listOf(objectOf({ kind: TEXT, justification: TEXT, against: TEXT })),
+            },
+            required: ['wpId', 'verdict'],
+        },
+        async execute(_id, params) {
+            return runSubmission('gov_submit_test', normalizeTestSubmission(params), (value) => engine.submitTest(identity, value));
+        },
+    };
+}