@event4u/agent-config 9.26.0 → 9.27.0

package/src/scripts/check_rule_projection_integrity.ts

@@ -0,0 +1,364 @@
+#!/usr/bin/env tsx
+/**
+ * check_rule_projection_integrity.ts — the host rule trees are COMPLETE and
+ * FRESH against `dist/agent-src/rules/`, read as they stand on disk.
+ *
+ * WHY THIS GATE EXISTS (road-to-conformance-round5 Phase 1, measured 2026-08-07)
+ * ---------------------------------------------------------------------------
+ * `docs/contracts/rule-router.md:234` states that nothing loads
+ * `dist/router.json` at runtime, so **projection is the only reach mechanism
+ * there is**: a non-kernel rule activates by the model's judgment over text
+ * already in context, and the per-tool rule tree is what puts it there. That
+ * makes the state of the projection load-bearing, and it was broken:
+ *
+ *   - `.claude/rules/` in the working checkout held **92** entries. A
+ *     regeneration in a clean worktree produces **108**. The tree was last
+ *     generated **2026-07-05**, and **21 rules added since then had no entry** —
+ *     among them `secret-vcs-guard`, `broken-access-control`,
+ *     `senior-engineering-discipline`, `evaluator-independence`,
+ *     `session-canary`, `settings-ask-protocol`, `active-remediation`. At
+ *     project scope those 21 obligations were carried by nothing. The same 21
+ *     were absent from `.clinerules/` and `.cursor/rules/*.md`.
+ *   - The trees are gitignored and untracked, so no diff review sees the gap.
+ *
+ * WHY THE EXISTING GATES DO NOT CATCH IT
+ * --------------------------------------
+ *   - `check_bridge_derivation` **regenerates** the trees and then diffs, so it
+ *     can only ever observe a fixpoint; both CI and the pre-push chain run it
+ *     ahead of anything else, which is why five weeks of staleness were invisible.
+ *     Its symlink leg asserts that entries which EXIST resolve — a missing entry
+ *     is not a wrong entry.
+ *   - `check_generator_output_coverage.ts:37` asserts only that the output
+ *     *root* is classified in the ignore manifest, never its contents.
+ *   - `check_condensation.ts` stops at `dist/`.
+ *
+ * So the last hop — the one that decides what the model actually sees — was
+ * ungated. This gate reads the tree WITHOUT touching it: no regeneration, no
+ * writes. That is the whole design constraint, and it is why the check is a
+ * separate script rather than a third leg on `check_bridge_derivation`.
+ *
+ * HONEST SCOPE — where each leg has teeth
+ * ---------------------------------------
+ * On a fresh CI checkout the trees do not exist at all (gitignored), so CI must
+ * run this AFTER `task generate-tools`, where it is a **generator-regression**
+ * check: it proves the generator emitted every rule it planned to. The stale
+ * case is caught on a developer's working checkout, which is why the pre-push
+ * `preflight` chain runs it FIRST — before `check_bridge_derivation` regenerates
+ * and erases the evidence. Both registrations are deliberate; neither subsumes
+ * the other.
+ *
+ * THE TWO ASSERTIONS
+ * ------------------
+ * 1. COMPLETENESS. Every rule the generator would emit has an entry in every
+ *    active host rule tree. The expected set comes from
+ *    `condense.projected_rule_trees()` — the generator's OWN emit plan, which
+ *    `generate_rule_symlinks` also consumes. It is deliberately NOT a list in
+ *    this file and deliberately NOT `dist/agent-src/rules/` verbatim: a
+ *    hand-maintained array goes obsolete silently, and the dist directory
+ *    over-counts by the ADR-004 `type: manual` rules the trees omit on purpose
+ *    (113 files on disk, 5 manual, 108 projected). A completeness check keyed on
+ *    a non-canonical source propagates that source's mistakes as requirements.
+ * 2. FRESHNESS. No rule in `dist/agent-src/rules/` may be newer than the
+ *    projection entry pointing at it. Entries are symlinks, so the comparison
+ *    uses `lstat` on the LINK, never `stat`: `stat` follows the link and returns
+ *    the target's own mtime, which would compare the dist file with itself and
+ *    make the assertion vacuous. Verified empirically before wiring — with a
+ *    target touched after the link was created, `lstat(link).mtimeMs !==
+ *    stat(target).mtimeMs` while `stat(link).mtimeMs === stat(target).mtimeMs`.
+ *    Under `lean_projection: thin` the entries are real files rather than
+ *    symlinks; `lstat` is correct there too (the file's own mtime).
+ *
+ * NOT IN SCOPE. `.cursor/rules/*.mdc` and `.windsurf/rules/` are written by
+ * different generators with their own filters; this gate covers the three trees
+ * `condense.TOOL_DIRS` projects (`.claude/rules`, `.cursor/rules`, `.clinerules`)
+ * and their `.md` entries, which is where the measured defect was.
+ *
+ * CLI: `--root <path>` (default: this repo) · `--quiet` suppresses the
+ * per-target ledger line. Exit 0 = complete and fresh, or no tool active at all
+ * (announced on stderr — see `auditRuleProjection`); 1 = any gap, any stale
+ * entry, a ledger accounting error, or a dead scan scope.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { GateLedger, UnaccountedTargetsError } from './_lib/gate_ledger.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { _resetStateForTest as _pointCondenseAt, projected_rule_trees } from './condense.js';
+
+const _HERE = path.resolve(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/** Where the projected rules are condensed to — the freshness comparison's left side. */
+const DIST_RULES = path.join('dist', 'agent-src', 'rules');
+
+export type ProjectionFindingKind = 'missing' | 'stale' | 'dangling';
+
+export interface ProjectionFinding {
+    /** Repo-relative tool dir, e.g. `.claude/rules`. */
+    tree: string;
+    /** Rule basename, e.g. `secret-vcs-guard.md`. */
+    rule: string;
+    kind: ProjectionFindingKind;
+    message: string;
+}
+
+export interface ProjectionAudit {
+    findings: ProjectionFinding[];
+    /** `tree` → whether the directory exists at all; an absent tree fails every rule under it. */
+    treePresent: Record<string, boolean>;
+    ledger: GateLedger;
+}
+
+function _lstatOrNull(p: string): fs.Stats | null {
+    try {
+        return fs.lstatSync(p);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Audit `expected` (tool dir → rule basenames) against the trees under `repoRoot`.
+ *
+ * Pure read: every branch stats, none writes. `expected` is injected rather than
+ * computed here so the caller controls which root the generator's emit plan was
+ * derived from, and so a test can pin an expectation without a settings file.
+ */
+export function auditRuleProjection(
+    repoRoot: string,
+    expected: Readonly<Record<string, readonly string[]>>,
+): ProjectionAudit {
+    const ledger = new GateLedger('check_rule_projection_integrity');
+    const findings: ProjectionFinding[] = [];
+    const treePresent: Record<string, boolean> = {};
+
+    for (const [tree, rules] of Object.entries(expected)) {
+        ledger.plan(rules.map((r) => `${tree}/${r}`));
+    }
+
+    // The planned set is every (tree × rule) pair, and zero has TWO causes that
+    // are not the same defect. `projected_rule_trees()` returns one key per
+    // ACTIVE tool dir, so the key count is the discriminator:
+    //
+    //   - keys > 0, rules == 0 → the rule corpus is dead. No rule reached
+    //     `dist/agent-src/rules/`, or every scope filter rejected every rule,
+    //     and a green checkmark here would cover an assertion never evaluated.
+    //     This still throws.
+    //   - keys == 0 → `agents/.agent-tools.yml` selects zero tools, which
+    //     `_active_tools()` honours by design. There is no projection surface
+    //     in this checkout, so there is nothing to be stale or missing. That is
+    //     an absent optional surface, not a moved root.
+    //
+    // Conflating the two made the gate unsatisfiable on a supported config: it
+    // runs FIRST in the pre-push `preflight` chain, so a maintainer who
+    // deactivates the per-tool trees (they duplicate a globally installed
+    // `~/.claude`) could not push at all, with no fix available short of the
+    // env escape hatch. A gate whose only compliant path is to change an
+    // unrelated setting is not a gate. `main()` prints the skip explicitly —
+    // the empty case must be LOUD, never a silent green.
+    const noActiveTree = Object.keys(expected).length === 0;
+    assertScanned({
+        gate: 'check_rule_projection_integrity',
+        scanned: Object.values(expected).reduce((n, rules) => n + rules.length, 0),
+        units: 'projected rule entries',
+        roots: [DIST_RULES, ...Object.keys(expected)],
+        ...(noActiveTree
+            ? {
+                  allowEmpty:
+                      'OPTIONAL_INPUT: no host rule tree is active — agents/.agent-tools.yml ' +
+                      'selects zero tools, so the surface this gate audits does not exist in ' +
+                      'this checkout. With one or more active tools the emit plan carries the ' +
+                      'full rule set by construction, so a dead dist/agent-src/rules/ still fails here.',
+              }
+            : {}),
+    });
+
+    for (const [tree, rules] of Object.entries(expected)) {
+        const treeDir = path.join(repoRoot, tree);
+        const treeStat = _lstatOrNull(treeDir);
+        treePresent[tree] = treeStat !== null && treeStat.isDirectory();
+
+        for (const rule of rules) {
+            const target = `${tree}/${rule}`;
+            const entry = _lstatOrNull(path.join(treeDir, rule));
+            if (entry === null) {
+                findings.push({
+                    tree,
+                    rule,
+                    kind: 'missing',
+                    message: treePresent[tree]
+                        ? 'no projection entry — the rule reaches the model at no project scope'
+                        : 'projection tree does not exist',
+                });
+                ledger.fail(target, 'missing projection entry');
+                continue;
+            }
+
+            const dist = path.join(repoRoot, DIST_RULES, rule);
+            let distStat: fs.Stats;
+            try {
+                distStat = fs.statSync(dist);
+            } catch {
+                // Unreachable while `expected` derives from this same dist tree,
+                // but reachable if the tree changes under a running gate. Report
+                // rather than crash: a projection entry whose source is gone is
+                // a dangling link, which is a real defect either way.
+                findings.push({
+                    tree,
+                    rule,
+                    kind: 'dangling',
+                    message: `projection entry has no source at ${DIST_RULES}/${rule}`,
+                });
+                ledger.fail(target, 'dangling projection entry');
+                continue;
+            }
+
+            // `entry` is an lstat: for a symlink that is the LINK's mtime, which
+            // is what "when was this projected" means. `statSync` here follows
+            // nothing — dist rules are regular files.
+            if (distStat.mtimeMs > entry.mtimeMs) {
+                findings.push({
+                    tree,
+                    rule,
+                    kind: 'stale',
+                    message:
+                        `source is newer than the projection entry ` +
+                        `(${DIST_RULES}/${rule} ${new Date(distStat.mtimeMs).toISOString()} > ` +
+                        `entry ${new Date(entry.mtimeMs).toISOString()})`,
+                });
+                ledger.fail(target, 'stale projection entry');
+                continue;
+            }
+
+            ledger.complete(target);
+        }
+    }
+
+    return { findings, treePresent, ledger };
+}
+
+/** Group findings by tree, preserving rule order, for a report a reader can act on. */
+export function renderFindings(audit: ProjectionAudit): string[] {
+    const lines: string[] = [];
+    const byTree = new Map<string, ProjectionFinding[]>();
+    for (const f of audit.findings) {
+        const bucket = byTree.get(f.tree);
+        if (bucket === undefined) byTree.set(f.tree, [f]);
+        else bucket.push(f);
+    }
+    for (const [tree, group] of byTree) {
+        const missing = group.filter((f) => f.kind === 'missing');
+        const stale = group.filter((f) => f.kind === 'stale');
+        const dangling = group.filter((f) => f.kind === 'dangling');
+        if (audit.treePresent[tree] !== true) {
+            lines.push(`${tree}: tree does not exist — ${String(group.length)} rule(s) reach the model at no project scope`);
+        }
+        if (missing.length > 0) {
+            lines.push(`${tree}: ${String(missing.length)} rule(s) missing from the projection:`);
+            for (const f of missing) lines.push(`    - ${f.rule}`);
+        }
+        if (stale.length > 0) {
+            lines.push(`${tree}: ${String(stale.length)} projection entry/entries older than their source:`);
+            for (const f of stale) lines.push(`    - ${f.rule} — ${f.message}`);
+        }
+        if (dangling.length > 0) {
+            lines.push(`${tree}: ${String(dangling.length)} dangling projection entry/entries:`);
+            for (const f of dangling) lines.push(`    - ${f.rule} — ${f.message}`);
+        }
+    }
+    return lines;
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    const quiet = args.includes('--quiet');
+    const idx = args.indexOf('--root');
+    const root = path.resolve(idx !== -1 ? (args[idx + 1] ?? REPO_ROOT) : REPO_ROOT);
+
+    // `condense`'s emit plan reads `MODULE_STATE`, whose only root seam is this
+    // reassignment. Repointing it is what makes `--root` mean the same thing for
+    // the expected set and for the trees being audited — without it the gate
+    // would compare this repo's rules against another checkout's projection.
+    _pointCondenseAt(root);
+
+    let audit: ProjectionAudit;
+    try {
+        audit = auditRuleProjection(root, projected_rule_trees());
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
+    // Zero active trees is a legitimate config (see `auditRuleProjection`), but
+    // it means this run audited nothing. Say so on its own line instead of
+    // letting the success line below report "0 entries across 0 trees", which
+    // reads as a pass to every human and every log scraper.
+    if (Object.keys(audit.treePresent).length === 0) {
+        process.stderr.write(
+            '⚠️  check_rule_projection_integrity: no host rule tree is active ' +
+                '(agents/.agent-tools.yml selects zero tools) — nothing to audit. This gate ' +
+                'has teeth only where a tool is active; CI activates all eight.\n',
+        );
+        return 0;
+    }
+
+    const lines = renderFindings(audit);
+
+    let tally;
+    try {
+        tally = quiet ? audit.ledger.finalize() : audit.ledger.report();
+    } catch (exc) {
+        if (exc instanceof UnaccountedTargetsError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
+    if (lines.length > 0) {
+        for (const l of lines) process.stderr.write(`❌  ${l}\n`);
+        process.stderr.write(
+            `\nThe host rule trees are the ONLY carrier for a non-kernel rule's prose ` +
+                `(docs/contracts/rule-router.md § no runtime router). Regenerate with ` +
+                `\`task generate-tools\`, then re-run this gate.\n`,
+        );
+        return 1;
+    }
+
+    if (!quiet) {
+        process.stdout.write(
+            `✅  ${String(tally.completed)} rule projection entries complete and fresh across ` +
+                `${String(Object.keys(audit.treePresent).length)} host rule tree(s)\n`,
+        );
+    }
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+        return true;
+    }
+    // A symlinked invocation makes the raw URLs differ (import.meta.url is the
+    // resolved real path, argv[1] keeps the symlink). Compare realpaths, or the
+    // CLI silently no-ops when run through a projection — the bundled-CLI-entry
+    // landmine this repo has already paid for once.
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/condense.ts

@@ -1108,6 +1108,36 @@ function _scoped_rule_basenames(): string[] {
         .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
 }
 
+/**
+ * The emit plan of {@link generate_rule_symlinks}: active tool dir → the exact
+ * rule basenames it projects there.
+ *
+ * Exported so a completeness gate can assert a host rule tree matches the
+ * generator WITHOUT regenerating it. That distinction is the whole point:
+ * `check_bridge_derivation` regenerates and then diffs, so it can only ever see
+ * a fixpoint, and a five-week-stale tree on a working checkout is invisible to
+ * it. A gate that reads the tree as it stands needs the expected set from
+ * somewhere, and every other candidate source is wrong in a way that
+ * propagates: a hand-maintained array goes obsolete silently, and
+ * `dist/agent-src/rules/` over-counts by the ADR-004 `type: manual` rules these
+ * trees deliberately omit (113 files, 5 manual, 108 projected).
+ *
+ * `generate_rule_symlinks` consumes this too, so there is one emit plan rather
+ * than a gate's reconstruction of one.
+ */
+export function projected_rule_trees(
+    user_home: string = process.env['HOME'] ?? os.homedir(),
+): Record<string, string[]> {
+    const rules = _scoped_rule_basenames();
+    const dedup_on = _read_projection_scope_dedup();
+    const out: Record<string, string[]> = {};
+    for (const tool_dir of Object.keys(_filter_tool_dirs(TOOL_DIRS))) {
+        const skip = dedup_on ? _dedupable_rules(tool_dir, rules, user_home) : new Set<string>();
+        out[tool_dir] = rules.filter((r) => !skip.has(r));
+    }
+    return out;
+}
+
 export function generate_rule_symlinks(): number {
     const rules = _scoped_rule_basenames();
     const tool_dirs = _filter_tool_dirs(TOOL_DIRS);
@@ -1130,14 +1160,18 @@ export function generate_rule_symlinks(): number {
         );
     }
 
-    const dedup_on = _read_projection_scope_dedup();
     const user_home = process.env['HOME'] ?? os.homedir();
+    // Read the emit plan from the exported function rather than recomputing the
+    // dedup skip here, so the gate that asserts this tree is complete and the
+    // code that writes it cannot disagree.
+    const plan = projected_rule_trees(user_home);
     const skipped_per_tool: Record<string, Set<string>> = {};
 
     let total = 0;
     for (const [tool_dir, rel_prefix] of Object.entries(tool_dirs)) {
         const target_dir = path.join(MODULE_STATE.PROJECT_ROOT, tool_dir);
-        const skip = dedup_on ? _dedupable_rules(tool_dir, rules, user_home) : new Set<string>();
+        const emit_here = new Set(plan[tool_dir] ?? rules);
+        const skip = new Set(rules.filter((r) => !emit_here.has(r)));
         skipped_per_tool[tool_dir] = skip;
         _mkdirp(target_dir);
         // Clean stale symlinks — a rule that became de-duplicable this run is

package/src/scripts/conformance_scan.ts

@@ -42,6 +42,16 @@ export interface Violation {
   session: string;
   at: string;
   detail: string;
+  /**
+   * Language-pin only. Assistant turns since the last genuine user prompt, and
+   * whether a compaction boundary fell in between. Together they separate the
+   * two failures the round-5 audit found hiding under one count: a pin that was
+   * ABSENT because compaction removed it, and a pin that was PRESENT and
+   * ignored. The first is a state defect; the second is non-compliance, and
+   * only the second is unfixable by re-injection.
+   */
+  turns_since_prompt?: number;
+  compaction_since_prompt?: boolean;
 }
 
 export interface SessionReport {
@@ -165,6 +175,12 @@ export function scanSession(sessionId: string, lines: string[]): SessionReport {
   let authorized = new Set<GitOp>();
   let sawPending = false;
   let evaluationsThisTurn = 0;
+  // Round-5 provenance for language violations. The round-5 audit could only
+  // separate "the pin was absent" from "the pin was ignored" by reconstructing
+  // both facts from the raw store afterwards; recording them here is what makes
+  // that split reproducible against a future corpus instead of re-argued.
+  let turnsSincePrompt = 0;
+  let compactionSincePrompt = false;
 
   for (const line of lines) {
     if (!line.trim()) {
@@ -196,13 +212,29 @@ export function scanSession(sessionId: string, lines: string[]): SessionReport {
       continue;
     }
 
+    // A compaction boundary removes context the pin lived in. It is not a turn
+    // and it is not a prompt, but it changes what the model can still see — so
+    // it is recorded, not skipped silently.
+    if (entry["type"] === "system" && entry["subtype"] === "compact_boundary") {
+      compactionSincePrompt = true;
+      continue;
+    }
+
     const ut = userText(entry);
     if (ut !== null) {
+      // A compaction SUMMARY arrives as a `user` entry. Treating it as a chat
+      // message would let its language reset the pin — the exact defect class
+      // that made the first detector report 303 instead of 626.
+      if (entry["isCompactSummary"] === true) {
+        continue;
+      }
       if (isInjectedBody(ut)) {
         // Not a chat message — it changes neither the pin nor the ledger.
         continue;
       }
       report.user_turns += 1;
+      turnsSincePrompt = 0;
+      compactionSincePrompt = false;
       const c = classify(ut);
       if (c.language !== "und") {
         pinned = c.language;
@@ -222,6 +254,7 @@ export function scanSession(sessionId: string, lines: string[]): SessionReport {
     const prose = assistantText(entry);
     if (prose !== null) {
       report.assistant_turns += 1;
+      turnsSincePrompt += 1;
       if (pinned === "de") {
         const first = prose.split("\n").find((l) => l.trim()) ?? "";
         if (HARNESS_TEXT.test(first.trim())) {
@@ -234,6 +267,8 @@ export function scanSession(sessionId: string, lines: string[]): SessionReport {
             session: sessionId,
             at,
             detail: `German pin, English reply opener: "${first.slice(0, 110)}"`,
+            turns_since_prompt: turnsSincePrompt,
+            compaction_since_prompt: compactionSincePrompt,
           });
         }
       }