@event4u/agent-config 16.2.0 → 16.3.0

package/src/scripts/code_graph/verbs.ts

@@ -52,6 +52,38 @@ export function isAcceptedEdge(e: CodeEdge): boolean {
     return isStatedResolution(e.resolved_via);
 }
 
+/** Why a gate verb refused. A closed set so a caller can branch on it. */
+export type RefusalReason = 'foreign-edges-not-accepted' | 'entry-points-unavailable';
+
+/**
+ * A graph whose every edge came from a file this package did not build.
+ *
+ * Those edges are tagged `foreign` and sit in the guess set, so a gate verb
+ * walking one would accept nothing and report an empty answer — and an empty
+ * answer from a gate reads as "nothing to worry about", which is the wrong
+ * reading and the dangerous one. The verbs refuse instead, by name, so the
+ * consumer learns that their graph is readable but not gate-grade rather than
+ * being told their diff impacts nothing.
+ *
+ * A MIXED graph is not refused: it carries edges this package did resolve, and
+ * the guess filter already excludes the foreign ones from the walk.
+ */
+export function foreignRefusal(g: LoadedGraph): string | null {
+    // `graph` is null on the index-backed read path, which answers per-node
+    // from the twin and never materialises the edge list. Nothing to classify
+    // there, and an index-backed graph is one this package built.
+    const edges: readonly CodeEdge[] = g.graph?.edges ?? [];
+    if (edges.length === 0) return null;
+    if (!edges.every((e) => e.resolved_via === 'foreign')) return null;
+    return (
+        'every edge in this graph was read from a file this package did not build, so all of them ' +
+        'are guesses and none is gate-grade. A gate verb would accept no edge and report an empty ' +
+        'answer, which reads as "nothing found" rather than "nothing trusted". Build a native graph ' +
+        '(`agent-config graph build`) to use this verb, or use `query` and `explain`, which answer ' +
+        'from foreign edges and say so.'
+    );
+}
+
 /**
  * Relations that constitute a REFERENCE to the target, as opposed to
  * containment of it.
@@ -132,6 +164,10 @@ export interface ReachedNode {
 }
 
 export interface ImpactResult extends VerbReport {
+    /** Non-null when the verb REFUSED to answer. Every list is then empty. */
+    refusal: string | null;
+    /** Machine-readable reason, when `refusal` is set. */
+    refusal_reason: RefusalReason | null;
     /** Node ids the diff touched that the graph knows. */
     seeds: string[];
     /**
@@ -219,6 +255,26 @@ export function impact(
     depth = 2,
     isTest: (relPath: string) => boolean = () => false,
 ): ImpactResult {
+    const foreign = foreignRefusal(g);
+    if (foreign !== null) {
+        return {
+            source: g.source,
+            state,
+            accepted_via: '(none)',
+            rejected_via: '(none)',
+            refusal: foreign,
+            refusal_reason: 'foreign-edges-not-accepted',
+            seeds: [],
+            unresolved_files: [],
+            not_indexed_files: [],
+            dependents: [],
+            reached: [],
+            test_files: [],
+            producing_edges: [],
+            lines: [],
+            recommended_reads: [],
+        };
+    }
     const { seeds, unresolved, not_indexed } = seedsForFiles(g, files);
     const accepted: CodeEdge[] = [];
     const rejected: CodeEdge[] = [];
@@ -258,6 +314,8 @@ export function impact(
         state,
         accepted_via: viaHistogram(accepted),
         rejected_via: viaHistogram(rejected),
+        refusal: null,
+        refusal_reason: null,
         seeds,
         unresolved_files: unresolved,
         not_indexed_files: not_indexed,
@@ -334,6 +392,10 @@ export function testsFor(g: LoadedGraph, symbol: string, state: GraphState): Tes
 }
 
 export interface UntestedResult extends VerbReport {
+    /** Non-null when the verb REFUSED to answer. Every list is then empty. */
+    refusal: string | null;
+    /** Machine-readable reason, when `refusal` is set. */
+    refusal_reason: RefusalReason | null;
     seeds: string[];
     unresolved_files: string[];
     not_indexed_files: string[];
@@ -351,6 +413,24 @@ export interface UntestedResult extends VerbReport {
  * count and make the ratio meaningless.
  */
 export function untested(g: LoadedGraph, files: readonly string[], state: GraphState): UntestedResult {
+    const foreign = foreignRefusal(g);
+    if (foreign !== null) {
+        return {
+            source: g.source,
+            state,
+            accepted_via: '(none)',
+            rejected_via: '(none)',
+            refusal: foreign,
+            refusal_reason: 'foreign-edges-not-accepted',
+            seeds: [],
+            unresolved_files: [],
+            not_indexed_files: [],
+            untested: [],
+            tested: [],
+            lines: [],
+            recommended_reads: [],
+        };
+    }
     const { seeds, unresolved, not_indexed } = seedsForFiles(g, files);
     const accepted: CodeEdge[] = [];
     const rejected: CodeEdge[] = [];
@@ -375,6 +455,8 @@ export function untested(g: LoadedGraph, files: readonly string[], state: GraphS
         state,
         accepted_via: viaHistogram(accepted),
         rejected_via: viaHistogram(rejected),
+        refusal: null,
+        refusal_reason: null,
         seeds,
         unresolved_files: unresolved,
         not_indexed_files: not_indexed,
@@ -403,6 +485,8 @@ export interface DeadResult extends VerbReport {
     sources: EntryPointSource[];
     /** Non-null when the verb REFUSED to answer. The list is then empty. */
     refusal: string | null;
+    /** Machine-readable reason, when `refusal` is set. */
+    refusal_reason: RefusalReason | null;
     dead: string[];
     /** Entry points excluded from `dead` — the audit trail for the exclusion. */
     excluded: string[];
@@ -448,6 +532,23 @@ export function dead(
         state,
         sources: [...sources],
     };
+    // Checked BEFORE the entry-point sources: on an all-foreign graph every
+    // in-edge is a guess, so every symbol would report dead — the confident
+    // false "dead" this verb's own header calls worse than no verb at all.
+    const foreign = foreignRefusal(g);
+    if (foreign !== null) {
+        return {
+            ...base,
+            accepted_via: '(none)',
+            rejected_via: '(none)',
+            refusal: foreign,
+            refusal_reason: 'foreign-edges-not-accepted',
+            dead: [],
+            excluded: [],
+            lines: [],
+            recommended_reads: [],
+        };
+    }
     if (unavailable.length > 0 && opts.acceptMissingExports !== true) {
         return {
             ...base,
@@ -460,6 +561,7 @@ export function dead(
                 'A symbol they would have declared an entry point is indistinguishable from a dead one, ' +
                 'so no list is produced. Supply the missing source with --entry-points <file>, or state ' +
                 'that you accept the gap with --accept-missing-exports.',
+            refusal_reason: 'entry-points-unavailable',
             dead: [],
             excluded: [],
             lines: [],
@@ -496,6 +598,7 @@ export function dead(
         accepted_via: viaHistogram(accepted),
         rejected_via: viaHistogram(rejected),
         refusal: null,
+        refusal_reason: null,
         dead: list,
         excluded: excluded.sort(),
         lines: list,

package/src/scripts/compile_hook_manifest.ts

@@ -79,12 +79,44 @@ const TABLES = {
 
 export type TableName = keyof typeof TABLES;
 
+/**
+ * The TWO labels a compiled table carries, and why one was not enough.
+ *
+ * `fingerprint` binds the file to its YAML SOURCE — it answers "is this
+ * compiled from the YAML as it stands". `body_fingerprint` binds the file to
+ * ITSELF: it is the fingerprint of the exact body bytes this writer emitted,
+ * and it answers "is the body a reader is about to serve the body that was
+ * compiled".
+ *
+ * road-to-blocking-severities 2.3. The source label alone left a real hole,
+ * and it is the one the roadmap measured: edit a cell of the compiled `table`
+ * and leave `fingerprint` alone, and it still equals the YAML's fingerprint,
+ * so the reader serves the edited body — and since both readers prefer the
+ * compiled form, the edited cell is what every host is told while the reviewed
+ * YAML beside it says something else.
+ *
+ * WHAT THIS DOES NOT CLAIM. Someone who edits the body can recompute this
+ * label as easily as the writer does; it is an integrity check against a
+ * PARTIAL edit — a hand edit, a bad merge, a truncated write — not a signature.
+ * That is the same honesty the source label already owed: neither resists an
+ * author, and resisting an author is what the tool-call deny (2.2) and the
+ * ratification record (2.1) are for. Three cheap mechanisms over one expensive
+ * one, each named for what it actually covers.
+ *
+ * The body text is `JSON.stringify` of the parsed document, which is exactly
+ * what lands in the file, so a reader recovers it by re-stringifying what it
+ * parsed. A test pins that round trip rather than assuming it.
+ */
 export function compile(yamlText: string, table: TableName = 'manifest'): string {
     const spec = TABLES[table];
     const doc = (spec.yamlVersion === undefined
         ? parseYaml(yamlText)
         : parseYaml(yamlText, { version: spec.yamlVersion })) as unknown;
-    return JSON.stringify({ fingerprint: tableFingerprint(yamlText), [spec.key]: doc });
+    return JSON.stringify({
+        fingerprint: tableFingerprint(yamlText),
+        body_fingerprint: tableFingerprint(JSON.stringify(doc)),
+        [spec.key]: doc,
+    });
 }
 
 export function main(argv: readonly string[] = process.argv.slice(2)): number {

package/src/scripts/condense.ts

@@ -42,6 +42,7 @@ import {
     strip_source_prefix,
 } from './_lib/agent_src.js';
 import { rewriteProjectedBodyLinks } from './_lib/guidelines_lane.js';
+import { render_windsurfrules, strip_frontmatter } from './_lib/windsurf_render.js';
 // Import-safety note: `project_thin_rules` guards its CLI entry
 // (`_isCliEntry()` before `process.exit(main())`), so importing it here is
 // side-effect-free. condense.ts is bundled into the installer, where a bare
@@ -49,7 +50,7 @@ import { rewriteProjectedBodyLinks } from './_lib/guidelines_lane.js';
 // bundled-CLI-entry-guard landmine. Verified before wiring, not assumed.
 import { build_thin } from './project_thin_rules.js';
 import { build_claude_hook_matrix } from './_lib/claude_settings_hooks.js';
-import { describeDroppedHosts, normalizeLeanProjectionMode, resolveLeanProjectionHosts, thinsHost,
+import { describeDroppedHosts, resolveLeanProjection, thinsHost,
     writesThinFiles, type LeanProjectionHosts, type LeanProjectionMode } from './_lib/lean_projection_mode.js';
 import { is_claude_builtin_name } from './_lib/claude_builtin_names.js';
 import { project_settings_path, load_agent_settings } from './_lib/agent_settings.js';
@@ -461,16 +462,14 @@ function _read_projection_scope_dedup(): boolean {
 
 
 function _lean_projection_settings(): { mode: LeanProjectionMode; hosts: LeanProjectionHosts } {
-    const data = load_agent_settings({ project_path: MODULE_STATE.SETTINGS_FILE });
-    const lean = data['lean_projection'];
-    const obj =
-        typeof lean === 'object' && lean !== null && !Array.isArray(lean)
-            ? (lean as Record<string, unknown>)
-            : {};
-    return {
-        mode: normalizeLeanProjectionMode(obj['mode'] ?? ''),
-        hosts: resolveLeanProjectionHosts(obj['hosts']),
-    };
+    // Step 1.2 of `road-to-a-rule-carrier-that-works-outside-the-repo`: this is
+    // now the shared resolver rather than one of three private readers. The
+    // INPUT is unchanged — `MODULE_STATE.SETTINGS_FILE` is still the file, so
+    // the projector's answer is the answer it always gave — and only the code
+    // that interprets it is shared. That is risk 2 of the roadmap's register
+    // ("making the hook agree with the projector could also move the
+    // projector") discharged by construction instead of by a test alone.
+    return resolveLeanProjection({ settingsPath: MODULE_STATE.SETTINGS_FILE });
 }
 
 // --- hashing -----------------------------------------------------------------
@@ -778,15 +777,9 @@ function _filter_tool_dirs(mapping: Record<string, string>): Record<string, stri
     return out;
 }
 
-export function strip_frontmatter(content: string): string {
-    if (content.startsWith('---')) {
-        const end = content.indexOf('---', 3);
-        if (end !== -1) {
-            content = _lstripNewlines(content.slice(end + 3));
-        }
-    }
-    return content;
-}
+// Moved to `_lib/windsurf_render.ts` beside its one remaining caller here and
+// the census that renders through it; re-exported so every importer's path holds.
+export { strip_frontmatter };
 
 // ── Path rewriter (P1 of road-to-path-fixes.md) ───────────────────────────
 // Kept byte-identical to check_condensation.ts::_rewritePaths (the two MUST
@@ -1229,14 +1222,8 @@ export function generate_windsurfrules(): number {
     // on `.windsurf/rules`. Without this line removing the per-run filter regressed
     // it 13 → 113: the per-run filter had been covering it by accident.
     const rules = partition_rules_for_dir('.windsurf/rules', _scoped_rule_basenames());
-    const parts = ['# Auto-generated from dist/agent-src/rules/ — do not edit directly\n'];
-    for (const rule of rules) {
-        const p = path.join(MODULE_STATE.RULES_SOURCE, rule);
-        const content = strip_frontmatter(_readText(p));
-        parts.push(`---\n\n${_strip(content)}\n`);
-    }
     const output = path.join(MODULE_STATE.PROJECT_ROOT, '.windsurfrules');
-    _writeText(output, parts.join('\n') + '\n');
+    _writeText(output, render_windsurfrules(MODULE_STATE.RULES_SOURCE, rules));
     info(`  ✅  Generated .windsurfrules (${rules.length} rules)`);
     return rules.length;
 }

package/src/scripts/estate_exemption_shape.ts

@@ -0,0 +1,202 @@
+#!/usr/bin/env tsx
+/**
+ * What the `estate_offset_exempt` population actually says — the producing command.
+ *
+ * THIS IS A READER, NOT A GATE. It exits 0 on every corpus, including one where
+ * no reason names anything. The refusal lives in `check_estate_count`, applies
+ * to ADDED files only, and is grandfathered precisely because of what this
+ * script measures: 43 of the 221 reasons in the tree on 2026-10-01 name no
+ * alternative disposition, so a check that re-read them would land red on a
+ * fifth of its corpus.
+ *
+ * WHAT IT BUYS. Two numbers nobody could produce before: how many exemptions
+ * name a rejected alternative, and how many repeat another file's reason
+ * verbatim. Both are the inputs to whether the refusal vocabulary is the right
+ * one, and both move as the estate moves — so the NEXT reading is a delta
+ * rather than a re-derivation, which is the same bargain `roadmap_verify_share`
+ * makes for the verify grammar.
+ *
+ * THE VOCABULARY IS NOT THIS SCRIPT'S. It imports the lemma list the gate
+ * refuses on, so the report and the refusal cannot drift. A drifted pair fails
+ * silently and in the worst direction: the report says the tree conforms while
+ * the gate rejects it.
+ *
+ * CLI:
+ *   ./scripts-run src/scripts/estate_exemption_shape
+ *   ./scripts-run src/scripts/estate_exemption_shape --json
+ *   ./scripts-run src/scripts/estate_exemption_shape --root <dir>
+ *
+ * Exit codes: 0 always, except 2 for bad argv or a scan root that holds nothing.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { exemptionReason } from './_lib/estate_offsets.js';
+import { DISPOSITION_LEMMAS, lemmasNamed, namesDisposition, reasonKey } from './_lib/exemption_shape.js';
+import { DeadScopeError, assertScanned } from './_lib/scan_scope.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const _PROG = 'estate_exemption_shape';
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/** The three trees an exemption can sit in. `stubs/` and `skipped/` carry none. */
+const TREES: readonly { readonly label: string; readonly dir: string }[] = [
+    { label: 'active', dir: 'agents/roadmaps' },
+    { label: 'later', dir: 'agents/roadmaps/later' },
+    { label: 'archive', dir: 'agents/roadmaps/archive' },
+];
+
+export interface ExemptionRow {
+    readonly tree: string;
+    readonly file: string;
+    readonly reason: string;
+    /** The disposition lemmas this reason names; empty means it names none. */
+    readonly lemmas: readonly string[];
+}
+
+export interface ShapeReport {
+    readonly rows: readonly ExemptionRow[];
+    readonly shaped: number;
+    readonly shapeless: number;
+    /** Per-lemma hit counts, in the gate's own lemma order. */
+    readonly byLemma: Readonly<Record<string, number>>;
+    /** Groups of two or more files sharing one reason, largest first. */
+    readonly duplicates: readonly (readonly string[])[];
+}
+
+/** Read every exemption under `root`, in a stable order. */
+export function collectExemptions(root: string): ExemptionRow[] {
+    const rows: ExemptionRow[] = [];
+    for (const tree of TREES) {
+        const abs = path.join(root, tree.dir);
+        let names: string[];
+        try {
+            names = fs.readdirSync(abs);
+        } catch {
+            continue;
+        }
+        for (const name of [...names].sort()) {
+            if (!name.endsWith('.md')) continue;
+            const file = path.join(abs, name);
+            let text: string;
+            try {
+                if (!fs.statSync(file).isFile()) continue;
+                text = fs.readFileSync(file, 'utf-8');
+            } catch {
+                continue;
+            }
+            const reason = exemptionReason(text);
+            if (reason === null) continue;
+            rows.push({ tree: tree.label, file: `${tree.dir}/${name}`, reason, lemmas: lemmasNamed(reason) });
+        }
+    }
+    return rows;
+}
+
+/** Summarise the population against the gate's vocabulary. */
+export function report(rows: readonly ExemptionRow[]): ShapeReport {
+    const byLemma: Record<string, number> = {};
+    for (const l of DISPOSITION_LEMMAS) {
+        byLemma[l.name] = rows.filter((r) => r.lemmas.includes(l.name)).length;
+    }
+    const groups = new Map<string, string[]>();
+    for (const r of rows) {
+        const key = reasonKey(r.reason);
+        const list = groups.get(key) ?? [];
+        list.push(r.file);
+        groups.set(key, list);
+    }
+    const duplicates = [...groups.values()].filter((g) => g.length > 1).sort((a, b) => b.length - a.length);
+    return {
+        rows,
+        shaped: rows.filter((r) => namesDisposition(r.reason)).length,
+        shapeless: rows.filter((r) => !namesDisposition(r.reason)).length,
+        byLemma,
+        duplicates,
+    };
+}
+
+function render(rep: ShapeReport): string {
+    const out: string[] = [];
+    const total = rep.rows.length;
+    out.push(`${_PROG}: ${String(total)} exemption(s)`);
+    for (const tree of TREES) {
+        out.push(`  ${tree.label.padEnd(10)} ${String(rep.rows.filter((r) => r.tree === tree.label).length).padStart(4)}`);
+    }
+    out.push(`  names a rejected alternative  ${String(rep.shaped).padStart(4)}`);
+    out.push(`  names none                    ${String(rep.shapeless).padStart(4)}`);
+    out.push('  per lemma:');
+    for (const l of DISPOSITION_LEMMAS) {
+        out.push(`    ${l.name.padEnd(12)} ${String(rep.byLemma[l.name] ?? 0).padStart(4)}`);
+    }
+    const dupFiles = rep.duplicates.reduce((n, g) => n + g.length, 0);
+    out.push(`  verbatim duplicate groups     ${String(rep.duplicates.length).padStart(4)} covering ${String(dupFiles)} file(s)`);
+    for (const g of rep.duplicates) {
+        out.push(`    (${String(g.length)}x) ${g.join(', ')}`);
+    }
+    if (rep.shapeless > 0) {
+        out.push('  naming no rejected alternative:');
+        for (const r of rep.rows.filter((x) => !namesDisposition(x.reason))) {
+            out.push(`    ${r.file}: ${r.reason.slice(0, 120)}`);
+        }
+    }
+    return out.join('\n') + '\n';
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const json = argv.includes('--json');
+    const rootIdx = argv.indexOf('--root');
+    let root = REPO_ROOT;
+    if (rootIdx !== -1) {
+        const next = argv[rootIdx + 1];
+        if (next === undefined || next.startsWith('-')) {
+            process.stderr.write(`usage: ${_PROG} [--root <dir>] [--json]\n`);
+            return 2;
+        }
+        root = path.resolve(next);
+    }
+    const unknown = argv.filter((a) => a.startsWith('-') && a !== '--json' && a !== '--root');
+    if (unknown.length > 0) {
+        process.stderr.write(`${_PROG}: unknown argument(s) ${unknown.join(', ')}\n`);
+        return 2;
+    }
+
+    const rows = collectExemptions(root);
+    try {
+        // A root holding no roadmap at all is a dead scope, never an estate with
+        // nothing to report: this reader would otherwise print a confident zero
+        // over a path that does not exist.
+        assertScanned({
+            gate: _PROG,
+            scanned: TREES.reduce((n, t) => {
+                try {
+                    return n + fs.readdirSync(path.join(root, t.dir)).filter((f) => f.endsWith('.md')).length;
+                } catch {
+                    return n;
+                }
+            }, 0),
+            units: 'roadmap file(s)',
+            roots: TREES.map((t) => t.dir),
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${_PROG}: ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
+
+    const rep = report(rows);
+    if (json) {
+        process.stdout.write(JSON.stringify(rep, null, 2) + '\n');
+        return 0;
+    }
+    process.stdout.write(render(rep));
+    return 0;
+}
+
+if (path.resolve(process.argv[1] ?? '') === _HERE) {
+    process.exit(main());
+}

package/src/scripts/generate_host_cost_table.ts

@@ -63,7 +63,7 @@ import {
 const _HERE = fileURLToPath(import.meta.url);
 export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
-/** The contract the README points at for projection modes (README.md:288). */
+/** The contract the README points at for projection modes. */
 export const CONTRACT_REL = path.join('docs', 'contracts', 'rule-router.md');
 
 export const BEGIN = '<!-- BEGIN generated: host-standing-cost -->';