@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/work-orders/application-grading.js

@@ -0,0 +1,212 @@
+// Grading: the standing criteria cockpit adds to every grade, the test protection a grade and a test
+// run apply, `work grade` against an order's accepted contract and `grade --criteria` with no order.
+import { posix } from 'node:path';
+import { RefusalError } from '../environment/contract.js';
+import { runGate } from '../testing/gates.js';
+import { describeWeakening, testWeakeningDigest } from '../testing/weakening.js';
+import { scopeMatcher } from './contract.js';
+import { complete, now, refusal, TERMINAL, unsatisfied } from './application-context.js';
+import { decisions } from './application-decisions.js';
+// A list in a criterion's text stays readable; the full list is in the grade's result beside it.
+const listed = (rows, separator, limit = 3_000) => {
+    const text = rows.join(separator);
+    return text.length <= limit ? text : `${text.slice(0, limit)} (cut; ${rows.length} in all)`;
+};
+const weakeningPath = (row) => row.repository === '.' ? row.path : `${row.repository}:${row.path}`;
+// The agent's contract amendments since a person or CI last accepted it, each still to be judged by the next grade.
+function amendmentsToReview(record) {
+    const reviewed = record.amendments.findLastIndex(row => row.by !== 'agent');
+    return record.amendments.slice(reviewed + 1).flatMap(row => row.review);
+}
+// The paths a self-reported note does not name, alone or by a directory above them.
+const unaddressed = (note, paths) => paths.filter(path => {
+    const parts = path.split('/');
+    return !parts.some((_, index) => note.includes(index === parts.length - 1 ? path : `${parts.slice(0, index + 1).join('/')}/`));
+});
+const ACKNOWLEDGE = 'npx --no cockpit work acknowledge --config <your cockpit.toml> --work-order <id> --note <why this is not a weakening>';
+// Tests weakened since the base, judged by rule where no model reads the change. An acknowledgement
+// covers exactly the findings it was recorded for, so any further weakening fails again.
+function protection(weak, record, gate) {
+    const rows = weak.findings.map(describeWeakening);
+    const digest = testWeakeningDigest(weak.findings);
+    const acknowledged = weak.findings.length ? record?.acknowledgements.find(row => row.digest === digest) : undefined;
+    const how = !record ? 'a work order lets it be acknowledged; there is none for this grade'
+        : gate === 'person' ? `a person records it with ${ACKNOWLEDGE} --interactive` : gate === 'ci' ? `acknowledge it with ${ACKNOWLEDGE}, which the work verify job confirms in CI`
+            : `acknowledge it with ${ACKNOWLEDGE}`;
+    const verdict = !weak.findings.length ? undefined
+        : acknowledged ? { verdict: 'met', note: `weakening acknowledged by ${acknowledged.by}: ${acknowledged.note}`.slice(0, 4_000) }
+            : { verdict: 'unmet', note: `tests were weakened since the base (${rows.join('; ')}; test files from ${weak.patterns.source}); revert it, or ${how}`.slice(0, 4_000) };
+    return { verdict, value: { testFiles: weak.patterns.source, findings: rows, ...acknowledged ? { acknowledgedBy: acknowledged.by } : {} } };
+}
+const TESTS_JUSTIFIED = 'test-changes-justified';
+const AMENDMENTS_HOLD = 'amendments-hold-bar';
+const STANDING = [
+    { id: 'decisions-recorded', text: ({ docs, record }) => {
+            if (!docs?.decisions || !record)
+                return undefined;
+            const recorded = decisions(record).map(row => `${row.decision} (${row.title})${row.resolution?.record ? ` in ${row.resolution.record}` : ''}`).join('; ');
+            return ('Every lasting decision this change makes (a choice a later change must know about, such as a format, a boundary, '
+                + `a dependency or a rejected option) is recorded on the work order or in a decision record under ${docs.decisions}. Recorded on this order: ${recorded || 'none'}.`).slice(0, 2_000);
+        } },
+    { id: 'docs-updated', text: ({ docs }) => docs ? 'Documentation that describes behaviour this change alters is updated in the change, or no documentation describes it.' : undefined },
+    // Which paths changed outside scope is a git fact; whether each change was needed is a judgement.
+    { id: 'scope-changes-necessary', text: ({ outOfScope }) => outOfScope.length ? 'Each change outside the scope is necessary to the objective and harmless, such as a lockfile, a regenerated '
+            + 'reference or a changeset the in-scope change requires; any other is scope creep and fails this. The note names each path and says why. '
+            + `Changed outside scope: ${listed(outOfScope, ', ')}.` : undefined },
+    // The detector names candidates; whether each change keeps the tests' force is a judgement.
+    { id: TESTS_JUSTIFIED, weakening: true, text: ({ weak, record }) => {
+            if (!weak.findings.length)
+                return undefined;
+            const acknowledged = record?.acknowledgements.map(row => `${row.by}: ${row.note}`) ?? [];
+            return 'Each test change flagged below keeps the tests\' force: a removed or loosened test is replaced by one at least '
+                + 'as strict, or tested behaviour the change itself removes. A test weakened to make the change pass fails this. The note names each file and says why. '
+                + `Flagged (test files from ${weak.patterns.source}): ${listed(weak.findings.map(describeWeakening), '; ')}. `
+                + `Acknowledgements recorded on the order: ${acknowledged.length ? listed(acknowledged, '; ', 1_000) : 'none'}.`;
+        }, underChecks: { id: 'test-protection', verdict: ({ weak, record, acknowledge }) => protection(weak, record, acknowledge).verdict } },
+    // An agent may reword its own contract; whether the rewording lowers the bar is a judgement. Under
+    // checks nothing could judge it, so the amend gate passes such an amendment to a person instead.
+    { id: AMENDMENTS_HOLD, text: ({ amendments }) => amendments.length ? 'The amendments an agent made to the accepted contract do not lower the bar the work is held to: each clarifies or '
+            + 'tightens what it replaces, and none excuses work the original asked for. Before and after: '
+            + `${listed(amendments.map(row => `${row.field}: "${row.before}" -> "${row.after}"`), '; ')}.` : undefined,
+        remedy: id => `; the next amendment of ${id} is a person's: revert or rewrite workorders/${id}.md, then a person runs npx --no cockpit work accept --config <your cockpit.toml> --work-order ${id} --interactive` },
+];
+const RESERVED = new Set(STANDING.map(row => row.id));
+const standingCriteria = (input) => STANDING.flatMap(row => {
+    const text = row.text(input);
+    return text === undefined ? [] : [{ id: row.id, text }];
+});
+const standingVerdictsUnderChecks = (input) => STANDING.flatMap(row => {
+    const reached = row.underChecks?.verdict(input);
+    return reached ? [{ id: row.underChecks.id, ...reached }] : [];
+});
+const WEAKENING_IDS = new Set(STANDING.flatMap(row => row.weakening ? [row.id, ...row.underChecks ? [row.underChecks.id] : []] : []));
+const remedyOf = (id, orderId) => STANDING.find(row => row.id === id)?.remedy?.(orderId) ?? '';
+const split = (verdicts) => ({ others: verdicts.filter(row => row.verdict !== 'met' && !WEAKENING_IDS.has(row.id)),
+    weakening: verdicts.filter(row => WEAKENING_IDS.has(row.id) && row.verdict !== 'met').map(row => `${row.id} ${row.verdict}: ${row.note}`).join('; ') || undefined });
+// A test run's result, held to the protection of every open order.
+export async function testRun(captured, composition) {
+    const operation = captured.operation;
+    const prepared = await composition.gate(captured);
+    const run = await runGate(prepared.registry, prepared.request, prepared.dependencies);
+    // A passing run proves nothing if the tests it ran were weakened, so it is checked against the base of each open order.
+    // Under checks grading an unacknowledged finding fails the run; where a model grades, the grade judges it.
+    const open = (await composition.store.list()).filter(row => !TERMINAL.has(row.state));
+    // Orders accepted at the same commits share one observation of what changed since.
+    const observed = new Map();
+    const weakeningSince = (base) => {
+        const key = JSON.stringify(Object.entries(base).sort(([left], [right]) => left < right ? -1 : 1));
+        if (!observed.has(key))
+            observed.set(key, composition.testWeakening(base));
+        return observed.get(key);
+    };
+    const guards = await Promise.all(open.map(async (row) => ({ id: row.id, ...protection(await weakeningSince(row.accepted.base), row, composition.policy.gates.acknowledge) })));
+    const binding = composition.policy.grading === 'checks';
+    const testProtection = guards.length ? { comparedWith: guards.map(row => `${row.id}'s base`), orders: guards.map(row => ({ id: row.id, ...row.value })),
+        ...!binding && guards.some(row => row.value.findings.length) ? { note: `under [work] grading = "${composition.policy.grading}" each order's grade judges these findings as ${TESTS_JUSTIFIED}` } : {} }
+        : { comparedWith: [], note: 'no open work order records a base commit to compare tests with; accept an order before changing tests' };
+    const weakening = binding ? guards.flatMap(row => row.verdict?.verdict === 'unmet' ? [`${row.id}: ${row.verdict.note}`] : []).join(' | ') : '';
+    const failure = run.satisfiesGate ? '' : `${run.verdict}: ${run.reasons.join('; ') || 'declared gate was not satisfied'}`;
+    return !failure && !weakening ? complete(operation, { ...run, testProtection }) : unsatisfied(operation, { ...run, testProtection }, failure, weakening || undefined);
+}
+export async function gradeOrder(request, context) {
+    const { composition, operation, policy, store, current, runChecks } = context;
+    const { order, record } = await current(request.workOrderId);
+    if (policy.grading === 'self' ? !request.verdict || !request.note : request.verdict !== undefined || request.note !== undefined) {
+        return refusal(operation, policy.grading === 'self' ? '[work] grading = "self": pass --verdict met|unmet and --note <what you checked>'
+            : `--verdict and --note apply only under [work] grading = "self"; this cockpit grades with ${policy.grading}`);
+    }
+    let verdicts;
+    let evaluator;
+    const unchecked = order.criteria.filter(criterion => !criterion.check).map(criterion => criterion.id);
+    if (policy.grading === 'checks' && unchecked.length)
+        return refusal(operation, `[work] grading = "checks" closes an order only when cockpit ran a check for every criterion; ${unchecked.join(', ')} declare none`);
+    const judged = policy.grading !== 'checks';
+    const taken = judged ? order.criteria.filter(criterion => RESERVED.has(criterion.id)).map(criterion => criterion.id) : [];
+    if (taken.length)
+        return refusal(operation, `${order.id} names a criterion ${taken.join(', ')}, which cockpit adds to grades itself; rename it in workorders/${order.id}.md`);
+    // Checks bind in every mode, so an agent's own `met` never covers a failed check. Changes are read
+    // after the checks, so files a check writes count too.
+    const checks = await runChecks(order);
+    const { changes, weakening: weak } = await composition.review(record.accepted.base);
+    // The decision records an order is required to write are part of its work wherever scope points.
+    const decisionFiles = [composition.docs?.decisions, composition.docs?.decisionsIndex].filter((path) => path !== undefined);
+    const inScope = scopeMatcher([...order.scope, ...decisionFiles]);
+    const outOfScope = changes.map(change => change.path).filter(path => !inScope(path));
+    const guarded = protection(weak, record, policy.gates.acknowledge);
+    const amendments = judged ? amendmentsToReview(record) : [];
+    const standingInput = { docs: composition.docs, record, outOfScope, weak, amendments, acknowledge: policy.gates.acknowledge };
+    const standing = judged ? standingCriteria(standingInput) : [];
+    if (policy.grading === 'self') {
+        // The agent's verdict covers the standing criteria too, so its note must at least name what they list.
+        const missing = unaddressed(request.note, [...outOfScope, ...weak.findings.map(weakeningPath)]);
+        if (missing.length)
+            return refusal(operation, `[work] grading = "self": --note must name each path changed outside scope and each flagged test file, or a directory above it, `
+                + `and say why its change is needed; it does not name ${listed(missing, ', ', 1_000)}`);
+        verdicts = [...order.criteria, ...standing].map(criterion => ({ id: criterion.id, verdict: request.verdict, note: request.note }));
+    }
+    else if (policy.grading === 'checks') {
+        verdicts = order.criteria.map(criterion => {
+            const result = checks.find(row => row.criterion === criterion.id);
+            return { id: criterion.id, verdict: result.passed ? 'met' : 'unmet', note: `cockpit ran the check: ${result.outcome}` };
+        });
+        // No model reads the change under checks, so weakened tests fail the grade until acknowledged.
+        verdicts = [...verdicts, ...standingVerdictsUnderChecks(standingInput)];
+    }
+    else {
+        // The contract's own change is shown to the evaluator as a changed file, so a verdict on the amendments can quote it.
+        const contract = amendments.length ? [{ path: `workorders/${order.id}.md`, status: 'amended',
+                diff: amendments.map(row => `${row.field}\n- ${row.before}\n+ ${row.after}`).join('\n') }] : [];
+        const graded = await composition.evaluate({ objective: order.objective, criteria: [...order.criteria, ...standing], nonGoals: order.non_goals, scope: order.scope,
+            checks, changes: [...changes, ...contract], outOfScope });
+        if ('refusal' in graded)
+            return refusal(operation, `${graded.refusal.code}: ${graded.refusal.message}; ${graded.refusal.fix}`);
+        verdicts = graded.criteria;
+        evaluator = { tool: graded.evaluator.tool, fallbacks: graded.evaluator.fallbacks.map(row => ({ ...row })) };
+    }
+    // Where a model grades, whether a change outside scope was needed is its standing criterion; under checks nothing can judge it, so any fails.
+    const passed = verdicts.every(row => row.verdict === 'met') && checks.every(row => row.passed) && (judged || outOfScope.length === 0);
+    const grade = { at: now(), digest: record.accepted.digest, mode: policy.grading, passed,
+        criteria: [...verdicts], outOfScope: [...outOfScope], ...evaluator ? { evaluator } : {}, ...request.note ? { note: request.note } : {} };
+    const loweredBar = verdicts.find(row => row.id === AMENDMENTS_HOLD && row.verdict !== 'met');
+    await store.update(order.id, async (existing) => {
+        if (!existing || existing.accepted.digest !== record.accepted.digest)
+            throw new RefusalError(`${order.id} changed while it was graded; rerun work grade`);
+        return { record: { ...existing, state: passed ? 'graded' : 'accepted', attempts: existing.attempts + (passed ? 0 : 1), grade,
+                ...loweredBar ? { amendmentsFailedReview: { at: grade.at, note: loweredBar.note } } : {},
+                ...checks.length ? { checks: { at: now(), digest: record.accepted.digest, results: [...checks] } } : {} }, value: undefined };
+    });
+    const value = { id: order.id, state: passed ? 'graded' : 'accepted', mode: policy.grading, criteria: verdicts, checks, outOfScope, testProtection: guarded.value, ...evaluator ? { evaluator } : {} };
+    if (passed)
+        return complete(operation, value);
+    return unsatisfied(operation, value, [...split(verdicts).others.map(row => `${row.id} ${row.verdict}: ${row.note}${remedyOf(row.id, order.id)}`),
+        ...checks.filter(row => !row.passed).map(row => `check ${row.criterion}: ${row.outcome}`),
+        ...!judged && outOfScope.length ? [`changed outside scope: ${outOfScope.join(', ')}`] : []].join('; '), split(verdicts).weakening);
+}
+// The quick path: an independent grade of uncommitted work with no order and no record.
+export async function gradeCriteriaFile(request, context) {
+    const { composition, operation, policy, runChecks } = context;
+    const parsed = await composition.readCriteriaFile(request.criteriaFile);
+    if (!parsed.ok)
+        return refusal(operation, `${request.criteriaFile} is not a criteria file: ${parsed.problems.join('; ')}`);
+    const file = parsed.value;
+    const taken = file.criteria.filter(criterion => RESERVED.has(criterion.id)).map(criterion => criterion.id);
+    if (taken.length)
+        return refusal(operation, `${request.criteriaFile} names a criterion ${taken.join(', ')}, which cockpit adds to grades itself; rename it`);
+    const checks = await runChecks(file);
+    // The criteria file is the request, not part of the change it grades.
+    // With no order there is no recorded base, so the change since HEAD is compared, and the evaluator judges any test weakening.
+    const review = await composition.review(await composition.heads());
+    const changes = review.changes.filter(change => change.path !== posix.normalize(request.criteriaFile));
+    const inScope = scopeMatcher(file.scope);
+    const outOfScope = file.scope.length ? changes.map(change => change.path).filter(path => !inScope(path)) : [];
+    const weak = review.weakening;
+    const criteria = [...file.criteria, ...standingCriteria({ outOfScope, weak, amendments: [], acknowledge: policy.gates.acknowledge })];
+    const subject = { ...file.objective ? { objective: file.objective } : {}, criteria, nonGoals: [], scope: file.scope, checks, changes, outOfScope };
+    const graded = await composition.evaluate(subject);
+    if ('refusal' in graded)
+        return refusal(operation, `${graded.refusal.code}: ${graded.refusal.message}; ${graded.refusal.fix}`);
+    const passed = graded.criteria.every(row => row.verdict === 'met') && checks.every(row => row.passed);
+    const value = { criteria: graded.criteria, checks, outOfScope, testProtection: { testFiles: weak.patterns.source, findings: weak.findings.map(describeWeakening) }, evaluator: graded.evaluator };
+    return passed ? complete(operation, value) : unsatisfied(operation, value, split(graded.criteria).others.map(row => `${row.id} ${row.verdict}: ${row.note}`)
+        .concat(checks.filter(row => !row.passed).map(row => `check ${row.criterion}: ${row.outcome}`)).join('; '), split(graded.criteria).weakening);
+}

package/dist/work-orders/application.d.ts

@@ -0,0 +1,6 @@
+import { type BrowserCommandResult } from '../browser/commands.js';
+import { type WorkApplicationComposition } from './composition.js';
+import { type WorkApplicationOutcome, type WorkApplicationRequest } from './application-context.js';
+export { captureWorkApplicationRequest, type WorkApplicationOutcome, type WorkApplicationRequest } from './application-context.js';
+export declare function runWorkApplication(request: WorkApplicationRequest, composition: WorkApplicationComposition): Promise<WorkApplicationOutcome>;
+export declare function browserOutcome(operation: 'browser-drive' | 'browser-screenshot', result: BrowserCommandResult, failOnFindings: boolean): WorkApplicationOutcome;

package/dist/work-orders/application.js

@@ -0,0 +1,223 @@
+// Owns the work-order lifecycle: draft → accepted → checked → graded → done, with blocked and stale
+// derived from the record and the current file, and partial and abandoned as closures. Each command
+// that passes a gate asks the autonomy policy who may pass it; a person gate returns a continuation
+// the CLI completes only with the digest a person types in a terminal. It also routes the browser and
+// test-gate operations that share the work composition. Decisions, grading and closure are owned by the
+// application-* modules beside it, on the shared steps application-context.ts binds.
+import { executeBrowserCommand } from '../browser/commands.js';
+import { evaluateUiGate } from '../browser/ui-gate.js';
+import { policyWeakening } from '../autonomy.js';
+import { errorCause, RefusalError } from '../environment/contract.js';
+import { describeWeakening, testWeakeningDigest } from '../testing/weakening.js';
+import { checksBindsField, contractAmendment, workOrderDigest } from './contract.js';
+import { isWorkApplicationComposition } from './composition.js';
+import { captureWorkApplicationRequest, complete, displayState, now, openQuestions, refusal, TERMINAL, unsatisfied, workContext } from './application-context.js';
+import { pendingCi, signoff, verify } from './application-closure.js';
+import { decideOrder, DECISIONS_UNDECLARED, relatedDecisions, unresolvedDecisions } from './application-decisions.js';
+import { gradeCriteriaFile, gradeOrder, testRun } from './application-grading.js';
+export { captureWorkApplicationRequest } from './application-context.js';
+export async function runWorkApplication(request, composition) {
+    const captured = captureWorkApplicationRequest(request);
+    if (!captured)
+        return refusal('invalid', 'Work application requests require a closed selector-only shape');
+    if (!isWorkApplicationComposition(composition))
+        return refusal('invalid', 'An issued work application composition is required');
+    const operation = captured.operation;
+    try {
+        if (captured.operation === 'browser-drive' || captured.operation === 'browser-screenshot') {
+            const kind = captured.operation === 'browser-screenshot' ? 'screenshot' : 'drive';
+            return browserOutcome(captured.operation, await executeBrowserCommand(await composition.browser(kind, captured.role, captured.route)), captured.failOnFindings === true);
+        }
+        if (captured.operation === 'test-run')
+            return await testRun(captured, composition);
+        // A policy weakened in cockpit.toml since the last sync is not in force until a person accepts it there.
+        const recorded = await composition.recordedPolicy();
+        const weakened = recorded ? policyWeakening(recorded, composition.policy) : [];
+        if (weakened.length) {
+            return refusal(operation, `cockpit.toml weakens ${weakened.map(row => `${row.field} from ${row.from} to ${row.to}`).join(', ')} since the last sync; `
+                + 'a person runs npx --no cockpit sync --config <your cockpit.toml> --interactive and accepts the weakening, or the change is reverted');
+        }
+        return await work(captured, composition);
+    }
+    catch (error) {
+        return refusal(operation, errorCause(error));
+    }
+}
+// Findings are evidence for the agent and the grader to weigh, so they fail the command only for a criterion that demands a clean route.
+export function browserOutcome(operation, result, failOnFindings) {
+    if (result.kind === 'refusal')
+        return refusal(operation, result.reason);
+    const gate = evaluateUiGate({ activating: operation === 'browser-screenshot' ? 'screenshot' : 'drive', receipts: [result.receipt] });
+    if (gate.kind === 'refusal')
+        return refusal(operation, gate.reason);
+    if (failOnFindings && result.receipt.verdict === 'findings')
+        return unsatisfied(operation, result, browserFindingsReason(result.receipt));
+    return complete(operation, result);
+}
+function browserFindingsReason(receipt) {
+    return receipt.surfaces.flatMap(row => {
+        const found = row.diagnostics;
+        if (!found || row.verdict !== 'findings')
+            return [];
+        const parts = [[found.consoleErrors, 'console error'], [found.pageErrors, 'uncaught page error'], [found.failedRequests, 'failed request']]
+            .flatMap(([count, noun]) => count ? [`${count} ${noun}${count === 1 ? '' : 's'}`] : []);
+        return [`${row.name}: ${parts.join(', ')}`];
+    }).join('; ');
+}
+async function work(request, composition) {
+    const context = workContext(composition, request.operation);
+    const { operation, policy, store, observe, wip, gated, current, runChecks } = context;
+    if (request.operation === 'work-status') {
+        const ids = request.workOrderId ? [request.workOrderId] : [...new Set([...await composition.orderIds(), ...(await store.list()).map(row => row.id)])].sort();
+        const rows = await Promise.all(ids.map(observe));
+        const closed = new Set(rows.filter(row => row.record?.state === 'done').map(row => row.id));
+        return complete(operation, {
+            grading: policy.grading, gates: policy.gates, wip: { open: await wip(), cap: composition.caps.wip },
+            orders: await Promise.all(rows.map(async (row) => ({
+                id: row.id, state: displayState(row, composition.caps.attempts),
+                ...row.record?.closure ? { closedAs: row.record.closure.how, closedBy: row.record.closure.by } : {},
+                ...row.record ? { attempts: row.record.attempts, acceptedBy: row.record.accepted.by, openQuestions: openQuestions(row.record),
+                    acknowledgements: row.record.acknowledgements.map(({ by, note, findings }) => ({ by, note, findings })),
+                    awaitingCi: pendingCi(row.record), ...row.record.grade ? { grade: { mode: row.record.grade.mode, passed: row.record.grade.passed,
+                            criteria: row.record.grade.criteria, outOfScope: row.record.grade.outOfScope, ...row.record.grade.evaluator ? { evaluator: row.record.grade.evaluator } : {} } } : {} } : {},
+                ...row.order ? { waitingOn: row.order.depends_on.filter(dependency => !closed.has(dependency)) } : {},
+                ...row.record && !TERMINAL.has(row.record.state) ? { openDecisions: await unresolvedDecisions(row.record, composition) } : {},
+                ...row.order && !TERMINAL.has(row.record?.state ?? 'accepted') ? await relatedDecisions(context, row.order) : {},
+                ...row.problems.length ? { problems: row.problems } : {},
+            }))),
+        });
+    }
+    if (request.operation === 'work-accept') {
+        const row = await observe(request.workOrderId);
+        if (!row.order)
+            return refusal(operation, `workorders/${request.workOrderId}.md is not a work order: ${row.problems.join('; ')}`);
+        const order = row.order;
+        const shownOrder = [`Objective: ${order.objective}`, `Scope: ${order.scope.join(', ')}`, ...order.criteria.map(criterion => `${criterion.id}: ${criterion.text}${criterion.check ? ` [check: ${JSON.stringify(criterion.check)}]` : ''}`),
+            ...order.gates.length ? [`Gates: ${order.gates.join(', ')}`] : [], ...order.non_goals.map(goal => `Non-goal: ${goal}`)];
+        if (!row.record) {
+            if (await wip() >= composition.caps.wip)
+                return refusal(operation, `the work-in-progress cap is reached (${composition.caps.wip} accepted orders unfinished); close one with work signoff first`);
+            const sources = await composition.sourceDigests(order);
+            const base = await composition.heads();
+            const digest = workOrderDigest(order, sources, base);
+            return gated('accept', policy.gates.accept, [`Accept ${order.id} (digest ${digest})`, ...shownOrder], 'accept', async (by) => store.update(order.id, async (existing) => {
+                if (existing)
+                    throw new RefusalError(`${order.id} was accepted while this prompt was open; rerun work status`);
+                const record = { format: 'cockpit-work-order/v1', id: order.id, state: 'accepted',
+                    accepted: { at: now(), by, digest, order, sources, base }, amendments: [], acknowledgements: [], attempts: 0, notes: [] };
+                return { record, value: complete(operation, { id: order.id, state: 'accepted', by, digest, ...by === 'ci' ? { awaitingCi: ['accept'] } : {}, ...await relatedDecisions(context, order) }) };
+            }));
+        }
+        const record = row.record;
+        if (TERMINAL.has(record.state))
+            return refusal(operation, `${order.id} is closed (${record.state}); write a new order for further work`);
+        if (row.digest === record.accepted.digest)
+            return refusal(operation, `${order.id} is already accepted and unchanged since`);
+        const { removed: weakened, review } = contractAmendment(record.accepted.order, order);
+        // Removing a criterion or gate lowers the bar in every reading, so an agent never certifies it. A rewrite may
+        // only clarify: where a model grades, the next grade judges it; under checks nothing could, so a person does.
+        // So does the amendment after a grade that found the agent's earlier ones lowered the bar.
+        const unjudgeable = policy.grading === 'checks' ? review.filter(row => checksBindsField(row.field)) : [];
+        const failedReview = record.amendmentsFailedReview;
+        const decider = policy.gates.amend === 'agent' && (weakened.length || unjudgeable.length || failedReview) ? 'person' : policy.gates.amend;
+        const sources = await composition.sourceDigests(order);
+        const digest = workOrderDigest(order, sources, record.accepted.base);
+        return gated('amend', decider, [`Amend ${order.id} (digest ${record.accepted.digest} -> ${digest})`,
+            ...weakened.length ? [`This weakens the accepted contract: ${weakened.join('; ')}`] : [],
+            ...failedReview ? [`A grade found the agent's earlier amendments lower the bar: ${failedReview.note}`] : [],
+            ...review.map(row => `Changed ${row.field}: "${row.before}" -> "${row.after}"`), ...shownOrder], 'amend', async (by) => store.update(order.id, async (existing) => {
+            if (!existing || existing.accepted.digest !== record.accepted.digest)
+                throw new RefusalError(`${order.id} changed while this prompt was open; rerun work accept`);
+            const next = { ...existing, state: 'accepted', attempts: 0, checks: undefined, grade: undefined,
+                ...by === 'agent' ? {} : { amendmentsFailedReview: undefined },
+                accepted: { at: now(), by, digest, order, sources, base: existing.accepted.base },
+                amendments: [...existing.amendments, { at: now(), by, from: existing.accepted.digest, to: digest, weakened: [...weakened], review: [...review] }] };
+            return { record: next, value: complete(operation, { id: order.id, state: 'accepted', by, digest, amended: true, weakened,
+                    ...by === 'agent' && review.length && policy.grading !== 'checks' ? { judgedAtGrade: review.map(row => row.field) } : {}, ...await relatedDecisions(context, order) }) };
+        }));
+    }
+    if (request.operation === 'work-check') {
+        const { order, record } = await current(request.workOrderId);
+        const results = await runChecks(order);
+        if (!results.length)
+            return refusal(operation, `${order.id} declares no check on any criterion and no gates; add a check, or close it under [work] grading = "self"`);
+        const passed = results.every(row => row.passed);
+        await store.update(order.id, async (existing) => {
+            if (!existing || existing.accepted.digest !== record.accepted.digest)
+                throw new RefusalError(`${order.id} changed while its checks ran; rerun work check`);
+            return { record: { ...existing, state: passed ? 'checked' : 'accepted', attempts: existing.attempts + (passed ? 0 : 1), grade: undefined,
+                    checks: { at: now(), digest: record.accepted.digest, results: [...results] } }, value: undefined };
+        });
+        const value = { id: order.id, state: passed ? 'checked' : 'accepted', results };
+        return passed ? complete(operation, value) : unsatisfied(operation, value, `${results.filter(row => !row.passed).map(row => `${row.criterion}: ${row.outcome}`).join('; ')}`);
+    }
+    if (request.operation === 'work-note') {
+        if (request.kind === 'decision' && !composition.docs?.decisions)
+            return refusal(operation, DECISIONS_UNDECLARED);
+        await current(request.workOrderId).catch(async (error) => {
+            // A note on a stale or blocked order is how its cause gets recorded, so only a closed or unaccepted one refuses.
+            const record = await store.read(request.workOrderId);
+            if (!record || TERMINAL.has(record.state))
+                throw error;
+        });
+        const index = await store.update(request.workOrderId, async (existing) => {
+            if (!existing)
+                throw new RefusalError(`${request.workOrderId} is not accepted`);
+            return { record: { ...existing, notes: [...existing.notes, { at: now(), by: 'agent', kind: request.kind, text: request.text }] }, value: existing.notes.length + 1 };
+        });
+        return complete(operation, { id: request.workOrderId, note: index, ...request.kind === 'question' ? { question: index, state: 'blocked' } : {},
+            ...request.kind === 'decision' ? { decision: index, resolveWith: `npx --no cockpit work decide --config <your cockpit.toml> --work-order ${request.workOrderId} --decision ${index} --record` } : {} });
+    }
+    if (request.operation === 'work-decide')
+        return decideOrder(request, context);
+    if (request.operation === 'work-answer') {
+        const record = await store.read(request.workOrderId);
+        if (!record || TERMINAL.has(record.state))
+            return refusal(operation, `${request.workOrderId} has no open record to answer on`);
+        const question = record.notes[request.question - 1];
+        if (!question || question.kind !== 'question' || !openQuestions(record).includes(request.question))
+            return refusal(operation, `note ${request.question} on ${request.workOrderId} is not an open question`);
+        return gated('answer', policy.gates.answer, [`Open question ${request.question} on ${request.workOrderId}:`, `  ${question.text}`, 'Answer to record:', `  ${request.text}`], 'answer', async (by) => store.update(request.workOrderId, async (existing) => {
+            if (!existing || !openQuestions(existing).includes(request.question))
+                throw new RefusalError(`question ${request.question} was answered while this prompt was open`);
+            return { record: { ...existing, notes: [...existing.notes, { at: now(), by, kind: 'answer', text: request.text, answers: request.question }] },
+                value: complete(operation, { id: request.workOrderId, answered: request.question, by }) };
+        }));
+    }
+    if (request.operation === 'work-grade')
+        return gradeOrder(request, context);
+    if (request.operation === 'work-acknowledge') {
+        const { order, record } = await current(request.workOrderId);
+        const weak = await composition.testWeakening(record.accepted.base);
+        if (!weak.findings.length)
+            return refusal(operation, `${order.id} weakens no tests since its base, so there is nothing to acknowledge`);
+        const digest = testWeakeningDigest(weak.findings);
+        if (record.acknowledgements.some(row => row.digest === digest))
+            return refusal(operation, `this weakening of ${order.id} is already acknowledged; run work grade`);
+        const rows = weak.findings.map(describeWeakening);
+        return gated('acknowledge', policy.gates.acknowledge, [`Acknowledge that ${order.id} weakens tests since its base (test files from ${weak.patterns.source}):`,
+            ...rows.map(row => `  ${row}`), 'Reason given:', `  ${request.note}`], 'acknowledge', async (by) => store.update(order.id, async (existing) => {
+            if (!existing || existing.accepted.digest !== record.accepted.digest)
+                throw new RefusalError(`${order.id} changed while this prompt was open; rerun work acknowledge`);
+            if (testWeakeningDigest((await composition.testWeakening(existing.accepted.base)).findings) !== digest) {
+                throw new RefusalError(`the test changes of ${order.id} changed while this prompt was open; rerun work acknowledge`);
+            }
+            return { record: { ...existing, acknowledgements: [...existing.acknowledgements, { at: now(), by, digest, findings: rows, note: request.note }] },
+                value: complete(operation, { id: order.id, acknowledged: rows, by, digest }) };
+        }));
+    }
+    if (request.operation === 'work-signoff')
+        return signoff(request, context);
+    if (request.operation === 'work-recover') {
+        // A pid probe sees only this machine's processes, so the command looks where it cannot first: the
+        // lock's host and the containers cockpit labels. Applied, it removes nothing it has not shown gone.
+        const recovered = await store.recover(request.workOrderId, request.apply, composition.containers);
+        if (!request.apply || recovered.lock === 'none' || recovered.lock === 'removed')
+            return complete(operation, recovered);
+        return refusal(operation, `the lock on ${request.workOrderId} was left in place: its holder ${recovered.lock === 'live' ? 'is still running' : 'cannot be shown gone'} `
+            + `(${recovered.checked?.join('; ')}); wait for it to finish, or stop it on the host that holds it, then rerun work recover --apply`);
+    }
+    if (request.operation === 'work-verify')
+        return verify(context);
+    return gradeCriteriaFile(request, context);
+}

package/dist/work-orders/composition.d.ts

@@ -0,0 +1,101 @@
+import { type EvaluatorTool } from '../schema.js';
+import { type EffectivePolicy } from '../autonomy.js';
+import { type ChangedFile, type GradingSubject, type Verdict } from '../grading/grade.js';
+import { type BrowserCommandInput, type BrowserCommandKind } from '../browser/commands.js';
+import { type RepositoryWeakening, type TestFilePatterns } from '../testing/weakening.js';
+import { type GateDependencies, type GateRegistry, type GateRequest } from '../testing/gates.js';
+import { parseCriteriaFile, type ParsedFile, type WorkOrder, type WorkOrderCheck } from './contract.js';
+import { type CheckResult, type ContainerEvidence, type WorkStore } from './store.js';
+type GradingResult = Readonly<{
+    criteria: readonly Verdict[];
+    evaluator: Readonly<{
+        tool: string;
+        fallbacks: readonly Readonly<{
+            tool: string;
+            code: string;
+            message: string;
+        }>[];
+    }>;
+}> | Readonly<{
+    refusal: Readonly<{
+        code: string;
+        message: string;
+        fix: string;
+    }>;
+}>;
+export interface WorkApplicationComposition {
+    readonly policy: EffectivePolicy;
+    readonly caps: Readonly<{
+        wip: number;
+        attempts: number;
+    }>;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly store: WorkStore;
+    readonly recordedPolicy: () => Promise<EffectivePolicy | undefined>;
+    readonly orderIds: () => Promise<readonly string[]>;
+    readonly readOrder: (id: string) => Promise<ParsedFile<WorkOrder>>;
+    readonly readCriteriaFile: (path: string) => Promise<ReturnType<typeof parseCriteriaFile>>;
+    readonly sourceDigests: (order: Pick<WorkOrder, 'criteria'>) => Promise<Readonly<Record<string, string>>>;
+    readonly heads: () => Promise<Readonly<Record<string, string>>>;
+    readonly runCheck: (criterion: string, check: WorkOrderCheck) => Promise<CheckResult>;
+    readonly evaluate: (subject: GradingSubject) => Promise<GradingResult>;
+    /** Test weakening in each checkout since `base`, over the files this cockpit treats as tests. */
+    readonly testWeakening: (base: Readonly<Record<string, string>>) => Promise<TestWeakeningObservation>;
+    /** What changed in each checkout since `base` (committed, staged, unstaged and untracked, each with its diff), and its test weakening, from one listing of untracked files. */
+    readonly review: (base: Readonly<Record<string, string>>) => Promise<Readonly<{
+        changes: readonly ChangedFile[];
+        weakening: TestWeakeningObservation;
+    }>>;
+    readonly browser: (kind: BrowserCommandKind, role?: string, route?: string) => Promise<BrowserCommandInput>;
+    /** The [docs] table as declared; absent when the cockpit declares none. */
+    readonly docs?: Readonly<{
+        decisions?: string;
+        decisionsIndex?: string;
+    }>;
+    /** Each Markdown file in [docs] decisions, by reference, with its text; empty when the directory does not exist yet. */
+    readonly decisionRecords: () => Promise<ReadonlyMap<string, string>>;
+    /** A decision record's or the index's text, or undefined when the file does not exist. */
+    readonly readDocsFile: (reference: string) => Promise<string | undefined>;
+    /** Writes each record, a new one exclusively and an existing one replaced, then appends `indexLine` to [docs] decisions_index. */
+    readonly writeDecisionRecords: (writes: readonly Readonly<{
+        reference: string;
+        text: string;
+        create: boolean;
+    }>[], indexLine?: string) => Promise<void>;
+    readonly gate: (request: WorkApplicationGateRequest) => Promise<Readonly<{
+        registry: GateRegistry;
+        request: GateRequest;
+        dependencies: GateDependencies;
+    }>>;
+    /** The containers cockpit labels on this machine's local Docker daemon, where a lock's holder may run unseen by a pid probe. */
+    readonly containers: () => Promise<ContainerEvidence>;
+}
+type TestWeakeningObservation = Readonly<{
+    patterns: TestFilePatterns;
+    findings: readonly RepositoryWeakening[];
+}>;
+interface WorkApplicationGateRequest {
+    readonly operation: 'test-run';
+    readonly gate: string;
+    readonly mode: 'canonical' | 'full' | 'staged';
+    readonly select?: Readonly<{
+        kind: 'spec' | 'file' | 'test' | 'route';
+        value: string;
+    }>;
+}
+export declare function isWorkApplicationComposition(value: unknown): value is WorkApplicationComposition;
+type ConfiguredWorkApplicationCompositionResult = Readonly<{
+    kind: 'complete';
+    composition: WorkApplicationComposition;
+}> | Readonly<{
+    kind: 'refusal';
+    reason: string;
+}>;
+export declare function createConfiguredWorkApplicationComposition(input: Readonly<{
+    configPath: string;
+    env: Readonly<Record<string, string | undefined>>;
+}>, options?: Readonly<{
+    /** Grade with only this tool, with no fallback: the person named the grader for this run. */
+    evaluator?: EvaluatorTool;
+}>): Promise<ConfiguredWorkApplicationCompositionResult>;
+export {};