@event4u/agent-config 8.6.0 → 8.8.0

package/src/config/agent-settings.template.yml

@@ -64,12 +64,14 @@ projection:
   #   rule_workspaces: [engineering]
   # Default flip to a scoped value is a human release gate — see
   # agents/settings/contexts/consumer-scoping-audit-2026-07-07.md.
-  # rule_workspaces: []
+  # An EMPTY list is inactive (= legacy-all); only a non-empty list scopes.
+  rule_workspaces: []
   #
   # Optional second axis, same semantics per pack ids (packs.yml). When set,
   # a non-kernel rule also needs a `packs:` intersection to project — e.g.
   # deselecting `frontend-design` removes ui-audit-gate + design-fidelity.
-  # rule_packs: []
+  # Empty = inactive, same as rule_workspaces.
+  rule_packs: []
 
 # --- Discipline profile (successor knob, opt-in until the evidence gates pass) ---
 #
@@ -522,13 +524,21 @@ subagents:
   # on  = auto-dispatch delegable tasks without asking (surface the choice
   #       in one line).
   #
-  # Initial SHIPPED default is `ask` on hosts whose capability manifest reports
+  # SHIPPED default is `on` on hosts whose capability manifest reports
   # `subagent_spawn: true`, and `off` on hosts without a subagent primitive.
-  # The shipped default flips toward `on` (host-gated) only behind the Phase-6
-  # benchmark gate of road-to-auto-subagent-orchestration.md — never on an
-  # unmeasured claim. Auto-dispatch is also a no-op wherever the host manifest
-  # reports `subagent_spawn: false`, regardless of this value.
-  auto: ask
+  # Auto-dispatch stays a no-op wherever the manifest reports
+  # `subagent_spawn: false`, regardless of this value.
+  #
+  # The default was `ask` until 2026-07-09, when it was flipped to `on` after a
+  # re-evaluation (agents/settings/contexts/orchestration-default-flip-verdict.md
+  # § 2026-07-09; ADR-117). The flip rests on a bounded-downside argument, NOT a
+  # passed benchmark: delegable slices are already cost-routed to the cheapest
+  # capable tier, classification fires only on real structural signals (never
+  # unstructured or tiny work), and every return is verified — so `on` cannot
+  # delegate frontier-priced or speculative work. `resolveShippedDefault()`
+  # remains the telemetry-driven DEMOTION gate: a measured regression demotes
+  # back to `ask`.
+  auto: on
 
   # Route delegable sub-tasks to the lowest-capable model tier (cost + speed
   # via model downshift). true (default) = downshift per declared model_tier;
@@ -693,6 +703,17 @@ memory:
   # Example: ["api[_-]?key", "/Users/[a-z]+/Library"]
   redact_patterns: []
 
+  # Opt-in compact memory index at session start
+  # (road-to-memory-retrieval-economy Phase 5). When `on`, session_start
+  # injects a compact index of curated entries — id + title + ~tokens,
+  # hard cap 30 rows — through the hot-context hook surface. Bodies are
+  # never injected; the model fetches full entries via memory_get on
+  # demand. Default OFF: the ship-criterion (measured hit-rate gain at
+  # bounded fixed cost) is unproven — off unless proven.
+  #   off = (default) no session-start index.
+  #   on  = inject the compact index (spotlighted as DATA).
+  session_index: "off"
+
 # --- Knowledge cards: global cross-project sharing (ADR-100) ---
 #
 # Structure-grounding v2. Promote *expensive* (remote) knowledge cards from

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/orchestration_gate.ts

@@ -1,15 +1,19 @@
 /**
- * Default-flip decision gate (Phase 6).
+ * Default-flip / demotion decision gate (Phase 6 → telemetry-demotion).
  *
- * Pure, no-I/O. Encodes the Phase-6 falsification gate: the SHIPPED default for
- * `subagents.auto` flips toward `on` ONLY when a real benchmark shows a net
- * token-or-time win at held quality, and only on hosts with a subagent
- * primitive. Honest-null exit (no win, or quality regressed) keeps the
- * conservative default. Contract:
+ * Pure, no-I/O. Originally the Phase-6 falsification gate: the SHIPPED default
+ * for `subagents.auto` was to flip toward `on` ONLY on a passed benchmark.
+ *
+ * As of 2026-07-09 the shipped default IS `on` on subagent-capable hosts
+ * (ADR-117; agents/settings/contexts/orchestration-default-flip-verdict.md
+ * § 2026-07-09) — flipped on a bounded-downside re-evaluation, not a passed
+ * benchmark. This helper is therefore now the telemetry-driven DEMOTION gate:
+ * a `fail` verdict from accumulated real-world orchestration telemetry demotes
+ * the default back to `ask` (conservative). Contract:
  * `src/agent-src/contexts/execution/orchestration-benchmark-gate.md`.
  *
- * This helper decides; it never runs the benchmark. The measurement is the
- * empirical bench:ab step, authorised + run out of band.
+ * This helper decides; it never runs the measurement. The signal is realized
+ * orchestration telemetry, aggregated + evaluated out of band.
  */
 
 export interface BenchmarkResult {