@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/install.ts

@@ -2,7 +2,7 @@
 /**
  * Agent Config — Project Bridge Installer (TypeScript twin).
  *
- * Ported from the retired Python `src/scripts/install.py` (ADR-200).
+ * Ported from the retired Python installer (ADR-200).
  * The CLI contract pins the historical contract exactly — same flags, same
  * exit codes, same stdout/stderr split, byte-identical emitted output,
  * same filesystem effects, same subprocess argv/cwd/env. No behaviour
@@ -88,8 +88,9 @@ import * as mcp_consent from './_lib/mcp_consent_residual.js';
 import * as scoped_projection from './_lib/scoped_projection.js';
 import { createConflictTracker } from '../install/conflictTracker.js';
 import { mkdirp, pathExists, resolvePath, sha256OfFile } from '../install/fsPrimitives.js';
-import { filesByToolFromBridges as _files_by_tool_from_bridges, filesByToolFromDeploy as _files_by_tool_from_deploy, hydrateRecordedInventories, preservedIndex, readRecordedByTool, reconcileToolFiles, type ManifestFileEntry } from '../install/manifestFiles.js';
+import { dropGlobalScopeFiles, filesByToolFromBridges as _files_by_tool_from_bridges, filesByToolFromDeploy as _files_by_tool_from_deploy, hydrateRecordedInventories, preservedIndex, readRecordedByTool, reconcileToolFiles, type ManifestFileEntry } from '../install/manifestFiles.js';
 import { EXIT_COMPLETED_WITH_CONFLICTS } from '../install/preserve.js';
+import { recordGlobalDeploy, retainedFileMessage } from '../install/ownershipLedger.js';
 import * as surface_tiers from './_lib/surface_tiers.js';
 import * as global_deploy_inventory from './_lib/global_deploy_inventory.js';
 import * as rule_layer_overlap from './_lib/rule_layer_overlap.js';
@@ -105,8 +106,10 @@ import * as catalogue from './_lib/skill_catalogue.js';
 import { isInteractiveSession, type SessionProbe } from '../shared/interactiveContext.js';
 import * as claude_desktop_bundler from './_lib/claude_desktop_bundler.js';
 import * as claude_settings_hooks from './_lib/claude_settings_hooks.js';
+import { applyHostListingPolicies } from './_lib/skill_listing_overrides.js';
 import { hostBindings } from './hooks/host_lowering.js';
 import { find_project_root_with_anchor, load_agent_settings } from './_lib/agent_settings.js';
+import { legacyProjectionPin } from './_lib/projection_key_migration.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';
@@ -116,8 +119,10 @@ import {
     thinInstalledRuleLayer,
 } from '../install/installThinLayer.js';
 import { resolveGlobalRuleScope } from '../install/globalRuleScope.js';
+import { deployClaudeCarrier } from '../install/stagedRuntime.js';
+import { mergeToolsAliases as _merge_tools_aliases } from '../install/toolsArg.js';
 import { installerThinsHost } from './_lib/lean_projection_mode.js';
-import { GLOBAL_DEPLOY_SOURCES, RULE_SOURCE_REL } from '../install/wizard-plan.js';
+import { GLOBAL_DEPLOY_SOURCES, RULE_SOURCE_REL, dryRunTargetLines } 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';
@@ -348,6 +353,7 @@ const LEGACY_RENAME_MAP: Record<string, string> = {
 const state = {
     QUIET: false,
     PROGRESS_NDJSON: false,
+    FULL_PIN: false,
 };
 
 function _emit_progress(obj: Record<string, unknown>): void {
@@ -952,13 +958,7 @@ function ensure_claude_bridge(project_root: string, force: boolean): Record<stri
 // `_lib/mcp_bridge.ts`; only the call sites are here (see that module's header
 // for why). Names are forwarded so the export surface is unchanged.
 const ensure_mcp_bridge = mcp_bridge.makeEnsureMcpBridge(merge_json_file);
-const _resolve_tier_b = mcp_bridge.resolveTierB;
 const _tier_b_advisory = mcp_bridge.tierBAdvisory;
-const _prune_tier_b_modules = (
-    dr: Record<string, DeployResult>,
-    tier_b: ReadonlySet<string>,
-): [number, Record<string, DeployResult>] =>
-    _prune_modules_by(dr, mcp_bridge.tierBPrunePredicate(tier_b));
 
 function _cursor_dispatch_command(ac_event: string, native: string): string {
     // Hook-resilience shim (P1.4): missing binary → silent exit 0; a
@@ -1935,6 +1935,8 @@ interface Options {
     interactive: boolean;
     no_ui: boolean;
     dry_run: boolean;
+    /** `--full`: write the sticky user pin into the install receipt (`src/install/userPin.ts`). */
+    full: boolean;
     apply_payload: string | null;
     /**
      * Which rule layer owns the corpus when both `~/.claude/rules/` and
@@ -2306,7 +2308,7 @@ function _update_installed_tools_manifest(
         }
     }
 
-    installed_tools.write_manifest(target, version, entries);
+    installed_tools.write_manifest(target, version, dropGlobalScopeFiles(entries, scope === 'global' ? tools : new Set()));
     if (!state.QUIET) {
         const rel = isRelativeTo(target, project_root) ? path.relative(project_root, target) : target;
         info(`Manifest updated: ${rel}`);
@@ -2714,7 +2716,7 @@ function _copy_dir_dereferencing_symlinks(
             return [0, 0, written_paths];
         }
         mkdirp(path.dirname(dest));
-        const decision = tracker.resolve(dest, force);
+        const decision = tracker.resolve(dest, force, { from: resolved_src, packageRoot: package_root });
         if (decision === 'preserve') {
             tracker.preserve(dest, resolved_src, package_root);
             _log_tx_entry('skip', dest);
@@ -2789,7 +2791,7 @@ function _copy_dir_dereferencing_symlinks(
         if (file_filter !== null && !file_filter(entry)) {
             continue;
         }
-        const decision = tracker.resolve(target, force);
+        const decision = tracker.resolve(target, force, { from: resolved, packageRoot: package_root });
         if (decision === 'preserve') {
             tracker.preserve(target, resolved, package_root);
             skipped += 1;
@@ -2823,7 +2825,7 @@ function _write_claude_desktop_marker(
     // Generated, but manifest-recorded with a digest — so it is in the class the
     // preservation ruling covers, and it used to write unconditionally, ignoring
     // even `--force`, because the tracker was wired only into the copy loop.
-    if (tracker.resolve(target, force) === 'preserve') {
+    if (tracker.resolve(target, force, { content: body }) === 'preserve') {
         tracker.preserveContent(target, body);
         return [0, 1, []];
     }
@@ -2841,12 +2843,9 @@ function _deploy_claude_desktop(
     claude_desktop_bundler.build_skill_bundles(package_root, bundles_dir, force);
     claude_desktop_bundler.build_command_bundles(package_root, bundles_dir, force);
     const bundle_count = countZips(bundles_dir);
-    const [, , marker_paths] = _write_claude_desktop_marker(
-        force,
-        lockfile_path,
-        bundles_dir,
-        bundle_count,
-    );
+    const [, , marker_paths] = _write_claude_desktop_marker(force, lockfile_path, bundles_dir, bundle_count);
+    // The marker's digest is the ledger's to hold: a global lock entry records no files[].
+    recordGlobalDeploy({ toolId: 'claude-desktop', anchorRaw: USER_SCOPE_PATHS['claude-desktop'] as string, anchor: expanduser(USER_SCOPE_PATHS['claude-desktop'] as string), currentFiles: new Set(['agent-config.md']), destSubs: [], packageTag: PACKAGE_TAG_ID, preserved: tracker.conflictState.preserved, staged: tracker.conflictState.staged, recordedFor: tracker.recordedDigest });
     return [bundle_count, 0, 'deployed', [bundles_dir, ...marker_paths]];
 }
 
@@ -3015,18 +3014,11 @@ function _deploy_global_content(
             );
             // 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)}`);
-                }
-            }
+            deployClaudeCarrier({
+                packageRoot: package_root, rulesDir: path.join(anchor, 'rules'), quiet: state.QUIET, info, warn, userPin: state.FULL_PIN,
+                wantsThin: installerThinsHost(tool_id, { packageRoot: package_root }),
+                thin: (bodyLinkRoot) => describeThinInstalledLayer(thinInstalledRuleLayer({ rulesDir: path.join(anchor, 'rules'), packageRoot: package_root, preserved: preserved_now, bodyLinkRoot })),
+            });
             if (!state.QUIET) for (const l of installReceiptBudgetLines(package_root, undefined, { thisDeploy: new Map([[anchor, current_files]]) })) info(l);
         }
 
@@ -3044,25 +3036,14 @@ function _deploy_global_content(
         }
         _emit_progress({ type: 'verified', tool: tool_id });
 
-        const inventory = global_deploy_inventory.load_inventory();
-        let reaped: string[] = [];
-        const inv_tools = (inventory['tools'] as Record<string, unknown> | undefined) ?? {};
-        if (tool_id in inv_tools) {
-            reaped = reaped.concat(
-                global_deploy_inventory.reap_stale(tool_id, anchor, current_files, inventory),
-            );
-        }
-        reaped = reaped.concat(
-            global_deploy_inventory.reap_tagged_orphans(
-                anchor,
-                plan.map(([, dest_sub]) => dest_sub),
-                current_files,
-                PACKAGE_TAG_ID,
-            ),
-        );
-        reaped = [...new Set(reaped)].sort();
-        global_deploy_inventory.record_deploy(tool_id, anchor_raw, current_files, inventory);
-        global_deploy_inventory.save_inventory(inventory);
+        // Reap, then record the user-scoped ownership ledger — see the module.
+        const { reaped, retained } = recordGlobalDeploy({
+            toolId: tool_id, anchorRaw: anchor_raw, anchor, currentFiles: current_files,
+            destSubs: plan.map(([, dest_sub]) => dest_sub), packageTag: PACKAGE_TAG_ID,
+            preserved: tracker.conflictState.preserved, staged: tracker.conflictState.staged,
+            recordedFor: tracker.recordedDigest,
+        });
+        for (const p of retained) warn(retainedFileMessage(p));
         if (reaped.length > 0 && !state.QUIET) {
             info(
                 `  ${tool_id}: reaped ${reaped.length} stale deployed file(s) ` +
@@ -3072,11 +3053,8 @@ function _deploy_global_content(
         _emit_progress({ type: 'reaped', tool: tool_id, count: reaped.length });
         results[tool_id] = [written_total, skipped_total, 'deployed', written_paths];
 
-        // Single-surface model (road-to-claude-code-single-surface): the
-        // deterministic hook matrix registers directly in the user-scope
-        // settings file — the marketplace plugin is no longer required for
-        // hooks. Failure here must not sink the content deploy (hooks can
-        // be re-wired via `agent-config refresh --global` / doctor).
+        // The hook matrix registers in the user-scope settings file; failure must not sink the
+        // content deploy (re-wire via `agent-config refresh --global` / doctor).
         if (tool_id === 'claude-code') {
             try {
                 const manifest = path.join(package_root, 'src', 'scripts', 'hook_manifest.yaml');
@@ -3151,6 +3129,8 @@ function _preview_global_reap(
                 current_files,
                 PACKAGE_TAG_ID,
                 true,
+                // The ledger spares an edited retired file, so the preview must too.
+                global_deploy_inventory.recorded_digests(tool_id, anchor, inventory),
             ),
         );
         const paths = [...new Set(would_reap.map((p) => String(p)))].sort();
@@ -3296,19 +3276,8 @@ function _rule_filter_for_source(
         ruleFileArrives(srcFile, scope) && !isExclusivelyPackageOnly(srcFile);
 }
 
-/**
- * Prune every skill/command artefact whose `packs:` frontmatter is
- * non-empty AND has no intersection with `active_ids`. Untagged artefacts
- * (empty `packs:` frontmatter) are core/shared and always kept.
- */
-function _prune_scoped_modules(
-    deploy_results: Record<string, DeployResult>,
-    active_ids: ReadonlySet<string>,
-): [number, Record<string, DeployResult>] {
-    return _prune_modules_by(deploy_results, (p) =>
-        scoped_projection.is_pruned_under_scoped(p, active_ids),
-    );
-}
+/** Pack prune that keeps every skill a surviving artefact declares (ADR-289). */
+const _prune_scoped_modules = scoped_projection.prune_scoped_modules;
 
 function install_global(
     tools: Set<string>,
@@ -3438,13 +3407,6 @@ function install_global(
     // here and restores the full tree — never a partial or crashed prune.
     try {
         const { mode, active_packs } = _resolve_scoped_projection(package_root);
-        if (mode === 'tiered') {
-            const outcome = mcp_bridge.applyTieredPrune(deploy_results, package_root, _prune_modules_by);
-            deploy_results = outcome.deployResults;
-            if (!state.QUIET && outcome.message !== null) {
-                (outcome.level === 'warn' ? warn : info)(outcome.message);
-            }
-        }
         if (mode === 'scoped') {
             const packs_registry = _load_packs_registry(package_root);
             const active_ids = _compute_active_pack_ids(packs_registry, active_packs);
@@ -3463,6 +3425,8 @@ function install_global(
             warn(`Scoped-projection prune failed — restoring full tree (${String(e)}).`);
         }
     }
+    // After every prune, so only skills still on disk are computed into the listing override.
+    applyHostListingPolicies({ claudeCode: deploy_results['claude-code']?.[2] === 'deployed', codex: deploy_results['codex']?.[2] === 'deployed' }, os.homedir(), expanduser(USER_SCOPE_PATHS['claude-code']!), state.QUIET ? () => undefined : info);
 
     const failed_tools = new Set<string>(
         Object.keys(deploy_results).filter(
@@ -3758,18 +3722,6 @@ function arrayStrEqual(a: string[], b: string[]): boolean {
 
 // --- Argument parsing ---
 
-function _merge_tools_aliases(tools: string | null, ai: string | null): string {
-    const items: string[] = [];
-    for (const raw of [tools, ai]) {
-        if (!raw) continue;
-        for (const piece of raw.split(',')) {
-            const stripped = piece.trim();
-            if (stripped && !items.includes(stripped)) items.push(stripped);
-        }
-    }
-    return items.length > 0 ? items.join(',') : 'all';
-}
-
 const PROG = 'agent-config install';
 // Verbatim argparse usage block at COLUMNS=80 (captured from the .py). The
 // `--help` BODY (per-flag descriptions) is a documented divergence — argparse
@@ -3782,7 +3734,7 @@ const USAGE =
     '                  [--windsurf-user-hooks] [--gemini-user-hooks]\n' +
     '                  [--project PROJECT] [--package PACKAGE] [--quiet]\n' +
     '                  [--tools TOOLS] [--ai AI] [--packs PACKS] [--core-only]\n' +
-    '                  [--no-smoke] [--global]\n' +
+    '                  [--no-smoke] [--global] [--full]\n' +
     '                  [--scope {project,global,prompt,auto}]\n' +
     '                  [--layer {global,project,both-acknowledged}]\n' +
     '                  [--custom-path CUSTOM_PATH] [--offline] [--minimal]\n' +
@@ -3807,6 +3759,7 @@ const _STORE_TRUE_FLAGS: Record<string, keyof Options> = {
     '--interactive': 'interactive',
     '--no-ui': 'no_ui',
     '--dry-run': 'dry_run',
+    '--full': 'full',
 };
 
 const _VALUE_FLAGS: Record<string, keyof Options> = {
@@ -3856,6 +3809,7 @@ function parse_options(argv: string[]): Options {
         interactive: false,
         no_ui: false,
         dry_run: false,
+        full: false,
         apply_payload: null,
         layer: null,
     };
@@ -4478,7 +4432,7 @@ function _dry_run_summary(opts: Options): number {
     process.stdout.write(`  user-type:   ${opts.user_type || '(none)'}\n`);
     process.stdout.write(`  scope:       ${opts.scope || (opts.global_install ? 'global' : 'auto')}\n`);
     process.stdout.write(`  tools:       ${opts.tools || 'all'}\n`);
-    process.stdout.write(`  target:      ${target}\n`);
+    process.stdout.write(dryRunTargetLines(Boolean(opts.global_install) || opts.scope === 'global', _parse_tools(opts.tools || 'all'), target));
     process.stdout.write(`  minimal:     ${pyBool(opts.minimal)}\n`);
     process.stdout.write(`  force:       ${pyBool(opts.force)}\n`);
     process.stdout.write(`  offline:     ${pyBool(opts.offline)}\n`);
@@ -4567,6 +4521,7 @@ function pyRepr(v: unknown): string {
 function main(argv: string[]): number {
     const opts = parse_options(argv);
     state.QUIET = opts.quiet;
+    state.FULL_PIN = opts.full || _legacy_projection_pin();
 
     if (opts.apply_payload) {
         const payload_path = resolvePath(opts.apply_payload);
@@ -4750,6 +4705,22 @@ function _propose_modules_config(project_root: string, is_first_run: boolean): v
     );
 }
 
+/**
+ * ADR-293's one-window read of the removed projection keys — rules in
+ * `_lib/projection_key_migration.ts`. MACHINE-global layers only, with the
+ * TEMPLATE isolated (ADR-278 / D3: a template value is not consent, and the
+ * shipped template carried `delivery`), and a layer nothing can read states no
+ * preference. `_ABSENT_LAYER` is [project, template]; no tree contains either.
+ */
+const _ABSENT_LAYER: readonly [string, string] = ['project-settings', 'template'].map((n) => path.join(path.sep, 'dev', 'null', `agent-config-absent-${n}.yml`)) as unknown as readonly [string, string];
+function _legacy_projection_pin(): boolean {
+    let data: Record<string, unknown> | null = null;
+    try {
+        data = load_agent_settings({ project_path: _ABSENT_LAYER[0], template_path: _ABSENT_LAYER[1] });
+    } catch { /* empty */ }
+    return legacyProjectionPin(data, (line) => warn(line));
+}
+
 function _read_consumer_auto_switch(project_root: string): string {
     let data: Record<string, unknown>;
     try {
@@ -5101,8 +5072,6 @@ export {
     ensure_cursor_bridge,
     ensure_cline_bridge,
     ensure_mcp_bridge,
-    _prune_tier_b_modules,
-    _resolve_tier_b,
     _tier_b_advisory,
     ensure_windsurf_bridge,
     ensure_gemini_bridge,

package/src/scripts/interruption_report.ts

@@ -94,7 +94,17 @@ export interface RunReport {
     elapsed_minutes: number | null;
     waiting_minutes: number | null;
     working_minutes: number | null;
-    /** `engage` events for this run in `run-continuation.jsonl`. */
+    /**
+     * `engage` events for this run in `run-continuation.jsonl`.
+     *
+     * The concern that wrote that ledger was withdrawn on its own
+     * pre-registered kill date (road-to-what-was-built-and-never-ran Phase 4),
+     * so this reads a HISTORICAL record: three lines, the last from
+     * 2026-08-19. The read is kept because the kill criterion kept the
+     * observation record, and a run that engaged before the withdrawal did
+     * engage. A fresh checkout has no file and the count is 0, which is the
+     * same answer it gave for every run that never engaged.
+     */
     reengagements: number;
     /** `halt-stall` events — the anti-stall rung firing, not the loop working. */
     stall_halts: number;

package/src/scripts/layer_baseline_report.ts

@@ -0,0 +1,267 @@
+#!/usr/bin/env tsx
+/**
+ * The rule layer a setup delivers today, per host, as a reproducible fixture.
+ *
+ * Installed layer: a real `--global --tools=<host>` install into a scratch HOME,
+ * which is the only scope a consumer gets (ADR-020). Projected layer: the
+ * project rule directories of the package root at the measured commit. Hook
+ * commands: what the install wrote into the scratch HOME's claude settings.
+ * Resolved form: the layer-form decision fed the scratch HOME's machine evidence.
+ *
+ * DETERMINISTIC BY EXCLUSION, NOT BY CHANCE. A receipt, lock or install log is
+ * never read: each carries an install time. The scratch root is replaced by
+ * `<HOME>` and the measured checkout by `<PACKAGE_ROOT>` before a hook command
+ * is recorded, and the host's own version is not
+ * read, because it belongs to the machine and not to the commit. What remains is
+ * a function of the package tree, so two runs at one commit are byte-equal.
+ *
+ * REPORT-ONLY: exit 0 whenever every install ran, 1 when one failed, 2 on usage.
+ * Not named `check_*` or `lint_*`, which would enter it into the gate population.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/layer_baseline_report                     # print
+ *   ./scripts-run src/scripts/layer_baseline_report --write             # write the evidence file
+ *   ./scripts-run src/scripts/layer_baseline_report --package-root <dir> # measure another checkout
+ *   ./scripts-run src/scripts/layer_baseline_report --hosts claude-code # a subset
+ */
+
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { GLOBAL_RULE_DIRS, PROJECT_RULE_DIRS } from '../install/globalRuleLayers.js';
+import { decideLayerForm, gatherShippedEvidence, type LayerFormDecision } from './_lib/layer_form_decision.js';
+import { readMachineEvidence, withMachineEvidence } from './_lib/layer_form_evidence.js';
+import { is_thin_entry } from './_lib/thin_rules.js';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+export const REPORT_REL = 'agents/evidence/analysis/setup-layer-baseline.md';
+
+export interface RuleFile {
+    readonly name: string;
+    readonly bytes: number;
+    readonly form: 'full' | 'stub';
+}
+
+export interface LayerFixture {
+    readonly host: string;
+    readonly scope: 'installed' | 'projected';
+    readonly dir: string;
+    readonly present: boolean;
+    readonly files: readonly RuleFile[];
+    readonly bytes: number;
+    readonly full: number;
+    readonly stub: number;
+    readonly digest: string;
+}
+
+export interface HostFixture {
+    readonly host: string;
+    readonly installed: LayerFixture;
+    readonly hookCommands: readonly string[];
+    readonly form: LayerFormDecision;
+}
+
+export interface Baseline {
+    readonly commit: string;
+    readonly packageVersion: string;
+    readonly hosts: readonly HostFixture[];
+    readonly projected: readonly LayerFixture[];
+}
+
+export function readRuleLayer(host: string, scope: LayerFixture['scope'], dir: string, label: string): LayerFixture {
+    const present = fs.existsSync(dir);
+    const names = present ? fs.readdirSync(dir).filter((f) => /\.(md|mdc)$/.test(f)).sort() : [];
+    const files: RuleFile[] = names.map((name) => {
+        const body = fs.readFileSync(path.join(dir, name));
+        return { name, bytes: body.length, form: is_thin_entry(body.toString('utf-8')) ? 'stub' : 'full' };
+    });
+    const digest = createHash('sha256')
+        .update(files.map((f) => `${f.name}\t${f.bytes}\t${f.form}`).join('\n'))
+        .digest('hex')
+        .slice(0, 16);
+    return {
+        host,
+        scope,
+        dir: label,
+        present,
+        files,
+        bytes: files.reduce((n, f) => n + f.bytes, 0),
+        full: files.filter((f) => f.form === 'full').length,
+        stub: files.filter((f) => f.form === 'stub').length,
+        digest,
+    };
+}
+
+export function readHookCommands(home: string, packageRoot?: string): string[] {
+    const settings = path.join(home, '.claude', 'settings.json');
+    if (!fs.existsSync(settings)) return [];
+    const parsed = JSON.parse(fs.readFileSync(settings, 'utf-8')) as {
+        hooks?: Record<string, { matcher?: string; hooks?: { command?: string }[] }[]>;
+    };
+    const out: string[] = [];
+    for (const event of Object.keys(parsed.hooks ?? {})) {
+        for (const group of parsed.hooks?.[event] ?? []) {
+            for (const h of group.hooks ?? []) {
+                if (typeof h.command !== 'string') continue;
+                let command = h.command.split(home).join('<HOME>');
+                if (packageRoot !== undefined) command = command.split(packageRoot).join('<PACKAGE_ROOT>');
+                out.push(`${event}${group.matcher ? ` [${group.matcher}]` : ''}: ${command}`);
+            }
+        }
+    }
+    return out;
+}
+
+function scratchEnv(home: string): NodeJS.ProcessEnv {
+    const env: NodeJS.ProcessEnv = { ...process.env };
+    delete env['AGENT_CONFIG_DEPLOY_INVENTORY'];
+    delete env['AGENT_CONFIG_INSTALLED_TOOLS'];
+    env['HOME'] = home;
+    env['EVENT4U_CONFIG_HOME'] = path.join(home, '.event4u', 'agent-config');
+    env['AGENT_CONFIG_NO_UI'] = '1';
+    env['CI'] = '1';
+    return env;
+}
+
+function readPackageVersion(packageRoot: string): string {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8')) as { version?: unknown };
+        return typeof raw.version === 'string' && raw.version.trim() ? raw.version.trim() : 'unknown';
+    } catch {
+        return 'unknown';
+    }
+}
+
+function readCommit(packageRoot: string): string {
+    const r = spawnSync('git', ['-C', packageRoot, 'rev-parse', '--short=9', 'HEAD'], { encoding: 'utf-8' });
+    return r.status === 0 ? r.stdout.trim() : 'unknown';
+}
+
+export function measureHost(host: string, packageRoot: string, version: string): HostFixture {
+    const scratch = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'layer-baseline-')));
+    try {
+        const home = path.join(scratch, 'home');
+        const cwd = path.join(scratch, 'cwd');
+        fs.mkdirSync(home);
+        fs.mkdirSync(cwd);
+        const env = scratchEnv(home);
+        const r = spawnSync('bash', [path.join(packageRoot, 'src', 'scripts', 'install'), '--global', `--tools=${host}`, '--yes', '--quiet'], {
+            cwd,
+            env,
+            encoding: 'utf-8',
+            timeout: 240_000,
+        });
+        if (r.status !== 0) throw new Error(`install --tools=${host} exited ${String(r.status)}:\n${r.stdout}\n${r.stderr}`);
+        const rel = GLOBAL_RULE_DIRS[host] as string;
+        const installed = readRuleLayer(host, 'installed', path.join(home, rel), `<HOME>/${rel}`);
+        const machine = readMachineEvidence(packageRoot, { HOME: home, EVENT4U_CONFIG_HOME: env['EVENT4U_CONFIG_HOME'] });
+        const form = decideLayerForm(withMachineEvidence(gatherShippedEvidence(packageRoot, version)(host), machine));
+        return { host, installed, hookCommands: readHookCommands(home, packageRoot), form };
+    } finally {
+        fs.rmSync(scratch, { recursive: true, force: true });
+    }
+}
+
+export function buildBaseline(packageRoot: string, hosts: readonly string[]): Baseline {
+    const version = readPackageVersion(packageRoot);
+    const projected = Object.keys(PROJECT_RULE_DIRS)
+        .sort()
+        .map((rel) => readRuleLayer(PROJECT_RULE_DIRS[rel] as string, 'projected', path.join(packageRoot, rel), rel));
+    return {
+        commit: readCommit(packageRoot),
+        packageVersion: version,
+        hosts: hosts.map((h) => measureHost(h, packageRoot, version)),
+        projected,
+    };
+}
+
+function layerRow(l: LayerFixture, form: string): string {
+    return `| ${l.host} | ${l.scope} | \`${l.dir}\` | ${l.present ? l.files.length : 'absent'} | ${l.bytes} | ${l.full} | ${l.stub} | \`${l.digest}\` | ${form} |`;
+}
+
+export function renderBaseline(b: Baseline): string {
+    const lines = [
+        '<!-- evidence-type: analysis -->',
+        '# Setup layer baseline',
+        '',
+        `Measured at commit \`${b.commit}\`, package version \`${b.packageVersion}\`, by`,
+        '`./scripts-run src/scripts/layer_baseline_report`. Every row below names that commit.',
+        '',
+        'Excluded so that two runs at one commit are byte-equal: the install receipt, lock and',
+        'log (each carries an install time), the scratch root (recorded as `<HOME>`), the',
+        'measured checkout (recorded as `<PACKAGE_ROOT>`), and the host\'s own version (a',
+        'property of the machine, not of the commit).',
+        '',
+        '| host | scope | dir | files | bytes | full | stub | file-set digest | resolved form |',
+        '|---|---|---|---|---|---|---|---|---|',
+    ];
+    for (const h of b.hosts) lines.push(layerRow(h.installed, `${h.form.form} (${h.form.reason})`));
+    for (const p of b.projected) lines.push(layerRow(p, 'project tree, not decided per machine'));
+    lines.push('', '## Hook commands written', '');
+    for (const h of b.hosts) {
+        lines.push(`### ${h.host} — ${h.hookCommands.length} command(s)`, '');
+        if (h.hookCommands.length === 0) lines.push('None written.', '');
+        else lines.push('~~~text', ...h.hookCommands, '~~~', '');
+    }
+    lines.push('## File sets', '');
+    const seen = new Set<string>();
+    for (const l of [...b.hosts.map((h) => h.installed), ...b.projected]) {
+        if (!l.present || seen.has(l.digest)) continue;
+        seen.add(l.digest);
+        lines.push(`### \`${l.digest}\``, '', '~~~text', ...l.files.map((f) => `${f.name}\t${f.bytes}\t${f.form}`), '~~~', '');
+    }
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+
+interface Args {
+    readonly write: boolean;
+    readonly packageRoot: string;
+    readonly hosts: readonly string[];
+}
+
+export function parseArgs(argv: readonly string[]): Args | null {
+    let write = false;
+    let packageRoot = REPO_ROOT;
+    let hosts: string[] = Object.keys(GLOBAL_RULE_DIRS).sort();
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === '--write') write = true;
+        else if (a === '--package-root' && argv[i + 1] !== undefined) packageRoot = path.resolve(argv[++i] as string);
+        else if (a === '--hosts' && argv[i + 1] !== undefined) {
+            hosts = (argv[++i] as string).split(',').filter(Boolean);
+            if (hosts.some((h) => !(h in GLOBAL_RULE_DIRS))) return null;
+        } else return null;
+    }
+    return { write, packageRoot, hosts };
+}
+
+export function main(argv: readonly string[]): number {
+    const args = parseArgs(argv);
+    if (args === null) {
+        process.stderr.write(
+            `usage: layer_baseline_report [--write] [--package-root <dir>] [--hosts ${Object.keys(GLOBAL_RULE_DIRS).sort().join(',')}]\n`,
+        );
+        return 2;
+    }
+    let report: string;
+    try {
+        report = renderBaseline(buildBaseline(args.packageRoot, args.hosts));
+    } catch (e) {
+        process.stderr.write(`layer_baseline_report: ${(e as Error).message}\n`);
+        return 1;
+    }
+    if (args.write) {
+        fs.writeFileSync(path.join(REPO_ROOT, REPORT_REL), report);
+        process.stdout.write(`wrote ${REPORT_REL}\n`);
+    } else process.stdout.write(report);
+    return 0;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/learning_sidecar.ts

@@ -43,7 +43,7 @@ const PROG = 'learning_sidecar.ts';
 
 /** Half-life of a signal's weight, in days. */
 export const HALF_LIFE_DAYS = 30;
-/** Distinct origins required before a lesson is promoted. */
+/** Distinct origins required before a lesson is promoted — the local row of the evidence threshold in docs/contracts/retro-v1.md. */
 export const MIN_CORROBORATIONS = 2;
 // cache-invalidation: regenerated wholesale from the intake JSONL on every run
 // (no incremental/partial state); the in-file `schema_version` field is the

package/src/scripts/lint_agents_layout.ts

@@ -35,6 +35,9 @@ const AGENTS_ROOT = 'agents';
 const ALLOWED_FLAT_FILES: ReadonlySet<string> = new Set([
     'index.md',
     'roadmaps-progress.md',
+    // Generated owned-roadmap digest; beside the dashboard because inside
+    // `roadmaps/` every active-roadmap glob would read it as a roadmap.
+    'roadmaps-owned.md',
     '.gitkeep',
     '.event4u-bridge.yml',
     '.agent-tools.yml',