@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/_lib/advisory_verdicts.ts

@@ -0,0 +1,363 @@
+/**
+ * From raw source answers to a finding a person can act on
+ * (road-to-advisories-heard-the-same-day Phases 2.2–2.5 and 3).
+ *
+ * Deterministic and pure: no file, no network. The closed verdict vocabulary,
+ * the alias merge, the tiers, the delta ledger, acceptance with expiry and the
+ * noise budget all live here so each is testable over fixtures alone.
+ */
+
+import type { InventoryEntry } from './advisory_inventory.js';
+import type { RawFinding, Severity, SourceReport } from './advisory_sources.js';
+import { isVendorPatched } from './advisory_sources.js';
+
+export type Verdict =
+    | 'affected'
+    | 'fix-available'
+    | 'fix-fresh'
+    | 'no-fix'
+    | 'malware'
+    | 'eol'
+    | 'eol-soon'
+    | 'pre-announced'
+    | 'unknown'
+    | 'accepted';
+
+export type Tier = 'T0' | 'T1' | 'T2' | 'T3';
+
+export interface Finding {
+    /** Stable across runs: canonical ID + package + version. */
+    key: string;
+    /** The canonical ID — a CVE when one is among the aliases, else the first seen. */
+    id: string;
+    aliases: string[];
+    verdict: Verdict;
+    tier: Tier;
+    ecosystem: string;
+    package: string;
+    version: string | null;
+    fixed: string | null;
+    severity: Severity;
+    score: number | null;
+    kev: boolean;
+    date: string | null;
+    scope: 'runtime' | 'dev' | null;
+    /** `false` when the project's manifest is read and does not declare it (transitive); unknown counts as direct. */
+    direct?: boolean | null;
+    sources: string[];
+    /** Newest source-side `modified` stamp; a change means a corrected advisory. */
+    modified: string | null;
+    file: string;
+    line: number;
+    /** Why the verdict is what it is, when it is not obvious (`vendor-patched`, `source-unavailable`). */
+    note: string | null;
+}
+
+export interface Acceptance {
+    id: string;
+    reason: string;
+    /** ISO day; past it the acceptance lapses and the finding returns. */
+    expires: string;
+}
+
+const SEVERITY_RANK: Record<NonNullable<Severity>, number> = { low: 1, moderate: 2, high: 3, critical: 4 };
+
+function stronger(a: Severity, b: Severity): Severity {
+    if (a === null) return b;
+    if (b === null) return a;
+    return SEVERITY_RANK[a] >= SEVERITY_RANK[b] ? a : b;
+}
+
+/** A CVE is the alias most people search for; prefer it as the canonical ID. */
+function canonical(ids: string[]): string {
+    return ids.find((i) => i.startsWith('CVE-')) ?? ids.find((i) => i.startsWith('GHSA-')) ?? ids[0]!;
+}
+
+/**
+ * Merge source answers that describe the same thing: the same package version
+ * and overlapping ID sets (a GHSA, its CVE and its OSV record are one finding,
+ * reported once with every source that saw it — 2.4).
+ */
+export function mergeFindings(raw: RawFinding[]): RawFinding[][] {
+    const groups: Array<{ ids: Set<string>; items: RawFinding[]; pkg: string }> = [];
+    for (const f of raw) {
+        const pkg = `${f.ecosystem}\0${f.package}\0${f.version ?? ''}`;
+        const ids = [f.id, ...f.aliases];
+        const hit = groups.find((g) => g.pkg === pkg && ids.some((i) => g.ids.has(i)));
+        if (hit) {
+            for (const i of ids) hit.ids.add(i);
+            hit.items.push(f);
+        } else {
+            groups.push({ ids: new Set(ids), items: [f], pkg });
+        }
+    }
+    return groups.map((g) => g.items);
+}
+
+/** The verdict, from the strongest fact any source asserted (2.2). */
+export function verdictOf(items: RawFinding[], now: Date, acceptances: Acceptance[], ids: string[]): { verdict: Verdict; note: string | null } {
+    const today = now.toISOString().slice(0, 10);
+    if (acceptances.some((a) => ids.includes(a.id) && a.expires >= today)) return { verdict: 'accepted', note: null };
+    if (items.some((f) => f.kind === 'malware')) return { verdict: 'malware', note: null };
+    const kinds = new Set(items.map((f) => f.kind));
+    if (kinds.has('pre-announced')) return { verdict: 'pre-announced', note: 'patched versions not yet named' };
+    if (kinds.has('eol')) return { verdict: 'eol', note: null };
+    if (kinds.has('eol-soon')) return { verdict: 'eol-soon', note: null };
+    const version = items[0]!.version;
+    if (version !== null && isVendorPatched(version)) {
+        // A distro carries its own backports; the upstream number says nothing (2.5).
+        return { verdict: 'unknown', note: 'vendor-patched — judge by the distro advisory' };
+    }
+    const fixed = items.map((f) => f.fixed).find((v) => v !== null) ?? null;
+    if (fixed !== null) return { verdict: 'fix-available', note: null };
+    if (items.every((f) => f.source === 'native-npm' || f.source === 'native-composer')) {
+        // A native audit names the problem without a per-advisory fixed version.
+        return { verdict: 'affected', note: null };
+    }
+    return { verdict: 'no-fix', note: null };
+}
+
+/**
+ * Deterministic tiers (3.1). T0 interrupts, T1 is today, T2 is the digest, T3
+ * is the ledger. KEV raises a tier and never lowers one.
+ */
+export function tierOf(f: Pick<Finding, 'verdict' | 'severity' | 'score' | 'kev' | 'scope' | 'ecosystem'> & { direct?: boolean | null }): Tier {
+    const runtimeScope = f.scope !== 'dev';
+    const critical = f.severity === 'critical' || (f.score !== null && f.score >= 9);
+    const high = f.severity === 'high' || (f.score !== null && f.score >= 7);
+    let tier: Tier;
+    switch (f.verdict) {
+        case 'malware':
+            return 'T0';
+        case 'accepted':
+            return 'T3';
+        case 'pre-announced':
+            tier = critical && f.ecosystem === 'runtime' ? 'T0' : 'T1';
+            break;
+        case 'eol':
+            tier = 'T1';
+            break;
+        case 'eol-soon':
+        case 'unknown':
+            tier = 'T2';
+            break;
+        default:
+            // T0 is runtime-DIRECT with a fix (3.1); a known transitive is T1.
+            if (critical && runtimeScope && f.direct !== false && (f.verdict === 'fix-available' || f.verdict === 'fix-fresh')) tier = 'T0';
+            else if ((critical || high) && runtimeScope) tier = 'T1';
+            else if (critical || high || f.severity === 'moderate') tier = 'T2';
+            else tier = 'T3';
+    }
+    // KEV raises exactly one tier in a runtime scope: T3 → T2 → T1 → T0.
+    if (f.kev && runtimeScope && tier !== 'T0') tier = ({ T1: 'T0', T2: 'T1', T3: 'T2' } as const)[tier];
+    return tier;
+}
+
+/** Raw source answers → findings, one per real thing. */
+export function buildFindings(
+    raw: RawFinding[],
+    inventory: InventoryEntry[],
+    reports: SourceReport[],
+    opts: { now?: Date; acceptances?: Acceptance[] } = {},
+): Finding[] {
+    const now = opts.now ?? new Date();
+    const out: Finding[] = [];
+    for (const items of mergeFindings(raw)) {
+        const ids = [...new Set(items.flatMap((f) => [f.id, ...f.aliases]))];
+        const id = canonical(ids);
+        const first = items[0]!;
+        const scope = inventory.find((e) => e.name === first.package && e.file === first.file)?.scope ?? null;
+        // Direct when the manifest beside the lockfile declares it; transitive
+        // only when that manifest was read and does not.
+        const dir = first.file.includes('/') ? first.file.slice(0, first.file.lastIndexOf('/') + 1) : '';
+        const declared = inventory.filter((e) => e.provenance === 'declared' && e.ecosystem === first.ecosystem && e.file === `${dir}package.json`);
+        const direct = declared.length === 0 ? null : declared.some((e) => e.name === first.package);
+        const { verdict, note } = verdictOf(items, now, opts.acceptances ?? [], ids);
+        const base = {
+            verdict,
+            severity: items.map((f) => f.severity).reduce(stronger, null as Severity),
+            score: items.map((f) => f.score).find((s) => s !== null) ?? null,
+            kev: items.some((f) => f.kev),
+            scope,
+            direct,
+            ecosystem: first.ecosystem,
+        };
+        out.push({
+            key: `${id}|${first.package}|${first.version ?? ''}`,
+            id,
+            aliases: ids.filter((i) => i !== id).sort(),
+            tier: tierOf(base),
+            package: first.package,
+            version: first.version,
+            fixed: items.map((f) => f.fixed).find((v) => v !== null) ?? null,
+            date: items.map((f) => f.date).find((v) => v !== null) ?? null,
+            sources: [...new Set(items.map((f) => f.source))].sort(),
+            modified: items.map((f) => f.modified).filter((m): m is string => m !== null).sort().pop() ?? null,
+            file: first.file,
+            line: first.line,
+            note,
+            ...base,
+        });
+    }
+    // Silence is a verdict, never an empty list (F6): every source that did not
+    // answer becomes one `unknown` finding naming it.
+    // One unknown per source, however many reports it gave: the reasons join.
+    const unknown = new Map<string, SourceReport[]>();
+    for (const r of reports) {
+        if (r.status === 'ok') continue;
+        if (r.reason === 'private-names-present') continue; // a deliberate skip, not silence
+        if (r.source === 'kev') continue; // an enrichment: its failure is a report, never a finding
+        unknown.set(r.source, [...(unknown.get(r.source) ?? []), r]);
+    }
+    for (const [source, rs] of unknown) {
+        const r = { source, status: rs[0]!.status, reason: rs.map((x) => x.reason).filter((x): x is string => x !== null).join('; ') || null };
+        out.push({
+            key: `UNKNOWN-${r.source}`,
+            id: `UNKNOWN-${r.source}`,
+            aliases: [],
+            verdict: 'unknown',
+            tier: 'T2',
+            ecosystem: 'runtime',
+            package: r.source,
+            version: null,
+            fixed: null,
+            severity: null,
+            score: null,
+            kev: false,
+            date: null,
+            scope: null,
+            sources: [r.source],
+            modified: null,
+            file: '',
+            line: 0,
+            note: `source-${r.status}${r.reason === null ? '' : `: ${r.reason}`}`,
+        });
+    }
+    const order: Record<Tier, number> = { T0: 0, T1: 1, T2: 2, T3: 3 };
+    return out.sort((a, b) => order[a.tier] - order[b.tier] || a.key.localeCompare(b.key));
+}
+
+/**
+ * A source that did not answer cannot retract what it reported last time. A
+ * previous finding every one of whose sources failed this run is carried over —
+ * while the same package at the same version is still installed — so a 429 or
+ * a timeout never reads as "fixed". A source that answered `ok` is the only one
+ * that can drop a finding.
+ */
+export function carryForward(findings: Finding[], previous: Finding[], reports: SourceReport[], entries: InventoryEntry[]): Finding[] {
+    const failed = new Set(reports.filter((r) => r.status !== 'ok').map((r) => r.source as string));
+    if (failed.size === 0) return findings;
+    const have = new Set(findings.map((f) => f.key));
+    const carried = previous.filter(
+        (f) =>
+            !f.key.startsWith('UNKNOWN-') &&
+            !have.has(f.key) &&
+            f.sources.length > 0 &&
+            f.sources.every((s) => failed.has(s)) &&
+            entries.some((e) => e.name === f.package && e.version === f.version),
+    );
+    return [...findings, ...carried.map((f) => ({ ...f, note: `carried — ${f.sources.join(', ')} did not answer this run` }))];
+}
+
+// ---------------------------------------------------------------------------
+// The delta ledger and the noise budget
+// ---------------------------------------------------------------------------
+
+export interface LedgerEntry {
+    tier: Tier;
+    verdict: Verdict;
+    modified: string | null;
+    first_seen: string;
+    announced_at: string | null;
+}
+
+export interface Ledger {
+    entries: Record<string, LedgerEntry>;
+    /** ISO stamps of interrupting announcements, pruned to the last seven days. */
+    interrupts: string[];
+    /** Recorded transitions — a corrected advisory or a verdict change (2.5). */
+    transitions: Array<{ at: string; key: string; from: string; to: string }>;
+}
+
+/** At most this many interrupting notices per project per week; the rest go to the digest (0.3). */
+export const INTERRUPT_BUDGET_PER_WEEK = 3;
+
+export function emptyLedger(): Ledger {
+    return { entries: {}, interrupts: [], transitions: [] };
+}
+
+const RANK: Record<Tier, number> = { T0: 0, T1: 1, T2: 2, T3: 3 };
+
+export interface Announcement {
+    interrupt: Finding[];
+    digest: Finding[];
+    ledger: Ledger;
+}
+
+/**
+ * Only what is new, escalated or corrected is announced (3.2). T0/T1 interrupt
+ * until the weekly budget is spent, then fall into the digest — a fourth T1 in
+ * a week is still reported, just not as an interruption.
+ */
+export function announce(findings: Finding[], previous: Ledger, now: Date = new Date()): Announcement {
+    const at = now.toISOString();
+    const weekAgo = now.getTime() - 7 * 86400000;
+    const ledger: Ledger = {
+        entries: { ...previous.entries },
+        interrupts: previous.interrupts.filter((t) => Date.parse(t) >= weekAgo),
+        transitions: [...previous.transitions],
+    };
+    const interrupt: Finding[] = [];
+    const digest: Finding[] = [];
+    for (const f of findings) {
+        const old = ledger.entries[f.key];
+        const isNew = old === undefined;
+        const escalated = old !== undefined && RANK[f.tier] < RANK[old.tier];
+        const corrected = old !== undefined && f.modified !== null && old.modified !== null && f.modified !== old.modified;
+        const verdictMoved = old !== undefined && old.verdict !== f.verdict;
+        if (corrected || verdictMoved) {
+            ledger.transitions.push({ at, key: f.key, from: `${old!.verdict}/${old!.tier}`, to: `${f.verdict}/${f.tier}` });
+        }
+        ledger.entries[f.key] = {
+            tier: f.tier,
+            verdict: f.verdict,
+            modified: f.modified,
+            first_seen: old?.first_seen ?? at,
+            announced_at: old?.announced_at ?? null,
+        };
+        if (!(isNew || escalated || corrected || verdictMoved)) continue;
+        if ((f.tier === 'T0' || f.tier === 'T1') && ledger.interrupts.length < INTERRUPT_BUDGET_PER_WEEK) {
+            interrupt.push(f);
+            ledger.interrupts.push(at);
+        } else if (f.tier !== 'T3') {
+            digest.push(f);
+        }
+        ledger.entries[f.key]!.announced_at = at;
+    }
+    return { interrupt, digest, ledger };
+}
+
+/** An acceptance needs a reason and an expiry; a grep-negative is not a reason (3.3, K4). */
+/** An acceptance lasts at most this long; renewing it is the re-check. */
+export const ACCEPTANCE_MAX_DAYS = 365;
+
+export function validateAcceptance(a: Partial<Acceptance>, now: Date = new Date()): string | null {
+    if (typeof a.id !== 'string' || a.id === '') return 'an acceptance names the finding ID';
+    if (typeof a.reason !== 'string' || a.reason.trim().length < 10) return 'an acceptance carries a reason of at least a sentence';
+    // A search that found nothing is never a reason. "Not reachable" is one only
+    // with the mechanism named after it — a bare claim is the same grep in prose.
+    const searched = /\b(grep|not found|no (hits|matches))\b/i.test(a.reason);
+    const bare = /\b(not (used|reachable)|no usage)\b/i.test(a.reason) && a.reason.trim().split(/\s+/).length < 8;
+    if (searched || bare) {
+        return 'absence of a hit is not unreachability — name what makes the code path unreachable';
+    }
+    if (typeof a.expires !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(a.expires)) return 'an acceptance carries an expiry day (YYYY-MM-DD)';
+    // A real calendar day, after today, within a year: past is no acceptance,
+    // 9999-12-31 is a permanent one wearing a date.
+    const at = Date.parse(`${a.expires}T00:00:00Z`);
+    if (!Number.isFinite(at) || new Date(at).toISOString().slice(0, 10) !== a.expires) return 'the expiry is not a calendar day';
+    const days = (at - now.getTime()) / 86400000;
+    if (days <= 0) return 'the expiry is not in the future';
+    if (days > ACCEPTANCE_MAX_DAYS) return `an acceptance lasts at most ${ACCEPTANCE_MAX_DAYS} days — renew it then`;
+    return null;
+}

package/src/scripts/_lib/agent_artifact_location.ts

@@ -0,0 +1,177 @@
+/**
+ * The roadmap-location DETECTOR — one implementation, two callers.
+ *
+ * `check_agent_artifact_location` runs it over this repository in CI;
+ * `agent-config doctor` runs it over a consumer's tree through
+ * `install_reach_checks`. It lives here rather than in the gate so the CLI
+ * imports a module with no CLI-entry guard and no self-test machinery, and so
+ * the two callers cannot hold different definitions of what counts: a change to
+ * the detector moves both, which `tests/scripts/agent_artifact_location_two_callers.test.ts`
+ * asserts. Why the detection takes three content signals rather than the name
+ * test alone is stated in the gate's header.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { is_roadmap_candidate as isRoadmapCandidate } from '../../agent-src/scripts/update_roadmap_progress.js';
+
+/** The one legitimate home. Everything else is a finding. */
+export const ROADMAP_ROOT_REL = 'agents/roadmaps';
+
+/**
+ * Directories the walk never enters.
+ *
+ * `dist/` and the per-tool projection trees are generated copies — a finding
+ * there is a finding about `src/`, reported twice. `node_modules` and `.git`
+ * are not this repository's prose. `vendor` is the PHP equivalent of
+ * `node_modules` in a consumer tree — third-party prose, never theirs to move.
+ */
+const SKIP_DIRS: ReadonlySet<string> = new Set([
+    '.git',
+    'node_modules',
+    'vendor',
+    'dist',
+    '.augment',
+    '.claude',
+    '.cursor',
+    '.clinerules',
+    '.agents',
+    'coverage',
+    '.venv',
+]);
+
+/** Frontmatter keys that only a roadmap carries in this tree. */
+const FM_ROADMAP_RE = /^complexity:[ \t]*(lightweight|structural)[ \t]*$/m;
+/**
+ * Anchored at the absolute start of the string — `^` with no `m` flag — on
+ * purpose: this is a FRONTMATTER fence, which by the project's own convention
+ * only means something at byte offset 0 of the file. A `---` fence that
+ * begins three lines in is not frontmatter, it is a horizontal rule or a
+ * quoted example, so loosening this to `m` would create false positives of
+ * its own.
+ *
+ * The R2 review-input roadmap snapshots used to depend on that strictness as an
+ * INCIDENTAL exemption: their two-line HTML-comment header, written for a
+ * different gate, pushed this fence off offset 0. They are now exempt by path —
+ * see `isReviewInputRoadmapSnapshot` — so neither the header nor this regex's
+ * anchoring decides their fate any more.
+ *
+ * Tested in `check_agent_artifact_location.test.ts`
+ * (describe: "review-input snapshot convention").
+ */
+const FM_RE = /^---\n([\s\S]*?)\n---/;
+const PHASE_RE = /^##[ \t]+Phase[ \t]/m;
+const CHECKBOX_RE = /^[ \t]*- \[[ x~-]\][ \t]/m;
+
+export interface Shape {
+    /** Which signals fired. Empty means not roadmap-shaped. */
+    readonly signals: readonly string[];
+    readonly isRoadmap: boolean;
+}
+
+/**
+ * Decide whether a file's CONTENT is a roadmap.
+ *
+ * All three signals are required. Each is individually common; together they are
+ * this repository's roadmap format and nothing else's.
+ */
+export function roadmapShape(text: string): Shape {
+    const signals: string[] = [];
+    const fm = FM_RE.exec(text);
+    if (fm !== null && FM_ROADMAP_RE.test(fm[1] as string)) {
+        signals.push('roadmap frontmatter (`complexity:` lightweight|structural)');
+    }
+    if (PHASE_RE.test(text)) {
+        signals.push('a `## Phase` heading');
+    }
+    if (CHECKBOX_RE.test(text)) {
+        signals.push('at least one checkbox step');
+    }
+    return { signals, isRoadmap: signals.length === 3 };
+}
+
+export interface Finding {
+    readonly rel: string;
+    readonly signals: readonly string[];
+}
+
+export interface ScanResult {
+    readonly findings: readonly Finding[];
+    /** Every `.md` file the walk visited — the scope, not the matches. */
+    readonly scanned: number;
+}
+
+function walkMarkdown(root: string): string[] {
+    const out: string[] = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const cur = stack.pop() as string;
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(cur, { withFileTypes: true });
+        } catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (e.isSymbolicLink()) continue;
+            const full = path.join(cur, e.name);
+            if (e.isDirectory()) {
+                if (!SKIP_DIRS.has(e.name)) stack.push(full);
+            } else if (e.name.toLowerCase().endsWith('.md')) {
+                out.push(full);
+            }
+        }
+    }
+    return out.sort();
+}
+
+/**
+ * The one declared exemption: an R2 review-input roadmap snapshot.
+ *
+ * `dispatch_r2_reviewer.ts` writes a verbatim roadmap copy to exactly this
+ * shape, and a file in it is non-authoritative evidence whoever wrote it —
+ * nothing reads it back as a roadmap. Decided by path, not by a marker an
+ * author could type anywhere (authority-routing roadmap 5.1, `## Decisions`):
+ * measured 2026-10-07, every roadmap-shaped file outside the root was one of
+ * these snapshots, so the path names the whole population and nothing else.
+ * Takes the repository-relative POSIX path the walker produces; the walker
+ * never follows a symlink, so a link cannot manufacture an exempt path.
+ */
+const REVIEW_INPUT_SNAPSHOT_PATH_RE = /^agents\/evidence\/(?:[^/]+\/)*[^/.][^/]*\.review-input\/roadmap\.md$/;
+
+export function isReviewInputRoadmapSnapshot(rel: string): boolean {
+    return REVIEW_INPUT_SNAPSHOT_PATH_RE.test(rel) && !rel.split('/').some((s) => s === '..' || s === '.');
+}
+
+/** `true` when `child` is at or below `root`. */
+function isUnder(child: string, root: string): boolean {
+    const rel = path.relative(root, child);
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+export function scan(root: string): ScanResult {
+    const roadmapRoot = path.join(root, ...ROADMAP_ROOT_REL.split('/'));
+    const files = walkMarkdown(root);
+    const findings: Finding[] = [];
+    for (const f of files) {
+        if (isUnder(f, roadmapRoot)) continue;
+        if (isReviewInputRoadmapSnapshot(path.relative(root, f).split(path.sep).join('/'))) continue;
+        // Cheap name pre-filter first — the SHARED definition, imported, so the
+        // roadmap corpus and this guard cannot drift apart.
+        if (!isRoadmapCandidate(f)) continue;
+        let text: string;
+        try {
+            text = fs.readFileSync(f, 'utf-8');
+        } catch {
+            continue;
+        }
+        const shape = roadmapShape(text);
+        if (!shape.isRoadmap) continue;
+        findings.push({
+            rel: path.relative(root, f).split(path.sep).join('/'),
+            signals: shape.signals,
+        });
+    }
+    return { findings, scanned: files.length };
+}

package/src/scripts/_lib/agent_settings.ts

@@ -299,17 +299,12 @@ export const MERGEABLE_KEYS: readonly string[] = [
     // GUI; whitelisting decides only whether the value SURVIVES the merge
     // (ADR-271, road-to-design-intent-conformance 2.3).
     'design.fidelity_mode',
-    // `lean_projection.*` is a per-MACHINE setting and the install it governs is
-    // a user-scope one: the layer being thinned is `~/.claude/rules`, which
-    // belongs to the machine and not to any checkout. Without these two rows a
-    // consumer who wrote the opt-in into the user-global file got no error, no
-    // warning and no effect — the same silent-filter defect the two entries
-    // above repair, reaching a third key, and unsatisfiable-by-construction on
-    // an ADR-020 global-only install, where no project layer exists to carry it.
-    // Whitelisting decides only whether a value SURVIVES the merge: it sets
-    // nothing, and `installerThinsHost` still refuses a template-only value.
-    'lean_projection.mode',
-    'lean_projection.hosts',
+    // `retro.enabled` is the one switch over the automatic retro (ADR-292). It
+    // ships `true`, so the only value worth writing is `false`, and a user who
+    // writes it once in the user-global file expects every checkout without its
+    // own value to honour it — without this row the off switch would be
+    // discarded silently. A project value still wins.
+    'retro.enabled',
 ];
 
 /** The shipped template, relative to the package root. */
@@ -800,7 +795,7 @@ export function resolve_project_root(
  * `agents/settings/`, then the per-machine local override. When `cwd` is
  * `null` or no anchor is reached, falls back to the legacy three-path set.
  */
-function _resolve_cascade_paths(
+export function _resolve_cascade_paths(
     cwd: string | null,
     project_path: string | null,
 ): string[] {