@event4u/agent-config 9.10.0 → 9.12.0

package/src/scripts/council_cli.ts

@@ -69,7 +69,7 @@ import {
     resolve_config_path,
 } from './ai_council/config.js';
 import { AuthCache, select_solo_member } from './ai_council/solo_dispatch.js';
-import { InvalidModeError, resolve_mode } from './ai_council/modes.js';
+import { InvalidModeError, resolve_global_mode, resolve_mode } from './ai_council/modes.js';
 import { appendEvent } from './ai_council/events_log.js';
 import {
     type ClassificationResult,
@@ -564,7 +564,11 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
         );
     }
     const members_cfg = (ai['members'] as Dict) || {};
-    const global_mode = ai['mode'] as string | null | undefined;
+    // Accepts BOTH the synthesized flat `mode` and the raw `defaults.mode`
+    // shape — see modes.ts::resolve_global_mode. Reading only the flat key
+    // dropped the configured default for every caller that hands this
+    // exported function a raw `.ai-council.yml` dict.
+    const global_mode = resolve_global_mode(ai);
     const cli_budget_cfg = _isDict(ai) ? ((ai['cli_call_budget'] as Dict) || {}) : {};
     const cli_caps = _isDict(cli_budget_cfg)
         ? ((cli_budget_cfg['max_calls_per_day'] as Dict) || {})

package/src/scripts/evaluator_umbrella.sh

@@ -65,11 +65,38 @@ UNPACKED_BYTES="$(npm pack --dry-run --json --ignore-scripts --silent 2>/dev/nul
 step "headless consumer install from the tarball"
 WORK="$(mktemp -d)"
 trap 'rm -rf "$WORK"' EXIT
+COLD_START_T0="$(node -e 'console.log(Date.now())')"
 ( cd "$WORK" && npm init -y >/dev/null 2>&1 \
   && npm install --omit=dev --no-audit --no-fund --silent "$ROOT/$TARBALL" )
 PKG_DIR="$WORK/node_modules/@event4u/agent-config"
 [[ -d "$PKG_DIR" ]] || { echo "❌ install did not produce the package dir" >&2; exit 1; }
 
+# ------------------------------------------- 3b. cold start: install → doctor
+# The bare-machine wall-clock a first-time user lives through, measured end to
+# end from `npm install` to `doctor` having run. This is EVIDENCE, never a
+# promise, and deliberately NOT a budget entry: it is dominated by network and
+# registry latency, which are not ours to guarantee. A gate on it would flap on
+# runner weather and teach the reader to ignore the line
+# (road-to-zero-ceremony-install Phase 6).
+step "cold start: install → doctor (evidence, not a gate)"
+COLD_START_MS="$(node -e '
+const {execFileSync}=require("node:child_process");
+const [bin, t0] = process.argv.slice(1);
+try { execFileSync(bin, ["doctor"], {stdio:"ignore"}); }
+catch { /* doctor may report findings; the run still bounds the wall-clock */ }
+console.log(Date.now() - Number(t0));' "$WORK/node_modules/.bin/agent-config" "$COLD_START_T0")"
+COLD_START_CONDITIONS="$(uname -s)/$(uname -m) · node $(node --version) · npm $(npm --version) · npm install --omit=dev from a LOCAL tarball (no registry round-trip for the package itself; a real first-touch install adds registry latency)"
+printf 'cold_start_install_to_doctor_ms=%s\n' "$COLD_START_MS"
+printf 'cold_start_conditions=%s\n' "$COLD_START_CONDITIONS"
+if [[ -n "${GITHUB_STEP_SUMMARY:-}" ]]; then
+  {
+    printf '### Cold start — install → doctor\n\n'
+    printf '**%s ms**\n\n' "$COLD_START_MS"
+    printf 'Conditions: %s\n\n' "$COLD_START_CONDITIONS"
+    printf 'Evidence, not a promise — no shipped claim states this as a guarantee.\n'
+  } >> "$GITHUB_STEP_SUMMARY"
+fi
+
 # --------------------------------------------------------- 4. staleness lints
 step "staleness lints (pre-migration refs)"
 ./scripts-run src/scripts/lint_pre_migration_refs
@@ -128,10 +155,16 @@ const m={
   mcp_boot_to_initialize_ms: Number(process.argv[6]),
   cli_help_command_count: Number(process.argv[7]),
   mcp_public_tool_count: Number(process.argv[8]),
+  // Evidence-only: carried in the artifact with its conditions, never gated.
+  // check_evaluator_budgets iterates the BUDGET entries, so an extra
+  // measurement is recorded and ignored by the gate — by design.
+  cold_start_install_to_doctor_ms: Number(process.argv[9]),
+  cold_start_conditions: process.argv[10],
 };
 fs.writeFileSync(process.argv[1], JSON.stringify(m, null, 2));
 console.log(JSON.stringify(m, null, 1));' \
-  "$MEASURE_TMP" "$UNPACKED_BYTES" "$NM_MB" "$DEP_COUNT" "$CLI_MS" "$MCP_MS" "$CLI_COUNT" "$MCP_TOOLS"
+  "$MEASURE_TMP" "$UNPACKED_BYTES" "$NM_MB" "$DEP_COUNT" "$CLI_MS" "$MCP_MS" "$CLI_COUNT" "$MCP_TOOLS" \
+  "$COLD_START_MS" "$COLD_START_CONDITIONS"
 
 step "budget gate (absolute + >regression_pct creep)"
 ./scripts-run src/scripts/check_evaluator_budgets --measurements "$MEASURE_TMP"

package/src/scripts/install-hooks.sh

@@ -51,6 +51,27 @@ else
     fi
 fi
 
+# road-to-local-ci-trust Phase 2: the CI-only repo-content gates, as one task.
+# Deliberately placed AFTER the consistency block above — `task consistency`
+# runs `task sync`, which generates the `.augment/` projection. Several
+# preflight gates read that tree, so on a FRESH worktree (this repo's standard
+# workflow) running preflight first would fail with "produced by regeneration
+# but absent before" — red for a reason the contributor did not cause, which is
+# exactly the anti-pattern this gate set exists to avoid. Measured 15s against
+# the 25s `pre_push_budget_seconds` ceiling in src/config/ci-local-parity.yml.
+# `check_enforcement_coverage` (30.7s) stays out of preflight by design.
+echo "🔍 Preflight — the CI-only repo-content gates..."
+if [ "${AGENT_CONFIG_SKIP_PREPUSH_PREFLIGHT:-}" = "1" ]; then
+    echo "⏭️  skipped via AGENT_CONFIG_SKIP_PREPUSH_PREFLIGHT=1"
+elif ! command -v task >/dev/null 2>&1; then
+    echo "⚠️  'task' not found — skipping preflight for this push."
+elif ! task preflight; then
+    echo "❌  Preflight failed. These gates run in CI too, so pushing now buys a"
+    echo "    red run and a fixup re-push. Fix the failures above, or"
+    echo "    AGENT_CONFIG_SKIP_PREPUSH_PREFLIGHT=1 for a genuine WIP push."
+    exit 1
+fi
+
 echo "🔍 Checking for leftover conflict markers / unmerged paths..."
 if ! ./scripts-run src/scripts/check_no_conflict_markers --quiet; then
     echo "❌  Conflict markers or unmerged paths present. Resolve them (e.g. 'git checkout HEAD -- <file>' or finish the merge), then re-push."
@@ -127,11 +148,22 @@ if git diff --cached --name-only | grep -qE '^agents/roadmaps(-progress\.md|/)';
     ./scripts-run .augment/scripts/update_roadmap_progress --check
     rstatus=$?
     if [ $rstatus -ne 0 ]; then
+        # The check fails for THREE distinct reasons and prints the real one
+        # above: a stale dashboard, an unresolved `[~]` deferred item (Iron
+        # Law 3), or a completed-but-unarchived roadmap. Naming only the first
+        # sent a maintainer chasing a regeneration that was already correct —
+        # and a safety gate whose text points at the wrong cause trains people
+        # to distrust the gate, which costs more than the wrong message.
         echo ""
-        echo "❌  Commit blocked — agents/roadmaps-progress.md is stale."
-        echo "   Run './agent-config roadmap:progress' (or"
-        echo "   './scripts-run .augment/scripts/update_roadmap_progress'),"
-        echo "   stage agents/roadmaps-progress.md, then re-commit."
+        echo "❌  Commit blocked — the roadmap dashboard gate failed."
+        echo "   The cause is printed above. The three it reports:"
+        echo "     · dashboard stale      → './agent-config roadmap:progress',"
+        echo "                               then stage agents/roadmaps-progress.md"
+        echo "     · Iron Law 3           → unresolved '[~]' deferred items. Surface"
+        echo "                               them and ask the user; NOT the agent's"
+        echo "                               to clear (roadmap-management § 4b)"
+        echo "     · completed roadmap    → 'git mv' it into agents/roadmaps/archive/,"
+        echo "                               then regenerate"
         echo "   To bypass for an unrelated WIP commit: git commit --no-verify"
         exit 1
     fi

package/src/scripts/install.ts

@@ -82,6 +82,13 @@ import * as user_global_paths from './_lib/user_global_paths.js';
 import * as claude_desktop_bundler from './_lib/claude_desktop_bundler.js';
 import * as claude_settings_hooks from './_lib/claude_settings_hooks.js';
 import { find_project_root_with_anchor, load_agent_settings } from './_lib/agent_settings.js';
+import {
+    LEGACY_ALL,
+    ruleFileArrives,
+    ruleScopeFromSettings,
+    type RuleScope,
+} from '../install/rule_scope.js';
+import { RULE_SOURCE_REL } from '../install/wizard-plan.js';
 import { flattenSurface, computeSurfaceDelta, type SettingsSurface } from '../shared/settingsSurface.js';
 import { settingsSchema } from '../server/schemas/settings.js';
 import { zodToJsonSchema } from 'zod-to-json-schema';
@@ -2730,17 +2737,71 @@ function _inject_package_tag(
     }
 }
 
+/**
+ * Would dereferencing `entry` escape the package root?
+ *
+ * `_copy_dir_dereferencing_symlinks` copies the REALPATH of every entry, so a
+ * symlink in the shipped tree pointing outside the package would copy an
+ * arbitrary readable file into the deploy destination — and those destinations
+ * are agent-readable instruction dirs (`~/.claude/rules/`, `~/.codeium/…`). A
+ * tampered tarball carrying `rules/x.md -> ~/.ssh/id_rsa` would land that file
+ * where an agent reads rules.
+ *
+ * Defence-in-depth for `docs/threat-model.md` row b (supply-chain compromise):
+ * the package is the install-time trust anchor, so this is not the primary
+ * control — but the check is one comparison and `package_root` was already
+ * threaded through, so there is no reason to ship without it.
+ *
+ * Both sides are realpath'd before comparing, so a macOS `/var` → `/private/var`
+ * root does not read as an escape. A `null` package_root means the caller did
+ * not scope the copy (several do) — unchanged, permissive behaviour there.
+ */
+function _escapes_package_root(resolved: string, package_root: string | null): boolean {
+    if (package_root === null) return false;
+    let root: string;
+    try {
+        root = fs.realpathSync(package_root);
+    } catch {
+        // Unresolvable root — cannot judge containment, so do not block the copy.
+        return false;
+    }
+    return !global_deploy_inventory.is_ancestor(root, resolved);
+}
+
+/**
+ * Copy `src` → `dest`, dereferencing symlinks, returning
+ * `[written, skipped, written_paths]`.
+ *
+ * `file_filter` is an optional predicate over the SOURCE path; `false` means the
+ * file is not part of this install and is neither copied nor counted. It MUST be
+ * the same predicate handed to `global_deploy_inventory.expected_deploy_files`
+ * for the same source — that function computes what the reaper considers
+ * "should exist", so filtering one side only either leaves excluded files behind
+ * forever or deletes files the copy just wrote.
+ */
 function _copy_dir_dereferencing_symlinks(
     src: string,
     dest: string,
     force: boolean,
     package_root: string | null = null,
+    file_filter: global_deploy_inventory.FileFilter | null = null,
 ): [number, number, string[]] {
     let written = 0;
     let skipped = 0;
     const written_paths: string[] = [];
     if (!pathExists(src)) return [0, 0, written_paths];
     if (!isDir(src)) {
+        if (file_filter !== null && !file_filter(src)) return [0, 0, written_paths];
+        let resolved_src = src;
+        try {
+            resolved_src = fs.realpathSync(src);
+        } catch {
+            resolved_src = src;
+        }
+        if (_escapes_package_root(resolved_src, package_root)) {
+            warn(`refused: ${src} dereferences outside the package root — not copied`);
+            return [0, 0, written_paths];
+        }
         mkdirp(path.dirname(dest));
         const decision = _resolve_file_conflict(dest, force);
         if (decision === 'skip') return [0, 1, written_paths];
@@ -2784,6 +2845,13 @@ function _copy_dir_dereferencing_symlinks(
         } catch {
             resolvedIsDir = false;
         }
+        // Containment is checked on the RESOLVED path, before either the
+        // recursion or the copy — a symlinked directory escaping the root would
+        // otherwise pull its whole subtree in.
+        if (_escapes_package_root(resolved, package_root)) {
+            warn(`refused: ${entry} dereferences outside the package root — not copied`);
+            continue;
+        }
         if (resolvedIsDir) {
             mkdirp(target);
             const [sub_w, sub_s, sub_p] = _copy_dir_dereferencing_symlinks(
@@ -2791,12 +2859,20 @@ function _copy_dir_dereferencing_symlinks(
                 target,
                 force,
                 package_root,
+                file_filter,
             );
             written += sub_w;
             skipped += sub_s;
             written_paths.push(...sub_p);
             continue;
         }
+        // The predicate sees the SOURCE path (the rule-scope predicate reads the
+        // file's own frontmatter tags). Skipped files are counted as neither
+        // written nor skipped-as-identical: they are not part of this install,
+        // so the inventory twin must omit them too or the reaper drifts.
+        if (file_filter !== null && !file_filter(entry)) {
+            continue;
+        }
         const decision = _resolve_file_conflict(target, force);
         if (decision === 'skip') {
             skipped += 1;
@@ -2949,6 +3025,10 @@ function _deploy_global_content(
     lockfile_path: string,
 ): Record<string, DeployResult> {
     const results: Record<string, DeployResult> = {};
+    // Resolved ONCE per deploy, not per tool: every tool installs the same rule
+    // tree, and re-reading settings per tool could yield different answers
+    // mid-run if the file changed underneath.
+    const rule_scope = _resolve_global_rule_scope(package_root);
     for (const tool_id of [...tools].sort()) {
         if (tool_id === 'claude-desktop') {
             results[tool_id] = _deploy_claude_desktop(force, package_root, lockfile_path);
@@ -2975,13 +3055,30 @@ function _deploy_global_content(
         for (const [src_rel, dest_sub] of plan) {
             const src = path.join(package_root, src_rel);
             const dest = dest_sub ? path.join(anchor, dest_sub) : anchor;
-            const [w, s, paths] = _copy_dir_dereferencing_symlinks(src, dest, force, package_root);
+            // ONE filter instance, handed to BOTH the copy and the inventory.
+            // `expected_deploy_files` is what the reaper treats as "should
+            // exist": filtering only the copy would leave previously-installed
+            // maintainer rules on disk forever, and filtering only the
+            // inventory would delete rules the copy just wrote. Both, or
+            // neither — never one.
+            const rule_filter = _rule_filter_for_source(src_rel, rule_scope);
+            const [w, s, paths] = _copy_dir_dereferencing_symlinks(
+                src,
+                dest,
+                force,
+                package_root,
+                rule_filter,
+            );
             written_total += w;
             skipped_total += s;
             written_paths.push(...paths);
             current_files = setUnion(
                 current_files,
-                global_deploy_inventory.expected_deploy_files(src, dest_sub ? dest_sub : ''),
+                global_deploy_inventory.expected_deploy_files(
+                    src,
+                    dest_sub ? dest_sub : '',
+                    rule_filter,
+                ),
             );
         }
         // Flat-command → skill-wrapper re-projection for Claude Code
@@ -3091,6 +3188,9 @@ function _preview_global_reap(
 ): Record<string, string[]> {
     const inventory = global_deploy_inventory.load_inventory();
     const preview: Record<string, string[]> = {};
+    // The preview must compute the SAME expected set the real deploy will, or
+    // `--dry-run` under-reports the rules a scoped upgrade is about to reap.
+    const rule_scope = _resolve_global_rule_scope(package_root);
     for (const tool_id of [...tools].sort()) {
         const plan = GLOBAL_DEPLOY_SOURCES[tool_id];
         if (plan === undefined) continue;
@@ -3102,7 +3202,11 @@ function _preview_global_reap(
             const src = path.join(package_root, src_rel);
             current_files = setUnion(
                 current_files,
-                global_deploy_inventory.expected_deploy_files(src, dest_sub ? dest_sub : ''),
+                global_deploy_inventory.expected_deploy_files(
+                    src,
+                    dest_sub ? dest_sub : '',
+                    _rule_filter_for_source(src_rel, rule_scope),
+                ),
             );
         }
         let would_reap: string[] = [];
@@ -3334,11 +3438,25 @@ function _compute_active_pack_ids(
  * artefact of any kind.
  */
 function _resolve_global_settings_doc(): Record<string, unknown> | null {
+    const p = _resolve_global_settings_path();
+    return p === null ? null : _load_yaml_doc(p);
+}
+
+/**
+ * The path `_resolve_global_settings_doc` would read, or `null` when no global
+ * settings artefact exists at all.
+ *
+ * Split out because "absent" and "present but unparseable" are different facts
+ * and one caller must tell them apart: `_load_yaml_doc` maps BOTH to `{}`, which
+ * silently turns a YAML typo into legacy-all rule scoping — defeating a scoping
+ * decision the user made, with no signal. See `_resolve_global_rule_scope`.
+ */
+function _resolve_global_settings_path(): string | null {
     const root = user_global_paths.event4u_root();
     const canonical = path.join(root, 'settings', SETTINGS_FILE);
-    if (pathExists(canonical)) return _load_yaml_doc(canonical);
+    if (pathExists(canonical)) return canonical;
     const legacy = path.join(root, SETTINGS_FILE);
-    if (pathExists(legacy)) return _load_yaml_doc(legacy);
+    if (pathExists(legacy)) return legacy;
     return null;
 }
 
@@ -3369,6 +3487,84 @@ function _resolve_scoped_projection(
     return { mode, active_packs };
 }
 
+/**
+ * Resolve the rule scope governing THIS global deploy — the same way the wizard
+ * does (`src/server/routes/install.ts::_resolveRuleScope`), so the two global
+ * paths cannot ship different rule sets for the same settings.
+ *
+ * Settings resolution mirrors `_resolve_scoped_projection` above: an existing
+ * global settings doc is authoritative, and only a genuinely fresh machine falls
+ * through to the packaged template. Any read or parse failure resolves to
+ * `LEGACY_ALL` — over-shipping is the safe direction, and the compat exclusion
+ * (`source-of-truth.md`) still applies even then.
+ */
+function _resolve_global_rule_scope(package_root: string): RuleScope {
+    const settings_path = _resolve_global_settings_path();
+
+    // No global settings artefact at all — a genuinely fresh machine. Fall
+    // through to the packaged template silently: there is no user decision to
+    // contradict, and this is the documented upgrade-compat path.
+    if (settings_path === null) {
+        try {
+            return ruleScopeFromSettings(_load_default_settings(package_root));
+        } catch {
+            return LEGACY_ALL;
+        }
+    }
+
+    // A doc EXISTS, so the user has expressed a configuration. Failing to read
+    // it is not the same as not having one: falling back to legacy-all here
+    // ships the maintainer-only rules the user may have deliberately scoped out,
+    // and `_load_yaml_doc` would report that as an indistinguishable `{}`. So
+    // parse it explicitly and be LOUD when it does not parse — over-shipping
+    // stays the safe direction, but it must not be a silent one.
+    let text: string;
+    try {
+        text = readText(settings_path);
+    } catch (e) {
+        warn(
+            `could not read ${settings_path} (${String(e)}) — rule scoping falls back ` +
+                'to legacy-all, so ALL rules including maintainer-only ones will be ' +
+                'installed. Fix the file to restore scoping.',
+        );
+        return LEGACY_ALL;
+    }
+    const parsed = yamlSafeLoad(text);
+    if (!_isPlainObject(parsed)) {
+        warn(
+            `${settings_path} is not a YAML mapping — rule scoping falls back to ` +
+                'legacy-all, so ALL rules including maintainer-only ones will be ' +
+                'installed. Fix the file to restore scoping.',
+        );
+        return LEGACY_ALL;
+    }
+    try {
+        return ruleScopeFromSettings(parsed as Record<string, unknown>);
+    } catch (e) {
+        warn(
+            `could not derive rule scope from ${settings_path} (${String(e)}) — ` +
+                'falling back to legacy-all; ALL rules will be installed.',
+        );
+        return LEGACY_ALL;
+    }
+}
+
+/**
+ * The rule-scope filter for one `GLOBAL_DEPLOY_SOURCES` row, or `null` when the
+ * row is not the rules tree.
+ *
+ * Keyed on `src_rel === RULE_SOURCE_REL` exactly as `expandWizardSources` keys
+ * it — the two must agree on WHICH source gets filtered, not only on the
+ * predicate.
+ */
+function _rule_filter_for_source(
+    src_rel: string,
+    scope: RuleScope,
+): global_deploy_inventory.FileFilter | null {
+    if (src_rel !== RULE_SOURCE_REL) return null;
+    return (srcFile: string): boolean => ruleFileArrives(srcFile, scope);
+}
+
 /**
  * Prune every skill/command artefact whose `packs:` frontmatter is
  * non-empty AND has no intersection with `active_ids`. Untagged artefacts
@@ -5035,5 +5231,14 @@ export {
     _compute_active_pack_ids,
     _resolve_global_settings_doc,
     _resolve_scoped_projection,
+    // road-to-consistent-rule-scoping Phase 2: the CLI global deploy path had
+    // no direct test — the existing rule-scoping suite covers the PLAN path
+    // (`expandWizardSources`) only, which is why the two diverged unnoticed.
+    _deploy_global_content,
+    // road-to-local-ci-trust: exported for the symlink-confinement tests
+    // (PR #1076 review-gate finding).
+    _copy_dir_dereferencing_symlinks,
+    _preview_global_reap,
+    _resolve_global_rule_scope,
 };
 export type { Options, PackRecord, DeployResult };

package/src/scripts/lint_eval_fixture_citations.ts

@@ -0,0 +1,113 @@
+#!/usr/bin/env tsx
+/**
+ * Every design-artifact eval fixture id must be cited by some surface.
+ *
+ * The fixtures file used to assert that the lifecycle contract's branch table
+ * "references these ids". It cites nine of them; the rest are gated elsewhere
+ * (the design-fidelity mechanics guideline, the lane-matrix test) — and a
+ * handful were cited by nothing at all. An uncited fixture is an eval nobody
+ * runs and no contract depends on, which is exactly the shape of coverage that
+ * looks real in a count and is absent in practice.
+ *
+ * This checks citation, not correctness: an id must appear outside its own
+ * definition. Which surface cites it is the author's call.
+ *
+ * Exit codes: 0 every id cited, 1 one or more uncited.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const QUIET = process.argv.includes('--quiet');
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+const FIXTURES = path.join(REPO, 'tests', 'design-artifacts', 'eval-fixtures.md');
+
+/** Surfaces allowed to satisfy a citation. */
+const SCAN_ROOTS: readonly string[] = [
+    path.join(REPO, 'docs', 'contracts'),
+    path.join(REPO, 'docs', 'guidelines'),
+    path.join(REPO, 'src', 'skills'),
+    path.join(REPO, 'src', 'rules'),
+    path.join(REPO, 'tests', 'scripts'),
+];
+
+const SCAN_EXTS: ReadonlySet<string> = new Set(['.md', '.ts']);
+
+function walk(dir: string, out: string[]): void {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return;
+    }
+    for (const entry of entries) {
+        const p = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            walk(p, out);
+        } else if (SCAN_EXTS.has(path.extname(entry.name))) {
+            out.push(p);
+        }
+    }
+}
+
+function main(): number {
+    let fixtureText: string;
+    try {
+        fixtureText = fs.readFileSync(FIXTURES, { encoding: 'utf-8' });
+    } catch {
+        process.stderr.write(`lint-eval-fixture-citations: cannot read ${FIXTURES}\n`);
+        return 1;
+    }
+
+    // Ids are declared as `### daf-...` headings or as leading table cells.
+    const ids = new Set<string>();
+    for (const m of fixtureText.matchAll(/^###\s+(daf-[a-z0-9-]+)\s*$/gm)) {
+        ids.add(m[1] as string);
+    }
+    for (const m of fixtureText.matchAll(/^\|\s*`(daf-[a-z0-9-]+)`\s*\|/gm)) {
+        ids.add(m[1] as string);
+    }
+    if (ids.size === 0) {
+        process.stderr.write('lint-eval-fixture-citations: no fixture ids found — parser drift.\n');
+        return 1;
+    }
+
+    const files: string[] = [];
+    for (const root of SCAN_ROOTS) {
+        walk(root, files);
+    }
+    const haystack = files
+        .map((f) => {
+            try {
+                return fs.readFileSync(f, { encoding: 'utf-8' });
+            } catch {
+                return '';
+            }
+        })
+        .join('\n');
+
+    const uncited = [...ids].filter((id) => !haystack.includes(id)).sort();
+    if (uncited.length > 0) {
+        for (const id of uncited) {
+            process.stdout.write(
+                `lint-eval-fixture-citations: \`${id}\` is cited by no contract, ` +
+                    'guideline, skill, rule, or test — an eval nobody runs.\n',
+            );
+        }
+        process.stderr.write(
+            `lint-eval-fixture-citations: ${uncited.length} of ${ids.size} fixture id(s) uncited.\n`,
+        );
+        return 1;
+    }
+    if (!QUIET) {
+        process.stdout.write(
+            `lint-eval-fixture-citations: ${ids.size} fixture id(s), all cited.\n`,
+        );
+    }
+    return 0;
+}
+
+process.exit(main());