@event4u/agent-config 9.31.0 → 9.33.0

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "9.31.0",
+    "version": "9.33.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including \"zero runtime daemon\".",
     "license": "MIT",
     "private": false,

package/src/agent-src/scripts/roadmap_gates.ts

@@ -18,10 +18,34 @@
  * Blocking a pipeline on "the user has an open decision" would turn a
  * visibility aid into a second thing to fight.
  *
+ * `--reply` is the same projection shaped for the END OF A CHAT REPLY rather
+ * than a terminal pane, and it exists because the pull channel above is only
+ * read by someone who already knows to ask. Transcript forensics over three
+ * consumer sessions found five "what do I do now?" follow-ups, every one of
+ * them next to a blocker the agent HAD reported — as a file reference, as a
+ * bare option count, or as a choice of substitute work. What the same corpus
+ * also shows is that a tool's output gets carried into the reply verbatim
+ * (the dashboard's step count appears word-for-word inside eight option
+ * blocks). So the fix is not to make the agent format better from memory; it
+ * is to hand it the finished text. See ADR-222.
+ *
+ * Two properties carry the contract mechanically:
+ *   - Nothing owned by the user open ⇒ EMPTY output. "No blocker → no block"
+ *     stops being a judgement call, so the command is safe to call
+ *     unconditionally at reply-close.
+ *   - Exactly ONE blocker is rendered in full — the one that unblocks most.
+ *     Every other one is a single trailing line. The user is never handed a
+ *     flat list to weigh themselves.
+ *
+ * Labels are English like the rest of the CLI surface; the agent mirrors them
+ * into the user's language when it lifts them into a reply, exactly as it does
+ * for `Recommendation:` / `Empfehlung:`.
+ *
  * Invocation (from project root):
  *   ./agent-config gates            # decisions owned by the user
  *   ./agent-config gates --all      # every open blocker, grouped by owner
  *   ./agent-config gates --json     # machine-readable
+ *   ./agent-config gates --reply    # reply-close form; empty when none
  */
 
 import * as path from 'node:path';
@@ -209,6 +233,76 @@ function render(entries: readonly Entry[], all: boolean): string {
     return lines.join('\n') + '\n';
 }
 
+/**
+ * Reply-close form: the one blocking decision in full, the rest as one line.
+ *
+ * Deliberately narrower than `render()`. `Status` and `Owner` are roadmap-file
+ * metadata that a reader of a reply cannot act on, so they are dropped; what
+ * survives is what the user has to DO and how they will know it is done. The
+ * five-field shape stays where it is enforced — in the roadmap file — and does
+ * not follow the blocker into prose it would only pad.
+ *
+ * Returns '' when nothing is owned by the user, so the caller can append the
+ * result unconditionally and get silence when silence is correct.
+ */
+function renderReply(entries: readonly Entry[]): string {
+    const mine = entries.filter((e) => needsUser(e.blocker.owner));
+    if (mine.length === 0) {
+        return '';
+    }
+
+    // `collectEntries` already sorted by unblocking weight, so the first entry
+    // IS the one that matters most. Picking it here rather than asking the
+    // caller to choose is the point: a flat list is the failure mode.
+    const lead = mine[0] as Entry;
+    const rest = mine.slice(1);
+    const lines: string[] = [];
+
+    lines.push(`Blocked: ${lead.blocker.blocks} — ${lead.roadmapRel}`);
+
+    const steps = regroupTodo(lead.blocker.todo);
+    const doLabel = isLegacy(lead.blocker) ? 'Blocked until:' : 'Do:';
+    if (steps.length === 0) {
+        lines.push(
+            `${doLabel} (no steps recorded — the blocker entry needs a **What to do:** list)`,
+        );
+    } else if (steps.length === 1) {
+        lines.push(...wrap(`${doLabel} ${steps[0] as string}`, WIDTH, '    '));
+    } else {
+        // Emitted as authored, never re-numbered: real blocker entries already
+        // carry their own `1.` / `2.` markers (the CI-enforced `What to do:`
+        // shape), so adding our own would produce "1. 1. …". An entry that
+        // arrives unnumbered stays unnumbered — that is a fact about the
+        // roadmap entry, and papering over it here would hide it from the
+        // person who could fix it.
+        lines.push(`${doLabel}`);
+        for (const s of steps) {
+            lines.push(...wrap(`  ${s}`, WIDTH, '     '));
+        }
+    }
+    lines.push(...wrap(`Done when: ${lead.blocker.resolvedWhen}`, WIDTH, '    '));
+
+    if (rest.length > 0) {
+        // A count, not a roster. Naming all of them reproduces the exact
+        // failure this form exists to end — "zwölf Entscheidungen bei Dir …
+        // rund 850 Zeilen", which the transcript shows produced no decision at
+        // all. The one that blocks is written out above; the rest are one
+        // command away, and saying so is shorter than listing them and more
+        // honest than hiding them.
+        lines.push('');
+        lines.push(
+            ...wrap(
+                `${rest.length} other decision${rest.length !== 1 ? 's' : ''} also wait${rest.length === 1 ? 's' : ''} on you, ` +
+                    'none blocking this — `agent-config gates`.',
+                WIDTH,
+                '    ',
+            ),
+        );
+    }
+
+    return lines.join('\n') + '\n';
+}
+
 function renderJson(entries: readonly Entry[], all: boolean): string {
     const pick = all ? entries : entries.filter((e) => needsUser(e.blocker.owner));
     return (
@@ -270,18 +364,28 @@ function main(argv?: readonly string[]): number {
     const args = argv ?? process.argv.slice(2);
     const all = args.includes('--all');
     const json = args.includes('--json');
+    const reply = args.includes('--reply');
 
     const repoRoot = _resolveRepoRoot(process.cwd());
     const roadmapRoot = path.join(repoRoot, 'agents', 'roadmaps');
     if (!_isDir(roadmapRoot)) {
+        // `--reply` stays silent here too: a project without roadmaps has no
+        // blocker to hand over, and a reply-close line saying so would be the
+        // ceremony the form exists to avoid.
         process.stdout.write(
-            json ? '{"needsYou":0,"other":0,"blockers":[]}\n' : 'No roadmaps directory — nothing to report.\n',
+            reply
+                ? ''
+                : json
+                  ? '{"needsYou":0,"other":0,"blockers":[]}\n'
+                  : 'No roadmaps directory — nothing to report.\n',
         );
         return 0;
     }
 
     const entries = collectEntries(roadmapRoot);
-    process.stdout.write(json ? renderJson(entries, all) : render(entries, all));
+    process.stdout.write(
+        reply ? renderReply(entries) : json ? renderJson(entries, all) : render(entries, all),
+    );
     return 0;
 }
 
@@ -308,5 +412,5 @@ if (_isCliEntry()) {
     process.exitCode = main();
 }
 
-export { main, needsUser, regroupTodo, wrap, collectEntries, render, renderJson };
+export { main, needsUser, regroupTodo, wrap, collectEntries, render, renderJson, renderReply };
 export type { Entry };

package/src/agent-src/templates/scripts/ownership-map.example.yml

@@ -3,7 +3,7 @@
 # Copy this file to `.github/ownership-map.yml` (preferred) or
 # `agents/ownership-map.yml` and adapt the entries to your stack.
 # Omitting the file entirely is fine — routing falls back to the
-# generic role vocabulary from `reviewer-awareness`.
+# common role vocabulary in `skill:review-routing`.
 #
 # First match wins per file. List narrower globs before broader ones.
 

package/src/agent-src/templates/scripts/work_engine/delivery_state.ts

@@ -96,6 +96,7 @@ export class DeliveryState {
     contract: Record<string, Any> | null;
     stitch: Record<string, Any> | null;
     stack: Record<string, Any> | null;
+    self_fix: Record<string, Any> | null;
 
     constructor(args: {
         ticket: Record<string, Any>;
@@ -117,6 +118,7 @@ export class DeliveryState {
         contract?: Record<string, Any> | null;
         stitch?: Record<string, Any> | null;
         stack?: Record<string, Any> | null;
+        self_fix?: Record<string, Any> | null;
     }) {
         this.ticket = args.ticket;
         this.persona = args.persona ?? 'senior-engineer';
@@ -137,6 +139,10 @@ export class DeliveryState {
         this.contract = args.contract ?? null;
         this.stitch = args.stitch ?? null;
         this.stack = args.stack ?? null;
+        // Per-lane bounded-loop counters (`{test: {attempts, signatures[]}}`).
+        // `null` means no red check has been seen yet — distinct from `{}`,
+        // which means a lane record was created and then emptied.
+        this.self_fix = args.self_fix ?? null;
     }
 }
 

package/src/agent-src/templates/scripts/work_engine/directives/backend/_self_fix.ts

@@ -0,0 +1,332 @@
+/**
+ * Bounded self-fix loop — the shared primitive behind the red-check lanes.
+ *
+ * The gap this closes, verified in code before it was built: `test` and
+ * `verify` both halt to `Outcome.BLOCKED` the instant their recorded verdict
+ * is not `success`, and neither carries an attempt counter. The halt surface
+ * they emit is a *user* question block with no `@agent-directive:` line, so a
+ * red check the agent could have fixed unaided still costs a user round-trip.
+ *
+ * What this module adds is a counter and two floors — nothing else. It
+ * deliberately adds **no critic**: the verdict is already a deterministic
+ * value the engine holds in hand, so there is no judgement for a second model
+ * to make. That distinction is why the TERMINAL honest null on
+ * `recursive-verification` (ADR-106: capability 87% vs 87%, McNemar p=1.0)
+ * does not bind here — the measured arm added a critic to decide whether an
+ * attempt was good enough, and its killer finding was that cost scaled with
+ * *all* tasks while benefit sat in the ~28% tail. A red-check retry fires only
+ * on a red: zero cost on the passing majority.
+ *
+ * The null does bind one thing, and it is honoured: the falsification shape.
+ * "The loop is redundant" must remain discoverable, so the loop never converts
+ * a red into a green. Every exit it owns is `PARTIAL` with the red verdict
+ * still on the surface.
+ *
+ * Two floors, neither invented here:
+ *
+ * - **Ceiling** — {@link SELF_FIX_CEILING} attempts per lane, which is the
+ *   N=3 validation-loop budget from the `autonomous-execution` rule, applied
+ *   per validation target (that rule resets its counter on a different
+ *   target, so the counters below are per-lane rather than per-run).
+ * - **No-progress** — two consecutive attempts producing an identical verdict
+ *   signature stop the loop immediately, budget remaining or not. This is the
+ *   floor the `recursive-verification` skill already stated in prose ("two
+ *   consecutive attempts score identical on the deterministic scorer; further
+ *   depth cannot help, so stop"), adopted as code rather than left as advice,
+ *   and it matches `context-hygiene`'s "same failure signature twice → stop
+ *   and pivot now".
+ *
+ * No-progress is checked BEFORE the ceiling on purpose: an unchanged signature
+ * means the remaining budget cannot help, so spending it would be the exact
+ * wasted-attempt pattern both rules name.
+ */
+
+import type { DeliveryState } from '../../delivery_state.js';
+import { type Any, Outcome, StepResult, agent_directive } from '../../delivery_state.js';
+
+/**
+ * Attempts allowed per lane before the loop exits PARTIAL.
+ *
+ * Deliberately the `autonomous-execution` N=3 budget rather than a fresh
+ * number: a second, differently-sized retry ceiling in the same package would
+ * be a rule the tree contradicts.
+ */
+export const SELF_FIX_CEILING = 3;
+
+/** Lanes that own a bounded loop. One counter each — they are distinct targets. */
+export const SELF_FIX_LANES = ['test', 'verify'] as const;
+
+export type SelfFixLane = (typeof SELF_FIX_LANES)[number];
+
+/**
+ * Keys excluded from the verdict signature at every depth.
+ *
+ * Without this the no-progress floor could never fire: a test verdict carries
+ * `duration_ms`, which changes on every run, so two byte-identical failures
+ * would sign differently and the loop would burn its whole budget on a target
+ * it was making no progress against.
+ */
+export const VOLATILE_KEYS: ReadonlyArray<string> = [
+    'duration_ms',
+    'elapsed_ms',
+    'timestamp',
+    'started_at',
+    'finished_at',
+    'ran_at',
+];
+
+/** Why the loop stopped, or that it has budget left. */
+export type SelfFixKind = 'retry' | 'exhausted' | 'no_progress';
+
+/** Verdict of {@link decide} — pure, so the caller owns every mutation. */
+export interface SelfFixDecision {
+    kind: SelfFixKind;
+    /** Attempts already spent on this lane before this decision. */
+    attempts: number;
+    /** 1-based number of the attempt a `retry` authorises. */
+    next_attempt: number;
+    ceiling: number;
+    signature: string;
+}
+
+/**
+ * Canonical, volatile-free signature of a recorded verdict.
+ *
+ * Two failures are "the same failure" when this string matches. Object keys
+ * are sorted so key order in the recorded state cannot masquerade as progress.
+ */
+export function verdict_signature(lane: string, verdict_payload: Any): string {
+    return `${lane}:${_canonical(verdict_payload)}`;
+}
+
+/** Read the per-lane counter without mutating anything. */
+export function decide(state: DeliveryState, lane: string, signature: string): SelfFixDecision {
+    const lane_state = _lane_state(state, lane);
+    const attempts = _nonNegativeInt(lane_state['attempts']);
+    const signatures = Array.isArray(lane_state['signatures'])
+        ? (lane_state['signatures'] as Any[]).filter((s): s is string => typeof s === 'string')
+        : [];
+    const previous = signatures.length > 0 ? signatures[signatures.length - 1] : null;
+
+    const base = {
+        attempts,
+        next_attempt: attempts + 1,
+        ceiling: SELF_FIX_CEILING,
+        signature,
+    };
+
+    // No-progress before the ceiling: an unchanged signature means the
+    // remaining budget cannot move this target, so spending it is waste.
+    if (previous !== null && previous === signature) {
+        return { kind: 'no_progress', ...base };
+    }
+    if (attempts >= SELF_FIX_CEILING) {
+        return { kind: 'exhausted', ...base };
+    }
+    return { kind: 'retry', ...base };
+}
+
+/**
+ * Spend one attempt on `lane` and remember its signature.
+ *
+ * Mutates `state.self_fix` in place, which is how the counter survives the
+ * halt: the dispatcher persists the state it was handed, so the next
+ * invocation reads the incremented value. Callers must invoke this exactly
+ * once per `retry` decision — recording on an exit would inflate the count.
+ */
+export function record_attempt(state: DeliveryState, lane: string, signature: string): void {
+    const container = _pyTruthy(state.self_fix) ? (state.self_fix as Record<string, Any>) : {};
+    const lane_state = _lane_state(state, lane);
+    const signatures = Array.isArray(lane_state['signatures'])
+        ? (lane_state['signatures'] as Any[]).filter((s): s is string => typeof s === 'string')
+        : [];
+    container[lane] = {
+        attempts: _nonNegativeInt(lane_state['attempts']) + 1,
+        signatures: [...signatures, signature],
+    };
+    state.self_fix = container;
+}
+
+/** DoD entries the agent has not recorded as proven. Never inferred. */
+export function unmet_dod(state: DeliveryState): Array<Record<string, Any>> {
+    const dod = (state.ticket ?? {})['dod'];
+    if (!Array.isArray(dod)) {
+        return [];
+    }
+    return (dod as Any[]).filter(
+        (item): item is Record<string, Any> => _isPlainObject(item) && item['proven'] !== true,
+    );
+}
+
+/**
+ * BLOCKED halt that delegates the fix instead of asking the user.
+ *
+ * The `@agent-directive:` first line is what makes this an agent round-trip
+ * rather than a user one — the same delegation shape `run-tests` and
+ * `review-changes` already use. The numbered options stay, because an
+ * orchestrator that does not honour directives must still leave the human
+ * something to act on.
+ */
+export function retry_halt(args: {
+    lane: string;
+    ticket_id: string;
+    verdict: Any;
+    decision: SelfFixDecision;
+    fix_hint: string;
+    rerun_directive: string;
+}): StepResult {
+    const { lane, ticket_id, verdict, decision, fix_hint, rerun_directive } = args;
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            agent_directive('fix-failing-checks', {
+                ticket: ticket_id,
+                lane,
+                attempt: decision.next_attempt,
+                ceiling: decision.ceiling,
+            }),
+            `> Ticket ${ticket_id} — \`${lane}\` reported \`${String(verdict)}\`. ` +
+                `Self-fix attempt ${decision.next_attempt} of ${decision.ceiling}.`,
+            `> The verdict is deterministic, so the fix is delegated rather than asked: ${fix_hint}`,
+            `> 1. Continue — fix the failures and re-run \`${rerun_directive}\``,
+            '> 2. Abort — stop this cycle and hand the failures back',
+        ],
+        message:
+            `Ticket ${ticket_id} ${lane} verdict was \`${String(verdict)}\`; ` +
+            `self-fix attempt ${decision.next_attempt}/${decision.ceiling} delegated.`,
+    });
+}
+
+/**
+ * PARTIAL exit — the loop stopped and the check is STILL RED.
+ *
+ * `PARTIAL` rather than `BLOCKED` because attempts were spent and changes may
+ * have landed, and emphatically not `SUCCESS`: the risk this loop carries is
+ * that it converts a visible red into an invisible one, which is worse than
+ * the round-trip it removes. The dispatcher halts on PARTIAL exactly as it
+ * halts on BLOCKED, and the red verdict is the second line of the surface.
+ */
+export function partial_exit(args: {
+    lane: string;
+    ticket_id: string;
+    verdict: Any;
+    decision: SelfFixDecision;
+    unmet: Array<Record<string, Any>>;
+    rerun_directive: string;
+}): StepResult {
+    const { lane, ticket_id, verdict, decision, unmet, rerun_directive } = args;
+    const reason =
+        decision.kind === 'no_progress'
+            ? `two consecutive attempts produced an identical \`${lane}\` verdict, ` +
+              'so further attempts cannot help'
+            : `the ${decision.ceiling}-attempt budget for \`${lane}\` is spent`;
+    const dod_lines =
+        unmet.length > 0
+            ? [
+                  '> Definition-of-done items still unproven:',
+                  ...unmet.map((item) => {
+                      const id = typeof item['id'] === 'string' ? item['id'] : '(no id)';
+                      const check = typeof item['check'] === 'string' ? item['check'] : '(no check)';
+                      return `>    - \`${id}\` — \`${check}\``;
+                  }),
+              ]
+            : [];
+    return new StepResult({
+        outcome: Outcome.PARTIAL,
+        questions: [
+            `> Ticket ${ticket_id} — self-fix stopped after ` +
+                `${decision.attempts} attempt(s): ${reason}.`,
+            `> \`${lane}\` is STILL \`${String(verdict)}\`. Nothing here claims completion.`,
+            ...dod_lines,
+            `> 1. I'll take it from here — hand me the failures and re-run \`${rerun_directive}\``,
+            '> 2. Continue anyway — override on a red verdict (NOT recommended)',
+            '> 3. Abort',
+        ],
+        message:
+            `Ticket ${ticket_id} ${lane} verdict is \`${String(verdict)}\` after ` +
+            `${decision.attempts} self-fix attempt(s) (${decision.kind}); exiting PARTIAL.`,
+    });
+}
+
+/** Per-lane record, defaulted without writing anything back. */
+function _lane_state(state: DeliveryState, lane: string): Record<string, Any> {
+    const container = _pyTruthy(state.self_fix) ? (state.self_fix as Record<string, Any>) : {};
+    const lane_state = container[lane];
+    return _isPlainObject(lane_state) ? lane_state : {};
+}
+
+/** Ints only; a bool, float, negative, or non-number resets to 0. */
+function _nonNegativeInt(value: Any): number {
+    if (typeof value !== 'number' || typeof value === 'boolean') {
+        return 0;
+    }
+    if (!Number.isInteger(value) || value < 0) {
+        return 0;
+    }
+    return value;
+}
+
+/**
+ * Deterministic JSON rendering with sorted keys and volatile keys removed.
+ *
+ * Hand-rolled rather than `JSON.stringify`: the replacer form cannot sort
+ * object keys, and key order is exactly what must not leak into the signature.
+ */
+function _canonical(value: Any): string {
+    if (value === null || value === undefined) {
+        return 'null';
+    }
+    if (typeof value === 'boolean' || typeof value === 'number') {
+        return String(value);
+    }
+    if (typeof value === 'string') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return '[' + value.map((v) => _canonical(v)).join(',') + ']';
+    }
+    if (_isPlainObject(value)) {
+        const keys = Object.keys(value)
+            .filter((k) => !VOLATILE_KEYS.includes(k))
+            .sort();
+        return '{' + keys.map((k) => `${JSON.stringify(k)}:${_canonical(value[k])}`).join(',') + '}';
+    }
+    return JSON.stringify(String(value));
+}
+
+/** Python truthiness for the container kinds this module reads. */
+function _pyTruthy(value: Any): boolean {
+    if (value === null || value === undefined || value === false) {
+        return false;
+    }
+    if (value === true) {
+        return true;
+    }
+    if (typeof value === 'number') {
+        return value !== 0;
+    }
+    if (typeof value === 'string') {
+        return value.length !== 0;
+    }
+    if (Array.isArray(value)) {
+        return value.length !== 0;
+    }
+    if (value instanceof Set || value instanceof Map) {
+        return value.size !== 0;
+    }
+    if (typeof value === 'object') {
+        return Object.keys(value as Record<string, Any>).length !== 0;
+    }
+    return true;
+}
+
+/** True for a dict-like value (mirrors Python `isinstance(x, dict)`). */
+function _isPlainObject(value: Any): value is Record<string, Any> {
+    return (
+        typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !(value instanceof Set) &&
+        !(value instanceof Map)
+    );
+}

package/src/agent-src/templates/scripts/work_engine/directives/backend/refine.ts

@@ -7,7 +7,9 @@
  * part of the contract).
  *
  * The step never calls an LLM. It inspects `state.ticket` (which carries
- * `input.data` after the CLI projection) and routes on shape:
+ * `input.data` after the CLI projection), shape-checks the optional
+ * `dod[]` slot (the executable definition-of-done —
+ * `src/scripts/schemas/dod.schema.json`), and routes on shape:
  *
  * - **Ticket envelope** (`id`, `title`, `acceptance_criteria`) — the
  *   R1 path. Validates the minimum viable shape and either returns
@@ -84,6 +86,15 @@ export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
             'user answers one clarifying question; the agent ' +
             're-runs `refine-prompt` against the refreshed prompt',
     },
+    {
+        code: 'malformed_dod',
+        trigger:
+            '`dod` key present but not a list, or an entry missing a ' +
+            'non-empty `id` / `check` string',
+        resolution:
+            'fix the `dod[]` entries against `src/scripts/schemas/dod.schema.json`, ' +
+            'or drop the key — the slot is optional',
+    },
     {
         code: 'prompt_ui_intent',
         trigger:
@@ -99,6 +110,27 @@ export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
 /** Route on envelope shape: ticket path or prompt path. */
 export function run(state: DeliveryState): StepResult {
     const data = state.ticket || {};
+
+    // The `dod[]` slot is shape-checked on BOTH paths before either routes, so
+    // a malformed definition-of-done cannot reach the self-fix loop that
+    // reports it. Absent key → no check, no behaviour change.
+    const dod_issues = diagnose_dod(data);
+    if (dod_issues.length > 0) {
+        const dod_ticket_id = _pyTruthy(data.id) ? _pyStr(data.id) : '(no id)';
+        return new StepResult({
+            outcome: Outcome.BLOCKED,
+            questions: [
+                `> Ticket ${dod_ticket_id} — the \`dod[]\` slot is malformed: ` + dod_issues.join('; ') + '.',
+                '> Every entry needs a non-empty `id` and a non-empty `check` ' +
+                    '(the command that proves it) — prose there cannot be run.',
+                '> 1. Fix the `dod[]` entries and re-invoke',
+                '> 2. Drop the `dod` key — the slot is optional',
+                '> 3. Abort',
+            ],
+            message: `Ticket ${dod_ticket_id} has a malformed dod[] slot: ` + dod_issues.join('; '),
+        });
+    }
+
     if (_is_prompt_envelope(data)) {
         return _run_prompt(state, data);
     }
@@ -117,6 +149,53 @@ export function run(state: DeliveryState): StepResult {
     });
 }
 
+/**
+ * Report what is wrong with an envelope's `dod[]` slot; `[]` when it is fine.
+ *
+ * Exported so the shape is testable on its own and so a caller can ask the
+ * question without triggering a halt. An absent key is valid — the slot is
+ * optional and omitting it means the author never declared a machine-checkable
+ * done-condition, which is different from declaring an empty one.
+ *
+ * `check` is required to be non-empty for the reason the schema states: the
+ * dispatcher spawns no subprocesses, so `check` is handed to an agent to run,
+ * and an agent cannot run a sentence.
+ */
+export function diagnose_dod(data: Record<string, Any>): string[] {
+    if (!_isPlainObject(data) || !('dod' in data)) {
+        return [];
+    }
+    const dod = data.dod;
+    if (!Array.isArray(dod)) {
+        return [`\`dod\` must be a list, got ${_pyTypeName(dod)}`];
+    }
+    const issues: string[] = [];
+    const seen = new Set<string>();
+    dod.forEach((entry, idx) => {
+        const position = idx + 1;
+        if (!_isPlainObject(entry)) {
+            issues.push(`entry ${position} must be an object, got ${_pyTypeName(entry)}`);
+            return;
+        }
+        const id = entry.id;
+        if (typeof id !== 'string' || !id.trim()) {
+            issues.push(`entry ${position} has no \`id\``);
+        } else if (seen.has(id)) {
+            issues.push(`entry ${position} repeats id \`${id}\``);
+        } else {
+            seen.add(id);
+        }
+        const check = entry.check;
+        if (typeof check !== 'string' || !check.trim()) {
+            issues.push(`entry ${position} has no \`check\` command`);
+        }
+        if ('proven' in entry && typeof entry.proven !== 'boolean') {
+            issues.push(`entry ${position} has a non-boolean \`proven\``);
+        }
+    });
+    return issues;
+}
+
 /**
  * True when `state.ticket` carries a prompt envelope.
  *
@@ -442,6 +521,32 @@ function _pyTruthy(value: unknown): boolean {
     return true;
 }
 
+/** Python `type(x).__name__` for the value kinds the dod diagnose path sees. */
+function _pyTypeName(value: unknown): string {
+    if (value === null || value === undefined) {
+        return 'NoneType';
+    }
+    if (typeof value === 'boolean') {
+        return 'bool';
+    }
+    if (typeof value === 'number') {
+        return Number.isInteger(value) ? 'int' : 'float';
+    }
+    if (typeof value === 'string') {
+        return 'str';
+    }
+    if (Array.isArray(value)) {
+        return 'list';
+    }
+    if (value instanceof Set) {
+        return 'set';
+    }
+    if (value instanceof Map || _isPlainObject(value)) {
+        return 'dict';
+    }
+    return typeof value;
+}
+
 /** True for a dict-like value (mirrors Python `isinstance(x, dict)`). */
 function _isPlainObject(value: unknown): value is Record<string, unknown> {
     return (