@event4u/agent-config 14.14.0 → 14.15.0

package/src/scripts/_lib/outcome_vocabularies.ts

@@ -13,7 +13,7 @@
  * |---|---|---|---|
  * | 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 |
+ * | run   | one command or gate RUN | here, consumed by `outcome_envelope` | 7 |  code-comment-allow report-comment -- one row of a pre-existing three-row table documenting the three vocabularies; the digit changed from 6 to 7 with the vocabulary, and the table is the registry's whole point
  *
  * All three are declared in code AND emitted today. `skipped` and `error` are
  * not aspirational: `envelopeOutcome` in `orchestration_record.ts` returns
@@ -33,16 +33,42 @@
  * `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.
+ * **Mappings are not written for symmetry.** Two crossings exist, and both are
+ * places where execution actually translates: `DispatchOutcome` -> phase in
+ * `orchestration_record.ts`, and `LadderAction` -> run in
+ * `continuation_ladder.ts` (added 2026-09-03 with the seventh run state, so the
+ * state has a producer rather than being a word nothing emits). A total
+ * phase<->step<->run mapping would be nine relations of which two are real, and
+ * the seven 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.
  *
+ * **The run vocabulary grew to seven on 2026-09-03** — exactly the first branch
+ * of the reopening condition above: the continuation ladder needed a word for a
+ * run whose plan premise moved, and had none. AI council (anthropic/claude-sonnet-4-5 +
+ * openai/codex-default, three rounds, blind chairman) resolved it unanimously
+ * as option (a), extend rather than overload `blocked` with a reason field. The
+ * seats attached the same prerequisites, discharged here: a versioned value
+ * domain ({@link RUN_TERMINAL_VOCABULARY_VERSION}), a tolerant read
+ * ({@link readRunTerminalState}), a declared downgrade
+ * ({@link RUN_TERMINAL_STATE_DOWNGRADE}) and the rollback trigger below.
+ *
+ * **Rollback trigger, stated rather than instrumented.** Withdraw
+ * `premise-invalidated` — remove it from {@link RUN_TERMINAL_STATES} and let the
+ * ladder rung report its declared downgrade `blocked` instead — on EITHER of:
+ * (1) any consumer is observed failing (a throw, a refused write, a dropped
+ * record) on encountering the value, or (2) `readRunTerminalState` returns
+ * `null` for a persisted value in normal operation, which would mean a writer
+ * emitted something this registry does not know. Both are single-occurrence
+ * triggers, not rates: the downgrade mapping already exists, so withdrawal
+ * costs one commit and no migration, and there is no reason to tolerate a
+ * budget of failures before paying that. No telemetry is built for this and
+ * none is claimed — condition (1) surfaces as a failing run and (2) as a null
+ * where a value was written.
+ *
  * Type-only + literal arrays. No `node:` import, so any surface may read it.
  */
 
@@ -82,9 +108,99 @@ export const RUN_TERMINAL_STATES = [
     'approval-required',
     'exhausted',
     'stagnated',
+    /**
+     * The plan premise this run was built on no longer holds — the situational
+     * -awareness fingerprint the run engaged under (`origin/main` plus every open
+     * PR head) was re-observed and differs.
+     *
+     * Added by `road-to-wired-instruments` Phase 2 under the AI-council decision
+     * of 2026-09-03 (option (a), unanimous). It is NOT `blocked` with a reason
+     * field: premise invalidation is operationally distinct from a missing
+     * precondition and from an exhausted budget, and folding it into either loses
+     * both aggregation by state and type-enforced exhaustive handling. The
+     * remedy differs too — re-probe and re-plan, where `blocked` says obtain the
+     * missing thing and `exhausted` says the budget was too small.
+     */
+    'premise-invalidated',
 ] as const;
 export type RunTerminalState = (typeof RUN_TERMINAL_STATES)[number];
 
+/**
+ * Version of the RUN vocabulary's VALUE DOMAIN — bumped when a member is added
+ * or removed, never for prose.
+ *
+ * Distinct from any table version: `runtime_journal.JOURNAL_SCHEMA_VERSION`
+ * covers tables and columns and is unaffected by a widening of what one column
+ * may contain, so a value-domain change needs its own number or it travels
+ * unversioned. A persisted shape carrying a `RunTerminalState` stamps THIS
+ * number beside the value, so a reader can tell a value it does not know from a
+ * value that is corrupt.
+ *
+ * v1 — the six original states.
+ * v2 — adds `premise-invalidated` (2026-09-03).
+ */
+export const RUN_TERMINAL_VOCABULARY_VERSION = 2;
+
+/** The vocabulary version each member first appeared in. */
+export const RUN_TERMINAL_STATE_SINCE: Readonly<Record<RunTerminalState, number>> = {
+    success: 1,
+    'clean-no-op': 1,
+    blocked: 1,
+    'approval-required': 1,
+    exhausted: 1,
+    stagnated: 1,
+    'premise-invalidated': 2,
+};
+
+/**
+ * What a consumer pinned to an older vocabulary version reports instead.
+ *
+ * `premise-invalidated` -> `blocked`: of the six v1 states it is the only one
+ * that is honest for a reader that cannot represent it — the run stopped on an
+ * external condition it cannot resolve by iterating. Mapping it to `exhausted`
+ * would invite the wrong remedy (raise the budget), which is the exact
+ * confusion the contract's own `exhausted`/`stagnated` split exists to prevent.
+ *
+ * Every member introduced after v1 MUST have a row here; `outcome_vocabularies`
+ * contract tests assert that, so a future eighth value cannot ship undowngradable.
+ */
+export const RUN_TERMINAL_STATE_DOWNGRADE: Readonly<Partial<Record<RunTerminalState, RunTerminalState>>> = {
+    'premise-invalidated': 'blocked',
+};
+
+/**
+ * The state a consumer pinned at `toVersion` should report for `state`.
+ *
+ * Returns the state unchanged when it already existed at that version, the
+ * declared downgrade when it did not, and `null` for a string this vocabulary
+ * does not know at all — never a throw, because this is the function a reader
+ * of PERSISTED data calls, and persisted data outlives the code that wrote it.
+ */
+export function downgradeRunTerminalState(
+    state: string,
+    toVersion: number,
+): RunTerminalState | null {
+    if (!isRunTerminalState(state)) return null;
+    if ((RUN_TERMINAL_STATE_SINCE[state] ?? 1) <= toVersion) return state;
+    return RUN_TERMINAL_STATE_DOWNGRADE[state] ?? null;
+}
+
+/**
+ * Tolerant read of a persisted terminal state: a member returns itself,
+ * anything else returns `null`. Never throws.
+ *
+ * `null` rather than a fabricated fallback is the load-bearing choice. This
+ * vocabulary's own consumers already treat a null terminal state as "not
+ * recorded" (`repeated_failure` counts it under `unknown`), and that is exactly
+ * what an unrecognised value IS to a reader that cannot name it. Substituting
+ * `blocked` here would manufacture a measurement out of an absence — the
+ * downgrade above is for a value the reader KNOWS is newer, which is a
+ * different fact from a value it cannot place.
+ */
+export function readRunTerminalState(v: unknown): RunTerminalState | null {
+    return isRunTerminalState(v) ? v : null;
+}
+
 /**
  * The crossings that exist. One row, because one crossing is real.
  *
@@ -112,6 +228,20 @@ export const CROSS_DOMAIN_MAPPINGS = [
          */
         semantics_version: 2,
     },
+    {
+        source: 'LadderAction',
+        target: 'run',
+        at: 'src/scripts/_lib/continuation_ladder.ts',
+        fn: 'terminalStateFor',
+        /**
+         * Version 1, and the mapping is TOTAL over `LadderAction` by
+         * construction: `TERMINAL_STATE_BY_ACTION` is a `Record<LadderAction,
+         * RunTerminalState | null>`, so adding a rung without deciding its
+         * terminal state does not compile. `engage` maps to null because it is
+         * the one action that is not terminal.
+         */
+        semantics_version: 1,
+    },
 ] as const;
 
 /** Is this string a phase outcome? The guard the audit-log consumer was missing. */

package/src/scripts/_lib/release_highlights.ts

@@ -279,9 +279,57 @@ export function derive_categories(commits: readonly SpanCommit[]): Record<string
  *
  * A label with no evidence is omitted, so the caller's `_none_` default still
  * applies where `_none_` is the true answer. One line per label keeps the
- * rendered head inside its cap; SHA citations are capped at `DERIVED_SHA_CAP`
- * with an explicit remainder count rather than a silent truncation.
+ * rendered head inside its cap; citations are capped at `DERIVED_SHA_CAP` with
+ * an explicit remainder count rather than a silent truncation.
+ *
+ * **PUBLISHABLE BY DEFAULT since 2026-09-03, and this is the third position
+ * this line has held.** It shipped `DERIVED_MARKER` plus a CATEGORY
+ * DESCRIPTION — "rule/schema diffs, breaking commits or removed public surface
+ * in 5a3b7c5". The 2026-09-01 flip then made that marker a hard refusal, and
+ * the combination had a consequence nobody priced: every release of this
+ * package touches `src/rules/` or `src/scripts/schemas/`, so **Behaviour
+ * changes** is always substantiated, so the generator always wrote a line the
+ * gate always refused. Every release halted, by construction. That was
+ * recorded as "the cadence the flip chose"; the maintainer's instruction of
+ * 2026-09-03 — *"fix the bug so this stops happening"* — is the authority for
+ * removing it.
+ *
+ * The fix is not a weaker gate, and it is not the marker moving somewhere
+ * cheaper (that was 2026-09-03's first attempt, `guard_release_curation`,
+ * which relocated the halt without removing it). It is the writer no longer
+ * emitting text that cannot ship. Two changes, and the first is what makes the
+ * second honest:
+ *
+ * 1. The line now states the COMMIT SUBJECTS behind each category, not the
+ *    name of the category's own detection rule. "hooks:effect reports whether
+ *    a bound concern fires (b0a03a7)" is a claim a reader can use; "rule/schema
+ *    diffs in b0a03a7" is a restatement of why the classifier fired.
+ * 2. `DERIVED_MARKER` is gone from the emission, so nothing unpublishable is
+ *    ever written and no release halts on the writer's own output.
+ *
+ * What is deliberately NOT relaxed: `highlight_contradictions` still refuses a
+ * human editing a substantiated line down to `_none_`, which is the failure the
+ * false 9.13.0 and 9.14.0 heads actually were; and the marker constant and its
+ * four guard sites stay, now covering only a marker somebody writes BY HAND.
+ * The honest cost of this change, stated rather than left to be discovered: the
+ * head is a categorised view of the span rather than curated prose, and it
+ * ships without a human having read it. An operator who wants better prose
+ * still edits it — they are no longer STOPPED until they do.
  */
+/**
+ * A commit subject reduced to the claim inside it.
+ *
+ * Drops the conventional-commit `type(scope):` prefix, because "feat(hooks):"
+ * is metadata about the commit and the changelog's own commit lists already
+ * carry it — what a highlight line needs is the sentence after the colon. Keeps
+ * the subject otherwise verbatim: rewording it here would make the head a
+ * paraphrase of the span rather than a citation of it, and the whole point of
+ * this module is that the two cannot disagree.
+ */
+function _claim_text(subject: string): string {
+    return subject.replace(/^[a-z]+(?:\([^)]*\))?!?:\s*/u, '').trim();
+}
+
 export function render_derived_head_values(
     hits: Readonly<Record<string, readonly CategoryHit[]>>,
 ): Record<string, string> {
@@ -292,11 +340,19 @@ export function render_derived_head_values(
         if (!reason || ev.length === 0) {
             continue;
         }
-        const shas = ev.map((h) => h.sha.slice(0, 7));
-        const shown = shas.slice(0, DERIVED_SHA_CAP);
-        const remainder = shas.length - shown.length;
-        const more = remainder > 0 ? ` +${remainder} more` : '';
-        out[label] = `${DERIVED_MARKER} ${reason} in ${shown.join(', ')}${more}.`;
+        const shown = ev.slice(0, DERIVED_SHA_CAP);
+        const remainder = ev.length - shown.length;
+        const more = remainder > 0 ? `; +${String(remainder)} more` : '';
+        const cited = shown
+            .map((h) => `${_claim_text(h.text)} (${h.sha.slice(0, 7)})`)
+            .join('; ');
+        // `reason` still names the classifier that fired, kept as the fallback
+        // for a hit whose subject renders empty after trimming — a subject that
+        // is nothing but a conventional-commit prefix. Without it the line
+        // would read "( b0a03a7)".
+        out[label] = cited ? `${cited}${more}.` : `${reason} in ${shown
+            .map((h) => h.sha.slice(0, 7))
+            .join(', ')}${more}.`;
     }
     return out;
 }
@@ -331,14 +387,23 @@ export function render_derived_head_values(
  * `CURATED_HEAD_INSTRUCTION` is a named sentinel imported from the module that
  * defines it — never a shape match over comment prose, which would reject
  * unrelated legitimate comments and miss this one after a reword.
+ *
+ * `where` names the branch the remedy edit belongs on, because the same
+ * blockers are now read at a FOURTH site that is not on `main`:
+ * `guard_release_branch_push` refuses the release branch's first push, where
+ * the file to edit is on `release/X.Y.Z`. One definition of the blockers with a
+ * parameterised remedy beats a second copy of the message that drifts.
  */
-export function publication_blockers(sectionBody: string, version: string): string[] {
+export function publication_blockers(
+    sectionBody: string,
+    version: string,
+    where = '`main`',
+): string[] {
     const out: string[] = [];
     if (sectionBody.includes(DERIVED_MARKER)) {
         out.push(
             `the ${version} section still carries \`${DERIVED_MARKER}\` — the generator's ` +
-                'draft head, not a curated claim. Rewrite those line(s) on ' +
-                `${'`main`'} and re-run.`,
+                `draft head, not a curated claim. Rewrite those line(s) on ${where} and re-run.`,
         );
     }
     if (sectionBody.includes(CURATED_HEAD_INSTRUCTION)) {

package/src/scripts/_lib/repeated_failure.ts

@@ -39,9 +39,26 @@ export const SUCCESS_TERMINALS: ReadonlySet<RunTerminalState> = new Set([
     'clean-no-op',
 ]);
 
+/**
+ * Neither a failure nor a success for this metric, and each excluded for its own
+ * reason rather than by omission.
+ *
+ * `approval-required` is the safety floor working; counting a floor doing its
+ * job as a failure would make the metric fall every time governance fires.
+ *
+ * `premise-invalidated` is the same shape one layer out: the run stopped because
+ * the world it planned against moved, which is the drift detector working, not
+ * the work failing. It is also the state whose base rate is set by OTHER people's
+ * pushes rather than by this run's quality — `origin/main` moves constantly — so
+ * counting it as a failure would make the repeated-failure rate track repository
+ * traffic. That is the concrete form of this roadmap's Risk 1, arriving through
+ * the metric instead of through the ladder.
+ */
+const EXCLUDED: ReadonlySet<RunTerminalState> = new Set(['approval-required', 'premise-invalidated']);
+
 // Every terminal state is classified or deliberately excluded -- silence about
 // one is how a metric quietly changes meaning when the vocabulary grows.
-const CLASSIFIED = new Set<string>([...FAILURE_TERMINALS, ...SUCCESS_TERMINALS, 'approval-required']);
+const CLASSIFIED = new Set<string>([...FAILURE_TERMINALS, ...SUCCESS_TERMINALS, ...EXCLUDED]);
 const _unclassified = RUN_TERMINAL_STATES.filter((t) => !CLASSIFIED.has(t));
 if (_unclassified.length > 0) {
     throw new Error(
@@ -86,7 +103,7 @@ export function repeatedFailureRate(
         // `ep.terminal_state` is already the AMENDED verdict: reconstructEpisode
         // drops superseded rows and takes the LAST effective terminal state.
         const t = ep.terminal_state;
-        if (t === null || !CLASSIFIED.has(t) || t === 'approval-required') {
+        if (t === null || !CLASSIFIED.has(t) || EXCLUDED.has(t)) {
             unknown += 1;
             continue;
         }

package/src/scripts/_lib/runtime_journal.ts

@@ -173,7 +173,7 @@ import type { DatabaseSync } from 'node:sqlite';
 
 import { current_branch, git_common_dir, git_dir } from './git_common_dir.js';
 import type { TerminalState } from './outcome_envelope.js';
-import { RUN_TERMINAL_STATES } from './outcome_vocabularies.js';
+import { readRunTerminalState, RUN_TERMINAL_STATES } from './outcome_vocabularies.js';
 import {
     isSqliteAvailableSync,
     loadSqliteSync,
@@ -303,7 +303,7 @@ export const CONSUMPTION_STATES = ['consumed', 'partially-consumed', 'rejected-w
 export type Consumption = (typeof CONSUMPTION_STATES)[number];
 
 /**
- * The six terminal states as a runtime array.
+ * The run terminal states as a runtime array.
  *
  * Re-export of `RUN_TERMINAL_STATES` from `outcome_vocabularies.ts`. It used to
  * be a second literal list here, guarded by two type-level assertions that
@@ -316,6 +316,12 @@ export type Consumption = (typeof CONSUMPTION_STATES)[number];
  *
  * The name is kept because it is exported and pinned by
  * `tests/scripts/runtime_journal.test.ts:205,207`.
+ *
+ * Growing this list does NOT move {@link JOURNAL_SCHEMA_VERSION}: that covers
+ * tables and columns and a mismatch discards the store, while a widened value
+ * domain changes neither. The domain carries its own version in the registry
+ * (`RUN_TERMINAL_VOCABULARY_VERSION`), and the read path tolerates a value it
+ * does not know rather than trusting the column — see `toEvent`.
  */
 export const TERMINAL_STATES = RUN_TERMINAL_STATES;
 
@@ -1019,7 +1025,7 @@ export function recordEvent(h: JournalHandle, input: RecordEventInput): JournalE
         !(TERMINAL_STATES as readonly string[]).includes(input.terminal_state)
     ) {
         throw new JournalContractError(
-            `terminal_state ${JSON.stringify(input.terminal_state)} is not one of the six.`,
+            `terminal_state ${JSON.stringify(input.terminal_state)} is not in the run vocabulary.`,
         );
     }
     if (
@@ -1105,7 +1111,8 @@ function toEvent(r: Record<string, unknown>): JournalEvent {
         worktree_id: String(r['worktree_id']),
         at: String(r['at']),
         capability: String(r['capability']),
-        terminal_state: (r['terminal_state'] as TerminalState | null) ?? null,
+        // Tolerant, not a cast: a value this build cannot place reads as null.
+        terminal_state: readRunTerminalState(r['terminal_state']),
         return_ref: (r['return_ref'] as string | null) ?? null,
         verification_ref: (r['verification_ref'] as string | null) ?? null,
         consumption: (r['consumption'] as Consumption | null) ?? null,