@event4u/agent-config 14.18.0 → 14.20.0

package/src/scripts/_lib/subagent_capsule.ts

@@ -109,7 +109,39 @@ export interface WorkerCapsule {
  * affordable precisely here — an envelope is consume-once and expires in
  * hours, so the migration window is a session, not a release.
  */
-export const CAPSULE_SCHEMA_VERSION = 3;
+export const CAPSULE_SCHEMA_VERSION = 4;
+
+/**
+ * Versions a reader ACCEPTS. Version 4 is the first bump that is purely
+ * ADDITIVE, and that is why it widens the accepted set instead of replacing it.
+ *
+ * The compatibility contract is stated here rather than inferred.
+ *
+ * - **Scope.** The version is ENVELOPE-WIDE, not per-variant. One number
+ *   describes the whole schema module, so a variant added later does not
+ *   silently re-date records of another variant.
+ * - **New reader, old record.** A v3 record validates. Its required set is v3's
+ *   — the fields added at v4 are not demanded of it, because demanding them
+ *   would be a retroactive requirement on records already written.
+ * - **Old reader, new record.** A v3-only reader rejects a v4 record with the
+ *   version violation named. That is the pre-existing loud-discard behaviour and
+ *   is affordable for the same reason v3 gave: a record is consume-once and
+ *   expires in {@link RECYCLE_MAX_AGE_HOURS} hours, so the migration window is a
+ *   session, not a release.
+ * - **Unknown version.** Anything outside this set is rejected with the set
+ *   printed. Absent is not a pass — an undated record is not "probably current".
+ * - **Unknown variant.** Rejected by `variant` check, never coerced. A reader
+ *   that does not know a variant must not guess at its required fields.
+ * - **Rollback.** Reverting to a v3-only reader after v4 records exist discards
+ *   those records loudly rather than mis-reading them; the loss is one session's
+ *   resume, which is the same loss as no record at all.
+ *
+ * Adding a required field is what forced v3 to be a hard break. v4 adds
+ * `successful_approaches`, `open_questions` and `predecessor`, and requires the
+ * first and third **only of records that declare themselves v4** — so no
+ * previously valid record becomes invalid.
+ */
+export const ACCEPTED_CAPSULE_VERSIONS: readonly number[] = [3, 4];
 
 /** The two CHECKPOINT variants sharing this schema. */
 export const CAPSULE_VARIANTS = ['worker', 'main_session'] as const;
@@ -280,6 +312,30 @@ export function validateCapsule(input: unknown): string[] {
  * wire gate; this variant is consumed from a FILE by
  * `handoff_context_hook`, so the module itself must be the strict gate.
  */
+/**
+ * The four questions a resuming session asks, and the field that answers each —
+ * written down rather than left implicit, because the gap that produced
+ * `successful_approaches` stayed invisible for exactly as long as the mapping
+ * was unwritten: three of the four had a field, the fourth had nothing, and no
+ * reader of the schema had a reason to notice.
+ *
+ * *What was it about?* is answered directly by `task`, with `summary` carrying
+ * the one-line outcome. *What was the goal?* is answered only by PROXY:
+ * `acceptance_criteria` states what **done** means, which is the goal expressed
+ * as a test rather than as an intention, and `next_task` narrows it to the
+ * successor's first move. *What did NOT work?* is `failed_approaches`, direct,
+ * required, explicit `none`. *What DID work?* is `successful_approaches`,
+ * direct, required at version 4, explicit `none`.
+ *
+ * The one proxy is labelled a proxy on purpose. A goal can be met by criteria
+ * nobody wrote down, so reading `acceptance_criteria` as the goal itself is the
+ * error the label exists to prevent.
+ *
+ * Everything else the schema carries — `remaining`, `not_carried_forward`,
+ * `constraints`, `decisions`, `open_questions`, the drift anchor — answers a
+ * question the four do not ask. That is not surplus; it is simply outside this
+ * mapping.
+ */
 export interface MainSessionRecycleEnvelope {
     /** Must be {@link CAPSULE_SCHEMA_VERSION}. */
     capsule_version: number;
@@ -371,6 +427,59 @@ export interface MainSessionRecycleEnvelope {
      * successor re-burning a recorded dead end.
      */
     failed_approaches: string[];
+    /**
+     * Approaches this session tried and KEPT — "did X, it worked because Y".
+     *
+     * **The counterpart `failed_approaches` did not have**, and its absence was
+     * a structural defect rather than an omission: a record that can say what to
+     * avoid and cannot say what to repeat is pessimistic by construction, and a
+     * successor re-derives every working decision from scratch while being
+     * warned off the dead ends.
+     *
+     * Required at capsule version 4 with at least one entry, for exactly the
+     * reason `failed_approaches` is: a session that kept nothing writes the
+     * single entry `none` explicitly, so "nothing worked" stays distinguishable
+     * from "nobody wrote it down". An optional field would re-create the silence
+     * one layer down.
+     */
+    successful_approaches?: string[];
+    /**
+     * Questions this session could not settle — the successor's first reading
+     * list. The worker variant has carried `open_risks` since v1
+     * (`WorkerCapsule.open_risks`) and the handoff template asks for open
+     * questions in prose; the session variant had neither, so the one thing a
+     * resuming session most needs to not silently drop had no field.
+     *
+     * Optional, unlike `successful_approaches`: an empty question list is not
+     * the same asymmetry — a record with nothing open is a complete claim, and
+     * `remaining` already carries the work.
+     */
+    open_questions?: string[];
+    /**
+     * The session that WROTE this record.
+     *
+     * Added with `predecessor` and not separable from it: an edge needs two
+     * endpoints, and before v4 a record carried neither. `workspace` answers
+     * "which checkout", which is what the identity check needs; it cannot
+     * answer "which session", which is what a chain needs.
+     */
+    session_id?: string;
+    /**
+     * The session this one continues, or the explicit string `none`.
+     *
+     * Required at capsule version 4. Before it, `grep -rn
+     * "predecessor_session\|lineage_id" src/` returned 0 and the reader
+     * injected whatever record was lying at the path — which is not the same
+     * question as "which record is mine" that the session key answers. A key
+     * says whose record this is; a predecessor edge says which record this
+     * session should be reading.
+     *
+     * `none` is a STATED ABSENCE, never an empty string or a missing field. The
+     * first session in a workspace has no predecessor and says so, so a reader
+     * never waits on something that will not arrive — and a NAMED predecessor
+     * that is absent is a refusal, never a fall-through to a different record.
+     */
+    predecessor?: string;
     /**
      * Drift anchor — all three, or none of them is one. Identity is the
      * canonicalized remote (or the realpath of the common git dir when there
@@ -615,6 +724,10 @@ const RECYCLE_ENVELOPE_KEYS: ReadonlySet<string> = new Set([
     'next_task',
     'suggested_skills',
     'failed_approaches',
+    'successful_approaches',
+    'open_questions',
+    'predecessor',
+    'session_id',
     'repo_identity',
     'branch',
     'head',
@@ -644,9 +757,16 @@ export function validateRecycleEnvelope(input: unknown): string[] {
         }
     }
 
-    if (e['capsule_version'] !== CAPSULE_SCHEMA_VERSION) {
-        errors.push(`capsule_version must be ${CAPSULE_SCHEMA_VERSION}`);
+    const version = e['capsule_version'];
+    if (typeof version !== 'number' || !ACCEPTED_CAPSULE_VERSIONS.includes(version)) {
+        errors.push(`capsule_version must be one of ${ACCEPTED_CAPSULE_VERSIONS.join(' | ')}`);
     }
+    // Requiredness is version-conditional, and only in the additive direction:
+    // a v4 record owes the v4 fields, a v3 record owes exactly what v3 owed.
+    // Demanding the new fields of an already-written record would be a
+    // retroactive requirement, which is the one thing the recorded schema lock
+    // forbids ("add fields or variants, never repurpose or remove one").
+    const atV4 = version === 4;
     if (e['variant'] !== 'main_session') {
         errors.push("variant must be 'main_session'");
     }
@@ -697,6 +817,38 @@ export function validateRecycleEnvelope(input: unknown): string[] {
         );
     }
 
+    // Version 4 additions. `successful_approaches` mirrors `failed_approaches`
+    // exactly — required with >= 1 entry, `none` written explicitly — because
+    // the asymmetry between the two is the defect the field exists to remove,
+    // and an optional counterpart to a required field re-creates it.
+    checkList(errors, 'successful_approaches', e['successful_approaches'], MAX_LINE_CHARS, atV4);
+    if (Array.isArray(e['successful_approaches']) && e['successful_approaches'].length === 0) {
+        errors.push(
+            'successful_approaches must carry at least one entry — write "none" explicitly, so ' +
+                'silence and "nothing worked" stay distinguishable',
+        );
+    }
+    checkList(errors, 'open_questions', e['open_questions'], MAX_LINE_CHARS, false);
+
+    // The predecessor edge (Phase 2.3). Required at v4, and an EMPTY value is
+    // not an answer: `none` is a claim ("this session starts a chain"), absence
+    // is a reader waiting for something that will not arrive.
+    const predecessor = e['predecessor'];
+    if (predecessor === undefined) {
+        if (atV4) {
+            errors.push(
+                'predecessor is required — name the session this one continues, or write "none" ' +
+                    'explicitly for the first session in a workspace',
+            );
+        }
+    } else if (!isShortLine(predecessor, MAX_REF_CHARS)) {
+        errors.push(`predecessor must be a single line of 1–${MAX_REF_CHARS} chars ("none" when there is no predecessor)`);
+    }
+
+    if (e['session_id'] !== undefined && !isShortLine(e['session_id'], MAX_REF_CHARS)) {
+        errors.push(`session_id must be a single line of 1–${MAX_REF_CHARS} chars`);
+    }
+
     // Drift anchor (Phase 3.2). Optional as a set — an older envelope simply
     // has none — but each present field must still be a short line.
     for (const field of ['repo_identity', 'branch', 'head', 'status_summary', 'last_verify'] as const) {

package/src/scripts/_lib/surface.ts

@@ -0,0 +1,86 @@
+/**
+ * surface — the IDE / CLI / cloud dimension of a dispatch, as an ENVELOPE
+ * field rather than a platform key.
+ *
+ * WHY A FIELD AND NOT A PLATFORM. `_lib/session_register.ts` records that the
+ * capability lattice has no IDE/CLI dimension, which is why it reports cursor
+ * covered whether or not its per-turn slots fire there. Splitting `cursor`
+ * into `cursor-ide` / `cursor-cli` would change `--platform`, the eight
+ * platform identifiers, and every manifest row keyed on them. A field changes
+ * none of those and is still the thing `host_lowering.yaml`'s `(host, surface,
+ * slot)` key needs.
+ *
+ * WHAT THIS CAN AND CANNOT DECIDE — the honest half.
+ *
+ * `unknown` is the default and, today, very nearly the only answer. Nothing in
+ * this tree distinguishes an IDE session from a CLI one on any host: no host
+ * payload observed here carries such a marker, and inferring it from a TTY or
+ * a terminal name would be a guess wearing a function's authority — the exact
+ * move the surrounding roadmap exists to remove. So there is no `ide` or `cli`
+ * branch. When a host is observed to send a distinguishing marker, it is added
+ * to {@link CLOUD_PAYLOAD_MARKERS}'s sibling with a dated citation, and the
+ * branch arrives with the evidence rather than ahead of it.
+ *
+ * The `cloud` branch is a DECLARED VOCABULARY, not an observation. This package
+ * will honour these payload keys if a host sends one; none has been observed
+ * sending one. That distinction is the point: the mechanism is real and tested,
+ * the host claim is absent and says so.
+ */
+
+/** The closed surface vocabulary. `unknown` is the safe default. */
+export const SURFACES = ['ide', 'cli', 'cloud', 'unknown'] as const;
+export type Surface = (typeof SURFACES)[number];
+
+/**
+ * Payload keys whose truthy presence declares a background / cloud agent.
+ *
+ * Declared, not observed — see the module header. Kept as a list so a host that
+ * starts sending one needs no code change, only a citation in this comment.
+ */
+export const CLOUD_PAYLOAD_MARKERS: readonly string[] = [
+    'background_agent',
+    'is_background',
+    'isBackgroundAgent',
+];
+
+/** Explicit override, for a caller that already knows the surface. */
+export const SURFACE_ENV_VAR = 'AGENT_CONFIG_SURFACE';
+
+function _isSurface(v: unknown): v is Surface {
+    return typeof v === 'string' && (SURFACES as readonly string[]).includes(v);
+}
+
+/**
+ * Resolve the surface for one dispatch.
+ *
+ * Precedence: an explicit environment override, then a declared payload
+ * marker, then `unknown`. An unrecognised override value is ignored rather
+ * than trusted — a typo must not become a capability claim.
+ */
+export function detectSurface(
+    payload: unknown,
+    env: Record<string, string | undefined> = process.env,
+): Surface {
+    const override = env[SURFACE_ENV_VAR];
+    if (_isSurface(override)) return override;
+
+    if (typeof payload === 'object' && payload !== null && !Array.isArray(payload)) {
+        const obj = payload as Record<string, unknown>;
+        for (const key of CLOUD_PAYLOAD_MARKERS) {
+            if (obj[key]) return 'cloud';
+        }
+    }
+    return 'unknown';
+}
+
+/**
+ * Read a persisted or caller-supplied surface value.
+ *
+ * Tolerant, not a cast: an unrecognised value — a row written by a newer build,
+ * a typo, an absent field — reads as `unknown`. Same posture as
+ * `readRunTerminalState`, and for the same reason: a value this build cannot
+ * place must not fail a write or a read.
+ */
+export function readSurface(v: unknown): Surface {
+    return _isSurface(v) ? v : 'unknown';
+}

package/src/scripts/_lib/ui_authority.ts

@@ -341,3 +341,119 @@ export function operationConflicts(authority: UiAuthority, op: Operation): Confl
     }
     return out;
 }
+
+/* -------------------------------------------------------------------------- */
+/* Antipattern signal classes against the precedence list                      */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The five classes a `design-antipatterns.md` catalog row may claim.
+ *
+ * Kept here, beside the precedence list, rather than in the catalog gate: the
+ * question "may this signal overrule what the user supplied" is a precedence
+ * question, and precedence lives in exactly one module by construction.
+ */
+export type SignalClass =
+    | 'floor'
+    | 'invariant'
+    | 'craft-presumption'
+    | 'style-preference'
+    | 'reference-constraint';
+
+/** The two classes that are opinions rather than thresholds. */
+export const SOFT_CLASSES = ['craft-presumption', 'style-preference'] as const;
+
+export interface SignalVerdict {
+    /**
+     * `blocks` — refuse the surface. `flags` — surface it as a rebuttable
+     * presumption. `yields` — say nothing: something with more authority has
+     * already decided this.
+     */
+    outcome: 'blocks' | 'flags' | 'yields';
+    /** The precedence level that outranked it, numbered as in this file's header. */
+    outranked_by: { level: number; source: ProvenanceSource; detail: string } | null;
+    reason: string;
+}
+
+/**
+ * Where a soft signal sits against the precedence list.
+ *
+ * A craft presumption is a good default and nothing more. When the run has a
+ * supplied reference (4), a coherent incumbent (5), or a project `DESIGN.md`
+ * register (6), that artifact has already decided the question the presumption
+ * would re-open, and re-opening it is the redesign-by-taste failure
+ * `design-fidelity` exists to stop.
+ *
+ * A `floor` or an `invariant` is NOT a taste call — an accessibility threshold
+ * or a structural correctness rule — so nothing on the list releases it, and a
+ * reference artifact that violates one is a finding about the reference.
+ *
+ * LEVELS 1–3 ARE DELIBERATELY NOT MECHANISED HERE. Explicit user authority, a
+ * registered hard constraint, and the surface brief all outrank a presumption a
+ * fortiori, but `Signals` carries them only as whole-surface fields
+ * (`surface_mode`, `register`, `change_intent`) with no per-pattern statement.
+ * Reading a brief's mere presence as blanket permission for every antipattern
+ * would silence the catalog on every briefed surface, which is the opposite of
+ * what those levels mean. A per-pattern override is `DESIGN.md`'s declared
+ * suppression, which is level 6 and IS handled.
+ */
+export function resolveSignal(signalClass: SignalClass, signals: Signals = {}): SignalVerdict {
+    if (signalClass === 'floor' || signalClass === 'invariant') {
+        return {
+            outcome: 'blocks',
+            outranked_by: null,
+            reason:
+                `a ${signalClass} is a threshold, not a preference — no supplied artifact releases it, `
+                + 'and an artifact that violates one is a finding about the artifact',
+        };
+    }
+
+    if (signalClass === 'reference-constraint') {
+        const present = signals.reference !== undefined || signals.design_md?.present === true;
+        return present
+            ? {
+                outcome: 'blocks',
+                outranked_by: null,
+                reason: 'the reference or DESIGN.md this constraint is bound to is present in this run, so it carries that artifact\'s own authority',
+            }
+            : {
+                outcome: 'flags',
+                outranked_by: null,
+                reason: 'the reference this constraint is bound to is not present in this run, so it has no artifact behind it',
+            };
+    }
+
+    if (signals.reference !== undefined) {
+        return {
+            outcome: 'yields',
+            outranked_by: { level: 4, source: 'reference-artifact', detail: signals.reference.path ?? signals.reference.maturity },
+            reason: `a ${signalClass} never outranks a supplied reference artifact`,
+        };
+    }
+    if (signals.incumbent?.coherent === true) {
+        return {
+            outcome: 'yields',
+            outranked_by: { level: 5, source: 'incumbent-scan', detail: 'coherent incumbent' },
+            reason: `a ${signalClass} never outranks a coherent incumbent`,
+        };
+    }
+    if (signals.design_md?.present === true) {
+        return {
+            outcome: 'yields',
+            outranked_by: { level: 6, source: 'design-md', detail: signals.design_md.register ?? 'register unstated' },
+            reason: `a ${signalClass} never outranks a project DESIGN.md register`,
+        };
+    }
+    if (signals.product_md?.present === true) {
+        return {
+            outcome: 'yields',
+            outranked_by: { level: 6, source: 'product-md', detail: signals.product_md.register ?? 'register unstated' },
+            reason: `a ${signalClass} never outranks a project PRODUCT.md register`,
+        };
+    }
+    return {
+        outcome: 'flags',
+        outranked_by: null,
+        reason: `a ${signalClass} with nothing above it on the precedence list is a rebuttable presumption`,
+    };
+}

package/src/scripts/adr/regenerate_index.ts

@@ -16,7 +16,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { readAdrAxisCells, readAdrFrontmatterScalars } from '../_lib/adr_frontmatter.js';
+import { dated_trigger_day, readAdrAxisCells, readAdrFrontmatterScalars } from '../_lib/adr_frontmatter.js';
 import { generatedByItalic } from '../_lib/generated_by.js';
 
 // ^ADR-(\d{3})-([a-z0-9-]+)\.md$
@@ -262,6 +262,41 @@ export function scanOutside(repoRoot: string, roots: readonly string[] = OUTSIDE
     return out;
 }
 
+/**
+ * The rows whose `review_trigger` opens with a calendar date.
+ *
+ * WHY THIS SECTION CARRIES THE DATE AND NOT THE FIRED/NOT-FIRED STATE
+ * ------------------------------------------------------------------
+ * `regenerate_index --check` byte-compares this file in CI
+ * (`.github/workflows/rule-backstops.yml`), so anything rendered here has to be
+ * a function of the tree alone. A `fired` / `not-fired` column would be a
+ * function of the tree AND the day, which means the index would go stale on a
+ * calendar boundary nobody committed and red every open pull request until
+ * someone regenerated it. The date is the decidable half; the reader compares
+ * it to today, and `adr_cite_check` prints the comparison for a machine.
+ */
+export interface DatedTriggerRow {
+    label: string;
+    path: string;
+    day: string;
+    decision: string;
+}
+
+export function datedTriggerRows(rows: readonly Row[]): DatedTriggerRow[] {
+    const out: DatedTriggerRow[] = [];
+    for (const r of rows) {
+        const day = dated_trigger_day(r.review_trigger ?? '');
+        if (day === null) continue;
+        out.push({
+            label: 'num' in r ? `ADR-${r.num as string}` : (r.path as string).slice(0, -3),
+            path: r.path as string,
+            day,
+            decision: r.decision ?? r.slug ?? '—',
+        });
+    }
+    return out.sort((a, b) => a.day.localeCompare(b.day) || a.label.localeCompare(b.label));
+}
+
 /** Mirror `render(num, leg)`. */
 export function render(num: Row[], leg: Row[], outside: OutsideRow[] = []): string {
     const out = [
@@ -277,6 +312,24 @@ export function render(num: Row[], leg: Row[], outside: OutsideRow[] = []): stri
     if (leg.length > 0) {
         out.push('', '## Unnumbered (legacy)', '', HEAD, ...leg.map(row));
     }
+    const dated = datedTriggerRows([...num, ...leg]);
+    if (dated.length > 0) {
+        out.push(
+            '',
+            '## Dated review triggers',
+            '',
+            'A `review_trigger` that opens with a calendar date is the one reopen condition',
+            'this repository can decide without interpreting anything, so it is listed where a',
+            'reader meets it rather than only in a command they would have to know to run.',
+            'Compare the expiry to today; `./scripts-run src/scripts/adr_cite_check <ADR-NNN>`',
+            'prints `fired` or `not-fired` for the same date. Every other trigger is semantic',
+            'and reports `indeterminate` — a trigger that merely mentions a date is not listed.',
+            '',
+            '| Expiry | # | Decision |',
+            '|---|---|---|',
+            ...dated.map((d) => `| ${d.day} | [${d.label}](${d.path}) | ${d.decision} |`),
+        );
+    }
     if (outside.length > 0) {
         out.push(
             '',

package/src/scripts/adr_cite_check.ts

@@ -25,7 +25,7 @@
  *     (measured: ADR-035 still asserts a rejection ADR-232 reopened).
  *   - **review_trigger** — verbatim, plus a state.
  *
- * `indeterminate` is a FIRST-CLASS trigger result, not a failure. Every
+ * `indeterminate` is a FIRST-CLASS trigger result, not a failure. Almost every
  * `review_trigger` in the corpus is a semantic condition ("reopen when the
  * capacity premise changes", "if a fifth band appears"), so forcing them to a
  * boolean would convert uncertainty into either permission or blockage. Both
@@ -33,6 +33,29 @@
  * trigger grammar as a prerequisite for exactly this reason. An `indeterminate`
  * result means: this may not be presented as an unqualified lock — route it.
  *
+ * THE DATED SUB-CLASS, AND WHY THE 2026-08-19 REJECTION DOES NOT REACH IT
+ * ----------------------------------------------------------------------
+ * The sentence above used to open "Every `review_trigger` in the corpus is a
+ * semantic condition"; it is weakened rather than deleted because the claim was
+ * true when written and one record has since falsified it.
+ *
+ * What those two seats rejected was forcing SEMANTIC conditions to a boolean.
+ * A trigger that OPENS with a calendar date is not one: `fired` / `not-fired`
+ * is decided by comparing that date to `asOf()`, which is arithmetic and
+ * carries no interpretation of the tree, so a second reader of the same commit
+ * gets the same answer. That is the entire carve-out — a leading
+ * `Expiry YYYY-MM-DD`, or a bare leading ISO date, and nothing else. A
+ * condition that merely MENTIONS a date somewhere in its prose ("revisit at the
+ * 2026-11-10 review date, or earlier on either observable event") is a semantic
+ * condition and stays `indeterminate`, which is what keeps this from being the
+ * rejected grammar by increments.
+ *
+ * `dated-unparsed` exists so the carve-out cannot fail silently. A trigger that
+ * announces itself as dated and whose date this parser cannot read is a defect
+ * in the record or in the parser; returning `indeterminate` for it would hide
+ * that defect behind the exact state every trigger had before the carve-out
+ * existed, where no test could ever see it as a regression.
+ *
  * It also prints the two descriptive axes (`provenance`, `evidence`) and
  * `authority_basis`, and for an accepted E0/E1 record that does NOT carry
  * `authority_basis: owner_intent` it prints
@@ -73,12 +96,16 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import {
     type AdrFrontmatter,
     authorityBasisOf,
+    dated_trigger_day,
+    DATED_TRIGGER_PROBE,
+    iso_day,
     evidenceOf,
     isLowEvidenceAccepted,
     provenanceOf,
     readAdrFrontmatter,
     readAdrFrontmatterScalars,
 } from './_lib/adr_frontmatter.js';
+import { asOf } from './_lib/as_of.js';
 import { GateLedger } from './_lib/gate_ledger.js';
 import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
 import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
@@ -149,8 +176,12 @@ export const SURFACES_NOT_SCANNED = [
  */
 export const PARTIAL_COVERAGE: readonly string[] = [];
 
-/** A trigger state. `none` means the ADR never recorded a reopen condition. */
-export type TriggerState = 'none' | 'indeterminate' | 'fired' | 'not-fired';
+/**
+ * A trigger state. `none` means the ADR never recorded a reopen condition;
+ * `dated-unparsed` means it recorded one that announces a date this parser
+ * could not read, which is a defect and not an answer.
+ */
+export type TriggerState = 'none' | 'indeterminate' | 'fired' | 'not-fired' | 'dated-unparsed';
 
 export interface CiteResult {
     ref: string;
@@ -469,12 +500,21 @@ export function amendment_blocks(body: string): string[] {
 /**
  * A trigger's state, from what is mechanically decidable and nothing else.
  *
- * There is no clause that returns `fired` or `not-fired` from prose, and that
- * absence is the design: every trigger in the corpus is semantic. The states
- * exist in the type because a future structured trigger can carry them; today
- * the honest answers are `none` and `indeterminate`.
+ * Two clauses return a decided answer, and both read a leading calendar date
+ * and nothing else — see `DATED_TRIGGER_RE` for why the anchor is the safety
+ * property. Every semantic trigger still returns `indeterminate`, which is a
+ * first-class result here and not a failure.
+ *
+ * The clock is read ONLY when a dated trigger is actually present — `asOf()`
+ * warns on stderr for an unpinned run, and a corpus with no dated trigger has
+ * no verdict that depends on the hour, so announcing one there would be noise
+ * on a stream other tools read beside the payload.
+ *
+ * @param asOfDate the "now" to compare against; defaults to the `asOf()` seam,
+ *                 so a CI run compares against the commit date and is
+ *                 reproducible from the commit alone.
  */
-export function trigger_state(fm: Record<string, string>): TriggerState {
+export function trigger_state(fm: Record<string, string>, asOfDate?: Date): TriggerState {
     const t = (fm['review_trigger'] ?? '').trim();
     if (t === '') return 'none';
     // The transitional migration value records that no condition has been
@@ -485,6 +525,9 @@ export function trigger_state(fm: Record<string, string>): TriggerState {
     // nobody has evaluated. Found in completion review; the field did not
     // exist in this file's corpus when the mapping was written.
     if (t.toLowerCase() === 'unclassified') return 'none';
+    const day = dated_trigger_day(t);
+    if (day !== null) return iso_day(asOfDate ?? asOf()) >= day ? 'fired' : 'not-fired';
+    if (DATED_TRIGGER_PROBE.test(t)) return 'dated-unparsed';
     return 'indeterminate';
 }
 
@@ -530,6 +573,15 @@ export function verdict_for(r: Omit<CiteResult, 'verdict'>): string {
     if (r.trigger_state === 'none') {
         return 'LIVE, NO REOPEN CONDITION — the ADR records no `review_trigger`, so nothing would ever reopen it on its own. Treat that as a defect in the ADR, not as strength of the lock.';
     }
+    if (r.trigger_state === 'fired') {
+        return 'LIVE, TRIGGER FIRED — the reopen condition is a date and that date has passed. The record still binds until someone acts on it, and citing it without naming the fired trigger presents a lapsed review as a current one.';
+    }
+    if (r.trigger_state === 'not-fired') {
+        return 'LIVE, TRIGGER NOT YET FIRED — the reopen condition is a date still in the future. This is the one state in which a trigger genuinely adds nothing to the citation, and it stops being true on a known day.';
+    }
+    if (r.trigger_state === 'dated-unparsed') {
+        return 'LIVE, DATED TRIGGER UNREADABLE — the reopen condition announces a date this tool could not parse. That is a defect in the record or in the parser, not a verdict: fix the trigger to open with `Expiry YYYY-MM-DD` rather than reading this as "unknown".';
+    }
     return 'LIVE, TRIGGER INDETERMINATE — the reopen condition is semantic and this tool cannot decide it. Not an unqualified lock: evaluate the condition against the current tree and route the result.';
 }
 
@@ -823,21 +875,25 @@ export interface CorpusRow {
     /** Does the record carry a `review_trigger` at all? */
     has_trigger: boolean;
     /** Only meaningful when `has_trigger`; see `TRIGGER_VERDICTS`. */
-    trigger: 'fired' | 'not-fired' | 'indeterminate' | 'none';
+    trigger: TriggerState;
     reopen_policy: string;
     /** Cited anywhere OUTSIDE `docs/decisions/`. */
     cited_outside: boolean;
 }
 
 /**
- * The three states 2.2 requires, and why a fourth exists beside them.
+ * The states a record CARRYING a trigger can be in, and why `none` is not one.
+ *
+ * `none` is outside the denominator, not a bucket inside it: the survey asks
+ * that these sum to "the number of ADRs carrying a trigger", and a record with
+ * no trigger carries none.
  *
- * `none` is NOT one of the three. The step asks that fired + not-fired +
- * indeterminate sum to "the number of ADRs carrying a trigger", so a record
- * with no trigger is outside the denominator rather than a fourth bucket
- * inside it.
+ * `dated-unparsed` was added with the dated sub-class and belongs in the sum
+ * for the same reason `none` does not — a record in that state DOES carry a
+ * trigger. Leaving it out would have made the sum line report a mismatch, i.e.
+ * announced a defect in the survey where the defect is in the ADR.
  */
-export const TRIGGER_VERDICTS = ['fired', 'not-fired', 'indeterminate'] as const;
+export const TRIGGER_VERDICTS = ['fired', 'not-fired', 'indeterminate', 'dated-unparsed'] as const;
 
 /** Every ADR file, surveyed. */
 export function corpus_survey(repo_root: string = REPO_ROOT): CorpusRow[] {

package/src/scripts/ai_council/clients.ts

@@ -1,7 +1,7 @@
 // External-AI clients for the council — ported from the retired Python
 // `src/scripts/ai_council/clients.py` (ADR-200).
 //
-// Mirrors the contract from `scripts/skill_trigger_eval.py`:
+// Mirrors the contract from `src/scripts/skill_trigger_eval.ts`:
 // - Tokens come exclusively from `~/.event4u/agent-config/<provider>.key`
 //   (legacy `~/.config/agent-config/<provider>.key` is read as a fallback so
 //   pre-2.4 installs keep working until the user moves the files into the new