@event4u/agent-config 7.5.0 → 8.0.0

package/src/scripts/condense.ts

@@ -250,6 +250,8 @@ interface ModuleState {
     PERSONAS_SOURCE: string;
     USER_TYPES_SOURCE: string;
     CLAUDE_SKILLS_DIR: string;
+    CLAUDE_AGENTS_DIR: string;
+    SUBAGENTS_SOURCE: string;
     PLUGIN_SKILLS_DIR: string;
     // Injectable multi-root helpers (monkeypatch seam).
     iter_all_sources: () => Iterable<[string, string]>;
@@ -271,6 +273,12 @@ function _deriveState(root: string): ModuleState {
         PERSONAS_SOURCE: path.join(root, 'dist/agent-src', 'personas'),
         USER_TYPES_SOURCE: path.join(root, 'dist/agent-src', 'user-types'),
         CLAUDE_SKILLS_DIR: path.join(root, '.claude', 'skills'),
+        // ADR-109: subagents project from src/ directly (NOT dist/) — a subagent
+        // is an executable system prompt Claude Code runs verbatim; telegraph
+        // condensation would alter its behaviour, and it is not routed through the
+        // pack/discovery condensation flow.
+        CLAUDE_AGENTS_DIR: path.join(root, '.claude', 'agents'),
+        SUBAGENTS_SOURCE: path.join(root, 'src', 'subagents'),
         PLUGIN_SKILLS_DIR: path.join(root, '.claude-plugin', 'skills'),
         iter_all_sources: _agent_src_iter_all_sources,
         resolve_logical: _agent_src_resolve_logical,
@@ -922,11 +930,84 @@ export function _rewrite_paths(content: string, source_relative_path: string): s
 // Expose the HRR marker for tests (mirrors condense._HRR_BANNER_MARKER access).
 export { _HRR_BANNER_MARKER };
 
-export function generate_rule_symlinks(): number {
-    const rules = _iterdirSorted(MODULE_STATE.RULES_SOURCE)
+// ── Consumer-scoped rule projection (road-to-request-scoped-rule-load P1) ──
+//
+// Opt-in via `projection.rule_workspaces: [<workspace-id>, …]` in
+// `.agent-settings.yml`. Absent / empty = legacy-all (every rule projects —
+// today's behaviour, non-breaking). When set, a non-kernel rule projects
+// only if its `workspaces:` frontmatter intersects the configured set.
+// Kernel rules (`type: always` / `alwaysApply: true`) ALWAYS project —
+// the kernel is unconditional and workspace-independent by definition
+// (rule-router contract § Schema v2). Untagged rules fail safe: they ship.
+// ADR-040: projection-time filtering only, no runtime resolver.
+
+function _read_projection_list(key: string): string[] | null {
+    const data = load_agent_settings({ project_path: MODULE_STATE.SETTINGS_FILE });
+    const proj = data['projection'];
+    const value =
+        typeof proj === 'object' && proj !== null && !Array.isArray(proj)
+            ? (proj as Record<string, unknown>)[key]
+            : null;
+    if (Array.isArray(value) && value.length > 0) {
+        return value.map((v) => String(v));
+    }
+    return null;
+}
+
+function _read_rule_workspaces(): string[] | null {
+    return _read_projection_list('rule_workspaces');
+}
+
+function _read_rule_packs(): string[] | null {
+    return _read_projection_list('rule_packs');
+}
+
+/**
+ * Whether a rule source file projects under the given workspace + pack
+ * scopes. Both scopes are independent constraints: when configured, the
+ * rule's frontmatter list must intersect (installed workspaces AND
+ * installed packs). Kernel always projects; untagged axes fail safe.
+ */
+export function rule_in_scope(
+    source_path: string,
+    scope: readonly string[] | null,
+    pack_scope: readonly string[] | null = null,
+): boolean {
+    if (scope === null && pack_scope === null) {
+        return true;
+    }
+    const [meta] = _parse_frontmatter(_readText(source_path));
+    if (meta['type'] === 'always' || meta['alwaysApply'] === true) {
+        return true; // kernel always projects
+    }
+    const axis = (key: string, configured: readonly string[] | null): boolean => {
+        if (configured === null) {
+            return true;
+        }
+        const values = Array.isArray(meta[key])
+            ? (meta[key] as unknown[]).map((w) => String(w))
+            : [];
+        if (values.length === 0) {
+            return true; // untagged → fail safe: ship it
+        }
+        return values.some((v) => configured.includes(v));
+    };
+    return axis('workspaces', scope) && axis('packs', pack_scope);
+}
+
+/** List rule basenames under RULES_SOURCE, workspace/pack scope applied. */
+function _scoped_rule_basenames(): string[] {
+    const scope = _read_rule_workspaces();
+    const pack_scope = _read_rule_packs();
+    return _iterdirSorted(MODULE_STATE.RULES_SOURCE)
         .filter((p) => p.endsWith('.md') && _isFile(p))
+        .filter((p) => rule_in_scope(p, scope, pack_scope))
         .map((p) => path.basename(p))
         .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+export function generate_rule_symlinks(): number {
+    const rules = _scoped_rule_basenames();
     const tool_dirs = _filter_tool_dirs(TOOL_DIRS);
 
     let thin_files: Record<string, string> | null = null;
@@ -980,10 +1061,7 @@ export function generate_rule_symlinks(): number {
 }
 
 export function generate_windsurfrules(): number {
-    const rules = _iterdirSorted(MODULE_STATE.RULES_SOURCE)
-        .filter((p) => p.endsWith('.md') && _isFile(p))
-        .map((p) => path.basename(p))
-        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const 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);
@@ -1036,14 +1114,44 @@ function _yaml_scalar(value: string): string {
     return JSON.stringify(value);
 }
 
-function _emit_cursor_mdc(source: string, target: string): void {
+/**
+ * Derive host-native activation globs from a rule's `triggers:` frontmatter
+ * (road-to-request-scoped-rule-load Phase 2). `file_pattern` triggers map
+ * verbatim; `path_prefix` triggers map to `<prefix>**`. Keyword / phrase /
+ * intent / command triggers produce no glob — those rules stay
+ * description-activated (Cursor Agent-Requested / Windsurf model_decision).
+ */
+export function derive_trigger_globs(meta: Record<string, unknown>): string[] {
+    const triggers = meta['triggers'];
+    if (!Array.isArray(triggers)) {
+        return [];
+    }
+    const globs: string[] = [];
+    for (const t of triggers) {
+        if (t === null || typeof t !== 'object' || Array.isArray(t)) continue;
+        const obj = t as Record<string, unknown>;
+        if (typeof obj['file_pattern'] === 'string' && obj['file_pattern']) {
+            globs.push(obj['file_pattern']);
+        } else if (typeof obj['path_prefix'] === 'string' && obj['path_prefix']) {
+            const prefix = obj['path_prefix'] as string;
+            globs.push(prefix.endsWith('/') ? `${prefix}**` : `${prefix}**`);
+        }
+    }
+    // De-dup, keep declaration order (deterministic output).
+    return [...new Set(globs)];
+}
+
+export function _emit_cursor_mdc(source: string, target: string): void {
     const [meta, body] = _parse_frontmatter(_readText(source));
     const description = _strip(String(meta['description'] ?? '').replace(/\n/g, ' '));
     const always_apply = Boolean(meta['alwaysApply'] || meta['type'] === 'always');
+    // Path-shaped triggers become Cursor auto-attach globs; rules without
+    // them keep `globs: ` empty and stay Agent-Requested via description.
+    const globs = always_apply ? [] : derive_trigger_globs(meta);
     const lines = [
         '---',
         `description: ${_yaml_scalar(description)}`,
-        'globs: ',
+        `globs: ${globs.join(',')}`,
         `alwaysApply: ${always_apply ? 'true' : 'false'}`,
         '---',
         '',
@@ -1053,16 +1161,19 @@ function _emit_cursor_mdc(source: string, target: string): void {
     _writeText(target, lines.join('\n'));
 }
 
-function _emit_windsurf_rule(source: string, target: string): void {
+export function _emit_windsurf_rule(source: string, target: string): void {
     const [meta, body] = _parse_frontmatter(_readText(source));
     const description = _strip(String(meta['description'] ?? '').replace(/\n/g, ' '));
     const always_apply = Boolean(meta['alwaysApply'] || meta['type'] === 'always');
-    const trigger = always_apply ? 'always_on' : 'model_decision';
+    // Path-shaped triggers activate host-natively via Windsurf's `glob`
+    // trigger; keyword/intent-only rules keep `model_decision`.
+    const globs = always_apply ? [] : derive_trigger_globs(meta);
+    const trigger = always_apply ? 'always_on' : globs.length > 0 ? 'glob' : 'model_decision';
     const lines = [
         '---',
         `trigger: ${trigger}`,
         `description: ${_yaml_scalar(description)}`,
-        'globs: ',
+        `globs: ${globs.join(',')}`,
         '---',
         '',
         _pyRstrip(body) + '\n',
@@ -1096,7 +1207,11 @@ function _clean_modern_dir(target_dir: string, valid_names: ReadonlySet<string>)
 }
 
 export function generate_cursor_mdc_rules(): number {
-    const rules = _rglobSorted(MODULE_STATE.RULES_SOURCE, '*.md').filter((p) => _isFile(p));
+    const scope = _read_rule_workspaces();
+    const pack_scope = _read_rule_packs();
+    const rules = _rglobSorted(MODULE_STATE.RULES_SOURCE, '*.md')
+        .filter((p) => _isFile(p))
+        .filter((p) => rule_in_scope(p, scope, pack_scope));
     const stems = rules.map((r) => path.basename(r, '.md'));
     const valid = new Set([
         ...stems.map((s) => `${s}.mdc`),
@@ -1111,7 +1226,11 @@ export function generate_cursor_mdc_rules(): number {
 }
 
 export function generate_windsurf_modern_rules(): number {
-    const rules = _rglobSorted(MODULE_STATE.RULES_SOURCE, '*.md').filter((p) => _isFile(p));
+    const scope = _read_rule_workspaces();
+    const pack_scope = _read_rule_packs();
+    const rules = _rglobSorted(MODULE_STATE.RULES_SOURCE, '*.md')
+        .filter((p) => _isFile(p))
+        .filter((p) => rule_in_scope(p, scope, pack_scope));
     const valid = new Set(rules.map((r) => path.basename(r)));
     _clean_modern_dir(_WINDSURF_RULES_DIR(), valid);
     for (const rule of rules) {
@@ -1475,6 +1594,221 @@ export function generate_claude_commands(active_command_slugs: ReadonlySet<strin
     return count;
 }
 
+/**
+ * Project `src/subagents/*.md` (subagent-v1, ADR-109) → `.claude/agents/*.md`
+ * in Claude Code's native subagent format.
+ *
+ * The source frontmatter carries governance metadata (schema_version, trust,
+ * lifecycle, discovery, source) that Claude Code does not understand; the native
+ * `.claude/agents/` format wants only `{name, description, tools, model}` + the
+ * system-prompt body. This is a **frontmatter transform**, not a symlink:
+ *
+ *  - `model_tier` → native `model:` via `_TIER_TO_CLAUDE_MODEL` (ADR-034/035);
+ *    the `inherit` sentinel passes through to `model: inherit`.
+ *  - `tools` (a YAML list) → the comma-joined form Claude Code accepts.
+ *  - the body (everything after the closing `---`) is copied verbatim.
+ *
+ * Static projection only — Claude Code (or the user via `@<name>`) decides
+ * dispatch; nothing here runs an agent. Reads from `src/` directly (subagent
+ * prompts are not telegraph-condensed). Reaps stale generated `.claude/agents/`
+ * files whose source no longer exists.
+ */
+export function generate_claude_subagents(): number {
+    if (!_isDir(MODULE_STATE.SUBAGENTS_SOURCE)) {
+        return 0;
+    }
+    _mkdirp(MODULE_STATE.CLAUDE_AGENTS_DIR);
+
+    const sources = _rglobSorted(MODULE_STATE.SUBAGENTS_SOURCE, '*.md').filter((p) => _isFile(p));
+    const current = new Set<string>();
+    let count = 0;
+
+    for (const src of sources) {
+        const stem = path.basename(src, '.md');
+        const text = _readText(src);
+        if (!text.startsWith('---\n')) {
+            continue;
+        }
+        const end = text.indexOf('\n---\n', 4);
+        if (end === -1) {
+            continue;
+        }
+        const fmBlock = text.slice(4, end);
+        const body = text.slice(end + 5);
+        const fm = _yamlParse(fmBlock) as Record<string, unknown> | null;
+        if (fm === null) {
+            continue;
+        }
+        const name = typeof fm['name'] === 'string' ? (fm['name'] as string) : stem;
+        const description = typeof fm['description'] === 'string' ? (fm['description'] as string) : '';
+        const toolsRaw = fm['tools'];
+        const tools = Array.isArray(toolsRaw) ? toolsRaw.map((t) => String(t)).join(', ') : String(toolsRaw ?? '');
+        const tier = typeof fm['model_tier'] === 'string' ? (fm['model_tier'] as string) : 'inherit';
+        const model = tier === 'inherit' ? 'inherit' : (_TIER_TO_CLAUDE_MODEL[tier] ?? 'inherit');
+
+        const out =
+            '---\n' +
+            `name: ${name}\n` +
+            `description: ${description}\n` +
+            `tools: ${tools}\n` +
+            `model: ${model}\n` +
+            '---\n' +
+            body;
+
+        const target = path.join(MODULE_STATE.CLAUDE_AGENTS_DIR, `${name}.md`);
+        _writeText(target, out);
+        current.add(`${name}.md`);
+        count += 1;
+    }
+
+    // Reap stale generated agent files (source removed). Only touch plain .md
+    // files we would have generated; never follow into unrelated content.
+    for (const item of _iterdirSorted(MODULE_STATE.CLAUDE_AGENTS_DIR)) {
+        const base = path.basename(item);
+        if (base === 'README.md' || current.has(base)) {
+            continue;
+        }
+        if (_isFile(item) && base.endsWith('.md') && !_isSymlink(item)) {
+            fs.unlinkSync(item);
+        }
+    }
+
+    info(`  ✅  Created ${count} subagent entries in .claude/agents/`);
+    return count;
+}
+
+/**
+ * Cross-host degradation for subagent-v1 (ADR-109 §4).
+ *
+ * Only Claude Code has native subagents (`generate_claude_subagents`). On the
+ * other rules-surface hosts a subagent projects to a **loadable context file** —
+ * a *passive reference*, honestly labelled: there is NO host-native `@`-dispatch
+ * (faking it would need a runtime the package refuses to add). Council
+ * (claude-sonnet-4-5 + gpt-4o, 2026-07-05) converged here over honest-null: the
+ * body is 95% reusable review discipline, 5% dispatch syntax, so an advanced user
+ * on Cursor / Windsurf / Cline loads it on intent and applies the discipline
+ * manually. This is **governance parity, not feature parity** — trust / lifecycle
+ * / model_tier stay legible; automation does not.
+ *
+ * Placement is reaper-safe by construction:
+ *  - Cursor / Windsurf → a dedicated `subagents/` subdir with its own reaper,
+ *    so it never collides with the aggressive `_clean_modern_dir` rule reapers.
+ *  - Cline → a flat real `<name>.subagent.md` in `.clinerules/` (whose reaper
+ *    only unlinks *symlinks*, so a real file survives).
+ *
+ * Copilot / Gemini are skipped (no per-file context surface), per ADR-109 §4.
+ * Reads from `src/` directly (subagent prompts are not telegraph-condensed).
+ */
+export function generate_subagent_host_contexts(): number {
+    if (!_isDir(MODULE_STATE.SUBAGENTS_SOURCE)) {
+        return 0;
+    }
+    const sources = _rglobSorted(MODULE_STATE.SUBAGENTS_SOURCE, '*.md').filter((p) => _isFile(p));
+
+    // Build the passive-reference body once per subagent, keyed by projected name.
+    const rendered: Array<{ name: string; text: string }> = [];
+    for (const src of sources) {
+        const stem = path.basename(src, '.md');
+        const text = _readText(src);
+        if (!text.startsWith('---\n')) {
+            continue;
+        }
+        const end = text.indexOf('\n---\n', 4);
+        if (end === -1) {
+            continue;
+        }
+        const fm = _yamlParse(text.slice(4, end)) as Record<string, unknown> | null;
+        if (fm === null) {
+            continue;
+        }
+        const body = text.slice(end + 5);
+        const name = typeof fm['name'] === 'string' ? (fm['name'] as string) : stem;
+        const description = typeof fm['description'] === 'string' ? (fm['description'] as string) : '';
+        // `trust` is either a flat string or the subagent-v1 nested object
+        // {level, confidence, human_review_required}; surface the level either way.
+        const trustRaw = fm['trust'];
+        const trust =
+            typeof trustRaw === 'string'
+                ? trustRaw
+                : typeof trustRaw === 'object' && trustRaw !== null && typeof (trustRaw as Record<string, unknown>)['level'] === 'string'
+                  ? ((trustRaw as Record<string, unknown>)['level'] as string)
+                  : 'unknown';
+        const lifecycle = typeof fm['lifecycle'] === 'string' ? (fm['lifecycle'] as string) : 'unknown';
+        const tier = typeof fm['model_tier'] === 'string' ? (fm['model_tier'] as string) : 'inherit';
+        const toolsRaw = fm['tools'];
+        const tools = Array.isArray(toolsRaw)
+            ? toolsRaw.map((t) => String(t)).join(', ')
+            : String(toolsRaw ?? '');
+        const out =
+            '---\n' +
+            `description: ${description}\n` +
+            '---\n\n' +
+            `# Subagent (passive reference): ${name}\n\n` +
+            '> Passive subagent reference. This host has **no native subagent dispatch** —\n' +
+            `> there is no \`@${name}\` here. Load this discipline manually and apply it.\n` +
+            '> Governance parity (trust / lifecycle / model tier) is preserved below;\n' +
+            '> feature parity is not (ADR-109 §4).\n\n' +
+            `- trust: ${trust}\n` +
+            `- lifecycle: ${lifecycle}\n` +
+            `- model tier: ${tier}\n` +
+            (tools ? `- tools: ${tools}\n` : '') +
+            '\n' +
+            _pyRstrip(body) +
+            '\n';
+        rendered.push({ name, text: out });
+    }
+
+    // Host targets: [dir, filename(name)->basename, reaper-predicate].
+    const targets: Array<{ active: boolean; dir: string; file: (n: string) => string; owns: (b: string) => boolean }> = [
+        {
+            active: _tool_active('cursor'),
+            dir: path.join(MODULE_STATE.PROJECT_ROOT, '.cursor', 'subagents'),
+            file: (n) => `${n}.md`,
+            owns: (b) => b.endsWith('.md'),
+        },
+        {
+            active: _tool_active('windsurf'),
+            dir: path.join(MODULE_STATE.PROJECT_ROOT, '.windsurf', 'subagents'),
+            file: (n) => `${n}.md`,
+            owns: (b) => b.endsWith('.md'),
+        },
+        {
+            active: _tool_active('cline'),
+            dir: path.join(MODULE_STATE.PROJECT_ROOT, '.clinerules'),
+            file: (n) => `${n}.subagent.md`,
+            owns: (b) => b.endsWith('.subagent.md'),
+        },
+    ];
+
+    let count = 0;
+    for (const t of targets) {
+        if (!t.active) {
+            continue;
+        }
+        const current = new Set(rendered.map((r) => t.file(r.name)));
+        _mkdirp(t.dir);
+        for (const r of rendered) {
+            _writeText(path.join(t.dir, t.file(r.name)), r.text);
+            count += 1;
+        }
+        // Reap stale generated files we own whose source is gone. Never touch
+        // symlinks (cline's rule symlinks) or a README.
+        if (_exists(t.dir)) {
+            for (const item of _iterdirSorted(t.dir)) {
+                const base = path.basename(item);
+                if (base === 'README.md' || current.has(base)) {
+                    continue;
+                }
+                if (_isFile(item) && !_isSymlink(item) && t.owns(base)) {
+                    fs.unlinkSync(item);
+                }
+            }
+        }
+    }
+    info(`  ✅  Projected ${count} passive subagent context file(s) to non-Claude-Code hosts`);
+    return count;
+}
+
 export function generate_plugin_command_skills(): number {
     if (!_isDir(path.join(MODULE_STATE.PROJECT_ROOT, 'src', 'domains'))) {
         return 0;
@@ -1713,6 +2047,8 @@ function _generate_tools_inner(
     }
     const skills = _tool_active('claude-code') ? generate_claude_skills(skill_names) : 0;
     const commands = _tool_active('claude-code') ? generate_claude_commands(cmd_slugs) : 0;
+    const subagents = _tool_active('claude-code') ? generate_claude_subagents() : 0;
+    const subagent_contexts = generate_subagent_host_contexts();
     const plugin_cmd_skills = _tool_active('claude-code') ? generate_plugin_command_skills() : 0;
     const plugin_hooks = _tool_active('claude-code') ? generate_plugin_hooks() : 0;
     const personas = generate_persona_symlinks();
@@ -1723,7 +2059,7 @@ function _generate_tools_inner(
     const windsurf_wf = _tool_active('windsurf') ? generate_windsurf_workflows(cmd_slugs) : 0;
     const summary =
         `✅  generate-tools — rules=${rules} skills=${skills} ` +
-        `commands=${commands} plugin_cmd_skills=${plugin_cmd_skills} ` +
+        `commands=${commands} subagents=${subagents} subagent_contexts=${subagent_contexts} plugin_cmd_skills=${plugin_cmd_skills} ` +
         `plugin_hooks=${plugin_hooks} ` +
         `personas=${personas} user_types=${user_types} ` +
         `cursor_mdc=${cursor_mdc} windsurf_rules=${windsurf_modern} ` +

package/src/scripts/consolidate_knowledge_events.ts

@@ -0,0 +1,192 @@
+#!/usr/bin/env tsx
+/**
+ * Consolidation report generator for `/team-knowledge consolidate` —
+ * road-to-knowledge-system Phase 5. Reads the pending typed-observation
+ * intake, aggregates by topic, and finds the nearest existing knowledge
+ * page for each aggregate (mechanical similarity only). It NEVER decides
+ * NEW/EXTEND/CONFIRM/CONFLICT and NEVER writes a page — per the council
+ * verdict, that triage is always a human-reviewed judgment call the
+ * command prose makes from this report.
+ *
+ * Default mode prints the report and exits — intake is untouched.
+ * `--commit` additionally clears the consumed intake AFTER printing,
+ * for use once the agent has written the reviewed batch (mirrors
+ * memory-consolidation's --preview / --commit-intake split).
+ *
+ * Usage:
+ *   consolidate_knowledge_events.ts [--intake-dir <dir>] [--knowledge-dir <dir>] [--format text|json] [--commit]
+ *
+ * Exit codes: 0 = report printed (regardless of pending-event count), 1 = usage error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { findMostSimilar, type Candidate } from './_lib/text_similarity.js';
+import { clearAllEvents, readAllEvents, type KnowledgeEvent } from './_lib/knowledge_events.js';
+
+const PROG = 'consolidate_knowledge_events.ts';
+const DEFAULT_INTAKE_DIR = path.join('agents', 'knowledge', 'intake');
+const DEFAULT_KNOWLEDGE_DIR = path.join('agents', 'knowledge');
+const PAGE_DIRS = ['concepts', 'procedures'] as const;
+
+/** Stable aggregation key per event type — events with the same key describe the same emerging topic. */
+export function aggregationKey(event: KnowledgeEvent): string {
+    switch (event.type) {
+        case 'convention_detected':
+            return `convention:${event.pattern}`;
+        case 'mistake_made':
+            return `mistake:${event.recurrenceKey}`;
+        case 'api_shape_learned':
+            return `api:${event.method} ${event.endpoint}`;
+        case 'context_stale':
+            return `stale:${event.pagePath}#${event.field}`;
+    }
+}
+
+/** Short human-readable text representing the aggregate, used for the similarity scan against existing pages. */
+function aggregateText(event: KnowledgeEvent): string {
+    switch (event.type) {
+        case 'convention_detected':
+            return event.pattern;
+        case 'mistake_made':
+            return `${event.errorCategory} ${event.correction}`;
+        case 'api_shape_learned':
+            return `${event.method} ${event.endpoint}`;
+        case 'context_stale':
+            return `${event.field} ${String(event.expected)} ${String(event.actual)}`;
+    }
+}
+
+export interface AggregateGroup {
+    key: string;
+    events: KnowledgeEvent[];
+    nearestPage: { path: string; score: number } | null;
+}
+
+function listMarkdownFiles(dirPath: string): string[] {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    return entries.filter((e) => e.isFile() && e.name.endsWith('.md')).map((e) => e.name);
+}
+
+function loadPageCandidates(knowledgeDir: string): Candidate[] {
+    const out: Candidate[] = [];
+    for (const dir of PAGE_DIRS) {
+        const scanDir = path.join(knowledgeDir, dir);
+        for (const file of listMarkdownFiles(scanDir)) {
+            let text = '';
+            try {
+                text = fs.readFileSync(path.join(scanDir, file), 'utf8');
+            } catch {
+                continue;
+            }
+            out.push({ id: `${dir}/${file}`, text });
+        }
+    }
+    return out;
+}
+
+/** Pure aggregation + similarity-scan step. Never touches disk beyond the passed-in candidates. */
+export function buildReport(events: KnowledgeEvent[], pageCandidates: Candidate[]): AggregateGroup[] {
+    const groups = new Map<string, KnowledgeEvent[]>();
+    for (const event of events) {
+        const key = aggregationKey(event);
+        const bucket = groups.get(key) ?? [];
+        bucket.push(event);
+        groups.set(key, bucket);
+    }
+
+    const out: AggregateGroup[] = [];
+    for (const [key, groupEvents] of groups) {
+        const first = groupEvents[0];
+        if (first === undefined) continue;
+        const representative = aggregateText(first);
+        const match = findMostSimilar(representative, pageCandidates);
+        out.push({
+            key,
+            events: groupEvents,
+            nearestPage: match && match.classification !== 'create' ? { path: match.id, score: match.score } : null,
+        });
+    }
+    return out.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+}
+
+function renderText(report: AggregateGroup[]): string {
+    if (report.length === 0) return `${PROG}: no pending knowledge events.\n`;
+    const lines: string[] = [`${PROG}: ${report.length} topic(s) pending review.`, ''];
+    for (const group of report) {
+        lines.push(`## ${group.key} (${group.events.length} event(s))`);
+        if (group.nearestPage) {
+            lines.push(
+                `  Nearest existing page: ${group.nearestPage.path} (${(group.nearestPage.score * 100).toFixed(0)}% similar) — triage EXTEND/CONFIRM/CONFLICT`,
+            );
+        } else {
+            lines.push('  No similar existing page found — triage NEW');
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+
+function printUsage(): void {
+    process.stdout.write(`usage: ${PROG} [--intake-dir DIR] [--knowledge-dir DIR] [--format text|json] [--commit]\n`);
+}
+
+export function main(argv: string[]): number {
+    let intakeDir = DEFAULT_INTAKE_DIR;
+    let knowledgeDir = DEFAULT_KNOWLEDGE_DIR;
+    let format: 'text' | 'json' = 'text';
+    let commit = false;
+
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '-h' || arg === '--help') {
+            printUsage();
+            return 0;
+        } else if (arg === '--intake-dir') {
+            intakeDir = argv[++i] ?? intakeDir;
+        } else if (arg === '--knowledge-dir') {
+            knowledgeDir = argv[++i] ?? knowledgeDir;
+        } else if (arg === '--format') {
+            const value = argv[++i];
+            if (value !== 'text' && value !== 'json') {
+                process.stderr.write(`${PROG}: error: --format must be text or json\n`);
+                return 1;
+            }
+            format = value;
+        } else if (arg === '--commit') {
+            commit = true;
+        } else {
+            process.stderr.write(`${PROG}: error: unrecognized argument: ${arg}\n`);
+            printUsage();
+            return 1;
+        }
+    }
+
+    const events = readAllEvents(intakeDir);
+    const candidates = loadPageCandidates(knowledgeDir);
+    const report = buildReport(events, candidates);
+
+    if (format === 'json') {
+        process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    } else {
+        process.stdout.write(renderText(report));
+    }
+
+    if (commit) {
+        clearAllEvents(intakeDir);
+        process.stdout.write(`${PROG}: intake cleared.\n`);
+    }
+
+    return 0;
+}
+
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+    process.exit(main(process.argv.slice(2)));
+}