@event4u/agent-config 9.31.0 → 9.32.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Bootstrap shim for the event4u agent-config suite. This plugin ships ONLY the dispatcher hooks plus one install-pointer skill — ALL content (skills, rules, commands) is installed via `npx -y @event4u/agent-config init`, which writes the file projection AND registers the same hooks in ~/.claude/settings.json. DEPRECATED as a content channel; kept so the marketplace listing stays discoverable and existing installs keep working hooks.",
-    "version": "9.31.0",
+    "version": "9.32.0",
     "keywords": [
       "agent-config",
       "skills",

package/CHANGELOG.md

@@ -321,6 +321,57 @@ Entry-shape contract: [`docs/contracts/CHANGELOG-conventions.md`](docs/contracts
 > that forces a new era split (`# Era: 9.32.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
+## [9.32.0](https://github.com/event4u-app/agent-config/compare/9.31.0...9.32.0) (2026-08-10)
+
+### Release highlights
+
+<!-- Curated head: fill before merge, keep it under 10 lines, and leave `_none_` where it is genuinely the answer. The generated log below is unchanged. -->
+- **Behaviour changes:** _auto-derived, rewrite before merge:_ rule/schema diffs, breaking commits or removed public surface in 1f01490, e05de77.
+- **Default changes + migration:** _none_
+- **Security and correctness:** _none_
+- **Honest nulls:** _none_
+- **Known limitations:** _none_
+
+### Features
+
+* **work-engine:** route both red-check lanes through the self-fix loop ([10c8f7e](https://github.com/event4u-app/agent-config/commit/10c8f7eafbf21fc03a5f301163c941a20df4a885))
+* **work-engine:** bounded self-fix loop primitive + executable dod schema ([1f01490](https://github.com/event4u-app/agent-config/commit/1f0149035c1a27729b729dab1dedd861ccdf9812))
+* **envelope:** drift anchor, scripted grounding, verbatim error strings ([6c9187e](https://github.com/event4u-app/agent-config/commit/6c9187e30f41c87553764759096a3f7f4d19a126))
+* **envelope:** successor tailoring, mandatory failed_approaches, data-never-instruction boundary ([b03beac](https://github.com/event4u-app/agent-config/commit/b03beac1ad1325253c89a63eac9abc9f051269d3))
+* **orchestration:** report per-field provenance for host capabilities ([f4958de](https://github.com/event4u-app/agent-config/commit/f4958decf4a70b445a38747bff768ab449877d52))
+
+### Bug Fixes
+
+* **gates:** stop the R2 review-input copy from laundering fixture secrets ([c63d350](https://github.com/event4u-app/agent-config/commit/c63d3502013e7bc261096d02e2c102a52e2f1ec7))
+* **golden:** teach the replay the delegated bad-verdict surface, re-lock baselines ([1ff480c](https://github.com/event4u-app/agent-config/commit/1ff480c6adeb88af32198a19d41838e2f9f5dcc0))
+* **envelope:** close the eight R2 review findings ([b0d153c](https://github.com/event4u-app/agent-config/commit/b0d153cb3084dac2a20093b73d28a3ce3c12324c))
+* **tests:** type the self-fix state helpers against the wire types ([60d2724](https://github.com/event4u-app/agent-config/commit/60d272419b07b5abea1ce6ffa430faf127fcde4a))
+* **handoff:** stop offering the caller its own empty session ([b72f772](https://github.com/event4u-app/agent-config/commit/b72f772a03207aa4feeded3acd5b68823e3fd79c))
+* **tests:** narrow regex captures in the capability parity block ([6f27615](https://github.com/event4u-app/agent-config/commit/6f276154b83781404d6551113c6d43e5cf040423))
+* **carrier:** a paths: disagreement is a delivery defect, not inert metadata ([318fb81](https://github.com/event4u-app/agent-config/commit/318fb818eb543f27fc4c3b138ce762dc8c9e9640))
+
+### Documentation
+
+* **review:** re-bind the findings artefact to the post-fix scope ([7a9bbbb](https://github.com/event4u-app/agent-config/commit/7a9bbbb2d7f4f04786771914bf7b3b68aba23e10))
+* **review:** record the R2 completion-review findings before fixing them ([27322e8](https://github.com/event4u-app/agent-config/commit/27322e876c76f96d6a67131f9e96a1759290a8f5))
+* **roadmap:** P2.2 build half shipped, its threshold unevaluated with a blocker ([1e478fd](https://github.com/event4u-app/agent-config/commit/1e478fdc317fdf12df001c1b98ef264df54a3742))
+* **contracts:** the flow contract documents the self-fix loop and the dod slot ([0ebaaba](https://github.com/event4u-app/agent-config/commit/0ebaabae9e12c75446efefc5be6f6b33b9d0435f))
+* **roadmap:** capability-answerability Phase 1 closed, blocker narrowed to one question ([c37af04](https://github.com/event4u-app/agent-config/commit/c37af045ecbf62b31e6878befdc88d763498d7a9))
+* **rules:** delegation-policy names the capability provenance check ([e05de77](https://github.com/event4u-app/agent-config/commit/e05de771d74e8284e2e64e91e33be66b1bd15e23))
+* **contracts:** the host-capability contract documents six fields, not five ([566b984](https://github.com/event4u-app/agent-config/commit/566b984681d1a1a5ef76643fa6f90f297c284e81))
+
+### Tests
+
+* **work-engine:** pin the loop contract and update the changed halt shapes ([eb88aa6](https://github.com/event4u-app/agent-config/commit/eb88aa695121a01c0c1e10de9804f1df3424c334))
+
+### Other
+
+* **carrier:** re-bind to the post-merge scope — the fixed point ([884104c](https://github.com/event4u-app/agent-config/commit/884104c15d8257579a320932c671b489d96e7b06))
+* **carrier:** re-bind the R2 round to the shipping content, all 6 terminal ([9bbfbc3](https://github.com/event4u-app/agent-config/commit/9bbfbc35388f54c77fdae27315025843a6ea79f5))
+* **carrier:** R2 completion review round 1 — 6 findings, all open ([75be940](https://github.com/event4u-app/agent-config/commit/75be940f4f9bcbf71e1f1248467637fc51c6b63b))
+
+Tests: 12818 (+89 since 9.31.0)
+
 ## [9.31.0](https://github.com/event4u-app/agent-config/compare/9.30.0...9.31.0) (2026-08-10)
 
 ### Release highlights

package/dist/agent-src/contexts/execution/host-capability-manifest.md

@@ -16,7 +16,8 @@ A single JSON object, `schema_version: 1`:
   "parallel_spawn": false,
   "status_polling": false,
   "separate_quota_pool": false,
-  "agent_teams": false
+  "agent_teams": false,
+  "worker_respawn": false
 }
 ```
 
@@ -64,11 +65,41 @@ to in-session execution rather than attempting an unsupported primitive.
 | `status_polling` | bool | Monitoring running subagents (progress / completion checks). `false` → fire-and-collect only, no mid-run polling. |
 | `separate_quota_pool` | bool | Quota-arbitrage bonus (Phase 2) — subagents draw from a distinct quota pool than the session. `false` → assume shared quota. |
 | `agent_teams` | bool | Claude Code's experimental multi-instance Agent Teams primitive (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`). `false` → the [judgment ladder](auto-dispatch-classification.md#judgment-ladder-phase-2--road-to-always-on-orchestration)'s rung 3 (team) degrades to parallel subagents, recorded as `degraded_from: 3`. |
+| `worker_respawn` | bool | The host can kill a running worker and spawn a fresh one that continues the SAME task mid-flight. `false` on every host today, deliberately — set `true` only once OBSERVED, never by inference from spawning and killing existing separately. `false` → degrade to stop-loss behaviour, loudly. |
 
 A field being `true` is a **precondition**, not a mandate: `parallel_spawn:
 true` permits concurrency but the dispatch cap still applies (see
 `subagents.max_parallel` in subagent-configuration.md).
 
+## Provenance — "probe" is a misnomer for five of the six fields
+
+```
+NEVER READ A false FIELD AS "THIS HOST CANNOT DO IT".
+A REGISTRY ROW IS A COMMITTED OBSERVATION, NOT A LIVE CHECK.
+A default FIELD MEANS NOBODY ANSWERED — RENDERED AS false BECAUSE THAT IS THE
+SAFE DEGRADATION, NOT BECAUSE ANYTHING WAS MEASURED.
+```
+
+The six booleans look alike and are not. `HOST_CAPABILITY_REGISTRY` holds
+exactly one row today, so on every other host **all six** fields are the safe
+default — and `agent_teams` is the only field any live check touches. The name
+`probeHostCapabilities` says "detected" about values that were mostly asserted
+at authoring time.
+
+`describeHostCapabilities(hostId)` returns the same manifest plus a
+`sources` map naming, per field, which of the three answered:
+
+| Source | Means | Re-checked at run time |
+|---|---|---|
+| `registry` | this repo observed the capability on this host once and committed it to the table | no |
+| `live-probe` | established in THIS process, from the environment | yes |
+| `default` | nothing answered; `SAFE_DEFAULT` applied | n/a |
+
+`agent-config routing:doctor [--platform <host>]` prints it. Read the
+provenance before treating a `false` as a host limitation: on an unrecognized
+host every field is `default`, which is an absence of knowledge and not a
+measurement.
+
 ## Related
 
 - [`subagent-configuration`](../subagent-configuration.md) — the `subagents.*`

package/dist/agent-src/rules/delegation-policy.md

@@ -105,7 +105,17 @@ plus this telemetry). The
 capability gate itself resolves from the committed host registry merged with a
 live environment probe in `src/scripts/_lib/host_capability.ts`
 (`probeHostCapabilities` — capability is a fact about the host, never a
-settings override). What stays
+settings override).
+
+**Never read a `false` capability as a host limitation without checking where it
+came from.** The registry holds one row, so on every other host all six fields
+are the all-false safe default — which records that *nobody answered*, not that
+the host cannot spawn. `agent-config routing:doctor [--platform <host>]` prints
+the value **and** its provenance per field (`registry` = a committed observation
+this repo made once · `live-probe` = established in this process · `default` =
+no answer). Run it before concluding delegation is unavailable here; the
+same-shaped wrong guess about the council is the incident
+[`council-availability`](council-availability.md) exists for. What stays
 model-carried, honestly: the decomposition itself, the per-return
 verification, and every dispatch on hosts without hook slots. The nudges are
 advisory by design — whether they change behaviour is measured by the

package/dist/agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "9.31.0"
+agent_config_version: "9.32.0"
 
 # --- Project identity ---
 project:

package/dist/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/dist/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/dist/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 (