@event4u/agent-config 9.28.0 → 9.29.0

package/src/scripts/check_detector_corpus.ts

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * Detector corpus gate (P4.3 of road-to-rule-delivery-integrity).
+ *
+ * Every self-repair detector must carry all THREE fixture classes, and every
+ * fixture must behave as its class says:
+ *
+ *   fire            a recorded real failure the detector must catch
+ *   near-miss-fire  a real failure phrased unlike the canonical one, which must
+ *                   still be caught — recall at the boundary
+ *   must-not-fire   text that superficially matches and must stay silent
+ *
+ * The three-class rule is the point of the gate rather than a stylistic one.
+ * Precision and recall fail in opposite directions and a single corpus hides
+ * that: a detector with `fire` cases only looks perfect while opening records on
+ * praise, which is exactly what `detectUserReport` did until 2026-08-09 (it
+ * fired on "das ist fine, du hast nichts falsch gemacht"). A missing class is
+ * therefore a gate failure, not a warning — the absent half is where the defects
+ * live.
+ *
+ * Registration is explicit: a detector added to `self_repair.ts` without a
+ * matching corpus entry fails here, which is the coupling that keeps the corpus
+ * from silently lagging the code.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import * as YAML from 'yaml';
+
+import {
+    type DefectFinding,
+    type TurnSnapshot,
+    detectCouncilClaim,
+    detectLanguageMirror,
+    detectUserReport,
+} from './_lib/self_repair.js';
+import { assertScanned } from './_lib/scan_scope.js';
+
+export const CORPUS_REL = path.join('tests', 'fixtures', 'self-repair-detector-corpus.yml');
+
+const GATE = 'check_detector_corpus';
+const CLASSES = ['fire', 'near-miss-fire', 'must-not-fire'] as const;
+type FixtureClass = (typeof CLASSES)[number];
+
+/** One corpus entry, in the union of shapes the three detectors need. */
+export interface Fixture {
+    text?: string;
+    reply?: string;
+    pinned_language?: 'de' | 'en';
+    tool_commands?: string[];
+    note?: string;
+}
+
+export type Corpus = Record<string, Partial<Record<FixtureClass, Fixture[]>>>;
+
+/**
+ * Every detector that must appear in the corpus, with how to run it.
+ *
+ * Keyed by the `defect_class` the detector produces, so the corpus reads as a
+ * list of defect classes rather than of function names.
+ */
+export const DETECTORS: Record<string, (f: Fixture) => DefectFinding | null> = {
+    'user-reported': (f) => detectUserReport(f.text ?? f.reply ?? ''),
+    'council-availability-claim': (f) => detectCouncilClaim(asTurn(f)),
+    'language-mirror': (f) => detectLanguageMirror(asTurn(f)),
+};
+
+function asTurn(f: Fixture): TurnSnapshot {
+    return {
+        prompt: f.text ?? '',
+        reply: f.reply ?? '',
+        toolCommands: f.tool_commands ?? [],
+        pinnedLanguage: f.pinned_language ?? null,
+    };
+}
+
+export interface Finding {
+    detector: string;
+    kind: 'missing-class' | 'empty-class' | 'wrong-outcome' | 'unregistered';
+    message: string;
+}
+
+/** Pure: audit a parsed corpus against the registered detectors. */
+export function auditCorpus(corpus: Corpus): { findings: Finding[]; fixtures: number } {
+    const findings: Finding[] = [];
+    let fixtures = 0;
+
+    for (const name of Object.keys(corpus)) {
+        if (!(name in DETECTORS)) {
+            findings.push({
+                detector: name,
+                kind: 'unregistered',
+                message: `corpus names "${name}", which is not a registered detector`,
+            });
+        }
+    }
+
+    for (const [name, run] of Object.entries(DETECTORS)) {
+        const entry = corpus[name];
+        if (entry === undefined) {
+            findings.push({
+                detector: name,
+                kind: 'missing-class',
+                message: `no corpus entry at all — needs all of: ${CLASSES.join(', ')}`,
+            });
+            continue;
+        }
+        for (const cls of CLASSES) {
+            const cases = entry[cls];
+            if (cases === undefined) {
+                findings.push({
+                    detector: name,
+                    kind: 'missing-class',
+                    message: `missing the \`${cls}\` class`,
+                });
+                continue;
+            }
+            if (cases.length === 0) {
+                // An empty class is the same hole as a missing one wearing a key.
+                findings.push({
+                    detector: name,
+                    kind: 'empty-class',
+                    message: `\`${cls}\` is present but empty`,
+                });
+                continue;
+            }
+            for (const f of cases) {
+                fixtures += 1;
+                const fired = run(f) !== null;
+                const shouldFire = cls !== 'must-not-fire';
+                if (fired !== shouldFire) {
+                    const what = f.text ?? f.reply ?? '(empty)';
+                    findings.push({
+                        detector: name,
+                        kind: 'wrong-outcome',
+                        message:
+                            `\`${cls}\` fixture ${shouldFire ? 'did NOT fire' : 'FIRED'}: ` +
+                            JSON.stringify(what.slice(0, 90)),
+                    });
+                }
+            }
+        }
+    }
+    return { findings, fixtures };
+}
+
+export function loadCorpus(repoRoot: string): Corpus {
+    const p = path.join(repoRoot, CORPUS_REL);
+    const parsed = YAML.parse(fs.readFileSync(p, 'utf-8')) as { detectors?: Corpus };
+    return parsed.detectors ?? {};
+}
+
+export function main(repoRoot: string = process.cwd()): number {
+    const corpus = loadCorpus(repoRoot);
+    const { findings, fixtures } = auditCorpus(corpus);
+
+    // A corpus that parsed to nothing is the dead-scope case, not a pass.
+    assertScanned({
+        gate: GATE,
+        scanned: fixtures,
+        units: 'detector fixtures',
+        roots: [CORPUS_REL],
+    });
+
+    if (findings.length > 0) {
+        process.stderr.write(`${GATE}: ${String(findings.length)} finding(s)\n\n`);
+        for (const f of findings) {
+            process.stderr.write(`  ${f.detector}: ${f.message}\n`);
+        }
+        process.stderr.write(
+            `\nEvery detector needs all three classes (${CLASSES.join(', ')}) and every\n` +
+                'fixture must behave as its class says. Precision and recall fail in\n' +
+                'opposite directions; a corpus missing one half hides the other.\n',
+        );
+        return 1;
+    }
+
+    process.stdout.write(
+        `✅  ${GATE}: ${String(Object.keys(DETECTORS).length)} detector(s) × ` +
+            `${String(CLASSES.length)} classes, ${String(fixtures)} fixtures, all behaving\n`,
+    );
+    return 0;
+}
+
+function isCliEntry(): boolean {
+    const argv1 = process.argv[1];
+    if (argv1 === undefined) {
+        return false;
+    }
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(argv1))
+        );
+    } catch {
+        return pathToFileURL(argv1).href === import.meta.url;
+    }
+}
+
+if (isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/check_hook_bundle_freshness.ts

@@ -31,7 +31,10 @@
  * WHAT IT DOES NOT DO: it never builds. Building into a live hook path is a
  * documented hazard in this repo (an esbuild run that overwrites the
  * dispatcher a running hook is executing can wedge the tool loop), so the
- * remedy is printed for a human to run deliberately.
+ * remedy is printed for a human to run deliberately. The SAFE rebuild
+ * (build to .new → probe → atomic rename) lives in `rebuild_hook_bundle.ts`,
+ * which preflight runs right before this gate — so a red here means the heal
+ * itself failed or was bypassed, not merely that a merge landed.
  *
  * Exit codes: 0 = fresh, or no self-hosted bundle to check · 1 = stale.
  */

package/src/scripts/condense.ts

@@ -1174,11 +1174,27 @@ export function generate_rule_symlinks(): number {
         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
+        // Clean stale entries — a rule that became de-duplicable this run is
         // stale at project scope too, so it has to go with the rest.
+        //
+        // Symlink-only was correct while every tool dir was a symlink tree. Two
+        // paths now write REAL files (`thin` mode, and the Claude emitter
+        // below), and a stale real file is invisible to an `_isSymlink` test —
+        // so a renamed or newly de-duplicable rule would leave its body behind,
+        // loaded unconditionally, forever.
+        //
+        // Ownership test for a real file: its basename is an agent-config rule
+        // in the projection source. A consumer's own hand-written rule is only
+        // touched if it collides with one of ours by name, in which case it was
+        // already being overwritten.
         for (const item of _iterdirSorted(target_dir)) {
             const name = path.basename(item);
-            if (_isSymlink(item) && (!rules.includes(name) || skip.has(name)) && name !== 'README.md') {
+            if (name === 'README.md') {
+                continue;
+            }
+            const is_ours =
+                _isSymlink(item) || _isFile(path.join(MODULE_STATE.RULES_SOURCE, name));
+            if (is_ours && (!rules.includes(name) || skip.has(name))) {
                 fs.unlinkSync(item);
             }
         }
@@ -1192,6 +1208,11 @@ export function generate_rule_symlinks(): number {
             }
             if (thin_files !== null) {
                 _writeText(link, thin_files[rule] as string);
+            } else if (tool_dir === '.claude/rules') {
+                // Host-native activation (P3.1): emit the rule with the host's
+                // own `paths:` key instead of symlinking agent-config
+                // frontmatter this host does not read.
+                _emit_claude_rule(path.join(MODULE_STATE.RULES_SOURCE, rule), link);
             } else {
                 fs.symlinkSync(path.join(rel_prefix, rule), link);
             }
@@ -1355,6 +1376,145 @@ export function _emit_windsurf_rule(source: string, target: string): void {
     _writeText(target, lines.join('\n'));
 }
 
+/**
+ * A brace group the host expands, versus an agent-config placeholder that only
+ * LOOKS like one.
+ *
+ * `path_prefix: "{module_root}/"` in `roadmap-ci-steps-policy` is resolved by
+ * this suite from `modules.root_paths`. Emitted verbatim into a host `paths:`
+ * list it is a brace group with no comma, which the host expands to the literal
+ * string `{module_root}` — a pattern that matches no file. The rule would then
+ * reach the model **never** instead of on-demand, and nothing would say so: the
+ * probed contract records this exact degradation as silent
+ * (`claude-code-rules-dir-contract.md` § constraints).
+ *
+ * Dropping the pattern is fail-safe in the one direction that matters. A rule
+ * left with no pattern at all carries no `paths:` key and loads
+ * unconditionally — the status quo, not a regression. A rule carrying a
+ * no-op pattern is invisible.
+ *
+ * The discriminator is the comma, not a placeholder allowlist: `{ts,tsx}` is a
+ * real alternation, `{module_root}` cannot be one.
+ */
+export function _is_unresolved_placeholder(pattern: string): boolean {
+    for (const m of pattern.matchAll(/\{([^}]*)\}/g)) {
+        if (!(m[1] as string).includes(',')) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * `[` opens a bracket expression for the host. An unparseable one makes that
+ * pattern match nothing while the rule's other patterns keep working — so a
+ * literal `[` in a trigger is escaped rather than trusted.
+ */
+export function _escape_claude_bracket(pattern: string): string {
+    return pattern.replace(/\[/g, '\\[');
+}
+
+/**
+ * Expanded-pattern cost of one glob: the product of its brace alternations.
+ * The host budgets a rule's whole `paths:` list at 1,000 expanded patterns and
+ * 4 MiB, and a list over budget is used UNEXPANDED — braces then match
+ * literally, i.e. nothing. Counting keeps the emitter under the cliff instead
+ * of discovering it as a silent no-op.
+ */
+export function _expanded_pattern_count(pattern: string): number {
+    let n = 1;
+    for (const m of pattern.matchAll(/\{([^}]*)\}/g)) {
+        n *= (m[1] as string).split(',').length;
+    }
+    return n;
+}
+
+/** Host-documented budget for one rule's whole `paths:` list. */
+export const CLAUDE_PATHS_PATTERN_BUDGET = 1000;
+
+export interface ClaudePathsPlan {
+    /** Patterns to emit under `paths:`, in declaration order. */
+    globs: string[];
+    /** Patterns deliberately not emitted, with the reason a reader can act on. */
+    dropped: { pattern: string; reason: 'unresolved-placeholder' | 'over-budget' }[];
+}
+
+/**
+ * Derive the host's `paths:` list for one rule, with every drop recorded.
+ *
+ * Kernel / always-apply rules get an EMPTY list on purpose: absent `paths:` is
+ * how this host says "load unconditionally", which is exactly what an Iron-Law
+ * rule needs. Scoping one would be a correctness regression dressed as a byte
+ * saving — and the same contract notes path-scoped rules are not re-injected
+ * after `/compact`, so an obligation that must survive compaction cannot be
+ * path-scoped at all.
+ */
+export function _claude_paths_plan(meta: Record<string, unknown>): ClaudePathsPlan {
+    const always_apply = Boolean(meta['alwaysApply'] || meta['type'] === 'always');
+    if (always_apply) {
+        return { globs: [], dropped: [] };
+    }
+    const globs: string[] = [];
+    const dropped: ClaudePathsPlan['dropped'] = [];
+    let spent = 0;
+    for (const raw of derive_trigger_globs(meta)) {
+        if (_is_unresolved_placeholder(raw)) {
+            dropped.push({ pattern: raw, reason: 'unresolved-placeholder' });
+            continue;
+        }
+        const cost = _expanded_pattern_count(raw);
+        if (spent + cost > CLAUDE_PATHS_PATTERN_BUDGET) {
+            dropped.push({ pattern: raw, reason: 'over-budget' });
+            continue;
+        }
+        spent += cost;
+        globs.push(_escape_claude_bracket(raw));
+    }
+    return { globs, dropped };
+}
+
+/**
+ * Emit a Claude Code rule carrying the host's OWN activation key.
+ *
+ * Sibling of {@link _emit_cursor_mdc} and {@link _emit_windsurf_rule}, and the
+ * third member of a set that had two. `.claude/rules` was a symlink projection
+ * of `dist/agent-src/rules`, which carried agent-config's own frontmatter
+ * vocabulary (`type`, `tier`, `triggers`, `alwaysApply`, …) into a host that
+ * reads **none** of it — so every rule loaded unconditionally and the corpus
+ * arrived in full every session.
+ *
+ * Emitted frontmatter is therefore `paths:` and nothing else: the one key the
+ * probed contract records as read by this host. A rule with no path-shaped
+ * trigger gets no frontmatter at all rather than a block the host ignores —
+ * keys that do nothing are bytes in every session's standing context.
+ *
+ * The body is copied byte-for-byte from the projection source (ADR-201's
+ * copy-plus-rewrite discipline); only the frontmatter is host-shaped.
+ */
+export function _emit_claude_rule(source: string, target: string): void {
+    const [meta, body] = _parse_frontmatter(_readText(source));
+    const plan = _claude_paths_plan(meta);
+    for (const d of plan.dropped) {
+        _print(
+            `  ⚠️  ${path.basename(target)}: dropped \`paths:\` pattern ${JSON.stringify(d.pattern)} (${d.reason}) — ` +
+                (plan.globs.length > 0
+                    ? 'the rule keeps its other patterns'
+                    : 'the rule now loads unconditionally'),
+        );
+    }
+    const lines: string[] = [];
+    if (plan.globs.length > 0) {
+        lines.push('---', 'paths:');
+        for (const g of plan.globs) {
+            lines.push(`  - ${_yaml_scalar(g)}`);
+        }
+        lines.push('---', '');
+    }
+    lines.push(_pyRstrip(body) + '\n');
+    _mkdirp(path.dirname(target));
+    _writeText(target, lines.join('\n'));
+}
+
 /** Python str.rstrip() with no args. */
 function _pyRstrip(s: string): string {
     return s.replace(/\s+$/u, '');