@event4u/agent-config 9.9.0 → 9.10.0

package/src/scripts/encoding_corpus_report.ts

@@ -0,0 +1,216 @@
+#!/usr/bin/env tsx
+/**
+ * Measure the encoding floor against the FROZEN corpus
+ * (road-to-runtime-encoding-hardening Phase 4).
+ *
+ * Renders the numbers from the corpus — never hand-typed — and evaluates them
+ * against the thresholds the roadmap pre-registered BEFORE the detector existed:
+ *
+ *   recall on in-scope positives            >= 0.95
+ *   recall on unambiguous classes           >= 0.99
+ *     (zero-width, bidi, variation-selector)
+ *   false-positive rate on clean negatives  <= 0.005
+ *   added runtime model spend               == 0   (structural: no model call)
+ *   added latency                           <  2 ms p95 per message
+ *
+ * A positive counts as DETECTED when the floor either strips its signal
+ * (`sanitize_text` changed the value) or reports it (`scan_encoding_findings`
+ * returned a finding). Both are "the vector did not reach the model unnoticed",
+ * which is the property under test.
+ *
+ * Usage:
+ *     encoding_corpus_report            # human summary + exit 1 if a gate fails
+ *     encoding_corpus_report --json     # machine payload
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { OUT_DIR, type CorpusEntry } from './encoding_corpus.js';
+import { sanitize_text, scan_encoding_findings } from './_lib/retrieval_sanitize.js';
+
+/** Pre-registered acceptance thresholds — do not edit to make a run pass. */
+export const THRESHOLDS = {
+    recall_all: 0.95,
+    recall_unambiguous: 0.99,
+    fp_rate_max: 0.005,
+    latency_p95_ms_max: 2,
+} as const;
+
+/** Classes the roadmap singled out as unambiguous → higher recall bar. */
+export const UNAMBIGUOUS_CHANNELS: readonly string[] = [
+    'zero-width',
+    'zero-width-joiner-bom',
+    'bidi-control',
+    'variation-selector-run',
+];
+
+function _readJsonl(name: string): CorpusEntry[] {
+    return fs
+        .readFileSync(path.join(OUT_DIR, name), 'utf-8')
+        .split('\n')
+        .filter((l) => l !== '')
+        .map((l) => JSON.parse(l) as CorpusEntry);
+}
+
+/** True when the floor either stripped or reported the entry's signal. */
+export function detected(text: string): { hit: boolean; stripped: boolean; flagged: boolean } {
+    const stripped = sanitize_text(text) !== text;
+    const flagged = scan_encoding_findings(text).length > 0;
+    return { hit: stripped || flagged, stripped, flagged };
+}
+
+export interface Report {
+    readonly corpus: { positives: number; negatives: number };
+    readonly recall_all: number;
+    readonly recall_unambiguous: number;
+    readonly fp_rate: number;
+    readonly per_channel: Record<string, { n: number; detected: number; recall: number }>;
+    readonly false_positives: readonly string[];
+    readonly latency_p95_ms: number;
+    readonly model_calls: 0;
+    readonly gates: Record<string, { value: number; threshold: number; pass: boolean }>;
+    readonly verdict: 'ADOPT' | 'DETECT-AND-FLAG-ONLY' | 'FAIL';
+}
+
+function _p95(samples: readonly number[]): number {
+    const sorted = [...samples].sort((a, b) => a - b);
+    const idx = Math.min(sorted.length - 1, Math.floor(sorted.length * 0.95));
+    return sorted[idx] ?? 0;
+}
+
+export function measure(): Report {
+    const positives = _readJsonl('positives.jsonl');
+    const negatives = _readJsonl('negatives.jsonl');
+
+    const perChannel: Record<string, { n: number; detected: number; recall: number }> = {};
+    const latencies: number[] = [];
+    let hits = 0;
+    for (const e of positives) {
+        const t0 = process.hrtime.bigint();
+        const d = detected(e.text);
+        latencies.push(Number(process.hrtime.bigint() - t0) / 1e6);
+        const slot = perChannel[e.channel] ?? { n: 0, detected: 0, recall: 0 };
+        slot.n += 1;
+        if (d.hit) {
+            slot.detected += 1;
+            hits += 1;
+        }
+        slot.recall = slot.detected / slot.n;
+        perChannel[e.channel] = slot;
+    }
+
+    const falsePositives: string[] = [];
+    for (const e of negatives) {
+        const t0 = process.hrtime.bigint();
+        const d = detected(e.text);
+        latencies.push(Number(process.hrtime.bigint() - t0) / 1e6);
+        if (d.hit) falsePositives.push(`${e.id}: ${e.text.slice(0, 90)}`);
+    }
+
+    const unambiguous = positives.filter((e) => UNAMBIGUOUS_CHANNELS.includes(e.channel));
+    const unambiguousHits = unambiguous.filter((e) => detected(e.text).hit).length;
+
+    const recallAll = positives.length === 0 ? 0 : hits / positives.length;
+    const recallUnambiguous = unambiguous.length === 0 ? 0 : unambiguousHits / unambiguous.length;
+    const fpRate = negatives.length === 0 ? 0 : falsePositives.length / negatives.length;
+    const p95 = _p95(latencies);
+
+    const gates = {
+        recall_all: { value: recallAll, threshold: THRESHOLDS.recall_all, pass: recallAll >= THRESHOLDS.recall_all },
+        recall_unambiguous: {
+            value: recallUnambiguous,
+            threshold: THRESHOLDS.recall_unambiguous,
+            pass: recallUnambiguous >= THRESHOLDS.recall_unambiguous,
+        },
+        fp_rate: { value: fpRate, threshold: THRESHOLDS.fp_rate_max, pass: fpRate <= THRESHOLDS.fp_rate_max },
+        latency_p95_ms: {
+            value: p95,
+            threshold: THRESHOLDS.latency_p95_ms_max,
+            pass: p95 < THRESHOLDS.latency_p95_ms_max,
+        },
+    };
+
+    // The roadmap's pre-registered branch: recall clears but FP is over budget →
+    // ship detect-and-flag only, never automatic quarantine, and publish the FP
+    // number. Nothing here quarantines anyway, so this records which branch the
+    // measurement selected rather than switching behaviour after the fact.
+    const recallOk = gates.recall_all.pass && gates.recall_unambiguous.pass;
+    const verdict: Report['verdict'] = !recallOk
+        ? 'FAIL'
+        : gates.fp_rate.pass && gates.latency_p95_ms.pass
+          ? 'ADOPT'
+          : 'DETECT-AND-FLAG-ONLY';
+
+    return {
+        corpus: { positives: positives.length, negatives: negatives.length },
+        recall_all: recallAll,
+        recall_unambiguous: recallUnambiguous,
+        fp_rate: fpRate,
+        per_channel: perChannel,
+        false_positives: falsePositives,
+        latency_p95_ms: p95,
+        model_calls: 0,
+        gates,
+        verdict,
+    };
+}
+
+function _render(r: Report): string {
+    const pct = (n: number): string => (n * 100).toFixed(2) + '%';
+    const lines: string[] = [];
+    lines.push(`corpus: ${r.corpus.positives} positives · ${r.corpus.negatives} negatives`);
+    lines.push('');
+    lines.push('per-channel recall');
+    for (const [ch, s] of Object.entries(r.per_channel).sort()) {
+        const mark = s.recall === 1 ? '  ' : '!!';
+        lines.push(`  ${mark} ${ch.padEnd(24)} ${s.detected}/${s.n}  ${pct(s.recall)}`);
+    }
+    lines.push('');
+    for (const [name, g] of Object.entries(r.gates)) {
+        const cmp = name === 'fp_rate' || name === 'latency_p95_ms' ? '<=' : '>=';
+        const val = name === 'latency_p95_ms' ? `${g.value.toFixed(3)} ms` : pct(g.value);
+        const thr = name === 'latency_p95_ms' ? `${g.threshold} ms` : pct(g.threshold);
+        lines.push(`  ${g.pass ? 'PASS' : 'FAIL'}  ${name.padEnd(20)} ${val} ${cmp} ${thr}`);
+    }
+    lines.push(`  PASS  ${'model_calls'.padEnd(20)} 0 (structural: no model call on this path)`);
+    if (r.false_positives.length > 0) {
+        lines.push('');
+        lines.push(`false positives (${r.false_positives.length}):`);
+        for (const fp of r.false_positives.slice(0, 12)) lines.push(`  - ${fp}`);
+        if (r.false_positives.length > 12) {
+            lines.push(`  … ${r.false_positives.length - 12} more`);
+        }
+    }
+    lines.push('');
+    lines.push(`verdict: ${r.verdict}`);
+    return lines.join('\n') + '\n';
+}
+
+export function main(argv: readonly string[] | null = null): number {
+    const args = argv ?? process.argv.slice(2);
+    const r = measure();
+    if (args.includes('--json')) {
+        process.stdout.write(JSON.stringify(r, null, 2) + '\n');
+    } else {
+        process.stdout.write(_render(r));
+    }
+    return r.verdict === 'FAIL' ? 1 : 0;
+}
+
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) return false;
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exitCode = main();
+}

package/src/scripts/generate_index.ts

@@ -25,6 +25,7 @@ import {
     strip_source_prefix,
 } from './_lib/agent_src.js';
 import { computeStatus as domainSoundnessStatus } from './domain_soundness_status.js';
+import { skip_compile_disabled_rule } from './condense.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -243,6 +244,12 @@ export function _collect_skills(): Entry[] {
     return _sortedKeys(seen).map((k) => seen.get(k) as Entry);
 }
 
+// docs/catalog.md is a SHIPPED file, so a relative link from it must resolve inside
+// package.json#files. docs/proof.md is not shipped and cannot be: it is 58KB of
+// generated output linking eight paths under internal/bench/, tests/ and src/scripts/
+// that are themselves unshipped, so shipping it would hand consumers a page of dead
+// links. The published site URL is the honest target for a consumer-facing pointer.
+
 export function _collect_rules(): Entry[] {
     const seen = new Map<string, Entry>();
     for (const srcRoot of artefact_roots()) {
@@ -255,6 +262,14 @@ export function _collect_rules(): Entry[] {
             if (seen.has(stem)) {
                 continue;
             }
+            // A compile-disabled rule has no dist/agent-src/ counterpart, and the
+            // table links the SHIPPED path — so listing it emits a dead link. The
+            // toggle is a separate axis from the source file's existence; this is its
+            // fifth consumer after the router compiler, the dist writer, check_sync,
+            // and the per-tool symlink generator. Same predicate in all five.
+            if (skip_compile_disabled_rule(`rules/${stem}.md`)) {
+                continue;
+            }
             const fm = _parse_frontmatter(fs.readFileSync(ruleMd, 'utf-8'));
             seen.set(stem, {
                 kind: 'rule',
@@ -420,7 +435,8 @@ export function _render_catalog(
         '> not yet. Coverage is reported per tier (`./scripts-run',
         '> src/scripts/skill_eval_coverage`) and CI-ratcheted so it can only rise.',
         '> Listing here never implies a skill is behaviourally tested — the',
-        '> current coverage and its gap are published on [the proof page](proof.md).',
+        '> current coverage and its gap are published on [the proof page]' +
+            '(https://event4u-app.github.io/agent-config/proof/).',
         '',
         '> **Non-coding domain correctness is scoped, not proven.** The',
         '> `finance` / `founder` / `ops` / `content` skills are forged on TS/PHP',
@@ -429,7 +445,8 @@ export function _render_catalog(
         '> cited formulas, or rubric targets matching a named external practice);',
         '> the rest are labeled `unvalidated` until they pass one',
         '> (`./scripts-run src/scripts/domain_soundness_status`). A disclaimer',
-        '> floor bounds liability, not correctness — see [the proof page](proof.md).',
+        '> floor bounds liability, not correctness — see [the proof page]' +
+            '(https://event4u-app.github.io/agent-config/proof/).',
         '',
         _render_table(skills, ['kind', 'name', 'source', 'description'], '../', _to_shipped_path),
         '',

package/src/scripts/install-hooks.sh

@@ -30,8 +30,8 @@ cat > "$HOOKS_DIR/pre-push" << 'EOF'
 # the old hook only verified dist sync + the COMMAND count — it missed
 # guideline/skill/rule count drift and the generate-tools / router / corpus
 # outputs (e.g. a new guideline bumping the count in README + docs/architecture).
-# `task consistency` is the EXACT CI mirror (sync-check + sync-check-hashes +
-# sync + generate-tools + compile-router + compile-corpus + `git diff --quiet`),
+# `task consistency` is the EXACT CI mirror (sync-check + sync + generate-tools
+# + compile-router + compile-corpus + `git diff --quiet`),
 # so any derived-output drift blocks the push here. Runtime ~15-40s (it
 # regenerates the tool trees) — cheaper than a red CI run and a fixup re-push.
 

package/src/scripts/lint_confusables.ts

@@ -34,86 +34,24 @@ import * as fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as sl from './_lib/security_lint.js';
+import { TOKEN_RE, classifyToken } from './_lib/confusables.js';
 
 export const CHECK = 'mixed-script-confusable';
 
-const MIN_LETTERS = 3;
-
-// Unicode-script classifiers via property escapes (requires the `u` flag).
-const _LATIN = /\p{Script=Latin}/u;
-const _CYRILLIC = /\p{Script=Cyrillic}/u;
-const _GREEK = /\p{Script=Greek}/u;
-const _LETTER = /\p{L}/u;
-// A "token" is a maximal run of letters / combining marks / decimal digits.
-const _TOKEN = /[\p{L}\p{M}\p{Nd}]+/gu;
-
-// Cyrillic + Greek codepoints that have a basic-Latin lookalike (Unicode TR39
-// confusables, common subset). A foreign letter only counts toward the
-// confusable signal when it is in this set — Greek math operators with no Latin
-// twin (Δ Σ Π Ω Φ Θ Λ Ξ Ψ Γ δ π ω …) are deliberately excluded so legit
-// notation does not false-positive.
-const _CONFUSABLE_FOREIGN: ReadonlySet<number> = new Set([
-    // Cyrillic lowercase ↔ Latin
-    0x0430 /*а→a*/, 0x0435 /*е→e*/, 0x043e /*о→o*/, 0x0440 /*р→p*/, 0x0441 /*с→c*/,
-    0x0443 /*у→y*/, 0x0445 /*х→x*/, 0x0455 /*ѕ→s*/, 0x0456 /*і→i*/, 0x0458 /*ј→j*/,
-    0x04bb /*һ→h*/, 0x0501 /*ԁ→d*/, 0x051b /*ԛ→q*/, 0x0577 /*no*/,
-    // Cyrillic uppercase ↔ Latin
-    0x0410 /*А→A*/, 0x0412 /*В→B*/, 0x0415 /*Е→E*/, 0x041a /*К→K*/, 0x041c /*М→M*/,
-    0x041d /*Н→H*/, 0x041e /*О→O*/, 0x0420 /*Р→P*/, 0x0421 /*С→C*/, 0x0422 /*Т→T*/,
-    0x0423 /*У→Y*/, 0x0425 /*Х→X*/, 0x0405 /*Ѕ→S*/, 0x0406 /*І→I*/, 0x0408 /*Ј→J*/,
-    // Greek lowercase ↔ Latin
-    0x03b1 /*α→a*/, 0x03b5 /*ε→e*/, 0x03bf /*ο→o*/, 0x03bd /*ν→v*/, 0x03c1 /*ρ→p*/,
-    0x03c5 /*υ→u*/, 0x03c7 /*χ→x*/, 0x03ba /*κ→k*/,
-    // Greek uppercase ↔ Latin (only those with a real Latin twin)
-    0x0391 /*Α→A*/, 0x0392 /*Β→B*/, 0x0395 /*Ε→E*/, 0x0396 /*Ζ→Z*/, 0x0397 /*Η→H*/,
-    0x0399 /*Ι→I*/, 0x039a /*Κ→K*/, 0x039c /*Μ→M*/, 0x039d /*Ν→N*/, 0x039f /*Ο→O*/,
-    0x03a1 /*Ρ→P*/, 0x03a4 /*Τ→T*/, 0x03a5 /*Υ→Y*/, 0x03a7 /*Χ→X*/, 0x0392 /*Β→B*/,
-]);
-
-type ScriptName = 'latin' | 'cyrillic' | 'greek' | 'other';
-
-function _script_of(ch: string): ScriptName {
-    if (_LATIN.test(ch)) return 'latin';
-    if (_CYRILLIC.test(ch)) return 'cyrillic';
-    if (_GREEK.test(ch)) return 'greek';
-    return 'other';
-}
+// The confusable table + the mixed-script decision rule live in ONE place so
+// this authoring-time linter and the runtime encoding scanner cannot drift apart
+// (road-to-runtime-encoding-hardening Phase 3). `_classify_token` stays exported
+// under its original name — it is this module's published surface and its tests
+// address it here.
+const _TOKEN = TOKEN_RE;
 
 /**
  * Classify a single token. Returns the offending mixed-script descriptor when
  * the token matches the homoglyph signature, else null.
+ *
+ * Thin re-export of the shared implementation — see `_lib/confusables.ts`.
  */
-export function _classify_token(token: string): string | null {
-    let latin = 0;
-    let cyrillic = 0;
-    let greek = 0;
-    let letters = 0;
-    for (const ch of token) {
-        if (!_LETTER.test(ch)) continue; // skip combining marks / digits for script vote
-        letters += 1;
-        const script = _script_of(ch);
-        if (script === 'latin') {
-            latin += 1;
-        } else if (script === 'cyrillic' || script === 'greek') {
-            // Only confusable foreign letters (TR39) count — math operators with
-            // no Latin twin are ignored, so legit notation never trips.
-            if (_CONFUSABLE_FOREIGN.has(ch.codePointAt(0) as number)) {
-                if (script === 'cyrillic') cyrillic += 1;
-                else greek += 1;
-            }
-        }
-    }
-    if (letters < MIN_LETTERS) return null;
-    const foreign = cyrillic + greek;
-    if (latin === 0 || foreign === 0) return null; // single-script (or no Latin) → legit
-    if (latin <= foreign) return null; // majority must be Latin (foreign word ≠ attack)
-    const which = cyrillic > 0 && greek > 0
-        ? 'cyrillic+greek'
-        : cyrillic > 0
-            ? 'cyrillic'
-            : 'greek';
-    return `latin+${which} (${latin} latin / ${foreign} foreign-confusable)`;
-}
+export const _classify_token = classifyToken;
 
 export function _scan(sf: sl.ScannedFile): sl.Finding[] {
     if (sf.pragma_allows(CHECK)) {

package/src/scripts/lint_hidden_unicode.ts

@@ -30,6 +30,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as sl from './_lib/security_lint.js';
@@ -261,6 +262,191 @@ export function _scan(sf: sl.ScannedFile): sl.Finding[] {
     return out;
 }
 
+// ---------------------------------------------------------------------------
+// Source-file pass — raw C0 control bytes make a text file INVISIBLE to tools
+// ---------------------------------------------------------------------------
+//
+// The `.md` corpus pass above defends the model's eyes. This pass defends the
+// *reviewer's* and the *gate's* eyes, which is a different failure.
+//
+// A raw control byte (NUL above all) in a text-intended source file makes
+// `file(1)`, `grep`, and every tool that sniffs for binary content classify the
+// file as binary and SKIP IT SILENTLY. A linter grepping such a file reads
+// nothing and reports clean; an agent gathering evidence concludes the code
+// does not exist. That is indistinguishable from a pass, which is the point.
+//
+// Discovered the hard way: `road-to-runtime-encoding-hardening` was authored on
+// the premise that `memory_lookup.ts` had "zero imports" and that the sanitize
+// floor therefore ran nowhere. The file simply carried a raw NUL as a composite
+// map-key separator, so `grep` never read it. The premise was a measurement
+// artifact. See `agents/evidence/reports/nul-byte-source-census.md`.
+//
+// Precision by construction — this pass flags ONLY raw C0 controls, never the
+// invisible/confusable classes `_scan` owns. In a `.ts` file a real bidi or
+// zero-width codepoint is usually a deliberate test fixture or a regex
+// character class (this repo has several, legitimately), so flagging those here
+// would demand an allowlist that grows until the gate is worthless. A raw
+// control byte has NO legitimate use in text-intended source: the language
+// escape (`\0`, `\x01`) compiles to the identical runtime string and keeps the
+// file readable by tools. The fix is always available, so the false-positive
+// rate is structurally zero rather than merely low.
+
+/** Extensions whose content is legitimately binary — never flagged. */
+const _BINARY_EXT: ReadonlySet<string> = new Set([
+    'png', 'jpg', 'jpeg', 'gif', 'ico', 'webp', 'avif', 'bmp', 'tiff',
+    'pdf', 'woff', 'woff2', 'ttf', 'otf', 'eot',
+    'zip', 'gz', 'tgz', 'bz2', 'xz', 'zst', '7z', 'rar',
+    'wasm', 'mp3', 'mp4', 'wav', 'ogg', 'webm', 'mov', 'avi',
+    'so', 'dylib', 'dll', 'node', 'a', 'o', 'exe',
+    'jar', 'class', 'pyc', 'pyo',
+    'db', 'sqlite', 'sqlite3', 'bin', 'dat',
+    'docx', 'xlsx', 'pptx', 'doc', 'xls', 'ppt', 'odt', 'ods', 'odp',
+]);
+
+/**
+ * Generated trees — skipped, because this is an AUTHORING rule.
+ *
+ * `dist/` and the per-tool projections are outputs of `src/` (see the
+ * `source-of-truth` rule: a projection is never edited by hand). Flagging a
+ * control byte there would point the author at a file they must not touch, and
+ * `dist/install/*.mjs` is a bundler artifact whose bytes are not even
+ * hand-authorable. Fix the source; the projection follows on `task sync`.
+ */
+const _GENERATED_PREFIXES: readonly string[] = [
+    'dist/',
+    '.augment/',
+    '.claude/',
+    '.cursor/',
+    '.clinerules/',
+    // Verbatim captured tool output, not authored text. These are RECORDINGS:
+    // escaping a control byte inside one would falsify the record it exists to
+    // preserve. If a capture needs to stay grep-readable, the fix is to escape
+    // at capture time — never to edit the artifact afterwards.
+    'agents/evidence/analysis/',
+    // The frozen hostile-encoding corpus. Its positives ARE raw control
+    // characters — that is the thing under test, so flagging them would demand
+    // escaping the fixtures and thereby delete the test. The corpus has its own,
+    // stronger integrity controls: a sha256 freeze plus a scope-guard test that
+    // is itself falsified by an out-of-scope fixture. Excluded here because it
+    // is DATA, on the same principle as the captures above.
+    'internal/bench/corpora/encoding-channels/',
+];
+
+function _isGenerated(rel: string): boolean {
+    return _GENERATED_PREFIXES.some((p) => rel.startsWith(p));
+}
+
+/**
+ * True for a raw control CODEPOINT that is not benign whitespace.
+ *
+ * Codepoints, not bytes, and that distinction is the whole point. A first cut
+ * of this pass tested bytes ≤ 0x1F and let two classes through: DEL (U+007F,
+ * a single byte above the range) and the C1 controls (U+0080–009F, which encode
+ * to a two-byte UTF-8 sequence containing no byte ≤ 0x1F). Both make `file(1)`
+ * and git classify a file as binary — `tests/scripts/retrieval_sanitize.test.ts`
+ * carried U+007F and U+009F, rendered as `Bin` in `git diff`, unreviewable on a
+ * PR, and passed the byte-level check. A gate that misses the thing it exists to
+ * catch is the failure this whole roadmap is about, so the range now matches
+ * `_classify`'s: C0 + DEL + C1, minus tab / LF / CR.
+ */
+function _isRawControlCodepoint(cp: number): boolean {
+    if (cp === 0x09 || cp === 0x0a || cp === 0x0d) return false;
+    return cp <= 0x1f || (cp >= 0x7f && cp <= 0x9f);
+}
+
+function _extensionOf(rel: string): string {
+    const base = rel.slice(rel.lastIndexOf('/') + 1);
+    const dot = base.lastIndexOf('.');
+    return dot <= 0 ? '' : base.slice(dot + 1).toLowerCase();
+}
+
+/** Tracked files, or `null` when git is unavailable (then the pass no-ops). */
+function _trackedFiles(): string[] | null {
+    const res = spawnSync('git', ['ls-files', '-z'], {
+        cwd: sl.ROOT,
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (res.status !== 0 || res.stdout === null) return null;
+    return res.stdout
+        .toString('utf-8')
+        .split('\0')
+        .filter((p) => p !== '');
+}
+
+/**
+ * Tracked files this pass is responsible for — text-intended, non-generated.
+ *
+ * Exported so a green run can state HOW MANY files it actually read. A check
+ * that reports "clean" without naming its scope is indistinguishable from a
+ * check whose scope matched nothing, which is the failure class this repo has
+ * already been bitten by.
+ */
+export function _eligibleSourceFiles(): string[] | null {
+    const tracked = _trackedFiles();
+    if (tracked === null) return null;
+    return tracked.filter((rel) => !_isGenerated(rel) && !_BINARY_EXT.has(_extensionOf(rel)));
+}
+
+/**
+ * Flag raw C0 control bytes in every tracked, text-intended file.
+ *
+ * `files` is injectable so the regression test can assert a synthetic NUL is
+ * caught — without that assertion there is no way to know this pass can still
+ * fail, which is the failure mode the whole check exists to prevent.
+ */
+export function _scanSourceControlBytes(files: readonly string[] | null = null): sl.Finding[] {
+    const tracked = files ?? _eligibleSourceFiles();
+    if (tracked === null) return [];
+    const out: sl.Finding[] = [];
+    for (const rel of tracked) {
+        // Re-applied here, not only in `_eligibleSourceFiles`: the exclusions
+        // are a property of the CHECK, so an explicit `files` list (a caller, a
+        // test) can never widen the scan past what the check is willing to
+        // claim. `_eligibleSourceFiles` exists to count, not to be the gate.
+        if (_isGenerated(rel)) continue;
+        if (_BINARY_EXT.has(_extensionOf(rel))) continue;
+        let data: Buffer;
+        try {
+            data = fs.readFileSync(path.join(sl.ROOT, rel));
+        } catch {
+            continue; // deleted, unreadable, or a submodule pointer
+        }
+        // A file that is not valid UTF-8 is binary regardless of its extension
+        // (an extensionless fixture, say) — not this check's business.
+        try {
+            new TextDecoder('utf-8', { fatal: true }).decode(data);
+        } catch {
+            continue;
+        }
+        // Iterate CODEPOINTS (the string is already known-valid UTF-8 here), so
+        // DEL and the C1 range are visible — see `_isRawControlCodepoint`.
+        let line = 1;
+        for (const ch of data.toString('utf-8')) {
+            const cp = ch.codePointAt(0);
+            if (cp === undefined) continue;
+            if (cp === 0x0a) {
+                line += 1;
+                continue;
+            }
+            if (!_isRawControlCodepoint(cp)) continue;
+            const hex = cp.toString(16).toUpperCase().padStart(2, '0');
+            out.push(
+                new sl.Finding(
+                    rel,
+                    line,
+                    CHECK,
+                    'HIGH',
+                    `raw control character U+${hex} in a text source — makes ` +
+                        'grep/file(1)/git treat this file as binary and skip it ' +
+                        'silently; use the language escape (e.g. \\0, \\x7F) instead',
+                    1.0,
+                ),
+            );
+        }
+    }
+    return out;
+}
+
 export function _sanitize(filePath: string): string {
     const raw = fs.readFileSync(filePath, 'utf-8');
     let cleaned = '';
@@ -323,6 +509,28 @@ export function main(argv: readonly string[] | null = null): number {
         }
     }
 
+    // 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`
+    // corpus) and a narrower codepoint set (C0 only). `--fix` does not touch
+    // these — rewriting a source file's bytes is the author's call, and the
+    // finding names the escape to use.
+    const sourceFiles = _eligibleSourceFiles();
+    for (const h of _scanSourceControlBytes(sourceFiles)) {
+        findings.push(h);
+    }
+    if (!args.json) {
+        // State the scope on every run. A bare "clean" cannot be told apart
+        // from a pass whose file list was empty.
+        const n = sourceFiles === null ? 0 : sourceFiles.length;
+        process.stdout.write(
+            sourceFiles === null
+                ? '  source pass: SKIPPED — `git ls-files` unavailable, 0 files read for raw control bytes\n'
+                : `  source pass: ${n} tracked text file(s) read for raw C0 control bytes ` +
+                      '(generated trees + verbatim captures excluded)\n',
+        );
+    }
+
     if (args.fix) {
         // sorted(flagged) — by path string.
         for (const p of [...flagged].sort()) {

package/src/scripts/lint_load_context.ts

@@ -36,9 +36,15 @@ const QUIET = process.argv.slice(2).includes('--quiet');
 // src/scripts/lint_load_context.ts → three dirs up is the repo root.
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
+// Retargeted 2026-07-29: the first two pointed at the ADR-051-emptied tree, so
+// this gate reported "clean (0 declarer(s))" in CI — the count was in its own
+// output the whole time. `agents/contexts` does not exist either (project-local
+// contexts live under agents/settings/contexts) and is kept only as a no-op for
+// consumer layouts that do have it.
 const SCAN_DIRS = [
-    path.join(ROOT, '.agent-src.uncondensed', 'rules'),
-    path.join(ROOT, '.agent-src.uncondensed', 'contexts'),
+    path.join(ROOT, 'src', 'rules'),
+    path.join(ROOT, 'src', 'agent-src', 'contexts'),
+    path.join(ROOT, 'agents', 'settings', 'contexts'),
     path.join(ROOT, 'agents', 'contexts'),
 ];
 
@@ -50,9 +56,10 @@ const ALLOWED_PREFIXES = [
 
 const LEGACY_PREFIX = '.agent-src.uncondensed/contexts/';
 
-const SOURCE_ROOT = path.join(ROOT, '.agent-src.uncondensed');
+// Base for resolving a logical `contexts/...` entry to a real file.
+const SOURCE_ROOT = path.join(ROOT, 'src', 'agent-src');
 
-const PUBLIC_RULE_PREFIX = '.agent-src.uncondensed/rules/';
+const PUBLIC_RULE_PREFIX = 'src/rules/';
 const PROJECT_LOCAL_PREFIX = 'agents/settings/contexts/';
 
 const HARD_FLOOR_RULES: ReadonlySet<string> = new Set([
@@ -217,7 +224,12 @@ function main(): number {
     const warnings: string[] = [];
     const graph: Record<string, string[]> = {};
 
-    for (const f of collect_files()) {
+    const _files = collect_files();
+    // Gate-coverage contract (src/config/gate-coverage.yml): count FILES INSPECTED,
+    // not declarers — "0 declarers" over 400 files is a legitimate result, "0 files"
+    // is blindness. Reporting declarers here would have hidden the dead root.
+    process.stdout.write(`scanned: ${String(_files.length)}\n`);
+    for (const f of _files) {
         const fm = parse_frontmatter(f);
         const lazyRaw = fm['load_context'];
         const eagerRaw = fm['load_context_eager'];