@event4u/agent-config 14.12.0 → 14.14.0

package/src/scripts/_lib/orchestration_record.ts

@@ -17,6 +17,16 @@
  */
 
 import type { LookupClass } from './auto_dispatch.js';
+import type { EvidenceBasis } from './evidence_basis.js';
+// TYPE-ONLY on purpose. `runtime_journal.ts` imports `node:sqlite` at runtime,
+// and this module is loaded by a PreToolUse-adjacent CLI path where opening a
+// database would be both wrong and slow. A `import type` is erased at compile
+// time, so the guard costs nothing at runtime while still being one definition
+// rather than a second copy of the key list -- the duplicate-enum failure step
+// 9.1 exists to prevent.
+import type { NoFreeForm } from './runtime_journal.js';
+import { type PrivacyClass } from './privacy_class.js';
+import type { PhaseOutcome } from './outcome_vocabularies.js';
 
 export type DispatchOutcome = 'DONE' | 'DONE_WITH_CONCERNS' | 'NEEDS_CONTEXT' | 'BLOCKED' | 'killed';
 /** Which route the rung took: deterministic primitive (lean-init L0),
@@ -24,12 +34,30 @@ export type DispatchOutcome = 'DONE' | 'DONE_WITH_CONCERNS' | 'NEEDS_CONTEXT' |
  *  subagent spawn. */
 export type RouteTaken = 'primitive' | 'subagent' | 'ask';
 export type VerifyMode = 'deterministic' | 'judge' | 'none';
-export type Provenance = 'measured' | 'estimated';
+/**
+ * Migrated onto the shared evidence-basis vocabulary
+ * (`road-to-delivered-cost-truth` 4.1). The two literals are unchanged on the
+ * wire — `measured` and `estimated` mean here exactly what the contract says
+ * they mean — but they are no longer declared privately, so this surface and
+ * the census can no longer drift apart on what "measured" is.
+ *
+ * Narrowed to the two values this field can actually take: an orchestration
+ * record's floor is either read from the transcript ledger or arithmetic over
+ * it, and admitting `model-judged` here would be widening a type to match a
+ * vocabulary rather than a fact.
+ */
+export type Provenance = Extract<EvidenceBasis, 'measured' | 'estimated'>;
 export type TierChosen = 'lite' | 'medium' | 'high';
 export type TierSource = 'static' | 'inferred' | 'inherit';
 export type Band = 'low' | 'medium' | 'high';
 export type LinePhase = 'refine' | 'memory' | 'analyze' | 'plan' | 'implement' | 'test' | 'verify' | 'report';
-export type LineOutcome = 'success' | 'blocked' | 'skipped' | 'error';
+/**
+ * Outcome of this audit-log line. Alias of the registry's `PhaseOutcome` —
+ * the name `LineOutcome` is kept because two modules import it, and the
+ * single definition now lives in `outcome_vocabularies.ts` so the contract
+ * table can be checked against it (`road-to-experience-loop-broadening` 1.3).
+ */
+export type LineOutcome = PhaseOutcome;
 /** Which capsule-emission trigger arm fired first (Phase 1 shadow comparison). */
 export type TriggerArm = 'watermark' | 'saturation' | 'tie';
 /** The orchestration form the form-gate selected (road-to-opt-subagent-harvest P2). */
@@ -58,6 +86,45 @@ export interface RecordInput {
     task_class?: string | null | undefined;
     /** Form-gate outcome: which of the seven modes (or 'none') the gate selected. */
     dispatch_mode?: DispatchModeId | null | undefined;
+    /**
+     * Stable skill ids that were APPLIED during this phase — the skills
+     * counterpart of `rules_applied`, which `audit-log-v1` has carried since v1
+     * while carrying no skills field at all.
+     *
+     * ABSENT and EMPTY mean different things, and the distinction is
+     * load-bearing rather than stylistic: the field OMITTED means *not
+     * recorded* (the producer had no skill observation to offer), while `[]`
+     * means *recorded, and none applied*. Folding the two together is what
+     * makes a per-asset report unable to tell "no signal" from "a negative
+     * signal", which is the failure `unknown != 0` exists to prevent
+     * downstream.
+     *
+     * Ids only, never bodies — privacy by construction, same as
+     * `rules_applied`. Bounded to <= 32; the remainder is dropped, mirroring
+     * the rules bound in the contract.
+     */
+    skills_applied?: string[] | null | undefined;
+    /**
+     * What this dispatch was supposed to produce. Drives the anti-forgery gate
+     * in `envelopeOutcome`. Absent or `unknown` disables the gate for this
+     * line, which is the safe default: a producer that cannot say what it
+     * expected must not have its outcome downgraded on a guess.
+     */
+    expected_output?: ExpectedOutput | null | undefined;
+    /**
+     * Measured lines changed by this dispatch. `null` means NOT MEASURED and is
+     * never read as zero — an unmeasured diff must not become a failure.
+     */
+    diff_lines?: number | null | undefined;
+    /**
+     * Trigger fires suppressed as duplicates since the last outcome record.
+     *
+     * Reported as its own quantity, never folded into a success rate's
+     * numerator or denominator: a duplicate is not an outcome, and it is also
+     * not nothing — a rising count is what an idle loop looks like from
+     * outside. See `src/scripts/_lib/empty_cycles.ts`.
+     */
+    empty_cycles?: number | null | undefined;
     task_size_estimate?: number | undefined;
     wall_clock_ms?: number | undefined;
     /** Absolute measured tokens the dispatched slice consumed (feeds the modeled cost-%). */
@@ -178,12 +245,148 @@ const PAYLOAD_HASH_RE = /^[a-f0-9]{8,64}$/i;
 /** Id-shaped origin tag — enum-ish, never free-form prose. */
 const ORIGIN_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
 
+/**
+ * Upper bound on an applied-id array, mirroring the `rules_applied` bound the
+ * contract has carried since v1 ("Bounded to <= 32; remainder dropped
+ * silently"). Stated as a named constant so the contract row and the code can
+ * be checked against one another instead of against a literal.
+ */
+const MAX_APPLIED_IDS = 32;
+
+/**
+ * What THIS producer's lines carry. `ids-only` and not `counts-only` because
+ * every line carries `rules_applied`, and some carry `skills_applied`.
+ */
+const PRODUCER_PRIVACY_CLASS: PrivacyClass = 'ids-only';
+
+type Assert<T extends true> = T;
+
+/**
+ * PRIVACY BY CONSTRUCTION, enforced rather than asserted.
+ *
+ * Until 2026-08-30 the privacy floor on this module was a docstring, and
+ * `docs/contracts/audit-log-v1.md` said so in its own words: "No test enforces
+ * this floor". A docstring cannot stop the next author adding a `payload` or a
+ * `detail` field, and `audit-log-v1`'s forward-compat rule means readers would
+ * silently carry it.
+ *
+ * This assertion makes that a COMPILE error. If {@link RecordInput} ever grows
+ * a key from `FREE_FORM_KEYS` -- `prompt`, `body`, `file_path`, `stdout`,
+ * `reason`, `payload` and the rest of the set an author reaches for when they
+ * want to stash content -- `NoFreeForm` resolves to `never`, this becomes
+ * `Assert<false>`, and the build stops. The type cannot be widened back without
+ * deleting this line, which is a visible act in a diff.
+ */
+type _RecordInputCarriesNoFreeFormField = Assert<
+    [NoFreeForm<RecordInput>] extends [never] ? false : true
+>;
+
+/**
+ * The NEGATIVE fixture, and it is the half that is easy to leave out.
+ *
+ * The assertion above proves the guard ACCEPTS the current type. On its own
+ * that is satisfied just as well by a guard that accepts everything -- a
+ * `NoFreeForm` that had been broken into `type NoFreeForm<T> = T` would keep it
+ * green forever. This fixture proves the guard REJECTS, which is the direction
+ * that actually protects anything.
+ *
+ * The `@ts-expect-error` is itself the assertion: the line below is required to
+ * be a type error. If the guard ever stops rejecting a free-form key, the error
+ * disappears, the directive becomes unused, and `tsc` fails on the unused
+ * directive. Either way the build stops -- so `npm run typecheck` checks both
+ * directions, not only the flattering one.
+ *
+ * NOTE for whoever runs this by hand: `tsc -p tsconfig.json` does NOT cover
+ * this file. That config includes only `src/cli`, `src/server`, `src/shared`
+ * and `src/install`; `src/scripts/**` is reached solely by
+ * `tsconfig.scripts.json`. Use `npm run typecheck`, which runs both. A bare
+ * `tsc -p tsconfig.json` over this module is a gate that scans nothing and
+ * exits green.
+ */
+interface _RecordInputWithForbiddenField extends RecordInput {
+    prompt?: string | undefined;
+}
+type _Rejected = [NoFreeForm<_RecordInputWithForbiddenField>] extends [never] ? false : true;
+// @ts-expect-error — a type carrying a free-form key must make this Assert<false>
+type _ForbiddenFieldIsRejected = Assert<_Rejected>;
+
 /** Map a dispatch outcome to the audit-log envelope outcome enum. */
-function envelopeOutcome(d: DispatchOutcome): LineOutcome {
+/**
+ * What a dispatch was supposed to produce. The gate below reads THIS, never the
+ * diff alone.
+ *
+ * The unconditional rule -- claimed success x empty diff => never `success` --
+ * is the form this step deliberately does NOT ship. Analysis, review and
+ * read-only research dispatches are a large share of this repository's subagent
+ * traffic and legitimately produce no diff; marking them all as failures would
+ * poison the very aggregation the gate exists to protect, in the opposite
+ * direction. Zero diff may be valid, so "zero diff = failure" must not be
+ * global.
+ */
+export const EXPECTED_OUTPUTS = ['code-change', 'analysis', 'review', 'unknown'] as const;
+export type ExpectedOutput = (typeof EXPECTED_OUTPUTS)[number];
+
+/**
+ * Version of the DispatchOutcome -> phase-outcome mapping that produced a line.
+ *
+ * Required by the AI council (2026-08-30, anthropic + openai, 2/2) as the
+ * condition on proceeding at all, and it addresses an asymmetry worth stating:
+ * a bad enforcement gate rolls back, a bad LABELLING change poisons historical
+ * analysis permanently, because audit-log-v1 lines are append-only and cannot
+ * be rewritten. A reader aggregating across the cutover must be able to see
+ * which semantics produced each line rather than infer it from a date.
+ *
+ * `1` -- unconditional: DONE / DONE_WITH_CONCERNS always mapped to `success`.
+ *        Every line written before 2026-08-30 carries these semantics and
+ *        carries NO `outcome_semantics` field, so an absent field reads as 1.
+ * `2` -- contract-gated: a `code-change` dispatch claiming success with a
+ *        measured empty diff no longer maps to `success`.
+ */
+export const OUTCOME_SEMANTICS_VERSION = 2;
+
+/**
+ * Translate a dispatch outcome into an audit-log phase outcome.
+ *
+ * This is the tree's ONLY cross-domain outcome mapping
+ * (`src/scripts/_lib/outcome_vocabularies.ts` CROSS_DOMAIN_MAPPINGS), so a
+ * change here reaches every downstream aggregation. It was audited before
+ * changing: `envelopeOutcome` has no caller outside this module, the only
+ * reader of `outcome` is `src/scripts/extract_audit_patterns.ts` -- read-only,
+ * stdout, whose sole non-zero exit is argument validation -- and that script is
+ * wired into no Taskfile, no gate-coverage entry and no workflow. The label
+ * therefore enters no automated control path, which is the condition the
+ * council set for this being a labelling change rather than an enforcement one.
+ *
+ * The anti-forgery clause fires only when ALL THREE hold: the dispatch declared
+ * itself a `code-change`, it claimed success, and the diff was MEASURED at
+ * zero. `diff_lines == null` means not measured, and an unmeasured diff must
+ * never become a failure -- that would manufacture the forgery in the other
+ * direction, which is the same defect wearing the opposite sign.
+ */
+function envelopeOutcome(d: DispatchOutcome, ctx?: OutcomeContext): LineOutcome {
     if (d === 'BLOCKED') return 'blocked';
     if (d === 'NEEDS_CONTEXT') return 'skipped';
     if (d === 'killed') return 'error';
-    return 'success'; // DONE / DONE_WITH_CONCERNS
+
+    const claimsSuccess = d === 'DONE' || d === 'DONE_WITH_CONCERNS';
+    if (
+        claimsSuccess &&
+        ctx?.expected_output === 'code-change' &&
+        typeof ctx.diff_lines === 'number' &&
+        ctx.diff_lines === 0
+    ) {
+        // A code dispatch that claims success and demonstrably changed nothing
+        // is an unverified self-report, not a result. `error` rather than
+        // `blocked`: nothing prevented it from running, and `blocked` is
+        // already the value for a dispatch that never got to try.
+        return 'error';
+    }
+    return 'success';
+}
+
+interface OutcomeContext {
+    expected_output?: ExpectedOutput | null | undefined;
+    diff_lines?: number | null | undefined;
 }
 
 function isInt(n: unknown): n is number {
@@ -288,7 +491,23 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
     if (input.origin != null && !ORIGIN_RE.test(input.origin)) {
         errors.push("origin must be an id-shaped tag like 'lean-init-2026' (lowercase alnum + hyphens)");
     }
+    if (input.expected_output != null && !EXPECTED_OUTPUTS.includes(input.expected_output)) {
+        errors.push(`expected_output must be one of ${EXPECTED_OUTPUTS.join(' | ')} (or omitted)`);
+    }
+    if (input.diff_lines != null && (!isInt(input.diff_lines) || input.diff_lines < 0)) {
+        errors.push('diff_lines must be a non-negative integer count, null for not-measured, or omitted');
+    }
+    if (input.skills_applied != null) {
+        if (!Array.isArray(input.skills_applied)) {
+            errors.push('skills_applied must be an array of skill ids, [] , or omitted');
+        } else if (!input.skills_applied.every((v) => typeof v === 'string' && ORIGIN_RE.test(v))) {
+            errors.push(
+                "skills_applied entries must be id-shaped skill names like 'code-review' (lowercase alnum + hyphens) — ids only, never bodies",
+            );
+        }
+    }
     for (const [key, v] of [
+        ['empty_cycles', input.empty_cycles],
         ['rules_carried', input.rules_carried],
         ['rules_used', input.rules_used],
         ['work_tokens', input.work_tokens],
@@ -336,6 +555,9 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
     const orchestration: Record<string, unknown> = {
         task_size_estimate: input.task_size_estimate ?? 0,
         spawn_count: input.spawn_count,
+        // Its OWN quantity, never folded into a rate. `null` = not tracked by
+        // this producer, which is not the same as zero duplicates observed.
+        empty_cycles: input.empty_cycles ?? null,
         tiers: input.tiers ?? [],
         token_delta: input.token_delta,
         token_delta_provenance: prov,
@@ -388,12 +610,38 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
         ts: input.ts,
         work_id: input.work_id ?? `orchestration-${input.ts}`,
         phase,
-        outcome: input.outcome ?? envelopeOutcome(dOutcome),
+        outcome:
+            input.outcome ??
+            envelopeOutcome(dOutcome, {
+                expected_output: input.expected_output,
+                diff_lines: input.diff_lines,
+            }),
+        // The cutover marker. An ABSENT field means semantics 1 (unconditional),
+        // which is every line written before 2026-08-30 -- so a reader
+        // aggregating across the boundary can segment rather than infer from a
+        // date. Emitted unconditionally because this producer always applies
+        // the current mapping.
+        outcome_semantics: OUTCOME_SEMANTICS_VERSION,
         confidence_band: band,
         risk_class: risk,
         memory: { asks: 0, hits: 0 },
         verify: { claims: 0, first_try_passes: 0 },
         rules_applied: ['delegation-policy'],
+        // MANDATORY, never optional and never derived by the reader. This line
+        // carries `rules_applied` and may carry `skills_applied`, both of which
+        // are stable artefact ids, so the class it declares is `ids-only`
+        // rather than `counts-only`. A consumer deciding whether this stream is
+        // safe to aggregate or export reads this field instead of re-deriving
+        // the answer from the producer's source.
+        privacy_class: PRODUCER_PRIVACY_CLASS,
+        // Emitted ONLY when the producer offered one. An omitted key means "not
+        // recorded"; `[]` means "recorded, none applied". Writing `null` or `[]`
+        // unconditionally would erase that distinction for every existing
+        // producer that has no skill observation to give, which is the whole
+        // reason the field is optional rather than defaulted.
+        ...(input.skills_applied != null
+            ? { skills_applied: input.skills_applied.slice(0, MAX_APPLIED_IDS) }
+            : {}),
         persona: input.persona ?? null,
         input_kind: 'orchestration',
         type: 'phase',

package/src/scripts/_lib/outcome_envelope.ts

@@ -0,0 +1,227 @@
+/**
+ * Machine-decidable outcomes: the terminal state, whether a retry can help, and
+ * whether a finding list is complete.
+ *
+ * `road-to-skill-ecosystem-runtime-enforcement` Phase 4, Steps 4-5. Two
+ * distinctions that an agent currently has to JUDGE from prose, and gets wrong
+ * in the same direction each time:
+ *
+ * 1. **Is this worth retrying?** A missing credential, a permission denial, a
+ *    spend cap and an upstream 5xx are all "the command failed", and retrying
+ *    any of them burns an iteration against a gap the loop cannot close. The
+ *    rules already say so — `context-hygiene`'s hard-blocker classes — and
+ *    nothing a script emits lets an agent decide it without reading English.
+ * 2. **Is this list complete?** A capped finding list reads as a complete one.
+ *    A gate that reports "3 findings" after truncating at 3 has said something
+ *    false, and the reader has no way to know.
+ *
+ * PER-CATEGORY caps rather than one global cap, because a single cap lets one
+ * high-volume check fill the budget and hide every other category behind it —
+ * which is the failure a cap is supposed to prevent, arriving through the cap.
+ */
+
+import type { RunTerminalState } from './outcome_vocabularies.js';
+
+/**
+ * The six terminal states. Contract: `contexts/execution/terminal-states.md`.
+ *
+ * Alias of the registry's `RunTerminalState`. This module stays the public
+ * surface — `runtime_journal.test.ts:212` pins the import path and `:215`
+ * asserts no second declaration — while the single definition moved to
+ * `outcome_vocabularies.ts` so the contract's table can be checked against it
+ * (`road-to-experience-loop-broadening` 1.3).
+ */
+export type TerminalState = RunTerminalState;
+
+/** States that are NOT success. An error or an exhausted budget never reports as one. */
+export const NON_SUCCESS_STATES: ReadonlySet<TerminalState> = new Set([
+    'blocked',
+    'approval-required',
+    'exhausted',
+    'stagnated',
+]);
+
+/**
+ * Why a failure is or is not worth retrying.
+ *
+ * `hard-blocker` is the load-bearing value: it says *stop now and surface*,
+ * not *try twice more first*. `context-hygiene` names the classes — missing
+ * credential, permission denied, quota or rate limit reached, upstream 5xx —
+ * and a first occurrence of any of them skips the retry budget entirely.
+ */
+export type RetryClass = 'retryable' | 'hard-blocker' | 'not-applicable';
+
+/**
+ * What the orchestrator did with a return — the acknowledgment half of the
+ * channel (`road-to-runtime-event-journal` Phase 3.1).
+ *
+ * The envelope already refuses to report a failure as a success. What it could
+ * not record is whether the *reader* did anything with that failure: a
+ * `blocked` return the orchestrator dropped on the floor is byte-identical to
+ * one it read, weighed, and deliberately set aside. Both are "a blocked return
+ * exists"; only one of them is a defect, and no field distinguished them.
+ *
+ * Three values, and the absent case is the fourth and the load-bearing one:
+ * ABSENT means nobody recorded a decision, which is exactly the ignored
+ * blocker `_lib/ignored_blocker.ts` reports.
+ */
+export type ConsumptionState = 'consumed' | 'partially-consumed' | 'rejected-with-reason';
+
+/**
+ * The acknowledgment record. A discriminated union, so the reason that
+ * `rejected-with-reason` needs is enforced by the TYPE rather than by a
+ * runtime check the caller meets or does not: `{ consumption:
+ * 'rejected-with-reason' }` with no `reason` does not compile.
+ *
+ * The other two states may carry a reason and are not required to — a
+ * consumed return needs no justification, and demanding one would make the
+ * cheap path expensive, which is how a field stops being filled at all
+ * (Risk 5).
+ */
+export type Acknowledgment =
+    | { readonly consumption: 'consumed'; readonly reason?: string }
+    | { readonly consumption: 'partially-consumed'; readonly reason?: string }
+    | { readonly consumption: 'rejected-with-reason'; readonly reason: string };
+
+export interface OutcomeEnvelope<T = unknown> {
+    state: TerminalState;
+    /** Whether a retry can plausibly change the outcome. */
+    retry: RetryClass;
+    /**
+     * What to do next, in the imperative, naming the thing to change. Required
+     * on every non-success state: a state without a next action is a report the
+     * reader must translate.
+     */
+    suggestion: string;
+    /** True when the payload was capped. A capped list without this reads as complete. */
+    truncated: boolean;
+    /** Per-category counts BEFORE capping, so a reader sees what was dropped. */
+    totals: Record<string, number>;
+    payload: T;
+    /**
+     * What the orchestrator did with this return, when it recorded anything.
+     *
+     * OPTIONAL on purpose, and the optionality is the measurement surface: an
+     * absent acknowledgment on a non-success state is a detectable ignored
+     * blocker, not a defaulted-to-fine one. Never default it to `consumed` —
+     * that would make every unread return look read, which is the exact
+     * failure the field exists to expose.
+     */
+    acknowledgment?: Acknowledgment;
+}
+
+/** Raised when an envelope is constructed in a state its own contract forbids. */
+export class EnvelopeContractError extends Error {}
+
+/**
+ * Build an envelope, refusing the two shapes that make one useless.
+ *
+ * A non-success state with no `suggestion` is refused, and so is `truncated`
+ * with empty `totals`: both are the "capped list reads as complete" failure in
+ * different clothes — one hides the next action, the other hides the drop.
+ */
+export function envelope<T>(init: {
+    state: TerminalState;
+    retry?: RetryClass;
+    suggestion?: string;
+    truncated?: boolean;
+    totals?: Record<string, number>;
+    payload: T;
+    /**
+     * Optional at construction. A producer almost never knows what its reader
+     * will do, so the normal path is {@link acknowledge} at the consuming end;
+     * this entry exists so a caller that IS both ends does not have to
+     * round-trip through a second call.
+     */
+    acknowledgment?: Acknowledgment;
+}): OutcomeEnvelope<T> {
+    const state = init.state;
+    const suggestion = init.suggestion ?? '';
+    if (NON_SUCCESS_STATES.has(state) && suggestion.trim() === '') {
+        throw new EnvelopeContractError(
+            `terminal state "${state}" requires a suggestion — a non-success outcome with no ` +
+                'named next action is a report the reader has to translate, which is the ' +
+                'judgement this envelope exists to remove.',
+        );
+    }
+    const truncated = init.truncated ?? false;
+    const totals = init.totals ?? {};
+    if (truncated && Object.keys(totals).length === 0) {
+        throw new EnvelopeContractError(
+            'truncated: true requires per-category totals — a capped list whose pre-cap counts ' +
+                'are unknown is indistinguishable from a complete one, which is the defect the ' +
+                'flag exists to remove.',
+        );
+    }
+    return {
+        state,
+        retry: init.retry ?? (state === 'success' || state === 'clean-no-op' ? 'not-applicable' : 'retryable'),
+        suggestion,
+        truncated,
+        totals,
+        payload: init.payload,
+        // Spread rather than assigned: under `exactOptionalPropertyTypes` an
+        // explicit `undefined` is NOT the same as an absent key, and the whole
+        // detector rests on absence meaning "nobody decided".
+        ...(init.acknowledgment === undefined ? {} : { acknowledgment: init.acknowledgment }),
+    };
+}
+
+/**
+ * Record what a reader did with a return, without mutating the original.
+ *
+ * Returns a NEW envelope. The producer's value stays as it was emitted, so an
+ * acknowledgment can never be mistaken for something the producer claimed
+ * about its own output — which is the same author-is-not-the-evaluator
+ * boundary the rest of this tree keeps.
+ */
+export function acknowledge<T>(env: OutcomeEnvelope<T>, ack: Acknowledgment): OutcomeEnvelope<T> {
+    return { ...env, acknowledgment: ack };
+}
+
+/**
+ * Cap a finding list PER CATEGORY and report what was dropped.
+ *
+ * @returns the kept items, the pre-cap totals per category, and whether
+ * anything was dropped. The caller passes `totals` straight into
+ * {@link envelope}, so the flag and the counts cannot drift apart.
+ */
+export function capPerCategory<T>(
+    items: readonly T[],
+    categoryOf: (item: T) => string,
+    perCategoryCap: number,
+): { kept: T[]; totals: Record<string, number>; truncated: boolean } {
+    const totals: Record<string, number> = {};
+    const seen: Record<string, number> = {};
+    const kept: T[] = [];
+    for (const item of items) {
+        const c = categoryOf(item);
+        totals[c] = (totals[c] ?? 0) + 1;
+        seen[c] = (seen[c] ?? 0) + 1;
+        if ((seen[c] ?? 0) <= perCategoryCap) kept.push(item);
+    }
+    return { kept, totals, truncated: kept.length < items.length };
+}
+
+/**
+ * Classify a failure into a retry class from what a command actually produced.
+ *
+ * Deliberately a small, named list rather than a general heuristic: every entry
+ * corresponds to a hard-blocker class the rules already name, and a classifier
+ * that guessed beyond them would turn a transient failure into a permanent one.
+ * Anything unmatched is `retryable`, which is the safe direction — a wasted
+ * retry costs one iteration, a wrongly-permanent verdict costs the whole task.
+ */
+export function classifyFailure(text: string): RetryClass {
+    const t = text.toLowerCase();
+    const hard: readonly RegExp[] = [
+        /\b(permission denied|forbidden|403)\b/,
+        /\b(unauthorized|401|not authenticated|authentication (failed|required))\b/,
+        /\b(quota|rate limit|too many requests|429)\b/,
+        /\b(missing|unset|not set)\b[^\n]{0,40}\b(credential|token|api[_ -]?key|secret)\b/,
+        /\bcommand not found\b/,
+        /\bno such (file or directory|command)\b/,
+        /\bspend (cap|limit) reached\b/,
+    ];
+    return hard.some((re) => re.test(t)) ? 'hard-blocker' : 'retryable';
+}

package/src/scripts/_lib/outcome_vocabularies.ts

@@ -0,0 +1,125 @@
+/**
+ * The three outcome vocabularies this repository actually produces, and the
+ * one crossing between them — in a single module, so a fourth cannot appear
+ * without a diff to this file.
+ *
+ * `road-to-experience-loop-broadening` step 1.3. That step was written on the
+ * premise that the tree holds **two** outcome enums and that one of them is
+ * documentation-only. Re-measured at `63d06b7eb`, both halves of that premise
+ * are wrong, and the corrected picture is why this module registers rather
+ * than unifies:
+ *
+ * | Vocabulary | Subject | Declared | Values |
+ * |---|---|---|---|
+ * | phase | one audit-log line — a `/work` PHASE | here, consumed by `orchestration_record` | 4 |
+ * | step  | one work-engine STEP | `work_engine/delivery_state.ts` (template tree) | 3 |
+ * | run   | one command or gate RUN | here, consumed by `outcome_envelope` | 6 |
+ *
+ * All three are declared in code AND emitted today. `skipped` and `error` are
+ * not aspirational: `envelopeOutcome` in `orchestration_record.ts` returns
+ * both, and `review_skipped_record.ts` writes `outcome: 'skipped'` onto a real
+ * audit line. An earlier reading of this tree concluded they "exist nowhere",
+ * because it grepped for enum MEMBER ASSIGNMENTS (`SKIPPED: 'skipped'`) and
+ * these are string-literal union members. The distinction cost a wrong premise
+ * once; it is written down here so it cannot cost it twice.
+ *
+ * **Why register and not unify.** AI council 2026-08-29 (anthropic + openai,
+ * 2 rounds, $0.00, both seats subscription-authed) split on the question and
+ * named the same discriminator: trace the producers before choosing. The trace
+ * settled it — the three subjects are genuinely different (a phase aggregates
+ * steps; a run is neither), all three are produced, and a cross-domain mapping
+ * already existed in the tree. A superset would admit states that are
+ * nonsense for their subject: a step ending `approval-required`, a run ending
+ * `partial`. So: separate vocabularies, one registry, mappings only where
+ * execution actually crosses.
+ *
+ * **Mappings are not written for symmetry.** Exactly one crossing exists
+ * (`DispatchOutcome` -> phase, in `orchestration_record.ts`). A total
+ * phase<->step<->run mapping would be nine relations of which one is real, and
+ * the eight invented ones would read as contract.
+ *
+ * `revisit-if`: a producer needs a value its vocabulary cannot express, or a
+ * second real crossing appears, or producer analysis shows two of the three
+ * subjects share identical terminal semantics with a lossless mapping — at
+ * which point unifying those two becomes the cheaper answer.
+ *
+ * Type-only + literal arrays. No `node:` import, so any surface may read it.
+ */
+
+/**
+ * Outcome of one audit-log line — a `/work` phase.
+ *
+ * Authoritative for `docs/contracts/audit-log-v1.md`'s `outcome` row. The
+ * binding is a test, not an import, because a markdown contract cannot import:
+ * `tests/contracts/outcome_vocabularies.test.ts`.
+ */
+export const PHASE_OUTCOMES = ['success', 'blocked', 'skipped', 'error'] as const;
+export type PhaseOutcome = (typeof PHASE_OUTCOMES)[number];
+
+/**
+ * Outcome of one work-engine step.
+ *
+ * Declared in `src/agent-src/templates/scripts/work_engine/delivery_state.ts`,
+ * which is a TEMPLATE and self-contained by contract — no template file
+ * imports from `src/scripts/`. So this is the lint-checked mirror, not the
+ * declaration, and the same test asserts the two agree.
+ */
+export const STEP_OUTCOMES = ['success', 'blocked', 'partial'] as const;
+export type StepOutcome = (typeof STEP_OUTCOMES)[number];
+
+/**
+ * Terminal state of one command or gate run.
+ *
+ * Authoritative for `contexts/execution/terminal-states.md`. Re-exported by
+ * `outcome_envelope.ts` as `TerminalState`, which stays the public surface —
+ * `runtime_journal.test.ts` pins that import path, and an anti-fork assertion
+ * there already prevents a second declaration.
+ */
+export const RUN_TERMINAL_STATES = [
+    'success',
+    'clean-no-op',
+    'blocked',
+    'approval-required',
+    'exhausted',
+    'stagnated',
+] as const;
+export type RunTerminalState = (typeof RUN_TERMINAL_STATES)[number];
+
+/**
+ * The crossings that exist. One row, because one crossing is real.
+ *
+ * Read as: code at `from` translates a value of `source` into a value of
+ * `target`. A row is added when execution starts crossing, never in advance.
+ */
+export const CROSS_DOMAIN_MAPPINGS = [
+    {
+        source: 'DispatchOutcome',
+        target: 'phase',
+        at: 'src/scripts/_lib/orchestration_record.ts',
+        fn: 'envelopeOutcome',
+        /**
+         * The mapping is VERSIONED as of 2026-08-30
+         * (road-to-experience-loop-broadening 2.2). Version 1 was
+         * unconditional: DONE / DONE_WITH_CONCERNS always became `success`.
+         * Version 2 is contract-gated -- a `code-change` dispatch claiming
+         * success with a MEASURED empty diff no longer does.
+         *
+         * Recorded here rather than only at the call site because this registry
+         * is the one place a reader looks to learn that a crossing exists, and a
+         * crossing whose semantics changed silently is worse than one nobody
+         * documented. Lines carry `outcome_semantics`; an absent field is
+         * version 1.
+         */
+        semantics_version: 2,
+    },
+] as const;
+
+/** Is this string a phase outcome? The guard the audit-log consumer was missing. */
+export function isPhaseOutcome(v: unknown): v is PhaseOutcome {
+    return typeof v === 'string' && (PHASE_OUTCOMES as readonly string[]).includes(v);
+}
+
+/** Is this string a run terminal state? */
+export function isRunTerminalState(v: unknown): v is RunTerminalState {
+    return typeof v === 'string' && (RUN_TERMINAL_STATES as readonly string[]).includes(v);
+}