@event4u/agent-config 9.20.0 → 9.22.0

package/src/scripts/lint_discovery_vocabulary.ts

@@ -19,6 +19,8 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = path.resolve(fileURLToPath(import.meta.url));
 // REPO_ROOT = Path(__file__).resolve().parent.parent.parent
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -179,6 +181,17 @@ function lint(quiet: boolean): number {
     const workspaces = _load(WORKSPACES_YML);
     const packs = _load(PACKS_YML);
 
+    // `_load` accepts an empty YAML list, so two present-but-emptied files read
+    // as a vocabulary of nothing. Assert the entries actually loaded — the ADR
+    // parity check below would report that as missing ids, which describes the
+    // symptom and not the cause.
+    assertScanned({
+        gate: 'lint_discovery_vocabulary',
+        scanned: workspaces.length + packs.length,
+        units: 'vocabulary entr(y/ies)',
+        roots: [_relToRoot(WORKSPACES_YML), _relToRoot(PACKS_YML)],
+    });
+
     const ws_ids = new Set<unknown>(workspaces.map((entry) => entry['id']));
     const pack_ids = new Set<unknown>(packs.map((entry) => entry['id']));
 
@@ -373,6 +386,12 @@ function main(): number {
             process.stderr.write(`${err.detail}\n`);
             return 1;
         }
+        if (err instanceof DeadScopeError) {
+            // Same code as a missing vocabulary file (1) — the gate has one
+            // failure code, and 2 belongs to the pinned YAML-loader contract.
+            process.stderr.write(`❌ ${err.message}\n`);
+            return 1;
+        }
         throw err;
     }
 }

package/src/scripts/lint_documented_commands.ts

@@ -32,6 +32,8 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { load as yamlLoad } from 'js-yaml';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 // NOTE: deliberately no runtime module dependency on the CLI registry —
 // src/cli/ is outside the package.json `files` whitelist, so importing it
 // would crash a global install (prepack-check). The registry file is parsed
@@ -625,6 +627,27 @@ function main(): number {
     const scanTrees: ScanTree[] = args.scanRoots.length
         ? args.scanRoots.map((dir) => ({ dir, match: (n: string) => n.endsWith('.md') }))
         : [...DEFAULT_SCAN_TREES];
+    // `_collectTargets` skips a scan tree whose dir is absent, so a renamed
+    // src/skills (or a --scan-root typo) yields zero targets and the run prints
+    // "Every documented package command resolves" having opened no doc. Exit 3
+    // matches the scan-failure code below: no targets means the linter did not
+    // run, which is not "0 violations" (0).
+    const targets = _collectTargets(args.root, scanTrees).length;
+    try {
+        assertScanned({
+            gate: 'lint_documented_commands',
+            scanned: targets,
+            units: 'doc file(s)',
+            roots: scanTrees.map((t) => t.dir),
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`${exc.message}\n`);
+            return 3;
+        }
+        throw exc;
+    }
+
     let violations: Violation[];
     try {
         violations = scan(args.root, scanTrees);

package/src/scripts/lint_empty_roadmaps.ts

@@ -15,6 +15,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 /** Mirror `QUIET = "--quiet" in sys.argv` (computed at import). */
 const QUIET = process.argv.slice(2).includes('--quiet');
 
@@ -115,6 +117,27 @@ function find_empty_roadmaps(root: string): string[] {
 
 function main(): number {
     const root = _repo_root();
+    // The scanned unit is every roadmap `*.md`, never the empty ones: this gate
+    // reports an ABSENCE, so "no empty roadmaps" and "no roadmaps at all" print
+    // the same green line. `_repo_root()` falls back to CWD when it finds no
+    // `agents/roadmaps` anywhere up the chain, which is exactly how a moved tree
+    // reaches zero silently.
+    const base = path.join(root, ROADMAP_DIR);
+    try {
+        assertScanned({
+            gate: 'lint_empty_roadmaps',
+            scanned: _isDir(base) ? _rglobMdSorted(base).length : 0,
+            units: 'roadmap file(s)',
+            roots: [ROADMAP_DIR],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     const empties = find_empty_roadmaps(root);
 
     if (empties.length === 0) {

package/src/scripts/lint_eval_fixture_citations.ts

@@ -19,6 +19,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const QUIET = process.argv.includes('--quiet');
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -79,6 +81,23 @@ function main(): number {
     for (const root of SCAN_ROOTS) {
         walk(root, files);
     }
+    // The citation haystack is the scanned unit. A vanished SCAN_ROOTS tree
+    // still fails — as "N of N uncited" — but names the fixtures as the
+    // culprit; asserting the walk here reports the real cause instead.
+    try {
+        assertScanned({
+            gate: 'lint_eval_fixture_citations',
+            scanned: files.length,
+            units: 'citation-surface file(s)',
+            roots: SCAN_ROOTS.map((r) => path.relative(REPO, r)),
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
     const haystack = files
         .map((f) => {
             try {

package/src/scripts/lint_eval_freshness.ts

@@ -40,6 +40,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 // REPO = Path(__file__).resolve().parents[2]
@@ -119,6 +121,19 @@ function _manifestPaths(): string[] {
     return out;
 }
 
+/** Immediate `src/skills/*` directories — the population `_manifestPaths` filters. */
+function _skillDirs(): string[] {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(SKILLS_DIR, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    return entries
+        .map((ent) => path.join(SKILLS_DIR, ent.name))
+        .filter((p) => _isDirPath(p));
+}
+
 function _isDirPath(p: string): boolean {
     try {
         return fs.statSync(p).isDirectory();
@@ -309,6 +324,26 @@ function main(argv?: readonly string[]): number {
     }
     const args = parsed.args as Args;
 
+    // The scanned unit is the skill directory, not the corpus manifests it
+    // filters down to: a skill without `data/manifest.json` is legitimately out
+    // of scope, so a zero-manifest count cannot be told from a healthy tree.
+    // Zero skill directories can — and `check()` returns clean over a missing
+    // SKILLS_DIR, which is the ✅ line printed over nothing.
+    try {
+        assertScanned({
+            gate: 'lint_eval_freshness',
+            scanned: _skillDirs().length,
+            units: 'skill director(ies)',
+            roots: [path.relative(REPO, SKILLS_DIR)],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     const errors = check();
     if (errors.length) {
         process.stderr.write('eval-freshness: corpus-backed skills missing a current last_eval:\n');

package/src/scripts/lint_examples.ts

@@ -23,6 +23,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 // Path(__file__).resolve().parent.parent.parent — three dirs up from the file.
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -145,9 +147,22 @@ function _pyRepr(s: string): string {
 
 export function main(): number {
     const demos = _sorted_demos(REPO_ROOT);
-    if (demos.length === 0) {
-        process.stderr.write(`❌  no demo files matched ${DEMO_GLOB}\n`);
-        return 1;
+    // Supersedes the bare `demos.length === 0 → exit 1` check: same exit code,
+    // but the message names the root, so a moved demo directory reads as a dead
+    // scope instead of "the glob matched nothing".
+    try {
+        assertScanned({
+            gate: 'lint_examples',
+            scanned: demos.length,
+            units: 'demo file(s)',
+            roots: [DEMO_GLOB],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
     }
     let failed = 0;
     for (const demo of demos) {

package/src/scripts/lint_explain_trace.ts

@@ -32,6 +32,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 function _repo_root(): string {
@@ -344,6 +346,27 @@ function main(argv?: readonly string[]): number {
     const opts = parse_args(argv ?? process.argv.slice(2));
 
     const schema = _load_schema();
+    // The payload is caller-supplied, so the gate's own scope is the schema —
+    // and `_load_schema` only proves the FILE is there. A schema that parses to
+    // an empty (or property-less) document validates every payload silently and
+    // prints `✅  explain-trace OK`. Count the property rules that will actually
+    // be applied; the keyword filtering below is judgement, this is reach.
+    try {
+        assertScanned({
+            gate: 'lint_explain_trace',
+            scanned: Object.keys(_isObject(schema['properties']) ? schema['properties'] : {}).length,
+            units: 'schema property rule(s)',
+            roots: ['docs/contracts/explain-trace.schema.json'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 2 = invocation error — the same code a missing schema returns.
+            // 1 would claim the payload is invalid, which is not what happened.
+            process.stderr.write(`❌  ${exc.message}\n`);
+            throw new SystemExit(2);
+        }
+        throw exc;
+    }
     // Python: jsonschema.Draft202012Validator.check_schema(schema) — the
     // explain-trace schema is a valid Draft-2020-12 document, so this never
     // raises in practice; the subset validator has no schema-validation step.

package/src/scripts/lint_featured_skills.ts

@@ -21,6 +21,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 // CWD-relative, exactly as the Python module's Path(...) literals.
@@ -132,9 +134,32 @@ function main(argv: readonly string[]): number {
     const [skills, commands, packs] = manifest_names(manifest);
     const body = fs.readFileSync(DOC, 'utf-8');
 
+    // The doc existing is not the doc being readable by this gate: LINK_RE is
+    // pinned to the `../dist/agent-src/{skills,commands}/…` link shape, so a
+    // restructured or emptied Featured Skills page yields zero entries and the
+    // OK line reports "0 artefact entries validated". Assert the raw match list,
+    // before the dedupe the checks below run on.
+    const links = _findLinks(body);
+    try {
+        assertScanned({
+            gate: 'lint_featured_skills',
+            scanned: links.length,
+            units: 'featured artefact link(s)',
+            roots: [DOC],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 is the gate's only failure code — the same one a missing DOC or
+            // manifest already returns.
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     const missing: string[] = [];
     const seen = new Set<string>();
-    for (const [cat, raw] of _findLinks(body)) {
+    for (const [cat, raw] of links) {
         const slug = slug_from_path(cat, raw);
         const key = `${cat}\0${slug}`;
         if (seen.has(key)) {

package/src/scripts/lint_flows.ts

@@ -41,6 +41,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import YAML from 'yaml';
 
 import { resolve_logical } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 // Path(__file__).resolve().parents[2] — repo root, two dirs up from src/scripts.
@@ -647,6 +648,24 @@ export function main(argv?: string[]): number {
         return 3;
     }
 
+    // Exit 3, not 1: an empty flows dir is the same class of failure as the
+    // `flows dir not found` / `schema not found` short-circuits above (the gate
+    // could not do its job), not a flow that violates the schema.
+    try {
+        assertScanned({
+            gate: 'lint_flows',
+            scanned: files.length,
+            units: 'flow file(s)',
+            roots: ['src/flows'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`${exc.message}\n`);
+            return 3;
+        }
+        throw exc;
+    }
+
     if (vios.length > 0) {
         process.stderr.write(`lint_flows: ${vios.length} violation(s):\n`);
         for (const v of vios) {

package/src/scripts/lint_frontmatter_boilerplate.ts

@@ -27,6 +27,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { artefact_roots } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 import {
     load_schema,
     parse_frontmatter,
@@ -303,6 +304,25 @@ function main(argv: readonly string[]): number {
         }
     }
 
+    // `_iter` skips a category whose base directory is absent, so an
+    // `artefact_roots()` that resolves to nothing (or four renamed category
+    // subdirs) yields no files at all and the gate reports "0 artefact(s)
+    // clean" — clean being exactly what it cannot know.
+    try {
+        assertScanned({
+            gate: 'lint_frontmatter_boilerplate',
+            scanned: total,
+            units: 'artefact(s)',
+            roots: artefact_roots().map((r) => path.relative(ROOT, r).split(path.sep).join('/') || '.'),
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     if (offenders > 0) {
         process.stderr.write(
             `\n== frontmatter-boilerplate: ${offenders}/${total} artefact(s) carry a ` +

package/src/scripts/lint_ghostwriter_source.ts

@@ -28,6 +28,8 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import YAML from 'yaml';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 const QUIET = process.argv.slice(2).includes('--quiet');
 
@@ -294,6 +296,30 @@ function main(): number {
     const cons_errors = lint_consumer_side();
     const errors = [...pkg_errors, ...cons_errors];
 
+    // Both tiers together are the corpus. The consumer tier is legitimately
+    // empty in the package repo, so counting it alone would read a vanished
+    // package-fixture dir as "no profiles to lint" and stay green.
+    const pkg_count = _exists(PACKAGE_DIR)
+        ? _globMdSorted(PACKAGE_DIR).filter((p) => !EXEMPT_STEMS.has(_stem(p))).length
+        : 0;
+    const cons_count = _exists(CONSUMER_DIR)
+        ? _globMdSorted(CONSUMER_DIR).filter((p) => !EXEMPT_STEMS.has(_stem(p))).length
+        : 0;
+    try {
+        assertScanned({
+            gate: 'lint_ghostwriter_source',
+            scanned: pkg_count + cons_count,
+            units: 'profile(s)',
+            roots: ['src/agent-src/ghostwriter', 'agents/ghostwriter'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     if (errors.length) {
         process.stderr.write(`❌  lint_ghostwriter_source: ${errors.length} violation(s)\n`);
         for (const line of errors) {
@@ -304,12 +330,6 @@ function main(): number {
     }
 
     if (!QUIET) {
-        const pkg_count = _exists(PACKAGE_DIR)
-            ? _globMdSorted(PACKAGE_DIR).filter((p) => !EXEMPT_STEMS.has(_stem(p))).length
-            : 0;
-        const cons_count = _exists(CONSUMER_DIR)
-            ? _globMdSorted(CONSUMER_DIR).filter((p) => !EXEMPT_STEMS.has(_stem(p))).length
-            : 0;
         process.stdout.write(
             `✅  lint_ghostwriter_source: ${pkg_count} package fixture(s), ` +
                 `${cons_count} consumer profile(s), all compliant\n`,

package/src/scripts/lint_glama_drift.ts

@@ -18,6 +18,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 const REPO = path.resolve(path.dirname(_HERE), '..', '..');
 const GLAMA_DIR = path.join(REPO, 'internal', 'glama');
@@ -44,6 +46,28 @@ function _canonicalCommand(scriptPath: string, stripPrefix?: string): string {
 
 function main(): number {
     const readmePath = path.join(GLAMA_DIR, 'README.md');
+
+    // No corpus — the gate guards three named files. If internal/glama/ moves,
+    // every read below throws rather than reporting; name the scope instead so
+    // the failure says which paths went missing.
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_glama_drift',
+            candidates: [
+                path.posix.join('internal', 'glama', 'README.md'),
+                ...SCRIPTS.map((s) => path.posix.join('internal', 'glama', s.file)),
+            ],
+            repoRoot: REPO,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 is the gate's only failure code — drift and "cannot run" share it.
+            console.error(`❌  ${exc.message}`);
+            return 1;
+        }
+        throw exc;
+    }
+
     const readme = fs.readFileSync(readmePath, 'utf8');
 
     let failed = false;

package/src/scripts/lint_global_paths.ts

@@ -21,6 +21,8 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
+import { assertScanned, DeadScopeError } from "./_lib/scan_scope.js";
+
 const DEFAULT_POLICY = path.join(
   path.dirname(fileURLToPath(import.meta.url)),
   "expected_perms.json",
@@ -171,7 +173,29 @@ export function lint(policyPath: string, quiet = false): number {
   const policyObj: PolicyObject = isObject(policy) ? policy : {};
   const findings: string[] = [];
 
+  // The unit is the POLICY rule, not the audited path: the global install tree
+  // is machine-state and is legitimately absent (CI, a fresh clone), so a count
+  // of audited paths would have to be `allowEmpty` and assert nothing. An empty
+  // policy is the real dead scope — it audits nothing while exiting 0. Exit 2
+  // matches the other policy-load failures above.
   const rootSpecRaw = policyObj["global_root"];
+  try {
+    assertScanned({
+      gate: "lint_global_paths",
+      scanned:
+        (isObject(rootSpecRaw) ? 1 : 0) +
+        asArray(policyObj["files"]).length +
+        asArray(policyObj["directories"]).length,
+      units: "policy rule(s)",
+      roots: [policyPath],
+    });
+  } catch (exc) {
+    if (exc instanceof DeadScopeError) {
+      process.stderr.write(`error: ${exc.message}\n`);
+      return 2;
+    }
+    throw exc;
+  }
   const rootSpec: PolicyObject = isObject(rootSpecRaw) ? rootSpecRaw : {};
   const rootPath = _expand(asString(rootSpec["path"], "~/.event4u/agent-config"));
   if (_exists(rootPath)) {

package/src/scripts/lint_governed_writes.ts

@@ -46,6 +46,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
+import { assertScanned, DeadScopeError } from "./_lib/scan_scope.js";
+
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
 export const REPO_ROOT = path.resolve(_HERE, "..", "..");
 export const SCRIPTS_DIR = path.join(REPO_ROOT, "src", "scripts");
@@ -288,6 +290,24 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
   const jsonMode = argv.includes("--json");
   const quiet = argv.includes("--quiet");
 
+  // The asserted unit is every eligible `.ts` file the walk yields, never the
+  // finding count: an empty findings list IS the pass state here, so a moved
+  // SCRIPTS_DIR would read as "clean" instead of "read nothing".
+  try {
+    assertScanned({
+      gate: "lint_governed_writes",
+      scanned: [...walkTsFiles(SCRIPTS_DIR, SCRIPTS_DIR)].length,
+      units: "script file(s)",
+      roots: ["src/scripts"],
+    });
+  } catch (exc) {
+    if (exc instanceof DeadScopeError) {
+      process.stderr.write(`❌  ${exc.message}\n`);
+      return 2;
+    }
+    throw exc;
+  }
+
   const findings = scanScriptsDir(SCRIPTS_DIR);
 
   if (jsonMode) {

package/src/scripts/lint_hidden_unicode.ts

@@ -34,6 +34,7 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as sl from './_lib/security_lint.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 export const CHECK = 'hidden-unicode';
 
@@ -499,7 +500,9 @@ export function main(argv: readonly string[] | null = null): number {
 
     const findings: sl.Finding[] = [];
     const flagged = new Set<string>();
+    let corpusFiles = 0;
     for (const sf of sl.iter_corpus()) {
+        corpusFiles += 1;
         const hits = _scan(sf);
         for (const h of hits) {
             findings.push(h);
@@ -509,6 +512,28 @@ export function main(argv: readonly string[] | null = null): number {
         }
     }
 
+    // `iter_corpus` skips a root that does not exist, so a moved corpus yields
+    // zero files and this security lint reports "clean" — and the umbrella
+    // aggregate reads that as 0 blocking findings. Count files READ, not
+    // findings. The second (source-bytes) pass states its own file count below
+    // and is separately visible, so this assertion guards the `.md` corpus.
+    // Exit 1 is this CLI's only failure code (2 is the pinned argparse usage
+    // error), so it carries "could not run" here.
+    try {
+        assertScanned({
+            gate: 'lint_hidden_unicode',
+            scanned: corpusFiles,
+            units: 'corpus file(s)',
+            roots: sl.DEFAULT_SCAN_ROOTS,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     // Second pass — raw control bytes in text-intended SOURCE files, which the
     // `.md` corpus above does not cover. Deliberately not folded into
     // `iter_corpus`: different scope (all tracked text files, not the `.md`