@event4u/agent-config 16.2.0 → 16.3.0

package/src/scripts/install.ts

@@ -76,6 +76,9 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import type * as YamlModule from 'yaml';
 
 import { build_merge_entries } from './_lib/json_pointers.js';
+import { deepMerge as deep_merge, isPlainObject as _isPlainObject, jsonEqual } from './_lib/json_merge.js';
+import { mergeHostConfig, HOOK_SIGNATURES } from './_lib/host_hook_merge.js';
+import { sweepReservedNames } from './_lib/reserved_name_sweep.js';
 import { withHostEnv } from './_lib/host_env_write.js';
 import { jsonDumpsCompact, jsonDumpsIndent } from './_lib/json_python_parity.js';
 import { is_claude_builtin_name } from './_lib/claude_builtin_names.js';
@@ -93,6 +96,7 @@ import * as rule_layer_overlap from './_lib/rule_layer_overlap.js';
 import * as installed_tools from './_lib/installed_tools.js';
 import { collect_drift, format_drift_report } from './_lib/install_drift.js';
 import * as user_global_paths from './_lib/user_global_paths.js';
+import * as gitignore_block from './_lib/gitignore_block.js';
 // The LIBRARY half, deliberately not `capture_skill_catalogue.js`: that module
 // is a CLI entry with a top-level `process.exit()`, and esbuild would bundle
 // that exit into the installer a consumer loads (`check_installer_import_purity`
@@ -103,15 +107,17 @@ import * as claude_desktop_bundler from './_lib/claude_desktop_bundler.js';
 import * as claude_settings_hooks from './_lib/claude_settings_hooks.js';
 import { hostBindings } from './hooks/host_lowering.js';
 import { find_project_root_with_anchor, load_agent_settings } from './_lib/agent_settings.js';
-import {
-    LEGACY_ALL,
-    ruleFileArrives,
-    ruleScopeFromSettings,
-    type RuleScope,
-} from '../install/rule_scope.js';
+import { ruleFileArrives, type RuleScope } from '../install/rule_scope.js';
 import { isExclusivelyPackageOnly, stampHostLayerFingerprint } from '../install/partitionEligibility.js'; // ADR-236
 import * as claude_rule_rewrite from '../install/claudeRuleRewrite.js';
-import { RULE_SOURCE_REL } from '../install/wizard-plan.js';
+import {
+    describeThinInstalledLayer,
+    installReceiptBudgetLines,
+    thinInstalledRuleLayer,
+} from '../install/installThinLayer.js';
+import { resolveGlobalRuleScope } from '../install/globalRuleScope.js';
+import { installerThinsHost } from './_lib/lean_projection_mode.js';
+import { GLOBAL_DEPLOY_SOURCES, RULE_SOURCE_REL } from '../install/wizard-plan.js';
 import { flattenSurface, computeSurfaceDelta, type SettingsSurface } from '../shared/settingsSurface.js';
 import { settingsSchema } from '../server/schemas/settings.js';
 import { zodToJsonSchema } from 'zod-to-json-schema';
@@ -481,63 +487,6 @@ function write_json_file(p: string, data: unknown): void {
     write_file(p, content);
 }
 
-function _isPlainObject(v: unknown): v is Record<string, unknown> {
-    return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
-
-/** `copy.deepcopy` for JSON-shaped values. */
-function deepcopy<T>(v: T): T {
-    if (v === null || typeof v !== 'object') return v;
-    if (Array.isArray(v)) return v.map((x) => deepcopy(x)) as unknown as T;
-    const out: Record<string, unknown> = {};
-    for (const k of Object.keys(v as Record<string, unknown>)) {
-        out[k] = deepcopy((v as Record<string, unknown>)[k]);
-    }
-    return out as unknown as T;
-}
-
-function deep_merge(
-    base: Record<string, unknown>,
-    overlay: Record<string, unknown>,
-): Record<string, unknown> {
-    const result = deepcopy(base);
-    for (const key of Object.keys(overlay)) {
-        const value = overlay[key];
-        if (
-            Object.prototype.hasOwnProperty.call(result, key) &&
-            _isPlainObject(result[key]) &&
-            _isPlainObject(value)
-        ) {
-            result[key] = deep_merge(
-                result[key] as Record<string, unknown>,
-                value as Record<string, unknown>,
-            );
-        } else {
-            result[key] = deepcopy(value);
-        }
-    }
-    return result;
-}
-
-/** Deep structural equality for JSON-shaped values (Python dict `==`). */
-function jsonEqual(a: unknown, b: unknown): boolean {
-    if (a === b) return true;
-    if (typeof a !== typeof b) return false;
-    if (Array.isArray(a) || Array.isArray(b)) {
-        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
-        return a.every((v, i) => jsonEqual(v, b[i]));
-    }
-    if (_isPlainObject(a) && _isPlainObject(b)) {
-        const ka = Object.keys(a);
-        const kb = Object.keys(b);
-        if (ka.length !== kb.length) return false;
-        return ka.every(
-            (k) => Object.prototype.hasOwnProperty.call(b, k) && jsonEqual(a[k], (b as Record<string, unknown>)[k]),
-        );
-    }
-    return false;
-}
-
 function merge_json_file(
     p: string,
     new_data: Record<string, unknown>,
@@ -557,7 +506,9 @@ function merge_json_file(
     }
 
     const existing = read_json_file(p);
-    const merged = deep_merge(existing, new_data);
+    // Hook arrays are shared with whatever else the consumer installed, so the
+    // `hooks` key merges per event by signature instead of being replaced.
+    const merged = mergeHostConfig(existing, new_data, HOOK_SIGNATURES[label] ?? '', deep_merge);
 
     if (jsonEqual(merged, existing)) {
         skip(`${label} already configured`);
@@ -1803,48 +1754,20 @@ export const PROJECT_BRIDGE_MARKERS: Record<string, string> = {
     kiro: '.kiro/steering/agent-config.md',
 };
 
-const _CLAUDE_SKILL_BUNDLE: ReadonlyArray<readonly [string, string]> = [
-    ['dist/agent-src/rules', 'rules'],
-    ['dist/agent-src/skills', 'skills'],
-    ['dist/agent-src/commands', 'commands'],
-    ['dist/agent-src/personas', 'personas'],
-];
-
-export const GLOBAL_DEPLOY_SOURCES: Record<string, ReadonlyArray<readonly [string, string]>> = {
-    'claude-code': _CLAUDE_SKILL_BUNDLE,
-    augment: [
-        ['dist/agent-src/rules', 'rules'],
-        ['dist/agent-src/skills', 'skills'],
-        ['dist/agent-src/commands', 'commands'],
-        ['dist/agent-src/contexts', 'contexts'],
-        ['dist/agent-src/personas', 'personas'],
-        ['dist/agent-src/templates', 'templates'],
-    ],
-    cursor: [
-        ['dist/agent-src/rules', 'rules'],
-        ['dist/agent-src/commands', 'commands'],
-        ['dist/agent-src/personas', 'personas'],
-    ],
-    windsurf: [['dist/agent-src/rules', 'rules']],
-    cline: [['dist/agent-src/rules', '']],
-    'gemini-cli': _CLAUDE_SKILL_BUNDLE,
-    codex: _CLAUDE_SKILL_BUNDLE,
-    continue: _CLAUDE_SKILL_BUNDLE,
-    roocode: _CLAUDE_SKILL_BUNDLE,
-    kilocode: _CLAUDE_SKILL_BUNDLE,
-    qoder: _CLAUDE_SKILL_BUNDLE,
-    opencode: _CLAUDE_SKILL_BUNDLE,
-    trae: _CLAUDE_SKILL_BUNDLE,
-    antigravity: _CLAUDE_SKILL_BUNDLE,
-    codebuddy: _CLAUDE_SKILL_BUNDLE,
-    droid: _CLAUDE_SKILL_BUNDLE,
-    warp: _CLAUDE_SKILL_BUNDLE,
-    kiro: [
-        ['dist/agent-src/rules', 'rules'],
-        ['dist/agent-src/skills', 'steering'],
-        ['dist/agent-src/personas', 'personas'],
-    ],
-};
+/**
+ * Re-exported from `wizard-plan.ts`, which is now the ONLY definition.
+ *
+ * It was defined here too, and the two copies were byte-identical in every
+ * one of their 18 host rows — a duplicate of the same truth, and the kind
+ * that stays correct right up until somebody edits one of them. Step 1.2 of
+ * `road-to-rule-triggers-and-links-that-hold` did exactly that: it added two
+ * directories here and the wizard kept installing without them.
+ *
+ * Re-exported rather than moved-and-left-broken so every caller of
+ * `install.ts::GLOBAL_DEPLOY_SOURCES` keeps working unchanged. Imported as
+ * well as re-exported because this file's own call sites read the binding.
+ */
+export { GLOBAL_DEPLOY_SOURCES };
 
 const _CLAUDE_DESKTOP_MARKER_TEMPLATE_HEAD = `# agent-config — Claude Desktop marker
 
@@ -2108,8 +2031,9 @@ export function _gate_rule_layer_overlap(
     layer: string | null,
     dry_run: boolean,
 ): boolean {
-    const global_dir = path.join(os.homedir(), '.claude', 'rules');
-    const project_dir = path.join(project_root, '.claude', 'rules');
+    // ONE source of truth for which directories the host loads, shared with the
+    // delivery carrier's scope filter (`rule_layer_overlap.hostRuleLayerDirs`).
+    const [global_dir, project_dir] = rule_layer_overlap.hostRuleLayerDirs(project_root);
     const g = rule_layer_overlap.readRuleLayer(global_dir);
     const p = rule_layer_overlap.readRuleLayer(project_dir);
     if (g === null || p === null) return true; // only one layer exists — nothing to double
@@ -2957,26 +2881,12 @@ export function _apply_claude_flat_command_wrappers(
     anchor: string,
     package_root: string,
     current_files: Set<string>,
-): { wrapped: string[]; collisions: string[]; reserved: string[] } {
+    recorded_files: ReadonlySet<string> = new Set<string>(),
+): { wrapped: string[]; collisions: string[]; reserved: string[]; foreign: string[] } {
     const wrapped: string[] = [];
     const collisions: string[] = [];
-    const reserved: string[] = [];
-    // Reserved-name sweep over ALL flat command files (any tier): a name
-    // shadowing a Claude Code built-in never ships on the claude-code anchor.
     const commands_dir = path.join(anchor, 'commands');
-    let flat_entries: string[] = [];
-    try {
-        flat_entries = fs.readdirSync(commands_dir).filter((f) => f.endsWith('.md'));
-    } catch {
-        // No commands dir → nothing to sweep.
-    }
-    for (const fname of flat_entries.sort()) {
-        const slug = fname.slice(0, -'.md'.length);
-        if (!is_claude_builtin_name(slug)) continue;
-        fs.rmSync(path.join(commands_dir, fname), { force: true });
-        current_files.delete(`commands/${fname}`);
-        reserved.push(slug);
-    }
+    const { reserved, foreign } = sweepReservedNames(commands_dir, current_files, is_claude_builtin_name, recorded_files);
     // Visible command slugs from the locked discovery manifest. `visibility`
     // is the source of truth (ADR-090/092); the integer `tier` stays only as
     // the fallback for a manifest published before `visibility` was emitted,
@@ -3023,7 +2933,7 @@ export function _apply_claude_flat_command_wrappers(
         current_files.add(`skills/${slug}/SKILL.md`);
         wrapped.push(slug);
     }
-    return { wrapped, collisions, reserved };
+    return { wrapped, collisions, reserved, foreign };
 }
 
 function _deploy_global_content(
@@ -3096,15 +3006,33 @@ function _deploy_global_content(
         if (tool_id === 'claude-code') {
             // Rules land verbatim from the copy above; see the module. It also
             // renders the flat-command wrapper report, unchanged.
-            const res = _apply_claude_flat_command_wrappers(anchor, package_root, current_files);
+            const res = _apply_claude_flat_command_wrappers(anchor, package_root, current_files, global_deploy_inventory.recorded_rel_files(tool_id, anchor));
+            const preserved_now = new Set(
+                tracker.conflictState.preserved.map((p) => path.resolve(p)),
+            );
             claude_rule_rewrite.rewriteAndReport(
                 path.join(anchor, 'rules'),
                 state.QUIET,
                 info,
                 warn,
                 res,
-                new Set(tracker.conflictState.preserved.map((p) => path.resolve(p))),
+                preserved_now,
             );
+            // Steps 1.1 and 1.4 of road-to-an-installed-layer-that-is-thinned;
+            // both modules' headers carry the reasoning.
+            if (installerThinsHost(tool_id, { packageRoot: package_root })) {
+                try {
+                    const thin = thinInstalledRuleLayer({
+                        rulesDir: path.join(anchor, 'rules'),
+                        packageRoot: package_root,
+                        preserved: preserved_now,
+                    });
+                    if (!state.QUIET) for (const l of describeThinInstalledLayer(thin)) info(l);
+                } catch (e) {
+                    warn(`claude-code: thinned rule layer not written — ${String(e)}`);
+                }
+            }
+            if (!state.QUIET) for (const l of installReceiptBudgetLines(package_root)) info(l);
         }
 
         const missing_targets = _verify_deploy_targets(anchor, plan);
@@ -3339,65 +3267,21 @@ function _resolve_scoped_projection(
 }
 
 /**
- * Resolve the rule scope governing THIS global deploy — the same way the wizard
- * does (`src/server/routes/install.ts::_resolveRuleScope`), so the two global
- * paths cannot ship different rule sets for the same settings.
+ * Resolve the rule scope governing THIS global deploy.
  *
- * Settings resolution mirrors `_resolve_scoped_projection` above: an existing
- * global settings doc is authoritative, and only a genuinely fresh machine falls
- * through to the packaged template. Any read or parse failure resolves to
- * `LEGACY_ALL` — over-shipping is the safe direction, and the compat exclusion
- * (`source-of-truth.md`) still applies even then.
+ * Thin wrapper: the body moved to `src/install/globalRuleScope.ts` (see that
+ * module's header for why). Name, signature and behaviour are unchanged, so the
+ * re-export below and every caller and test keep what they had.
  */
 function _resolve_global_rule_scope(package_root: string): RuleScope {
-    const settings_path = _resolve_global_settings_path();
-
-    // No global settings artefact at all — a genuinely fresh machine. Fall
-    // through to the packaged template silently: there is no user decision to
-    // contradict, and this is the documented upgrade-compat path.
-    if (settings_path === null) {
-        try {
-            return ruleScopeFromSettings(_load_default_settings(package_root), package_root);
-        } catch {
-            return LEGACY_ALL;
-        }
-    }
-
-    // A doc EXISTS, so the user has expressed a configuration. Failing to read
-    // it is not the same as not having one: falling back to legacy-all here
-    // ships the maintainer-only rules the user may have deliberately scoped out,
-    // and `_load_yaml_doc` would report that as an indistinguishable `{}`. So
-    // parse it explicitly and be LOUD when it does not parse — over-shipping
-    // stays the safe direction, but it must not be a silent one.
-    let text: string;
-    try {
-        text = readText(settings_path);
-    } catch (e) {
-        warn(
-            `could not read ${settings_path} (${String(e)}) — rule scoping falls back ` +
-                'to legacy-all, so ALL rules including maintainer-only ones will be ' +
-                'installed. Fix the file to restore scoping.',
-        );
-        return LEGACY_ALL;
-    }
-    const parsed = yamlSafeLoad(text);
-    if (!_isPlainObject(parsed)) {
-        warn(
-            `${settings_path} is not a YAML mapping — rule scoping falls back to ` +
-                'legacy-all, so ALL rules including maintainer-only ones will be ' +
-                'installed. Fix the file to restore scoping.',
-        );
-        return LEGACY_ALL;
-    }
-    try {
-        return ruleScopeFromSettings(parsed as Record<string, unknown>, package_root);
-    } catch (e) {
-        warn(
-            `could not derive rule scope from ${settings_path} (${String(e)}) — ` +
-                'falling back to legacy-all; ALL rules will be installed.',
-        );
-        return LEGACY_ALL;
-    }
+    return resolveGlobalRuleScope({
+        settingsPath: _resolve_global_settings_path(),
+        packageRoot: package_root,
+        readText,
+        parseYaml: yamlSafeLoad,
+        loadDefaults: () => _load_default_settings(package_root),
+        warn,
+    });
 }
 
 /**
@@ -5136,6 +5020,9 @@ function _main_project_install(
     if (will_launch) {
         return _wizard_spawn(project_root);
     }
+    // No wizard, so nothing else installs the managed ignore block.
+    const ign = gitignore_block.write_managed_block(project_root, opts.dry_run);
+    if (ign > 0) success(`.gitignore: ${opts.dry_run ? 'would add ' : '+'}${ign} managed entries`);
     return 0;
 }
 

package/src/scripts/installed_layer_report.ts

@@ -0,0 +1,103 @@
+#!/usr/bin/env tsx
+/**
+ * Report what a host actually loads, per host rule directory (step 0.1).
+ *
+ * REPORT-ONLY, AND THE NAME SAYS SO. Phase 0 of
+ * `road-to-a-rule-carrier-that-works-outside-the-repo` makes no behavior
+ * change, so this never fails on a number: exit 0 whenever it could read, 2 on
+ * usage. It is also deliberately NOT named `check_*` or `lint_*` —
+ * `_lib/gate_population.ts` enters any script with those prefixes into the gate
+ * population and the ledger then owes it a per-target accounting, which is the
+ * wrong contract for an instrument. A later ceiling over this measurement is a
+ * different script with a `check_` name.
+ *
+ * `--home` and `--project` exist so this can be pointed at a temporary `HOME`,
+ * which is the step's own framing and the thing that refutes
+ * `check_standing_rule_delivery`'s "no CI workflow performs a user-scope
+ * install": the installer reads `HOME` from the environment, so a runner can
+ * stage one and measure it. The library behind this takes the same two as
+ * parameters, which is what keeps CI, `doctor` and the upgrade receipt from
+ * each growing their own reader.
+ */
+
+import * as os from 'node:os';
+import * as path from 'node:path';
+import process from 'node:process';
+
+import { hostVersion } from './cache_realization_report.js';
+import { manifest_path } from './_lib/installed_tools.js';
+import {
+    buildInstalledLayerReport,
+    renderInstalledLayerReport,
+    type InstalledLayerReport,
+} from './_lib/installed_layer.js';
+
+const PROG = 'installed_layer_report';
+
+interface Args {
+    home: string;
+    project: string;
+    json: boolean;
+}
+
+export function parseArgs(argv: readonly string[]): Args | null {
+    let home = process.env['HOME'] ?? os.homedir();
+    let project = process.cwd();
+    let json = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === '--json') {
+            json = true;
+        } else if (a === '--home') {
+            i += 1;
+            const v = argv[i];
+            if (v === undefined) return null;
+            home = v;
+        } else if (a === '--project') {
+            i += 1;
+            const v = argv[i];
+            if (v === undefined) return null;
+            project = v;
+        } else if (a === '--quiet') {
+            // Accepted and ignored: this prints one block either way, and a flag
+            // that silences a report leaves nothing to have run it for.
+        } else {
+            return null;
+        }
+    }
+    return { home, project, json };
+}
+
+/** Build the report for one machine, resolving the manifest from the project root. */
+export function reportFor(args: Args): InstalledLayerReport {
+    return buildInstalledLayerReport({
+        home: args.home,
+        projectRoot: args.project,
+        manifestPath: manifest_path(args.project),
+        hostVersion: hostVersion(),
+    });
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const args = parseArgs(argv);
+    if (args === null) {
+        process.stderr.write(`usage: ${PROG} [--home <dir>] [--project <dir>] [--json]\n`);
+        return 2;
+    }
+    const report = reportFor(args);
+    if (args.json) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    } else {
+        process.stdout.write(`${renderInstalledLayerReport(report).join('\n')}\n`);
+    }
+    // One machine-readable line, in the shape every reporting script here uses.
+    // It counts FILES across every layer read, which is the denominator the
+    // character total is over — a reader comparing two runs needs both.
+    process.stdout.write(`scanned: ${String(report.totals.files)}\n`);
+    return 0;
+}
+
+const _entry = process.argv[1];
+if (_entry !== undefined && path.resolve(_entry) === path.resolve(new URL(import.meta.url).pathname)) {
+    process.exit(main());
+}

package/src/scripts/language_mirror_hook.ts

@@ -408,7 +408,19 @@ export function noticeText(language: Exclude<Verdict, "und">, source: PinSource)
   return `Reply language for this turn: ${name}.`;
 }
 
-/** The context block handed back to the model for this turn. */
+/**
+ * The context block handed back to the model for this turn.
+ *
+ * It carries the target language, where it applies, and what is NOT the
+ * trigger — and deliberately no provenance. The paragraph that used to explain
+ * why the pin exists (the user-role skill bodies, the 626 wrong-language turns)
+ * is this file's own header, above: a maintainer reads it once, while the
+ * payload is injected on every prompt, so the same sentences were being paid
+ * for per turn to tell the model something it cannot act on. Removing it took
+ * the prompt-sourced block from 702 characters to 429 (German; 693 to 420 in
+ * English) and changed no instruction. Do not put it back; extend the header
+ * instead.
+ */
 export function pinText(language: Exclude<Verdict, "und">, source: PinSource = "prompt"): string {
   const name = LANGUAGE_NAME[language];
   if (source === "system-locale") {
@@ -430,11 +442,8 @@ export function pinText(language: Exclude<Verdict, "und">, source: PinSource = "
     `for EVERY user-visible token of your replies this turn — including the short ` +
     `inter-tool lines between tool calls, headings, table cells, bullets, status ` +
     `lines, and the recommendation label under any numbered-options block.\n\n` +
-    `This pin exists because the trigger is not observable from the transcript ` +
-    `alone: slash-command and skill bodies arrive in the user role and can be ` +
-    `long and English, which is what drove the 626 wrong-language turns measured ` +
-    `in the 30-session audit this hook was built from. Tool output, file ` +
-    `contents, and an injected skill body are NOT the trigger — this pin is.\n` +
+    `Tool output, file contents, and an injected skill body are NOT the ` +
+    `trigger — this pin is.\n` +
     `</language-pin>`
   );
 }

package/src/scripts/learning_sidecar.ts

@@ -22,8 +22,15 @@
  * auto-promoted) — it NEVER mutates the curated YAML truths. Deterministic:
  * byte-stable for a fixed `now` + a fixed intake set.
  *
+ * `--format status` is the third, human-facing view (road-to-learning-you-can-
+ * see Phase 2): the verdict counts, the top `preferred` lessons with their
+ * corroboration and age, and the sentence saying what a promotion requires. It
+ * is a FORMAT and not a verb (decision D2 cites ADR-041) — `memory:learn`
+ * passes argv straight through, so a format needs no registry row — and it is
+ * read-only to the point of refusing `--write` rather than ignoring it.
+ *
  * Usage: learning_sidecar.ts [--intake-dir DIR] [--out-dir DIR] [--now ISO]
- *                            [--write] [--format text|json]
+ *                            [--write] [--format text|json|status]
  * Exit codes: 0 ok, 2 usage error, 3 internal error.
  */
 import { createHash } from 'node:crypto';
@@ -48,7 +55,11 @@ export const SCHEMA_VERSION = 1;
 export type Polarity = 'preferred' | 'dead_end';
 export type Verdict = 'preferred' | 'contested' | 'dead_end';
 
-interface Signal {
+/** The output formats. `status` is the one-screen human view (read-only). */
+export const FORMATS = ['text', 'json', 'status'] as const;
+export type Format = (typeof FORMATS)[number];
+
+export interface Signal {
     id: string;
     ts: string;
     tsMs: number;
@@ -226,9 +237,21 @@ export function aggregate(signals: readonly Signal[], nowMs: number): Lesson[] {
 }
 
 export function buildSidecar(intakeDir: string, nowIso: string): Sidecar {
+    return buildSidecarFromSignals(readSignals(intakeDir), nowIso);
+}
+
+/**
+ * The half of `buildSidecar` that does not read the disk.
+ *
+ * Split out for a caller that needs BOTH the input count and the output
+ * lessons from one pass — the session-end dogfood ledger records `signals_in`
+ * beside `lessons_out`, and reading the intake twice to get them would make the
+ * two numbers describe two different reads under the 2 s budget they exist to
+ * measure.
+ */
+export function buildSidecarFromSignals(signals: readonly Signal[], nowIso: string): Sidecar {
     const nowMs = _parseTsMs(nowIso) ?? 0;
-    const lessons = aggregate(readSignals(intakeDir), nowMs);
-    return { schema_version: SCHEMA_VERSION, generated_at: nowIso, lessons };
+    return { schema_version: SCHEMA_VERSION, generated_at: nowIso, lessons: aggregate(signals, nowMs) };
 }
 
 /** Render the human dead-ends + contested ledger. */
@@ -261,22 +284,98 @@ export function renderLessonsMd(sidecar: Sidecar): string {
     return L.join('\n');
 }
 
+/** How many `preferred` lessons the status screen lists before it stops. */
+export const STATUS_TOP_N = 5;
+
+/**
+ * The human step. Printed as the LAST line of the status screen, because this
+ * tree writes no rule and no skill on its own: a lesson becomes a durable
+ * artefact only when a person carries it through `/memory:propose` or the
+ * `learning-to-rule-or-skill` skill. A list of preferred lessons is one flag
+ * away from `--apply`, and naming the hand-off on every screen is the cheapest
+ * standing answer to "why is there no button".
+ */
+export const PROMOTION_HANDOFF =
+    'Promote by hand: /memory:propose · src/skills/learning-to-rule-or-skill/SKILL.md';
+
+/**
+ * One screen answering "what has this learned?" — verdict counts, the top
+ * `preferred` lessons with their corroboration and age, and what a promotion
+ * requires. READ ONLY by construction: it takes a built sidecar and returns a
+ * string, so there is no path from this function to the disk.
+ */
+export function renderStatus(sidecar: Sidecar): string {
+    const byVerdict: Record<Verdict, number> = { preferred: 0, contested: 0, dead_end: 0 };
+    for (const l of sidecar.lessons) byVerdict[l.verdict] += 1;
+
+    const nowMs = _parseTsMs(sidecar.generated_at) ?? 0;
+    const L: string[] = [];
+    L.push(`${PROG}: ${String(sidecar.lessons.length)} lesson(s) as of ${sidecar.generated_at}`);
+    L.push(
+        `preferred: ${String(byVerdict.preferred)} · ` +
+            `contested: ${String(byVerdict.contested)} · ` +
+            `dead-end: ${String(byVerdict.dead_end)}`,
+    );
+    L.push('');
+
+    const preferred = sidecar.lessons
+        .filter((l) => l.verdict === 'preferred')
+        .sort((a, b) => b.score - a.score || (a.path < b.path ? -1 : 1))
+        .slice(0, STATUS_TOP_N);
+    L.push(`Top ${String(STATUS_TOP_N)} preferred:`);
+    if (preferred.length === 0) {
+        L.push('  (none — a lesson needs corroboration before it appears here)');
+    } else {
+        preferred.forEach((l, i) => {
+            // Age is floored, so a lesson seen hours ago reads `0d old` rather
+            // than rounding up into a day it has not lived.
+            const ageDays = Math.max(0, Math.floor((nowMs - (_parseTsMs(l.last_ts) ?? nowMs)) / 86400000));
+            L.push(
+                `  ${String(i + 1)}. ${l.entry_type} @ ${l.path} — ` +
+                    `${String(l.corroborations)} origins, ${String(ageDays)}d old`,
+            );
+            L.push(`     ${l.body}`);
+        });
+    }
+    L.push('');
+    L.push(
+        `A lesson is promoted at ${String(MIN_CORROBORATIONS)} distinct origins, ` +
+            `weighted by a ${String(HALF_LIFE_DAYS)}-day half-life; nothing here promotes itself.`,
+    );
+    L.push(PROMOTION_HANDOFF);
+    return `${L.join('\n')}\n`;
+}
+
 export function main(argv: string[]): number {
     let intakeDir = path.join('agents', 'memory', 'intake');
     let outDir = path.join('agents', 'memory');
     let nowIso = '';
     let write = false;
-    let format: 'text' | 'json' = 'text';
+    let format: Format = 'text';
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i] as string;
         if (a === '--intake-dir') intakeDir = argv[++i] ?? intakeDir;
         else if (a === '--out-dir') outDir = argv[++i] ?? outDir;
         else if (a === '--now') nowIso = argv[++i] ?? '';
         else if (a === '--write') write = true;
-        else if (a === '--format') format = (argv[++i] as 'text' | 'json') ?? 'text';
-        else if (a === '-h' || a === '--help') {
+        else if (a === '--format') {
+            const raw = argv[++i] ?? '';
+            // Validated rather than cast. With two formats an unknown value
+            // fell through to `text` and looked like it had worked; with three,
+            // a typo in `status` would silently print the one-line text form
+            // and a reader would take that for the screen they asked for.
+            if (!(FORMATS as readonly string[]).includes(raw)) {
+                process.stderr.write(
+                    `${PROG}: error: argument --format: invalid choice: '${raw}' ` +
+                        `(choose from ${FORMATS.map((f) => `'${f}'`).join(', ')})\n`,
+                );
+                return 2;
+            }
+            format = raw as Format;
+        } else if (a === '-h' || a === '--help') {
             process.stdout.write(
-                `usage: ${PROG} [--intake-dir DIR] [--out-dir DIR] [--now ISO] [--write] [--format text|json]\n`,
+                `usage: ${PROG} [--intake-dir DIR] [--out-dir DIR] [--now ISO] [--write] ` +
+                    `[--format ${FORMATS.join('|')}]\n`,
             );
             return 0;
         } else {
@@ -284,6 +383,14 @@ export function main(argv: string[]): number {
             return 2;
         }
     }
+    if (format === 'status' && write) {
+        // Refused, not ignored. The acceptance criterion is that the screen
+        // leaves `git status` identical; ignoring the flag would honour that
+        // too, but it would do so silently, and a caller who asked for a write
+        // deserves to be told it did not happen.
+        process.stderr.write(`${PROG}: error: --format status is read-only; drop --write\n`);
+        return 2;
+    }
     if (!nowIso) {
         // Deterministic by contract: refuse to guess `now` from the clock when
         // writing, so output is reproducible. Callers pass --now explicitly.
@@ -310,6 +417,10 @@ export function main(argv: string[]): number {
         process.stdout.write(JSON.stringify(sidecar, null, 2) + '\n');
         return 0;
     }
+    if (format === 'status') {
+        process.stdout.write(renderStatus(sidecar));
+        return 0;
+    }
     const byVerdict = { preferred: 0, contested: 0, dead_end: 0 };
     for (const l of sidecar.lessons) byVerdict[l.verdict] += 1;
     process.stdout.write(