@event4u/agent-config 8.5.0 → 8.7.0

package/src/install/emit_host_rules_cli.ts

@@ -0,0 +1,190 @@
+#!/usr/bin/env tsx
+/**
+ * Consumer host-native rule emission
+ * (road-to-request-scoped-rule-load Phase 1b Step 3).
+ *
+ * Before this CLI, consumer Cursor got a symlink farm to raw `.md` (no
+ * `.mdc`, no auto-attach globs) and consumer `.windsurfrules` was built by
+ * a bash concatenator that STRIPPED all frontmatter — destroying the
+ * host-native trigger signal Phase 2 added to the projection path.
+ *
+ * ## Recorded decision — install-time emission, not dist artifacts
+ *
+ * Phase 1b Step 3 asked for one recorded choice: pre-built host artifacts
+ * in `dist/` vs emission at install time. Decision: INSTALL-TIME EMISSION,
+ * re-using the exported condense emitters (`_emit_cursor_mdc`,
+ * `_emit_windsurf_rule`, `strip_frontmatter`) verbatim. Rationale:
+ *   - a new `dist/agent-src/hosts/` tree would cascade through the
+ *     discovery manifest, artefact checksums, condensation hashes and the
+ *     always-budget gates for what is derived data;
+ *   - dist artifacts are scope-agnostic — install-time emission runs AFTER
+ *     the Phase-1b rule filter, so scoped installs get scoped host files
+ *     for free;
+ *   - re-using the exported emitters keeps consumer output byte-identical
+ *     to the maintainer projection (Pipeline B never drifts from A).
+ * The trade-off (node required at install time) matches the rule-scope
+ * resolver: no node → install.sh keeps its legacy fallback surfaces.
+ *
+ * Usage:
+ *   emit_host_rules_cli.ts --rules-dir <installed rules dir>
+ *                          --project-root <consumer root>
+ *                          --tools cursor,windsurf
+ *
+ * Exit codes: 0 emitted · 2 usage error · 1 emission failure (caller falls
+ * back to the legacy surface).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    _emit_cursor_mdc,
+    _emit_windsurf_rule,
+    strip_frontmatter,
+} from '../scripts/condense.js';
+
+function _ruleFiles(rulesDir: string): string[] {
+    return fs
+        .readdirSync(rulesDir)
+        .filter((n) => n.endsWith('.md'))
+        .sort()
+        .map((n) => path.join(rulesDir, n))
+        .filter((p) => {
+            try {
+                return fs.statSync(p).isFile();
+            } catch {
+                return false;
+            }
+        });
+}
+
+/** Remove entries not in `valid` (mirror of condense's `_clean_modern_dir`). */
+function _cleanDir(dir: string, valid: ReadonlySet<string>): void {
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(dir);
+    } catch {
+        return;
+    }
+    for (const name of entries) {
+        if (name === 'README.md' || valid.has(name)) {
+            continue;
+        }
+        const full = path.join(dir, name);
+        try {
+            if (fs.lstatSync(full).isDirectory()) {
+                fs.rmSync(full, { recursive: true, force: true });
+            } else {
+                fs.unlinkSync(full);
+            }
+        } catch {
+            /* best-effort clean */
+        }
+    }
+}
+
+export function emitCursor(rulesDir: string, projectRoot: string): number {
+    const targetDir = path.join(projectRoot, '.cursor', 'rules');
+    const files = _ruleFiles(rulesDir);
+    const valid = new Set<string>();
+    for (const src of files) {
+        const name = `${path.basename(src, '.md')}.mdc`;
+        _emit_cursor_mdc(src, path.join(targetDir, name));
+        valid.add(name);
+    }
+    _cleanDir(targetDir, valid);
+    return files.length;
+}
+
+export function emitWindsurf(rulesDir: string, projectRoot: string): number {
+    const perRuleDir = path.join(projectRoot, '.windsurf', 'rules');
+    const files = _ruleFiles(rulesDir);
+    const valid = new Set<string>();
+    for (const src of files) {
+        const name = path.basename(src);
+        _emit_windsurf_rule(src, path.join(perRuleDir, name));
+        valid.add(name);
+    }
+    _cleanDir(perRuleDir, valid);
+
+    // Concatenated legacy surface — same format as the projection-path
+    // generator (condense.generate_windsurfrules), consumer-sourced header.
+    const parts = ['# Auto-generated from .augment/rules/ — do not edit directly\n'];
+    for (const src of files) {
+        const content = strip_frontmatter(fs.readFileSync(src, 'utf-8'));
+        parts.push(`---\n\n${content.trim()}\n`);
+    }
+    fs.writeFileSync(path.join(projectRoot, '.windsurfrules'), parts.join('\n') + '\n', 'utf-8');
+    return files.length;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    let rulesDir = '';
+    let projectRoot = '';
+    let tools: string[] = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--rules-dir') {
+            rulesDir = argv[i + 1] ?? '';
+            i += 1;
+        } else if (arg === '--project-root') {
+            projectRoot = argv[i + 1] ?? '';
+            i += 1;
+        } else if (arg === '--tools') {
+            tools = (argv[i + 1] ?? '').split(',').filter((t) => t.length > 0);
+            i += 1;
+        } else {
+            process.stderr.write(`emit_host_rules_cli: unknown argument: ${arg}\n`);
+            return 2;
+        }
+    }
+    if (rulesDir === '' || projectRoot === '' || tools.length === 0) {
+        process.stderr.write(
+            'usage: emit_host_rules_cli.ts --rules-dir <dir> --project-root <dir> --tools cursor,windsurf\n',
+        );
+        return 2;
+    }
+    if (!fs.existsSync(rulesDir)) {
+        process.stderr.write(`emit_host_rules_cli: rules dir not found: ${rulesDir}\n`);
+        return 1;
+    }
+    try {
+        for (const tool of tools) {
+            if (tool === 'cursor') {
+                const n = emitCursor(rulesDir, path.resolve(projectRoot));
+                process.stdout.write(`cursor: ${n} .mdc rule(s)\n`);
+            } else if (tool === 'windsurf') {
+                const n = emitWindsurf(rulesDir, path.resolve(projectRoot));
+                process.stdout.write(`windsurf: ${n} rule(s) + .windsurfrules\n`);
+            } else {
+                process.stderr.write(`emit_host_rules_cli: unknown tool: ${tool}\n`);
+                return 2;
+            }
+        }
+        return 0;
+    } catch (e) {
+        process.stderr.write(
+            `emit_host_rules_cli: emission failed: ${e instanceof Error ? e.message : String(e)}\n`,
+        );
+        return 1;
+    }
+}
+
+function _isCliEntry(): boolean {
+    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.exit(main());
+}

package/src/install/plan.ts

@@ -46,6 +46,13 @@ export interface PlanSource {
     readonly destDir: string;
     /** Kind recorded on every {@link FileEntry} produced from this source. */
     readonly kind: FileKind;
+    /**
+     * Optional per-file predicate (absolute source path → include?).
+     * Files rejected here never enter the plan — the rule-scoping filter
+     * for `rules` sources (road-to-request-scoped-rule-load Phase 1b).
+     * Absent = include everything (legacy behaviour).
+     */
+    readonly fileFilter?: (srcFile: string) => boolean;
 }
 
 /** Inputs the planner needs to walk source trees and produce an {@link InstallPlan}. */
@@ -147,7 +154,10 @@ export function buildInstallPlan(inputs: PlanInputs): InstallPlan {
 
     for (const source of inputs.sources) {
         const bucket = filesByTool[source.toolId] ?? [];
-        const files = walkSourceTree(source.srcDir);
+        let files = walkSourceTree(source.srcDir);
+        if (source.fileFilter !== undefined) {
+            files = files.filter(source.fileFilter);
+        }
         for (const srcFile of files) {
             const rel = relative(source.srcDir, srcFile);
             const destPath = resolve(source.destDir, rel);

package/src/install/rule_scope.ts

@@ -0,0 +1,120 @@
+/**
+ * Install-time rule scoping — Pipeline B of consumer-scoped rule projection
+ * (road-to-request-scoped-rule-load Phase 1b).
+ *
+ * The projection filter (`rule_in_scope`, condense.ts) covered only the
+ * maintainer projection; the consumer install pipeline shipped rules
+ * unfiltered (dead `EXCLUDE_RULES` in install.sh; no exclude at all on the
+ * global payload). This module is the ONE scoping surface both install
+ * paths consume — it deliberately re-uses `rule_in_scope` so the install
+ * semantics can never drift from the projection semantics.
+ *
+ * ## The `source-of-truth.md` decision (Phase 1b Step 2 — recorded here)
+ *
+ * Before this module, `install.sh` excluded `source-of-truth.md` from
+ * PROJECT installs (hardcoded name) while the GLOBAL payload shipped it —
+ * the documented contradiction. Decision: the rule is excluded from BOTH
+ * consumer paths, always (even under legacy-all). Rationale: its Iron Law
+ * ("NEVER EDIT ANY GENERATED PROJECTION … ALWAYS WORK IN src/") describes
+ * THIS repository's build layout; in a consumer project there is no `src/`
+ * authoring tree and the installed files ARE the working surface — the rule
+ * is not merely useless there, it actively forbids legitimate consumer
+ * edits. Shipping it globally was the bug; project installs had it right.
+ * The compat list below is the pre-flip carrier of that decision; once the
+ * Phase-1 human gate flips consumer defaults to scoped, the rule drops out
+ * via its maintainer-only workspace tag and this list can retire.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { rule_in_scope } from '../scripts/condense.js';
+
+/**
+ * Rules excluded from EVERY consumer install path regardless of scope —
+ * same treatment on project and global (see module doc for the decision).
+ */
+export const COMPAT_ALWAYS_EXCLUDED: readonly string[] = ['source-of-truth.md'];
+
+/** Workspace/pack scope read from consumer settings. `null` axis = unset. */
+export interface RuleScope {
+    readonly workspaces: readonly string[] | null;
+    readonly packs: readonly string[] | null;
+}
+
+export const LEGACY_ALL: RuleScope = { workspaces: null, packs: null };
+
+/** Non-empty string-array extraction; anything else → null (legacy-all). */
+function _list(value: unknown): readonly string[] | null {
+    if (Array.isArray(value) && value.length > 0) {
+        return value.map((v) => String(v));
+    }
+    return null;
+}
+
+/**
+ * Extract `projection.rule_workspaces` / `projection.rule_packs` from an
+ * already-parsed settings object (same key contract as condense's
+ * `_read_projection_list` — absent / empty = legacy-all).
+ */
+export function ruleScopeFromSettings(settings: Record<string, unknown>): RuleScope {
+    const proj = settings['projection'];
+    if (typeof proj !== 'object' || proj === null || Array.isArray(proj)) {
+        return LEGACY_ALL;
+    }
+    const p = proj as Record<string, unknown>;
+    return {
+        workspaces: _list(p['rule_workspaces']),
+        packs: _list(p['rule_packs']),
+    };
+}
+
+/**
+ * Whether a rule FILE (path into the shipped `dist/agent-src/rules` tree)
+ * arrives in a consumer install under `scope`.
+ *
+ * Delegates the scoping decision to the projection-path predicate
+ * (`rule_in_scope` — kernel always ships, untagged axes fail safe) and adds
+ * the compat exclusion on top. Non-rule files (non-`.md`) always arrive.
+ */
+export function ruleFileArrives(sourcePath: string, scope: RuleScope): boolean {
+    if (!sourcePath.endsWith('.md')) {
+        return true;
+    }
+    const basename = path.basename(sourcePath);
+    if (COMPAT_ALWAYS_EXCLUDED.includes(basename)) {
+        return false;
+    }
+    return rule_in_scope(sourcePath, scope.workspaces, scope.packs);
+}
+
+/**
+ * Basenames from `rulesDir` that are EXCLUDED under `scope` — the shape the
+ * bash installer consumes (one basename per line via the CLI below).
+ */
+export function excludedRuleBasenames(rulesDir: string, scope: RuleScope): string[] {
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(rulesDir).sort();
+    } catch {
+        return [];
+    }
+    const out: string[] = [];
+    for (const name of entries) {
+        if (!name.endsWith('.md')) {
+            continue;
+        }
+        const full = path.join(rulesDir, name);
+        try {
+            if (!fs.statSync(full).isFile()) {
+                continue;
+            }
+        } catch {
+            continue;
+        }
+        if (!ruleFileArrives(full, scope)) {
+            out.push(name);
+        }
+    }
+    return out;
+}

package/src/install/rule_scope_cli.ts

@@ -0,0 +1,79 @@
+#!/usr/bin/env tsx
+/**
+ * CLI twin surface of {@link module:install/rule_scope} for the bash
+ * installer (road-to-request-scoped-rule-load Phase 1b).
+ *
+ * Prints one EXCLUDED rule basename per line for the given rules source
+ * dir + consumer settings file. `install.sh` consumes this to replace its
+ * dead hardcoded `EXCLUDE_RULES` list; on any failure the caller falls back
+ * to the static compat exclusion (fail-safe: over-ship, never under-ship).
+ *
+ * Usage:
+ *   rule_scope_cli.ts --rules-dir <dist/agent-src/rules> [--settings <file>]
+ *
+ * Exit codes: 0 ok (list on stdout, possibly empty) · 2 usage error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { load_agent_settings } from '../scripts/_lib/agent_settings.js';
+
+import { excludedRuleBasenames, ruleScopeFromSettings, LEGACY_ALL } from './rule_scope.js';
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    let rulesDir = '';
+    let settingsFile = '';
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--rules-dir') {
+            rulesDir = argv[i + 1] ?? '';
+            i += 1;
+        } else if (arg === '--settings') {
+            settingsFile = argv[i + 1] ?? '';
+            i += 1;
+        } else {
+            process.stderr.write(`rule_scope_cli: unknown argument: ${arg}\n`);
+            return 2;
+        }
+    }
+    if (rulesDir === '') {
+        process.stderr.write('usage: rule_scope_cli.ts --rules-dir <dir> [--settings <file>]\n');
+        return 2;
+    }
+
+    let scope = LEGACY_ALL;
+    if (settingsFile !== '' && fs.existsSync(settingsFile)) {
+        try {
+            const settings = load_agent_settings({ project_path: settingsFile });
+            scope = ruleScopeFromSettings(settings as Record<string, unknown>);
+        } catch {
+            // Unreadable settings → legacy-all (fail-safe: over-ship).
+            scope = LEGACY_ALL;
+        }
+    }
+
+    for (const name of excludedRuleBasenames(path.resolve(rulesDir), scope)) {
+        process.stdout.write(`${name}\n`);
+    }
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    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.exit(main());
+}

package/src/install/wizard-plan.ts

@@ -23,6 +23,7 @@ import { isAbsolute, join, resolve } from 'node:path';
 
 import type { ConflictPolicy, InstallPlan, InstallTarget } from './types.js';
 import { buildInstallPlan, type PlanSource } from './plan.js';
+import { ruleFileArrives, LEGACY_ALL, type RuleScope } from './rule_scope.js';
 
 /**
  * Per-tool user-scope anchor directory, mirrored 1:1 from
@@ -152,6 +153,14 @@ export interface WizardExpandInputs {
     readonly packageRoot: string;
     /** Override for the user's home directory (tests only). */
     readonly home?: string;
+    /**
+     * Workspace/pack scope applied to `rules` sources
+     * (road-to-request-scoped-rule-load Phase 1b). Absent = LEGACY_ALL,
+     * which still applies the compat exclusion (`source-of-truth.md`) so
+     * the global path finally matches the project path — the recorded
+     * decision in `rule_scope.ts`.
+     */
+    readonly ruleScope?: RuleScope;
 }
 
 /**
@@ -172,6 +181,8 @@ export interface WizardExpandInputs {
  */
 export function expandWizardSources(inputs: WizardExpandInputs): PlanSource[] {
     const { toolIds, packageRoot, home } = inputs;
+    const scope = inputs.ruleScope ?? LEGACY_ALL;
+    const ruleFilter = (srcFile: string): boolean => ruleFileArrives(srcFile, scope);
     const out: PlanSource[] = [];
     for (const toolId of toolIds) {
         const deploy = GLOBAL_DEPLOY_SOURCES[toolId];
@@ -181,7 +192,17 @@ export function expandWizardSources(inputs: WizardExpandInputs): PlanSource[] {
         for (const [srcRel, destSub] of deploy) {
             const srcDir = join(packageRoot, srcRel);
             const destDir = destSub.length === 0 ? destRoot : join(destRoot, destSub);
-            out.push({ toolId, srcDir, destDir, kind: 'deployed' });
+            // Rule sources get the install-time scoping filter — the same
+            // predicate the projection path uses (Phase 1b: Pipeline B may
+            // never drift from Pipeline A).
+            const isRuleSource = srcRel === 'dist/agent-src/rules';
+            out.push({
+                toolId,
+                srcDir,
+                destDir,
+                kind: 'deployed',
+                ...(isRuleSource ? { fileFilter: ruleFilter } : {}),
+            });
         }
     }
     return out;

package/src/scripts/_lib/auto_dispatch.ts

@@ -93,3 +93,66 @@ export function classifyTask(signals: TaskSignals, activation: ActivationInputs)
     const action: DispatchAction = activation.auto === 'on' ? 'dispatch' : 'ask';
     return { delegable: true, action, mode, reason };
 }
+
+// ── Per-slice tier inference (v1.5 — road-to-cost-aware-model-routing) ──
+
+/**
+ * Task-TYPE outputs the tier inference keys on. NEVER raw size metrics —
+ * size enters only as the negative guard below. Contract:
+ * `auto-dispatch-classification.md § Per-slice tier inference`.
+ */
+export type SliceType =
+    | 'read-only-fanout' // grep / inventory / discovery targets
+    | 'mechanical-covered' // template-driven transform WITH test coverage
+    | 'mutating-uncovered' // mutation without test coverage
+    | 'synthesis' // review / analysis / judgment slice
+    | 'unknown';
+
+export interface SliceTierSignals {
+    slice_type: SliceType;
+    /**
+     * Negative size guard: slice scope exceeds the mechanical envelope
+     * (multi-file mutation / beyond single responsibility). Revokes a `lite`
+     * candidacy — never creates one.
+     */
+    exceeds_mechanical_envelope?: boolean;
+}
+
+export type InferredTier = 'lite' | 'medium' | 'inherit';
+
+export interface TierInference {
+    tier: InferredTier;
+    /** 'inferred' for a real downshift decision; 'inherit' when no inference fired. */
+    tier_source: 'inferred' | 'inherit';
+    reason: string;
+}
+
+/**
+ * Infer a delegable slice's model tier from its task TYPE. Deterministic,
+ * no LLM meta-call. Unknown/ambiguous → inherit (session tier) — never
+ * guess down.
+ */
+export function inferSliceTier(signals: SliceTierSignals): TierInference {
+    const guard = signals.exceeds_mechanical_envelope === true;
+
+    switch (signals.slice_type) {
+        case 'read-only-fanout':
+        case 'mechanical-covered': {
+            if (guard) {
+                return {
+                    tier: 'medium',
+                    tier_source: 'inferred',
+                    reason: `${signals.slice_type} slice, but scope exceeds the mechanical envelope — lite candidacy revoked`,
+                };
+            }
+            const cascade = signals.slice_type === 'mechanical-covered' ? ' (verify-fail escalates to medium)' : '';
+            return { tier: 'lite', tier_source: 'inferred', reason: `${signals.slice_type} slice${cascade}` };
+        }
+        case 'mutating-uncovered':
+            return { tier: 'medium', tier_source: 'inferred', reason: 'mutating slice without test coverage' };
+        case 'synthesis':
+            return { tier: 'medium', tier_source: 'inferred', reason: 'synthesis/judgment slice — judge one tier up' };
+        default:
+            return { tier: 'inherit', tier_source: 'inherit', reason: 'unknown/ambiguous slice type — session tier, never guess down' };
+    }
+}

package/src/scripts/_lib/subagent_routing.ts

@@ -18,6 +18,16 @@
 export type Tier = 'lite' | 'medium' | 'high' | 'inherit';
 export type QuotaPool = 'separate' | 'shared';
 
+/**
+ * Where a resolved tier came from (road-to-cost-aware-model-routing Phase 0):
+ * - 'static'   — declared by frontmatter / category pin,
+ * - 'inferred' — produced by the deterministic per-slice tier inference,
+ * - 'inherit'  — session tier; no downshift decision was made.
+ * Mirrors the `tier_source` telemetry field in
+ * `src/agent-src/contexts/execution/orchestration-telemetry.md`.
+ */
+export type TierSource = 'static' | 'inferred' | 'inherit';
+
 /** Per-tier model alias overrides (empty string = use the tier's runtime default). */
 export interface ModelMap {
     lite?: string;
@@ -35,6 +45,12 @@ export interface RoutingInputs {
     model_map: ModelMap;
     /** From the host-capability manifest. */
     separate_quota_pool: boolean;
+    /**
+     * How `task_tier` was produced: 'static' (frontmatter/category pin) or
+     * 'inferred' (deterministic per-slice inference). Optional — absent
+     * defaults to 'static'. Ignored when the slice runs on the session tier.
+     */
+    task_tier_origin?: Exclude<TierSource, 'inherit'>;
 }
 
 export interface RoutingDecision {
@@ -44,6 +60,8 @@ export interface RoutingDecision {
     model: string;
     /** Whether a separate quota pool is used (bonus) or the shared one. */
     quota_pool: QuotaPool;
+    /** Telemetry value for `tier_source`: 'inherit' when no downshift decision applied. */
+    tier_source: TierSource;
     reason: string;
 }
 
@@ -64,6 +82,11 @@ export function resolveSubagentRouting(inp: RoutingInputs): RoutingDecision {
     const tier: Tier = !inp.downshift || inp.task_tier === 'inherit' ? inp.session_tier : inp.task_tier;
     const downshifted = inp.downshift && inp.task_tier !== 'inherit' && tier !== inp.session_tier;
 
+    // Telemetry provenance: only a real downshift decision carries its origin;
+    // session-tier runs (inherit task, downshift off, or tier == session) are 'inherit'.
+    const applied = inp.downshift && inp.task_tier !== 'inherit';
+    const tier_source: TierSource = applied ? (inp.task_tier_origin ?? 'static') : 'inherit';
+
     // Quota arbitrage: a bonus, only when BOTH the setting and the host allow it.
     const useSeparate = inp.quota_arbitrage && inp.separate_quota_pool;
     const quota_pool: QuotaPool = useSeparate ? 'separate' : 'shared';
@@ -76,6 +99,7 @@ export function resolveSubagentRouting(inp: RoutingInputs): RoutingDecision {
         tier,
         model: modelForTier(tier, inp.model_map),
         quota_pool,
+        tier_source,
         reason: reasonParts.join(' · '),
     };
 }