@b00dea/cockpit 0.1.0 → 0.1.1

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

@@ -0,0 +1,162 @@
+import { z } from 'zod';
+import { type WorkGate } from '../autonomy.js';
+import type { Decider } from '../schema.js';
+import { type WorkOrder } from './contract.js';
+import type { CheckResult, WorkRecord, WorkStore } from './store.js';
+import type { WorkApplicationComposition } from './composition.js';
+declare const Request: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    operation: z.ZodLiteral<"work-status">;
+    workOrderId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"work-accept">;
+    workOrderId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"work-check">;
+    workOrderId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"work-note">;
+    workOrderId: z.ZodString;
+    text: z.ZodString;
+    kind: z.ZodEnum<{
+        decision: "decision";
+        note: "note";
+        question: "question";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"work-decide">;
+    workOrderId: z.ZodString;
+    decision: z.ZodNumber;
+    resolution: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"record">;
+        path: z.ZodOptional<z.ZodString>;
+        supersedes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"none">;
+        reason: z.ZodString;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"work-answer">;
+    workOrderId: z.ZodString;
+    question: z.ZodNumber;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"work-grade">;
+    workOrderId: z.ZodString;
+    verdict: z.ZodOptional<z.ZodEnum<{
+        met: "met";
+        unmet: "unmet";
+    }>>;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"work-signoff">;
+    workOrderId: z.ZodString;
+    close: z.ZodEnum<{
+        abandoned: "abandoned";
+        done: "done";
+        partial: "partial";
+    }>;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"work-acknowledge">;
+    workOrderId: z.ZodString;
+    note: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"work-recover">;
+    workOrderId: z.ZodString;
+    apply: z.ZodBoolean;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"work-verify">;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"grade-criteria">;
+    criteriaFile: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodEnum<{
+        "browser-drive": "browser-drive";
+        "browser-screenshot": "browser-screenshot";
+    }>;
+    role: z.ZodOptional<z.ZodString>;
+    route: z.ZodOptional<z.ZodString>;
+    failOnFindings: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"test-run">;
+    gate: z.ZodString;
+    mode: z.ZodEnum<{
+        canonical: "canonical";
+        full: "full";
+        staged: "staged";
+    }>;
+    select: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            file: "file";
+            route: "route";
+            spec: "spec";
+            test: "test";
+        }>;
+        value: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>], "operation">;
+export type WorkApplicationRequest = z.infer<typeof Request>;
+export type Operation = WorkApplicationRequest['operation'];
+export declare function captureWorkApplicationRequest(value: unknown): WorkApplicationRequest | undefined;
+interface WorkApplicationContinuation {
+    readonly digest: string;
+    readonly prompt: string;
+    readonly decide: (answer: string) => Promise<WorkApplicationOutcome>;
+}
+export type WorkApplicationOutcome = Readonly<{
+    kind: 'complete';
+    operation: Operation;
+    value: unknown;
+}> | Readonly<{
+    kind: 'human-needed';
+    operation: Operation;
+    continuation: WorkApplicationContinuation;
+}> | Readonly<{
+    kind: 'refusal';
+    operation: Operation | 'invalid';
+    reason: string;
+}> | Readonly<{
+    kind: 'unsatisfied';
+    operation: Operation;
+    value: unknown;
+    reason: string;
+    weakening?: string;
+}>;
+export declare const refusal: (operation: Operation | 'invalid', reason: string) => WorkApplicationOutcome;
+export declare const complete: (operation: Operation, value: unknown) => WorkApplicationOutcome;
+export declare const unsatisfied: (operation: Operation, value: unknown, reason: string, weakening?: string) => WorkApplicationOutcome;
+export declare const now: () => string;
+export declare const TERMINAL: Set<"abandoned" | "accepted" | "checked" | "done" | "graded" | "partial">;
+export type Observed = Readonly<{
+    id: string;
+    order?: WorkOrder;
+    problems: readonly string[];
+    record?: WorkRecord;
+    digest?: string;
+}>;
+export declare function displayState(row: Observed, attemptCap: number): string;
+export declare function openQuestions(record: WorkRecord): readonly number[];
+export type WorkRequest = Exclude<WorkApplicationRequest, {
+    operation: 'test-run' | `browser-${string}`;
+}>;
+export interface WorkContext {
+    readonly composition: WorkApplicationComposition;
+    readonly operation: WorkRequest['operation'];
+    readonly policy: WorkApplicationComposition['policy'];
+    readonly store: WorkStore;
+    readonly observe: (orderId: string) => Promise<Observed>;
+    /** How many accepted orders are not closed. */
+    readonly wip: () => Promise<number>;
+    /** The records under [docs] decisions, read once per command. */
+    readonly decisionRecords: () => Promise<ReadonlyMap<string, string>>;
+    readonly gated: (gate: WorkGate, decider: Decider, lines: readonly string[], verb: string, apply: (by: Decider) => Promise<WorkApplicationOutcome>) => Promise<WorkApplicationOutcome>;
+    /** The order and its record, refused unless it is accepted, open, unchanged and not blocked. */
+    readonly current: (orderId: string) => Promise<Readonly<{
+        row: Observed;
+        record: WorkRecord;
+        order: WorkOrder;
+    }>>;
+    readonly runChecks: (order: Pick<WorkOrder, 'criteria' | 'gates'>) => Promise<readonly CheckResult[]>;
+}
+export declare function workContext(composition: WorkApplicationComposition, operation: WorkRequest['operation']): WorkContext;
+export {};

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

@@ -0,0 +1,137 @@
+// What every work command shares: the request it takes, the outcome it returns, the state it reads an
+// order in, and the steps several commands take (observing an order, passing a gate, running its
+// checks), bound to one composition.
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { decide } from '../autonomy.js';
+import { RefusalError } from '../environment/contract.js';
+import { REPOSITORY_FILE } from '../repository-path.js';
+import { WORK_ORDER_ID, workOrderDigest } from './contract.js';
+const id = z.string().regex(WORK_ORDER_ID);
+const note = z.string().trim().min(1).max(4_096).regex(/^[^\x00-\x08\x0b-\x1f\x7f]*$/);
+const docsReference = z.string().max(1_024).regex(REPOSITORY_FILE);
+const relativeFile = z.string().max(4_096).regex(/^(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$))[A-Za-z0-9._@+\-/]+$/);
+const Request = z.discriminatedUnion('operation', [
+    z.object({ operation: z.literal('work-status'), workOrderId: id.optional() }).strict(),
+    z.object({ operation: z.literal('work-accept'), workOrderId: id }).strict(),
+    z.object({ operation: z.literal('work-check'), workOrderId: id }).strict(),
+    z.object({ operation: z.literal('work-note'), workOrderId: id, text: note, kind: z.enum(['note', 'question', 'decision']) }).strict(),
+    z.object({ operation: z.literal('work-decide'), workOrderId: id, decision: z.number().int().min(1), resolution: z.discriminatedUnion('kind', [
+            z.object({ kind: z.literal('record'), path: docsReference.optional(), supersedes: z.string().regex(/^\d{1,9}$/).optional() }).strict(),
+            z.object({ kind: z.literal('none'), reason: note }).strict(),
+        ]) }).strict(),
+    z.object({ operation: z.literal('work-answer'), workOrderId: id, question: z.number().int().min(1), text: note }).strict(),
+    z.object({ operation: z.literal('work-grade'), workOrderId: id, verdict: z.enum(['met', 'unmet']).optional(), note: note.optional() }).strict(),
+    z.object({ operation: z.literal('work-signoff'), workOrderId: id, close: z.enum(['done', 'partial', 'abandoned']), note: note.optional() }).strict(),
+    z.object({ operation: z.literal('work-acknowledge'), workOrderId: id, note }).strict(),
+    z.object({ operation: z.literal('work-recover'), workOrderId: id, apply: z.boolean() }).strict(),
+    z.object({ operation: z.literal('work-verify') }).strict(),
+    z.object({ operation: z.literal('grade-criteria'), criteriaFile: relativeFile }).strict(),
+    z.object({ operation: z.enum(['browser-drive', 'browser-screenshot']), role: z.string().regex(/^[a-z0-9][a-z0-9_-]{0,63}$/).optional(),
+        route: z.string().regex(/^(?:[a-z0-9][a-z0-9_-]{0,63}|\/(?!\/)[^\s#\x00-\x1f\x7f]{0,511})$/).optional(),
+        failOnFindings: z.boolean().optional() }).strict(),
+    z.object({ operation: z.literal('test-run'), gate: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/), mode: z.enum(['canonical', 'full', 'staged']),
+        select: z.object({ kind: z.enum(['spec', 'file', 'test', 'route']), value: z.string().min(1).refine(value => Buffer.byteLength(value) <= 4_096 && !/[\x00-\x1f\x7f]/.test(value)) }).strict().optional() }).strict(),
+]);
+export function captureWorkApplicationRequest(value) {
+    const parsed = Request.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}
+export const refusal = (operation, reason) => ({ kind: 'refusal', operation, reason });
+export const complete = (operation, value) => ({ kind: 'complete', operation, value });
+export const unsatisfied = (operation, value, reason, weakening) => ({ kind: 'unsatisfied', operation, value, reason, ...weakening ? { weakening } : {} });
+export const now = () => new Date().toISOString();
+// Agent-written text is shown to a person with its control and bidirectional-override characters
+// replaced, so it can neither drive their terminal nor read in an order other than the one recorded.
+const shown = (value) => value.replace(/[\x00-\x09\x0b-\x1f\x7f-\x9f‪-‮⁦-⁩]/g, '�');
+export const TERMINAL = new Set(['done', 'partial', 'abandoned']);
+export function displayState(row, attemptCap) {
+    if (!row.record)
+        return row.order ? 'draft' : 'invalid';
+    if (TERMINAL.has(row.record.state))
+        return row.record.state;
+    if (!row.order || row.digest !== row.record.accepted.digest)
+        return 'stale';
+    if (openQuestions(row.record).length || row.record.attempts >= attemptCap)
+        return 'blocked';
+    return row.record.state;
+}
+export function openQuestions(record) {
+    return record.notes.flatMap((row, index) => row.kind === 'question' && !record.notes.some(answer => answer.answers === index + 1) ? [index + 1] : []);
+}
+export function workContext(composition, operation) {
+    const { policy, store } = composition;
+    const observe = async (orderId) => {
+        const [parsed, record] = await Promise.all([composition.readOrder(orderId), store.read(orderId)]);
+        if (!parsed.ok)
+            return { id: orderId, problems: parsed.problems, ...(record ? { record } : {}) };
+        // A source that cannot be read leaves this order without a digest, and so stale, not the whole listing refused.
+        let sources;
+        try {
+            sources = await composition.sourceDigests(parsed.value);
+        }
+        catch (error) {
+            if (!(error instanceof RefusalError))
+                throw error;
+            return { id: orderId, order: parsed.value, problems: [`a cited source cannot be read: ${error.message}`], ...(record ? { record } : {}) };
+        }
+        const base = record?.accepted.base ?? await composition.heads();
+        return { id: orderId, order: parsed.value, problems: [], ...(record ? { record } : {}), digest: workOrderDigest(parsed.value, sources, base) };
+    };
+    const wip = async () => (await store.list()).filter(record => !TERMINAL.has(record.state)).length;
+    let records;
+    const decisionRecords = () => records ??= composition.decisionRecords();
+    // Who passed a gate: the agent; a person, after typing the digest of exactly what they were shown;
+    // or CI, which locally records the step as awaiting the `work verify` job and passes it there.
+    const gated = async (gate, decider, lines, verb, apply) => {
+        const decision = decide(decider, composition.env);
+        if (decision === 'proceed')
+            return apply(decider === 'ci' ? 'ci' : 'agent');
+        if (decision === 'ci-only')
+            return apply('ci');
+        const digest = createHash('sha256').update(JSON.stringify({ gate, lines })).digest('hex');
+        let used = false;
+        return { kind: 'human-needed', operation, continuation: { digest,
+                prompt: [...lines.map(shown), `[work.gates] ${gate} = person. To ${verb} exactly this, type ${verb} ${digest}`].join('\n'),
+                decide: async (answer) => {
+                    if (used)
+                        return refusal(operation, `this prompt was already answered; rerun work ${operation.slice('work-'.length)}`);
+                    used = true;
+                    return answer.trim() === `${verb} ${digest}` ? apply('person') : refusal(operation, `Nothing was recorded: the person did not type ${verb} ${digest}`);
+                } } };
+    };
+    // Who closes or amends a capped order is whoever [work.gates] says; a sentence naming a person where the policy names the agent is a control that is not there.
+    const attemptCapRemedy = (orderId) => {
+        const by = (gate, verb, command) => policy.gates[gate] === 'person' ? `a person ${verb} it with ${command} --interactive`
+            : `${verb.replace(/s$/, '')} it with ${command}${policy.gates[gate] === 'ci' ? ', which the work verify job confirms in CI' : ''}`;
+        return `${by('signoff', 'closes', `npx --no cockpit work signoff --config <your cockpit.toml> --work-order ${orderId} --partial|--abandon --note <why>`)}, `
+            + `or ${by('amend', 'amends', `an edit to workorders/${orderId}.md and npx --no cockpit work accept --config <your cockpit.toml> --work-order ${orderId}`)}`;
+    };
+    const current = async (orderId) => {
+        const row = await observe(orderId);
+        if (!row.record)
+            throw new RefusalError(`${orderId} is not accepted yet; run npx --no cockpit work accept --config <your cockpit.toml> --work-order ${orderId}`);
+        const state = displayState(row, composition.caps.attempts);
+        if (TERMINAL.has(row.record.state))
+            throw new RefusalError(`${orderId} is closed (${row.record.state})`);
+        if (state === 'stale')
+            throw new RefusalError(`${orderId} changed since it was accepted${row.problems.length ? ` and does not parse: ${row.problems.join('; ')}` : ''}; `
+                + `run npx --no cockpit work accept --config <your cockpit.toml> --work-order ${orderId} to accept the change`);
+        if (state === 'blocked')
+            throw new RefusalError(openQuestions(row.record).length
+                ? `${orderId} has open question ${openQuestions(row.record).join(', ')}; it is answered with work answer`
+                : `${orderId} reached the attempt cap (${composition.caps.attempts}); record the root cause with work note, then ${attemptCapRemedy(orderId)}`);
+        return { row, record: row.record, order: row.order };
+    };
+    const runChecks = async (order) => {
+        const results = [];
+        // Checks share the product's state, so they run in the order the contract lists them.
+        for (const criterion of order.criteria)
+            if (criterion.check)
+                results.push(await composition.runCheck(criterion.id, criterion.check));
+        for (const gate of order.gates)
+            results.push(await composition.runCheck(`gate:${gate}`, { gate }));
+        return results;
+    };
+    return { composition, operation, policy, store, observe, wip, decisionRecords, gated, current, runChecks };
+}

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

@@ -0,0 +1,27 @@
+import type { WorkOrder } from './contract.js';
+import type { WorkRecord } from './store.js';
+import type { WorkApplicationComposition } from './composition.js';
+import { type WorkApplicationOutcome, type WorkContext, type WorkRequest } from './application-context.js';
+export declare const DECISIONS_UNDECLARED: string;
+export declare function decisions(record: WorkRecord): {
+    decision: number;
+    title: string;
+    resolution: {
+        at: string;
+        by: "agent" | "ci" | "person";
+        kind: "answer" | "decision" | "note" | "question" | "resolution";
+        text: string;
+        answers?: number | undefined;
+        resolves?: number | undefined;
+        record?: string | undefined;
+    } | undefined;
+}[];
+export declare function recordProblem(text: string | undefined, reference: string, orderId: string, filled: boolean): string | undefined;
+export declare function unresolvedDecisions(record: WorkRecord, composition: WorkApplicationComposition): Promise<readonly string[]>;
+export declare function relatedDecisions(context: WorkContext, order: WorkOrder): Promise<Readonly<{
+    relatedDecisions?: readonly string[];
+    relatedDecisionsUnavailable?: string;
+}>>;
+export declare function decideOrder(request: Extract<WorkRequest, {
+    operation: 'work-decide';
+}>, context: WorkContext): Promise<WorkApplicationOutcome>;

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

@@ -0,0 +1,121 @@
+// The decisions an order records: which are unresolved, whether a cited record still stands for its
+// decision, the records that bear on an order's scope, and `work decide`, which writes or cites one.
+import { posix } from 'node:path';
+import { RefusalError } from '../environment/contract.js';
+import { recordNumber, withStatus } from '../docs/decision-record.js';
+import { splitRepositoryPath } from '../repository-path.js';
+import { citedOrders, holdsPlaceholders, namesScope, nextRecordName, recordTitle, scaffoldRecord } from './decisions.js';
+import { complete, now, refusal, TERMINAL } from './application-context.js';
+// Decisions recorded on an order, each with its latest resolution.
+export const DECISIONS_UNDECLARED = 'decision records need a directory: declare one in cockpit.toml, for example [docs] decisions = "docs/adr", '
+    + 'with decisions_index = "docs/adr/README.md" if the records have an index';
+export function decisions(record) {
+    return record.notes.flatMap((row, index) => row.kind !== 'decision' ? [] : [{ decision: index + 1, title: recordTitle(row.text),
+            resolution: record.notes.findLast(note => note.kind === 'resolution' && note.resolves === index + 1) }]);
+}
+// Why a cited record no longer stands for its decision; `filled` also requires that the template's placeholders are gone.
+export function recordProblem(text, reference, orderId, filled) {
+    if (text === undefined)
+        return `its record ${reference} does not exist`;
+    if (!citedOrders(text).includes(orderId))
+        return `its record ${reference} does not cite ${orderId}; add the line "Work order: ${orderId}"`;
+    return filled && holdsPlaceholders(text) ? `its record ${reference} still holds the template's placeholders; replace each "<!-- cockpit: replace this ... -->" comment` : undefined;
+}
+export async function unresolvedDecisions(record, composition) {
+    const rows = [];
+    for (const row of decisions(record)) {
+        const name = `decision ${row.decision} (${row.title})`;
+        if (!row.resolution)
+            rows.push(`${name} is unresolved; run npx --no cockpit work decide --config <your cockpit.toml> --work-order ${record.id} --decision ${row.decision} --record, or with --none --reason "<why>"`);
+        else if (row.resolution.record) {
+            const problem = recordProblem(await composition.readDocsFile(row.resolution.record), row.resolution.record, record.id, true);
+            if (problem)
+                rows.push(`${name}: ${problem}`);
+        }
+    }
+    return rows;
+}
+// Decision records whose text names a path the order may change, so earlier decisions about that code are in front of the agent.
+export async function relatedDecisions(context, order) {
+    const { composition } = context;
+    const directory = composition.docs?.decisions;
+    if (!directory)
+        return {};
+    const { slug } = splitRepositoryPath(directory);
+    const prefix = slug === undefined ? '' : `${slug}:`;
+    let read;
+    // The listing is advice, so a directory cockpit cannot read is reported here and refused where a record is written.
+    try {
+        read = await context.decisionRecords();
+    }
+    catch (error) {
+        if (!(error instanceof RefusalError))
+            throw error;
+        return { relatedDecisionsUnavailable: error.message };
+    }
+    return { relatedDecisions: [...read.entries()]
+            .filter(([reference, text]) => reference !== composition.docs?.decisionsIndex && namesScope(text, order.scope, prefix)).map(([reference]) => reference) };
+}
+export async function decideOrder(request, context) {
+    const { composition, operation, store } = context;
+    const directory = composition.docs?.decisions;
+    if (!directory)
+        return refusal(operation, DECISIONS_UNDECLARED);
+    const orderId = request.workOrderId;
+    const record = await store.read(orderId);
+    if (!record || TERMINAL.has(record.state))
+        return refusal(operation, `${orderId} has no open record to resolve a decision on`);
+    const decision = record.notes[request.decision - 1];
+    if (decision?.kind !== 'decision')
+        return refusal(operation, `note ${request.decision} on ${orderId} is not a decision; work status lists each order's open decisions`);
+    const resolve = (fields, writes) => store.update(orderId, async (existing) => {
+        if (!existing || TERMINAL.has(existing.state))
+            throw new RefusalError(`${orderId} closed while its decision was being resolved`);
+        await writes?.();
+        return { record: { ...existing, notes: [...existing.notes, { at: now(), by: 'agent', kind: 'resolution', resolves: request.decision, ...fields }] }, value: undefined };
+    });
+    const resolution = request.resolution;
+    if (resolution.kind === 'none') {
+        await resolve({ text: resolution.reason });
+        return complete(operation, { id: orderId, decision: request.decision, resolution: 'none', reason: resolution.reason });
+    }
+    if (resolution.path !== undefined) {
+        if (!resolution.path.startsWith(`${directory}/`))
+            return refusal(operation, `${resolution.path} is not inside [docs] decisions ${directory}; write the record there`);
+        if (resolution.supersedes)
+            return refusal(operation, '--supersedes applies when cockpit writes the record; with a path, write the Supersedes line and the old record\'s status yourself');
+        const problem = recordProblem(await composition.readDocsFile(resolution.path), resolution.path, orderId, false);
+        if (problem)
+            return refusal(operation, `${resolution.path} cannot resolve decision ${request.decision}: ${problem}`);
+        await resolve({ text: `recorded in ${resolution.path}`, record: resolution.path });
+        return complete(operation, { id: orderId, decision: request.decision, record: resolution.path });
+    }
+    // Scaffold the record; the agent fills in its body, and signoff refuses while the template's placeholders remain.
+    const existing = await context.decisionRecords();
+    const names = [...existing.keys()].map(reference => reference.slice(directory.length + 1));
+    const title = recordTitle(decision.text);
+    const named = nextRecordName(names, title, now().slice(0, 10));
+    const reference = `${directory}/${named.name}`;
+    const writes = [{ reference, create: true, text: '' }];
+    let supersedes;
+    if (resolution.supersedes) {
+        if (!named.number)
+            return refusal(operation, `the records in ${directory} are named by date, so none has a number to supersede`);
+        const old = names.filter(name => Number(recordNumber(name)) === Number(resolution.supersedes));
+        if (old.length !== 1)
+            return refusal(operation, `${directory} has ${old.length ? `${old.length} records` : 'no record'} numbered ${resolution.supersedes}; pass the number of exactly one`);
+        supersedes = recordNumber(old[0]);
+        const marked = withStatus(existing.get(`${directory}/${old[0]}`), `superseded by ${named.number}`);
+        if (marked === undefined)
+            return refusal(operation, `${directory}/${old[0]} has no Status line to mark superseded; add "Status: accepted" to it`);
+        writes.push({ reference: `${directory}/${old[0]}`, create: false, text: marked });
+    }
+    writes[0].text = scaffoldRecord({ title, workOrder: orderId, ...named.number ? { number: named.number } : {}, ...supersedes ? { supersedes } : {} });
+    const index = composition.docs?.decisionsIndex;
+    if (index !== undefined && await composition.readDocsFile(index) === undefined)
+        return refusal(operation, `[docs] decisions_index ${index} does not exist; create it, or remove decisions_index from cockpit.toml`);
+    const link = index === undefined ? undefined : posix.relative(posix.dirname(splitRepositoryPath(index).path), splitRepositoryPath(reference).path);
+    await resolve({ text: `recorded in ${reference}`, record: reference }, () => composition.writeDecisionRecords(writes, link === undefined ? undefined : `- [${named.number ? `${named.number}. ` : ''}${title}](${link})`));
+    return complete(operation, { id: orderId, decision: request.decision, record: reference, written: writes.map(row => row.reference),
+        next: `fill in ${reference}: signoff refuses while its "cockpit: replace this" placeholders remain` });
+}

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

@@ -0,0 +1,11 @@
+import type { WorkApplicationComposition } from './composition.js';
+import { type WorkApplicationOutcome, type WorkApplicationRequest, type WorkContext, type WorkRequest } from './application-context.js';
+export declare function testRun(captured: Extract<WorkApplicationRequest, {
+    operation: 'test-run';
+}>, composition: WorkApplicationComposition): Promise<WorkApplicationOutcome>;
+export declare function gradeOrder(request: Extract<WorkRequest, {
+    operation: 'work-grade';
+}>, context: WorkContext): Promise<WorkApplicationOutcome>;
+export declare function gradeCriteriaFile(request: Extract<WorkRequest, {
+    operation: 'grade-criteria';
+}>, context: WorkContext): Promise<WorkApplicationOutcome>;