@event4u/agent-config 9.9.0 → 9.11.0

package/src/scripts/_lib/changelog_eras.ts

@@ -409,13 +409,97 @@ function _rstrip(text: string): string {
     return text.replace(/\s+$/u, '');
 }
 
+/**
+ * Split a current-era body into (carry-over, archived) at `boundary`.
+ *
+ * The archive is named `pre-<boundary>`, so by its own contract it may only
+ * hold entries STRICTLY OLDER than the boundary. Sections at or above it —
+ * i.e. the incoming release's own entry, when it is already prepended — stay
+ * in the new era.
+ *
+ * On a fresh release run the body never contains the incoming entry (the split
+ * runs before the prepend), so the carry-over is empty and this is a no-op.
+ * On a `--resume` run the entry IS already committed and the bump step is
+ * correctly skipped, so without this partition the split archived the release
+ * it was named after and nothing ever put it back: the current era ended up
+ * empty and the `changelog-entry` CI gate went red. That is the 9.10.0
+ * failure. The partition makes the two orderings converge.
+ *
+ * Changelog bodies are newest-first, so the carry-over is a prefix — but the
+ * scan is per-heading rather than "stop at the first older one" so a
+ * hand-edited out-of-order body cannot silently archive a newer entry.
+ */
+export function _partition_era_body(
+    body: readonly string[],
+    boundary: string,
+): { carry: string[]; archived: string[] } {
+    const b = _RELEASE_VERSION_RE.exec(boundary.trim());
+    if (!b) {
+        throw new Error(`not a bare semver (X.Y.Z): '${boundary}'`);
+    }
+    const bound: [number, number, number] = [
+        Number.parseInt(b[1]!, 10),
+        Number.parseInt(b[2]!, 10),
+        Number.parseInt(b[3]!, 10),
+    ];
+
+    // Section boundaries: every `## [X.Y.Z]` heading starts a new section.
+    // Content before the first heading (there should be none) rides along with
+    // the archive, matching the pre-fix behaviour for that shape.
+    const starts: number[] = [];
+    for (let i = 0; i < body.length; i++) {
+        if (VERSION_HEADING_RE.test(body[i]!)) {
+            starts.push(i);
+        }
+    }
+    if (starts.length === 0) {
+        return { carry: [], archived: [...body] };
+    }
+
+    const carry: string[] = [];
+    const archived: string[] = [...body.slice(0, starts[0]!)];
+    for (let s = 0; s < starts.length; s++) {
+        const from = starts[s]!;
+        const to = s + 1 < starts.length ? starts[s + 1]! : body.length;
+        const section = body.slice(from, to);
+        const m = VERSION_HEADING_RE.exec(body[from]!);
+        const v = m?.groups?.['version'];
+        const parsed = v ? _RELEASE_VERSION_RE.exec(v) : null;
+        if (parsed === null || parsed === undefined) {
+            archived.push(...section);
+            continue;
+        }
+        const cur: [number, number, number] = [
+            Number.parseInt(parsed[1]!, 10),
+            Number.parseInt(parsed[2]!, 10),
+            Number.parseInt(parsed[3]!, 10),
+        ];
+        const isOlder =
+            cur[0] < bound[0] ||
+            (cur[0] === bound[0] && cur[1] < bound[1]) ||
+            (cur[0] === bound[0] && cur[1] === bound[1] && cur[2] < bound[2]);
+        (isOlder ? archived : carry).push(...section);
+    }
+    return { carry, archived };
+}
+
+/** Drop trailing blank lines (in place semantics, returns the same array). */
+function _trim_trailing_blanks(xs: string[]): string[] {
+    while (xs.length > 0 && xs[xs.length - 1]!.trim() === '') {
+        xs.pop();
+    }
+    return xs;
+}
+
 /**
  * Execute `plan` against the on-disk CHANGELOG.md.
  *
  * - Refuses to overwrite an existing archive file.
- * - Moves every entry in the current era body into the new archive.
+ * - Moves every entry OLDER than the boundary into the new archive; an
+ *   already-prepended entry for the incoming release stays in the new era
+ *   (see `_partition_era_body`).
  * - Replaces the current era block with the collapsed pointer + the
- *   freshly-labelled new current era header (empty body).
+ *   freshly-labelled new current era header.
  */
 export function perform_split(plan: SplitPlan): void {
     if (fs.existsSync(plan.archive_path)) {
@@ -433,21 +517,31 @@ export function perform_split(plan: SplitPlan): void {
     }
 
     const [body_start, , next_era_line] = _era_body_bounds(lines, current_idx);
-    const entries = lines.slice(body_start, next_era_line);
-    // Trim trailing blank lines so the archive doesn't accumulate them.
-    while (entries.length > 0 && entries[entries.length - 1]!.trim() === '') {
-        entries.pop();
-    }
+    const body = lines.slice(body_start, next_era_line);
+    // Entries at/above the boundary (a resume run's already-prepended release
+    // entry) stay in the new era; only older ones are archived.
+    const { carry, archived } = _partition_era_body(body, plan.boundary);
+    // Trim trailing blank lines so neither side accumulates them.
+    _trim_trailing_blanks(archived);
+    _trim_trailing_blanks(carry);
 
     const collapsed = _splitlines(_rstrip_newlines(collapsed_era_block(plan.boundary)));
     const new_era = _splitlines(_rstrip_newlines(new_era_intro_block(plan.new_era_label, plan.boundary)));
 
     const head = lines.slice(0, current_idx);
     const tail = lines.slice(next_era_line);
-    const new_lines = [...head, ...collapsed, '', ...new_era, '', ...tail];
+    const new_lines = [
+        ...head,
+        ...collapsed,
+        '',
+        ...new_era,
+        '',
+        ...(carry.length > 0 ? [...carry, ''] : []),
+        ...tail,
+    ];
     const new_text = _rstrip(new_lines.join('\n')) + '\n';
 
-    const archive_body = entries.length > 0 ? _rstrip(entries.join('\n')) + '\n' : '';
+    const archive_body = archived.length > 0 ? _rstrip(archived.join('\n')) + '\n' : '';
     const archive_text = archive_file_header(plan.boundary) + archive_body;
 
     fs.mkdirSync(path.dirname(plan.archive_path), { recursive: true });

package/src/scripts/_lib/compile_time_toggles.ts

@@ -0,0 +1,79 @@
+/**
+ * Compile-time rule toggles — the single definition, shared by the router compiler
+ * and the projector.
+ *
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * The map used to live only in `compile_router.ts`, which meant a disabled rule was
+ * dropped from `dist/router.json` while its **body still shipped** as a file in
+ * `dist/agent-src/rules/` (and through the `.claude/rules/` symlink). ADR
+ * `telegraph/0002` originally claimed that flipping the toggle gave "zero-cost
+ * dormancy". That was measured and found half wrong on 2026-07-29: the router entry
+ * governs *trigger-routing*; **file existence governs always-loaded injection**, and
+ * the host reads the file — a maintainer session's context listed the body verbatim
+ * as "project instructions", never having consulted the router.
+ *
+ * Two surfaces, one switch. Sharing the definition is what lets the projector honour
+ * it, so `speak: false` means what the ADR assumed instead of the ADR being weakened
+ * to match a partial implementation.
+ */
+
+/**
+ * HOW A RULE GETS HERE — the dormancy routing (road-to-cache-economy Phase 3)
+ * --------------------------------------------------------------------------
+ * A rule body is re-written on EVERY subagent spawn, so an always-loaded rule
+ * that is not earning its keep is paid per spawn, not once. That makes "should
+ * this rule be dormant?" a real question — and this map is the ONLY place the
+ * answer may land. The route, in order:
+ *
+ *   1. **Candidate** — `preamble_byte_census` ranks always-loaded rules by
+ *      per-spawn token cost (`--top`). A candidate is a number, never an
+ *      impression: telegraph-speak was ~982 tokens.
+ *   2. **Evidence** — the same bar telegraph-speak had to clear: an output-side
+ *      bench showing the rule does not pay for itself, judged against the
+ *      kill-criterion, BEFORE dormancy. A preference is not evidence, and
+ *      "it looks verbose" is not a measurement.
+ *   3. **Landing** — a new entry in the map below, keyed on a real setting the
+ *      consumer can flip back. Never a fifth toggle axis: this predicate already
+ *      has four consumers (the router compiler, the dist writer, `check_sync`,
+ *      and the per-tool symlink generator), and a rule wired into three of four
+ *      is how the last attempt blocked its own push.
+ *
+ * What is explicitly NOT this route: dropping a rule from the router while its
+ * body still ships (that was the measured half-truth this file exists to fix),
+ * and gating bodies behind triggers wholesale — that is thin projection, which
+ * failed a 48% quality floor at 36.2% and stays disabled.
+ */
+
+/** Loose settings shape — the toggles only ever read nested plain objects. */
+export type ToggleSettings = Record<string, unknown>;
+
+/** rule-id → predicate. A rule is emitted (router AND projection) only when its
+ * predicate returns true. A rule absent from this map is always emitted. */
+export const COMPILE_TIME_TOGGLES: Record<string, (s: ToggleSettings) => boolean> = {
+    // `speak` defaults FALSE (dormant) per docs/adrs/telegraph/0002 — the absent-key
+    // fallback used to be `true`, which silently contradicted ADR 0001 (accepted,
+    // "default off until bench"). Measured basis: median vs_terse −9.27% (API) /
+    // −5.47% (exact cl100k_base) — telegraph emits MORE than a plain "be terse".
+    // Opt back in with an explicit `telegraph.speak: true` once an output-side bench
+    // clears the kill-criterion bar. `enabled` keeps its true default: it is the
+    // family master switch, and flipping it would silence sibling telegraph settings
+    // that were never measured negative.
+    //
+    // This predicate deliberately does NOT read `speak_scope`. That key disables the
+    // rule's *behaviour* and never removed its token cost — the trap the measurement
+    // exposed.
+    'telegraph-speak': (s: ToggleSettings): boolean => {
+        const tg = (s['telegraph'] as ToggleSettings | undefined) ?? {};
+        const enabled = tg['enabled'] === undefined ? true : tg['enabled'];
+        const speak = tg['speak'] === undefined ? false : tg['speak'];
+        return Boolean(enabled) && Boolean(speak);
+    },
+};
+
+/** True when the rule may be emitted. Unknown ids are always emitted — the map is an
+ * opt-in list of gated rules, never an allowlist of permitted ones. */
+export function rule_is_compile_enabled(rule_id: string, settings: ToggleSettings): boolean {
+    const predicate = COMPILE_TIME_TOGGLES[rule_id];
+    return predicate === undefined ? true : predicate(settings);
+}

package/src/scripts/_lib/confusables.ts

@@ -0,0 +1,101 @@
+/**
+ * Visible mixed-script confusable signature — the ONE definition in the tree.
+ *
+ * Extracted from `lint_confusables.ts` so the authoring-time linter and the
+ * runtime encoding scanner share one table and one decision rule
+ * (road-to-runtime-encoding-hardening Phase 3). Two copies of a confusable set
+ * is exactly the drift this extraction prevents: a codepoint added to one and
+ * not the other means the two surfaces disagree about what a homoglyph is.
+ *
+ * The dependency direction matters. This module imports NOTHING — no `fs`, no
+ * lint framework — so the runtime retrieval path can use it without pulling the
+ * authoring-time lint infrastructure into a request.
+ */
+
+/** A token needs this many letters before the signature can fire. */
+export 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. */
+export const TOKEN_RE = /[\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.
+ */
+export 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';
+}
+
+/**
+ * Classify a single token. Returns the offending mixed-script descriptor when
+ * the token matches the homoglyph signature, else null.
+ *
+ * The containment rules are the load-bearing part, and they are why this is one
+ * shared function rather than two similar ones: a Latin-majority token with at
+ * least one TR39-confusable foreign letter is the signal; a single-script token
+ * (a genuine Cyrillic or Greek word) is not; and a token whose foreign letters
+ * outnumber its Latin ones is a foreign word, not an attack.
+ */
+export function classifyToken(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)`;
+}

package/src/scripts/_lib/duplicate_scope_census.ts

@@ -0,0 +1,77 @@
+/**
+ * Duplicate-scope rule census — the shared byte-comparison primitive behind
+ * both C-2 (`cache_realization_report.ts`'s `computeDuplicateScope`, which
+ * turns this into a share of subagent write volume) and the `doctor`
+ * `duplicate-scope-rules` health check (`_cli/cmd_doctor.ts`), so the two
+ * surfaces can never drift on what counts as "shared" or how a redundant
+ * copy's size is estimated.
+ *
+ * `road-to-cache-economy.md` Phase 3: the same 110 rule
+ * filenames observed at both `~/.claude/rules` (user scope) and
+ * `dist/agent-src/rules` (project scope) on this maintainer's own checkout —
+ * C-2 confirmed at 38.5% of subagent write volume. This module answers only
+ * "which filenames are shared, and how many redundant bytes do they cost" —
+ * the write-volume share and the doctor warning are each computed by their
+ * own caller from this raw census.
+ *
+ * Detection only. Never deletes, never rewrites a user's file — see
+ * `non-destructive-by-default`.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface DuplicateScopeCensus {
+    evaluable: boolean;
+    reason?: string | undefined;
+    /** `.md` basenames present in BOTH directories, sorted. */
+    shared_filenames: string[];
+    /** Σ min(userBytes, projectBytes) over shared filenames — the conservative
+     *  estimate of the redundant copy (the roadmap's byte census found the two
+     *  scopes near-identical in size, so the min/max choice rarely matters). */
+    duplicate_chars: number;
+}
+
+/**
+ * For every `.md` filename present in BOTH `userRulesDir` and
+ * `projectRulesDir`, the redundant copy is estimated as the SMALLER of the
+ * two files' byte sizes, summed across all shared filenames.
+ */
+export function censusDuplicateScope(userRulesDir: string, projectRulesDir: string): DuplicateScopeCensus {
+    if (!fs.existsSync(userRulesDir) || !fs.existsSync(projectRulesDir)) {
+        return {
+            evaluable: false,
+            reason: `one or both rule directories are missing (user: ${userRulesDir}, project: ${projectRulesDir})`,
+            shared_filenames: [],
+            duplicate_chars: 0,
+        };
+    }
+
+    const userFiles = new Set(fs.readdirSync(userRulesDir).filter((f) => f.endsWith('.md')));
+    const projectFiles = fs.readdirSync(projectRulesDir).filter((f) => f.endsWith('.md'));
+
+    const shared: string[] = [];
+    let duplicateChars = 0;
+    for (const f of projectFiles) {
+        if (!userFiles.has(f)) continue;
+        shared.push(f);
+        const a = fs.statSync(path.join(userRulesDir, f)).size;
+        const b = fs.statSync(path.join(projectRulesDir, f)).size;
+        duplicateChars += Math.min(a, b);
+    }
+    shared.sort();
+
+    if (shared.length === 0) {
+        return {
+            evaluable: false,
+            reason: 'no shared .md filenames between the two rule scopes — this checkout has no duplicate-scope install',
+            shared_filenames: [],
+            duplicate_chars: 0,
+        };
+    }
+
+    return {
+        evaluable: true,
+        shared_filenames: shared,
+        duplicate_chars: duplicateChars,
+    };
+}