@event4u/agent-config 9.33.0 → 9.35.0

package/src/scripts/ai_council/prompts.ts

@@ -460,9 +460,19 @@ export const REQUIRED_SYNTHESIS_SECTIONS = ['Kill criteria', 'Concrete next step
  * fills the Convergence / Divergence slot) — not the template prompt. Every
  * lens must close with a non-empty `### Kill criteria` and `### Concrete next
  * step`; a missing or placeholder-empty section throws `SynthesisRenderError`
- * naming the first offender. Called on the synthesis-emit path (the chairman
- * synthesis in Phase 2, and any future synthesis-record step); safe to call on
- * decision and creative lenses alike, since both now require the two sections.
+ * naming the first offender. Safe to call on decision and creative lenses
+ * alike, since both now require the two sections.
+ *
+ * **Not wired onto the emit path, deliberately.** This docstring used to claim
+ * it was "called on the synthesis-emit path"; measured, the function had zero
+ * production call sites and only the test imported it. Wiring it
+ * unconditionally into `render()` is not available either: with no chairman the
+ * rendered body is the literal `*to be summarised by the host agent*`, which
+ * carries neither section, so every templated render would throw (verified —
+ * the probe raises `missing the required "### Kill criteria" section`). A
+ * caller that HAS a completed synthesis calls this; the templated default path
+ * has nothing to validate. The tally check below is the half that could be
+ * wired, because it is conditional on a verdict line the template never emits.
  */
 export function assert_synthesis_sections(text: string): void {
     const lines = text.split('\n');
@@ -488,6 +498,158 @@ export function assert_synthesis_sections(text: string): void {
     }
 }
 
+/** The reserved verdict label a synthesis uses when the tally did not converge. */
+export const SPLIT_VERDICT_LABEL = 'split';
+
+// Mirrors `_STANCE_RE`'s shape discipline: an explicit, single-field closing
+// line, never read out of surrounding prose.
+//
+// **Case-SENSITIVE, deliberately.** The `i` flag was here and was wrong: the
+// pattern is line-anchored, so `Verdict: option A is the stronger choice` —
+// ordinary chairman prose opening a line — parsed as a machine-readable verdict
+// carrying the whole sentence as its label. That is precisely the prose
+// inference the paragraph above forbids, arriving through the regex instead of
+// through a fallback. `VERDICT_LINE_CONTRACT` asks for the literal uppercase
+// token, so requiring it costs a compliant author nothing and closes the class.
+const _VERDICT_RE = /^\s*VERDICT:\s*(.+?)\s*$/gm;
+
+/**
+ * Mandatory closing-line contract for a synthesis rendered alongside a stance
+ * tally. The synthesis states its verdict as a machine-readable label rather
+ * than leaving it to be mined out of the recommendation prose — the same
+ * discipline `STANCE_LINE_CONTRACT` imposes on members.
+ */
+export const VERDICT_LINE_CONTRACT = `Close the synthesis with EXACTLY this line, and nothing after it:
+VERDICT: <option-label>
+Use the SAME <option-label> the Vote Tally cleared. Use \`${SPLIT_VERDICT_LABEL}\` when no option cleared the threshold — an honest split is a verdict, and claiming a winner the tally did not record is a render error.`;
+
+/**
+ * Parse the synthesis verdict line. Returns the LAST match (the final,
+ * most-authoritative one) or `null` when no well-formed line exists.
+ *
+ * `null` is a repair marker, never a guess: this function does not fall back to
+ * reading agreement out of the prose. That is the invariant `stance_tally`
+ * states for members ("the tally never infers a stance from the surrounding
+ * prose") and the one `check_finding_dispositions` states for the release
+ * ledger ("a comment is mutable and unaudited; it is transport, not a record").
+ */
+export function parse_verdict_line(text: string): { label: string; display: string } | null {
+    _VERDICT_RE.lastIndex = 0;
+    let last: RegExpExecArray | null = null;
+    let m: RegExpExecArray | null;
+    while ((m = _VERDICT_RE.exec(text)) !== null) {
+        last = m;
+    }
+    if (last === null) {
+        return null;
+    }
+    const raw = (last[1] ?? '').trim();
+    if (raw.length === 0) {
+        return null;
+    }
+    // An angle-bracketed label is the CONTRACT's own placeholder, not a verdict.
+    // This matters on the templated path: with no chairman the rendered body IS
+    // `VERDICT_LINE_CONTRACT`'s template text, so a parser without this guard
+    // would read `<option-label>` as a claimed winner and throw on every
+    // un-summarised render. Same treatment `assert_synthesis_sections` gives a
+    // placeholder-empty section.
+    if (/^<.*>$/.test(raw)) {
+        return null;
+    }
+    return { label: raw.toLowerCase(), display: raw };
+}
+
+/**
+ * Validate a completed synthesis against the stance tally it was rendered
+ * beside: a verdict naming a winner the tally did not clear throws
+ * `SynthesisRenderError`, the same way a missing section does.
+ *
+ * The defect this closes: `assert_synthesis_sections` is a *shape* check, so a
+ * synthesis could report agreement over a tally that recorded dissent and
+ * nothing downstream disagreed. That is the class behind the recorded 9.14.0
+ * release failure, where the head read "Security and correctness: none" over a
+ * critical finding — `check_finding_dispositions.ts` is the same check on the
+ * release surface.
+ *
+ * **An absent verdict line does not throw.** It is a repair marker under the
+ * same rule as an unparseable stance: the fail-safe direction is to record that
+ * the claim was not made, never to infer one from prose. That also keeps every
+ * synthesis rendered before `VERDICT_LINE_CONTRACT` shipped green.
+ */
+export function assert_synthesis_matches_tally(text: string, tally: TallyView): void {
+    const mismatch = describe_verdict_mismatch(text, tally);
+    if (mismatch !== null) {
+        throw new SynthesisRenderError(mismatch);
+    }
+}
+
+/** The slice of a `StanceTallyResult` the verdict check reads. */
+export interface TallyView {
+    consensus: { label: string } | null;
+    split: boolean;
+    options: ReadonlyArray<{ label: string }>;
+}
+
+/**
+ * The same comparison as `assert_synthesis_matches_tally`, returning the
+ * mismatch as a string instead of throwing — `null` means "no contradiction".
+ *
+ * **Why both shapes exist.** Throwing is right for a caller holding a finished
+ * synthesis it can refuse. It is wrong on the render path: `render()` throws
+ * before the tally and the Convergence blocks are pushed, so a mismatch would
+ * destroy the ENTIRE artifact — every member response, the peer review, the
+ * quorum bookkeeping — *after* every provider call has already been paid for.
+ * The module's own answer for an unverifiable claim is the `needs_repair`
+ * marker `render_vote_tally` prints, not a discarded pass, and the roadmap had
+ * already recorded that unconditionally wiring the sibling shape check was
+ * unsafe for this same reason. So the render path surfaces the contradiction
+ * where a reader will see it and keeps the artifact.
+ */
+export function describe_verdict_mismatch(text: string, tally: TallyView): string | null {
+    const verdict = parse_verdict_line(text);
+    if (verdict === null) {
+        return null; // repair marker, not a guess
+    }
+    // The reserved sense of `split` yields to a real option that carries the
+    // same label (R2 finding 8): the label vocabulary is free text mined from
+    // member `STANCE:` lines, so nothing stops an option genuinely called
+    // `split`, and when the tally clears it the CORRECT verdict would otherwise
+    // read as a contradiction. Deciding by whether the tally actually holds
+    // that option keeps one namespace without an escape syntax authors would
+    // have to learn.
+    const optionNamedSplit = tally.options.some(
+        (o) => o.label.toLowerCase() === SPLIT_VERDICT_LABEL,
+    );
+    const claimsSplit = verdict.label === SPLIT_VERDICT_LABEL && !optionNamedSplit;
+
+    if (tally.consensus === null) {
+        if (claimsSplit) {
+            return null;
+        }
+        // `split` is the tally's own word for this state; reading it here rather
+        // than re-deriving "no consensus ⇒ split" keeps the message honest when
+        // the tally is empty (zero options is not a split across zero options).
+        const how = tally.split
+            ? `split across ${tally.options.length} option(s)`
+            : 'no option-level stances parsed';
+        return (
+            `synthesis claims "${verdict.display}" but the tally recorded no consensus ` +
+            `(${how}); use \`${SPLIT_VERDICT_LABEL}\` or re-run the round`
+        );
+    }
+
+    if (claimsSplit) {
+        return `synthesis claims a split but the tally cleared "${tally.consensus.label}"`;
+    }
+    if (verdict.label !== tally.consensus.label.toLowerCase()) {
+        return (
+            `synthesis claims "${verdict.display}" but the tally cleared ` +
+            `"${tally.consensus.label}"`
+        );
+    }
+    return null;
+}
+
 /**
  * Drop any *whole line* containing a host-agent identity substring.
  *

package/src/scripts/ai_council/quorum.ts

@@ -93,6 +93,17 @@ export function evaluateQuorum(
  * full-attendance one. Advisory render and telemetry only: no gate reads it,
  * and nothing downstream may branch on it without its own decision record.
  *
+ * ONE such record now exists, and it is deliberately narrow: ADR-224
+ * (`docs/decisions/ADR-224-gate-scoped-solo-attendance-floor.md`) authorizes a
+ * `min_present: 2` floor to branch on this predicate **for gate-class passes
+ * only**, decided against a measured 12.5 % solo-conclusion rate. What landed
+ * from that authorization is `wouldSoloFloorHold` below, which is a
+ * counterfactual and branches nothing — so the sentence above still describes
+ * the code: no caller holds a pass on solo status today. It is stated here so
+ * a reader finds the authorization instead of re-deriving the prohibition, and
+ * so the next branch is visibly a separate argument: the exception is
+ * gate-class passes, not solo status generally.
+ *
  * `total` is deliberately NOT consulted. A council configured with a single
  * member concludes solo by construction, and that is still a conclusion
  * reached on one voice — collapsing it into "not solo" would hide exactly
@@ -102,3 +113,79 @@ export function evaluateQuorum(
 export function isSoloConcluded(result: QuorumResult): boolean {
     return result.status === 'concluded' && result.present === 1;
 }
+
+/**
+ * The floor value ADR-224 named: a gate-class pass wants at least two voices.
+ *
+ * A constant rather than a bare `2` at the call site so the shadow telemetry
+ * below and any future enforcement read the same number, and so changing it
+ * is one edit with one place to argue about.
+ */
+export const SOLO_FLOOR_MIN_PRESENT = 2;
+
+/**
+ * WOULD a `min_present` floor have held this pass? Counterfactual only — this
+ * predicate changes nothing and no caller branches on it to hold a gate.
+ *
+ * ADR-224 chose a gate-scoped `min_present: 2` floor against a solo-conclusion
+ * rate of 1 of 8 passes, whose 95 % interval spans roughly 0.3 %–53 %. Two
+ * facts, both read off the tree rather than assumed, decided that what lands
+ * first is the measurement and not the enforcement:
+ *
+ *  - **Nothing in the tree branches on `QuorumStatus` to hold anything.** The
+ *    only non-`quorum.ts` reader of `'inconclusive'` is
+ *    `council_cli.ts::_deserialise_quorum`, which validates a persisted string.
+ *    An enforced floor would therefore change zero behaviour today — there is
+ *    no gate for it to hold — while still being able to hang an advisory pass
+ *    the moment a consumer appears.
+ *  - **ADR-224's own review trigger (b) is "the gate-class floor lands and its
+ *    own fire-rate telemetry accumulates"**, which presumes exactly this
+ *    counterfactual is being recorded.
+ *
+ * So the floor is evaluated on EVERY pass and recorded, never applied. The
+ * fire-rate that accumulates from it is what makes the enforcement decision an
+ * evidence call later instead of a second point estimate.
+ *
+ * `minPresent` is clamped with the same discipline `resolveQuorumThreshold`
+ * applies, and the clamp carries meaning rather than only safety: where the
+ * ceiling resolves to 1 the floor never fires, so a council **configured**
+ * with one member is not counted as a degraded pass. That is the split
+ * `quorum-attendance-budget.json` already insists on for the solo-conclusion
+ * rate — a one-member roster and a two-member roster that lost one are
+ * different findings, and an unclamped floor would merge them.
+ *
+ * **The ceiling is the larger of `result.total` and `configuredTotal`, and it
+ * has to be.** Clamping against `result.total` alone was the first version of
+ * this function and it was structurally unable to fire on the exact case
+ * ADR-224 was decided on: `_postRunQuorum` computes `total` over the roster
+ * that CONSTRUCTED, so a two-member council where one member fails to
+ * construct reads `total = 1, present = 1`, the ceiling collapses to 1, and a
+ * conclusion reached on one of two configured voices records as "the floor
+ * would not have held". The series review trigger (b) accumulates would have
+ * been biased low by construction — a metric blind to its own target
+ * population. `configured_total` exists on the event line precisely to keep
+ * that pass distinguishable, and the fix is to consult it.
+ *
+ * `max`, not `configuredTotal` outright: `total > configuredTotal` is
+ * legitimate and not a shortfall, because `--siblings` fans one enabled config
+ * ENTRY into N clients. `configuredTotal` counts entries, `total` counts
+ * clients, and the honest ceiling is the largest roster the pass could have
+ * drawn on either way.
+ *
+ * A pass that never reached `concluded` is not held by the floor: it failed
+ * the threshold, which is a different outcome with a different cause. The two
+ * are mutually exclusive by construction, which is what makes them readable
+ * apart from the event log alone.
+ */
+export function wouldSoloFloorHold(
+    result: QuorumResult,
+    minPresent: number = SOLO_FLOOR_MIN_PRESENT,
+    configuredTotal?: number,
+): boolean {
+    if (result.status !== 'concluded') {
+        return false;
+    }
+    const ceiling = Math.max(result.total, configuredTotal ?? result.total);
+    const floor = Math.min(Math.max(Math.trunc(minPresent), 1), ceiling);
+    return result.present < floor;
+}

package/src/scripts/ai_team/review_gate.ts

@@ -42,6 +42,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 
 import { claude_config_dir, CODEX_MARKETPLACE_NAME, CODEX_PLUGIN_ID } from '../_lib/claude_plugin.js';
+import { isEnvKillSwitchActive } from '../_lib/env_kill_switch.js';
 import { atomic_write_json } from '../hooks/state_io.js';
 import { AI_TEAM_DEFAULTS, load_ai_team_config, type AiTeamConfig } from './config.js';
 
@@ -170,8 +171,7 @@ export function circuit_breaker_notice(bound: number): string {
 // ── ledger (events-log convention) ──────────────────────────────────
 
 function _kill_switch_active(): boolean {
-    const value = process.env[_KILL_SWITCH_ENV] ?? '';
-    return !(value === '' || value === '0' || value === 'false' || value === 'False');
+    return isEnvKillSwitchActive(_KILL_SWITCH_ENV);
 }
 
 function _iso_seconds_z(d: Date): string {

package/src/scripts/build_discovery_manifest.ts

@@ -38,6 +38,7 @@
  *
  * Schema: docs/contracts/discovery-manifest.schema.json
  */
+import * as child_process from 'node:child_process';
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -83,6 +84,7 @@ interface ModuleConfig {
     DEFAULT_DEPRECATION_REPORT: string;
     DEFAULT_TRUST_REPORT: string;
     DEFAULT_ORPHAN_REPORT: string;
+    DEFAULT_DORMANCY_REPORT: string;
     DEFAULT_WORKSPACES_JSON: string;
     DEFAULT_PACKS_JSON: string;
     // Patchable seams (Python monkeypatches these module attributes).
@@ -101,6 +103,7 @@ function _deriveConfig(root: string): ModuleConfig {
         DEFAULT_DEPRECATION_REPORT: path.join(disc, 'deprecation-report.md'),
         DEFAULT_TRUST_REPORT: path.join(disc, 'trust-report.md'),
         DEFAULT_ORPHAN_REPORT: path.join(disc, 'orphan-report.md'),
+        DEFAULT_DORMANCY_REPORT: path.join(disc, 'dormancy-report.md'),
         DEFAULT_WORKSPACES_JSON: path.join(disc, 'workspaces.json'),
         DEFAULT_PACKS_JSON: path.join(disc, 'packs.json'),
         artefact_roots: _artefact_roots,
@@ -937,6 +940,156 @@ function _deprecation_report(manifest: JsonObject): string {
     return lines.join('\n') + '\n';
 }
 
+/** Dormancy window, in months. `docs/governance.md` § Skill lifecycle policy. */
+const _DORMANCY_MONTHS = 6;
+
+/**
+ * What the dormancy report could actually establish from git in this checkout.
+ *
+ * `ok: false` is a first-class outcome, not an error: a shallow clone or a
+ * repository younger than the window cannot distinguish "untouched for six
+ * months" from "history truncated three months ago", and CI clones are shallow
+ * by default. The report NAMES that instead of emitting a list built on it.
+ */
+export interface DormancyProbe {
+    ok: boolean;
+    /** Why the signal is unavailable — set iff `ok` is false. */
+    reason?: string;
+    /** Repo-relative paths with at least one commit inside the window. */
+    touched: Set<string>;
+}
+
+function _git(root: string, args: readonly string[]): string | null {
+    try {
+        return child_process.execFileSync('git', [...args], {
+            cwd: root,
+            encoding: 'utf-8',
+            maxBuffer: 64 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Probe git once for the whole estate: one bounded `--since` walk, exactly the
+ * command `governance.md` names, rather than one `git log` per artefact.
+ */
+function _dormancy_probe(root: string, now: Date = new Date()): DormancyProbe {
+    const since = `${String(_DORMANCY_MONTHS)} months ago`;
+    if (_git(root, ['rev-parse', '--git-dir']) === null) {
+        return { ok: false, reason: 'not a git checkout — commit history is unavailable', touched: new Set() };
+    }
+    if ((_git(root, ['rev-parse', '--is-shallow-repository']) ?? '').trim() === 'true') {
+        return {
+            ok: false,
+            reason:
+                'shallow clone — a truncated history is indistinguishable from a dormant artefact. ' +
+                'Re-run after `git fetch --unshallow`.',
+            touched: new Set(),
+        };
+    }
+    const oldest = (_git(root, ['log', '--reverse', '--format=%cI', '--max-count=1']) ?? '').trim();
+    if (oldest !== '') {
+        const cutoff = new Date(now);
+        cutoff.setMonth(cutoff.getMonth() - _DORMANCY_MONTHS);
+        if (new Date(oldest) > cutoff) {
+            return {
+                ok: false,
+                reason:
+                    `repository history starts ${oldest.slice(0, 10)}, inside the ` +
+                    `${String(_DORMANCY_MONTHS)}-month window — every artefact would read as dormant`,
+                touched: new Set(),
+            };
+        }
+    }
+    const out = _git(root, ['log', `--since=${since}`, '--name-only', '--format=']);
+    if (out === null) {
+        return { ok: false, reason: 'git log failed', touched: new Set() };
+    }
+    const touched = new Set(out.split('\n').map((l) => l.trim()).filter((l) => l !== ''));
+    return { ok: true, touched };
+}
+
+/**
+ * The unit dormancy is measured over. A skill is a directory (governance names
+ * `git log -- src/skills/<name>/`), so a commit touching its `reference.md`
+ * keeps the skill alive; every other artefact is its own file.
+ */
+function _dormancy_unit(artefactPath: string): string {
+    return path.basename(artefactPath) === 'SKILL.md' ? path.dirname(artefactPath) : artefactPath;
+}
+
+/**
+ * Artefacts with no commit inside the dormancy window.
+ *
+ * Report-only by construction: `governance.md` § Skill lifecycle policy says
+ * dormancy triggers review, never auto-deprecation — and a finished artefact is
+ * indistinguishable from an abandoned one from commit dates, so the
+ * false-positive class is not empty and no argument makes it so.
+ */
+function _dormant_artefacts(manifest: JsonObject, probe: DormancyProbe): JsonObject[] {
+    if (!probe.ok) {
+        return [];
+    }
+    const alive = new Set<string>();
+    for (const p of probe.touched) {
+        alive.add(p);
+        // A touched file keeps its containing directory-shaped artefact alive.
+        for (let d = path.dirname(p); d !== '.' && d !== path.sep; d = path.dirname(d)) {
+            alive.add(d);
+        }
+    }
+    const out: JsonObject[] = [];
+    for (const a of manifest['artefacts'] as JsonObject[]) {
+        const unit = _dormancy_unit(a['path'] as string);
+        if (!alive.has(unit)) {
+            out.push({ path: a['path'], unit, category: a['category'] });
+        }
+    }
+    out.sort((a, b) => _cmpStr(a['path'] as string, b['path'] as string));
+    return out;
+}
+
+/** The dormancy section of the discovery report family (governance.md § Skill lifecycle policy). */
+function _dormancy_report(manifest: JsonObject, probe: DormancyProbe): string {
+    const lines = ['# Discovery — Dormancy Report', ''];
+    lines.push(`- Generated: \`${String(manifest['generated_at'])}\``);
+    lines.push(`- Window: **${String(_DORMANCY_MONTHS)} months** without a commit`);
+    lines.push('');
+    lines.push('> Dormancy triggers **review, never auto-deprecation**');
+    lines.push('> (`docs/governance.md` § Skill lifecycle policy). A finished artefact and an');
+    lines.push('> abandoned one look identical from commit dates, so this is a prompt to ask');
+    lines.push('> "still earning its slot?" — never a removal list, and never a gate.');
+    lines.push('');
+    if (!probe.ok) {
+        lines.push('## Signal unavailable');
+        lines.push('');
+        lines.push(`**No dormancy list is published**: ${String(probe.reason)}`);
+        lines.push('');
+        lines.push('An empty section here would read as "nothing is dormant", which is a');
+        lines.push('different claim from "the signal could not be computed".');
+        lines.push('');
+        return lines.join('\n') + '\n';
+    }
+    const items = _dormant_artefacts(manifest, probe);
+    lines.push(`- Dormant artefacts: **${items.length}**`);
+    lines.push('');
+    if (items.length === 0) {
+        lines.push('_None. Every artefact was touched inside the window._');
+        lines.push('');
+        return lines.join('\n') + '\n';
+    }
+    lines.push('| Path | Unit | Category |');
+    lines.push('|---|---|---|');
+    for (const a of items) {
+        lines.push(`| \`${String(a['path'])}\` | \`${String(a['unit'])}\` | ${String(a['category'])} |`);
+    }
+    lines.push('');
+    return lines.join('\n') + '\n';
+}
+
 /** Trust-level breakdown by workspace + human-review sanity flag. Mirrors `_trust_report`. */
 function _trust_report(manifest: JsonObject): string {
     const byWs = new Map<string, JsonObject>();
@@ -1195,6 +1348,7 @@ interface ParsedArgs {
     deprecation_report: string;
     trust_report: string;
     orphan_report: string;
+    dormancy_report: string;
     workspaces_json: string;
     packs_json: string;
     strict: boolean;
@@ -1231,6 +1385,7 @@ function parse_args(argv: readonly string[]): ParsedArgs {
         deprecation_report: _config.DEFAULT_DEPRECATION_REPORT,
         trust_report: _config.DEFAULT_TRUST_REPORT,
         orphan_report: _config.DEFAULT_ORPHAN_REPORT,
+        dormancy_report: _config.DEFAULT_DORMANCY_REPORT,
         workspaces_json: _config.DEFAULT_WORKSPACES_JSON,
         packs_json: _config.DEFAULT_PACKS_JSON,
         strict: false,
@@ -1242,6 +1397,7 @@ function parse_args(argv: readonly string[]): ParsedArgs {
         '                                   [--deprecation-report DEPRECATION_REPORT]\n' +
         '                                   [--trust-report TRUST_REPORT]\n' +
         '                                   [--orphan-report ORPHAN_REPORT]\n' +
+        '                                   [--dormancy-report DORMANCY_REPORT]\n' +
         '                                   [--workspaces-json WORKSPACES_JSON]\n' +
         '                                   [--packs-json PACKS_JSON] [--strict]\n' +
         '                                   [--quiet]\n';
@@ -1252,6 +1408,7 @@ function parse_args(argv: readonly string[]): ParsedArgs {
         '--deprecation-report': 'deprecation_report',
         '--trust-report': 'trust_report',
         '--orphan-report': 'orphan_report',
+        '--dormancy-report': 'dormancy_report',
         '--workspaces-json': 'workspaces_json',
         '--packs-json': 'packs_json',
     };
@@ -1324,6 +1481,10 @@ function main(argv: readonly string[]): number {
         _writeFileMkdir(args.deprecation_report, _deprecation_report(manifest));
         _writeFileMkdir(args.trust_report, _trust_report(manifest));
         _writeFileMkdir(args.orphan_report, _orphan_report(manifest));
+        _writeFileMkdir(
+            args.dormancy_report,
+            _dormancy_report(manifest, _dormancy_probe(_config.ROOT)),
+        );
         // Phase 5 sub-views.
         _writeFileMkdir(
             args.workspaces_json,
@@ -1425,6 +1586,10 @@ export {
     _trust_report,
     _orphan_artefacts,
     _orphan_report,
+    _dormancy_probe,
+    _dormancy_unit,
+    _dormant_artefacts,
+    _dormancy_report,
     _workspaces_view,
     _packs_view,
     _summary,

package/src/scripts/check_claims.ts

@@ -55,7 +55,14 @@ const LEDGER_REL = 'docs/CLAIMS.md';
 const SURFACE_ROOTS = ['README.md', 'docs'];
 
 const CLAIM_MARKER = /<!--\s*claim:([A-Za-z0-9._-]+)\s*-->/g;
-const URL_DATED = /^https?:\/\/\S+\(\d{4}-\d{2}-\d{2}\)\s*$/;
+// The documented grammar is `https://… (YYYY-MM-DD)` — with a space, in both
+// docs/CLAIMS.md § Evidence-pointer grammar and this file's own header. The
+// original pattern required the stamp to abut the URL (`\S+\(`), so every
+// pointer written the documented way was rejected. That went unnoticed because
+// the form had zero usage until the external research citations were bound;
+// the space is now optional, which accepts both spellings and keeps the
+// enforcement matching the spec rather than the other way round.
+const URL_DATED = /^https?:\/\/\S+\s*\(\d{4}-\d{2}-\d{2}\)\s*$/;
 
 /** Witness sweep (P1.2) — marketing-class surfaces where a bare number must
  *  not appear as a capability claim. docs/proof.md and docs/comparison.yaml
@@ -118,6 +125,17 @@ export interface LedgerEntry {
     evidence: string;
     status: string;
     last_verified: string;
+    /**
+     * Optional forward link on a `resolved-null` entry: the id of the claim that
+     * reopened the same question by a different mechanism. The retire-never-delete
+     * lifecycle keeps the null readable forever, but a reader arriving at a closed
+     * question has no way to learn it was later reopened — this is that link.
+     *
+     * Parsed and gated rather than merely documented: an unparsed field would be a
+     * documented claim the code does not honour, which is the defect class this
+     * ledger exists to make impossible.
+     */
+    superseded_by: string;
 }
 
 interface Args {
@@ -158,6 +176,7 @@ function load_ledger(): Map<string, LedgerEntry> {
                 evidence: cur.evidence ?? '',
                 status: cur.status ?? '',
                 last_verified: cur.last_verified ?? '',
+                superseded_by: cur.superseded_by ?? '',
             });
         }
         cur = {};
@@ -170,7 +189,7 @@ function load_ledger(): Map<string, LedgerEntry> {
             continue;
         }
         if (!cur.id) continue;
-        const field = line.match(/^-\s+(claim|kind|evidence|status|last_verified):\s*(.*)$/);
+        const field = line.match(/^-\s+(claim|kind|evidence|status|last_verified|superseded_by):\s*(.*)$/);
         if (field) {
             const key = field[1] as keyof LedgerEntry;
             (cur as Record<string, string>)[key] = (field[2] ?? '').trim();
@@ -320,6 +339,36 @@ function main(argv: string[] = process.argv.slice(2)): number {
         if (un) findings.push({ id: entry.id, file: LEDGER_REL, reason: `backed entry has dangling evidence — ${un}` });
     }
 
+    // 2b. Successor pointers: a `superseded_by` must name a real ledger entry,
+    //     and only a closed question can have a successor. The field exists so a
+    //     reader arriving at a `resolved-null` learns the question was reopened
+    //     by a different mechanism — a dangling id would send them nowhere, and
+    //     the field on a live entry would claim a closure that never happened.
+    for (const entry of ledger.values()) {
+        if (!entry.superseded_by) continue;
+        if (entry.status !== 'resolved-null') {
+            findings.push({
+                id: entry.id,
+                file: LEDGER_REL,
+                reason: `superseded_by is only meaningful on a resolved-null entry (status: ${entry.status || 'missing'})`,
+            });
+            continue;
+        }
+        if (!ledger.has(entry.superseded_by)) {
+            findings.push({
+                id: entry.id,
+                file: LEDGER_REL,
+                reason: `superseded_by names claim:${entry.superseded_by}, which is not in the ledger`,
+            });
+        } else if (entry.superseded_by === entry.id) {
+            findings.push({
+                id: entry.id,
+                file: LEDGER_REL,
+                reason: 'superseded_by points at its own entry',
+            });
+        }
+    }
+
     // 3. Witness sweep (road-to-opt-subagent-harvest P1.2): a QUANTIFIED
     //    capability claim on a marketing-class surface must be witnessed — a
     //    `<!-- claim:ID -->` marker on the same line, or an explicit

package/src/scripts/ci_time_ratio.ts

@@ -20,7 +20,9 @@
  * - Median ratio < 3× across all classes      → structural overhead acceptable
  *
  * Output: human-readable table on stdout + JSON to
- * `agents/runtime/reports/ci-time-ratio.json`.
+ * `agents/reports/ci-time-ratio.json` — the tracked report directory, and
+ * the path `DEFAULT_OUT` has always written. This docstring named a
+ * different, untracked directory until 2026-08-11; the code never did.
  *
  * Usage:
  *   node ci_time_ratio.js --limit 30