@event4u/agent-config 16.1.0 → 16.3.0

package/dist/install/installThinLayer.js

@@ -0,0 +1,261 @@
+/**
+ * Thin an INSTALLED Claude Code rule layer, in place, after the copy.
+ *
+ * `road-to-an-installed-layer-that-is-thinned` step 1.1. The global install step
+ * copies `dist/agent-src/rules` verbatim into `~/.claude/rules`
+ * (`install.ts::_copy_dir_dereferencing_symlinks`), so a consumer receives every
+ * rule body whether or not any trigger ever fires. The round that opened that
+ * roadmap measured a fresh install at 102 unconditional files and 338,225
+ * characters against a host that reports a 150,000 budget. Thinning existed —
+ * `project_thin_rules::build_thin` — but ran only on the maintainer projection,
+ * which no consumer receives.
+ *
+ * Three properties, each a defect this would otherwise reintroduce.
+ *
+ * **The stub is built from the SOURCE tree, never from the installed file.**
+ * `claudeRuleRewrite` runs immediately before this and reduces each installed
+ * rule to the host's activation vocabulary — `paths:` plus the ownership keys —
+ * dropping `description:` and the `triggers:` block. Those two are exactly what
+ * `thin_entry` reads to write the stub's matching signal, so a stub built from
+ * the rewritten file would carry an empty description and no `Fires on:` hint.
+ * Reading `<packageRoot>/dist/agent-src/rules/<name>` keeps the signal intact.
+ *
+ * **The installed frontmatter is kept verbatim.** The roadmap's step 1.1 ends
+ * "Ownership keys survive", and it is not decoration: `reap_tagged_orphans`
+ * calls the literal `package:` line "the only path with ownership proof
+ * independent of inventory history", and doctor's stale-orphan check reads the
+ * same tag. A stub that replaced the whole file would delete the reaper's only
+ * evidence for every thinned rule. So only the BODY is replaced; the header the
+ * copy and the rewrite produced is written back unchanged, which also preserves
+ * any `paths:` block — harmless, since a path-only rule is never thinned.
+ *
+ * **A user-modified file is skipped, not overwritten.** The preserved set comes
+ * from the conflict tracker, the same one the copy consulted. Step 1.3 requires
+ * an upgrade to preserve and report those files; thinning one would destroy an
+ * edit the copy had just declined to destroy.
+ *
+ * The rollback of step 1.2 needs nothing here, and the reason is the ordering.
+ *
+ * The install manifest records each deployed file's digest from the bytes ON
+ * DISK at manifest-write time, which is after this pass. So the next run sees
+ * `recorded-unchanged` for a thinned file, `decideDeployWrite` returns `write`,
+ * and the verbatim copy restores the full body. Switching the mode back to
+ * `eager-all` therefore un-thins by simply not running this pass — no inverse
+ * operation, and no stub left behind. The property that carries it is the
+ * ordering, which `tests/scripts/install_thin_layer.test.ts` pins directly.
+ *
+ * Side-effect-free apart from the writes it is asked to make. No CLI entry, no
+ * `process.exit` — this module is reachable from the `build:install-bundle`
+ * entry and `check_installer_import_purity` forbids both.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { buildHostLimitRows, loadHostInstructionLimits, readLayer, renderHostLimitRows, } from '../scripts/_lib/installed_layer.js';
+import { GLOBAL_RULE_DIRS, globalRuleLayerPath } from './globalRuleLayers.js';
+import { manifest_path } from '../scripts/_lib/installed_tools.js';
+import { NO_RECORDED_HASHES, readRecordedHashes } from './recordedOwnership.js';
+import { absoluteBodyLinkPrefix, build_thin, split_frontmatter, } from '../scripts/_lib/thin_rules.js';
+/**
+ * Replace the body of every thinnable rule in `rulesDir` with its stub.
+ *
+ * Idempotent: a layer already thinned is rewritten to byte-identical content,
+ * so a repeated install neither grows nor drifts.
+ */
+export function thinInstalledRuleLayer(opts) {
+    const packageRoot = path.resolve(opts.packageRoot);
+    const bodySourceDir = path.join(packageRoot, 'dist', 'agent-src', 'rules');
+    const bodyLinkPrefix = absoluteBodyLinkPrefix(packageRoot);
+    const preserved = opts.preserved ?? new Set();
+    // Scope is `null` on purpose. The copy already applied the install's rule
+    // scope, so the files that EXIST in `rulesDir` are the scoped set; asking
+    // `build_thin` to resolve the scope a second time would be a second reader
+    // of the same decision, and the two could disagree. Anything the stub map
+    // names that is not on disk is simply out of scope and is reported as such.
+    const stubs = build_thin(bodySourceDir, null, null, null, { packageRoot, bodyLinkPrefix });
+    let thinned = 0;
+    let rewritten = 0;
+    let kept = 0;
+    let charsBefore = 0;
+    let charsAfter = 0;
+    const preservedHits = [];
+    const absent = [];
+    const failed = [];
+    for (const [name, stubText] of stubs) {
+        const target = path.join(opts.rulesDir, name);
+        let installed;
+        try {
+            installed = fs.readFileSync(target, 'utf-8');
+        }
+        catch (e) {
+            // ENOENT is the documented meaning of `absent` — the copy's rule
+            // scope did not place this rule here. Anything else (EACCES, EISDIR,
+            // EIO) is a FAILURE wearing a scoping outcome's clothes, and the
+            // receipt prints failures and does not print absences, so the two
+            // must not share a bucket.
+            if (e.code === 'ENOENT')
+                absent.push(name);
+            else
+                failed.push({ rule: name, reason: String(e) });
+            continue;
+        }
+        // KEPT-VS-THINNED IS DECIDED BY IDENTITY, NOT BY A CONTENT SNIFF.
+        // `build_thin` returns either a stub or the SOURCE TEXT VERBATIM, so
+        // the full-bodied branch is exactly "the map value equals the source
+        // file". Testing `is_thin_entry(stubText)` instead would misread a
+        // source rule whose own body happened to contain the marker — and that
+        // rule would then be written as `installedFrontmatter + fullSourceText`,
+        // duplicating the frontmatter block. Zero such rules ship today, which
+        // makes it latent rather than live, and `THIN_ENTRY_MARKER`'s own
+        // docstring argues against exactly this kind of inferred detection.
+        let sourceText;
+        try {
+            sourceText = fs.readFileSync(path.join(bodySourceDir, name), 'utf-8');
+        }
+        catch {
+            sourceText = null;
+        }
+        if (stubText === sourceText) {
+            // Kept full-bodied by `build_thin`'s own predicate — kernel,
+            // trigger-less, path-only, or a declared `no_stub` member. The
+            // installed copy is already the right shape; touching it would be
+            // this pass inventing a decision the projector did not make.
+            kept += 1;
+            charsBefore += installed.length;
+            charsAfter += installed.length;
+            continue;
+        }
+        if (preserved.has(path.resolve(target))) {
+            preservedHits.push(name);
+            charsBefore += installed.length;
+            charsAfter += installed.length;
+            continue;
+        }
+        const [frontmatter] = split_frontmatter(installed);
+        charsBefore += installed.length;
+        // `split_frontmatter` answers `['', text]` for a file that OPENS a
+        // frontmatter block and never closes it — a truncated write, a file
+        // ending exactly on the closing fence with no trailing newline, CRLF.
+        // Writing `'' + stub` there would delete the `package:` line this
+        // module's header calls the reaper's only evidence, which is the one
+        // corruption this pass could cause. A file that claims a block it does
+        // not have is left exactly as found and reported.
+        //
+        // The test is a REGEX rather than `startsWith('---')` because the
+        // claim can be preceded by a BOM or by leading whitespace, and either
+        // one took the prefix check's "no block here" branch straight into the
+        // write it exists to prevent.
+        if (frontmatter === '' && /^\uFEFF?[\s]*---/.test(installed)) {
+            failed.push({
+                rule: name,
+                reason: 'opens a frontmatter block that never closes — left untouched so its ' +
+                    'ownership keys survive',
+            });
+            charsAfter += installed.length;
+            continue;
+        }
+        const next = `${frontmatter}${stubText}`;
+        try {
+            if (next !== installed) {
+                fs.writeFileSync(target, next, 'utf-8');
+                rewritten += 1;
+            }
+            thinned += 1;
+            charsAfter += next.length;
+        }
+        catch (e) {
+            failed.push({ rule: name, reason: String(e) });
+            charsAfter += installed.length;
+        }
+    }
+    if (stubs.size === 0) {
+        // A ZERO-STUB MAP AND A ZERO-THINNABLE LAYER PRINT THE SAME RECEIPT, so
+        // the one that is a failure has to say so. `_globSortedMd` swallows an
+        // unreadable directory and answers `[]`, which is what a wrongly
+        // resolved package root produces — the hazard `ThinRoots` exists for.
+        // Without this the feature would be silently not applied behind a
+        // success-shaped line, and the installer's try/catch sees only throws.
+        failed.push({
+            rule: bodySourceDir,
+            reason: 'no rule bodies found to build stubs from — the layer was left full-bodied',
+        });
+    }
+    return {
+        thinned,
+        rewritten,
+        kept,
+        preserved: preservedHits,
+        absent,
+        failed,
+        bodyLinkPrefix,
+        charsBefore,
+        charsAfter,
+    };
+}
+/**
+ * One receipt line per outcome, for a caller that prints.
+ *
+ * Returns the lines rather than writing them, so the installer's `--quiet` and
+ * its progress-event emitter stay the only things deciding what a consumer sees.
+ */
+export function describeThinInstalledLayer(res) {
+    const out = [];
+    out.push(res.rewritten === 0 && res.thinned > 0
+        ? `  claude-code: ${String(res.thinned)} rule(s) already thinned, ` +
+            `${String(res.kept)} kept full-bodied; ` +
+            `${String(res.charsAfter)} chars — nothing to rewrite`
+        : `  claude-code: thinned ${String(res.rewritten)} rule(s) to stubs, ` +
+            `${String(res.kept)} kept full-bodied; ` +
+            `${String(res.charsBefore)} -> ${String(res.charsAfter)} chars`);
+    if (res.preserved.length > 0) {
+        out.push(`  claude-code: ${String(res.preserved.length)} rule(s) left full — you edited them ` +
+            `and they are preserved, never overwritten (${res.preserved.join(', ')})`);
+    }
+    for (const f of res.failed) {
+        out.push(`  claude-code: ${f.rule}: could not write stub — ${f.reason}`);
+    }
+    return out;
+}
+/**
+ * The install receipt's instruction-budget block — step 1.4's "at install".
+ *
+ * The step asks for the limit, the split and the 80 % warning AT INSTALL, and
+ * the measurement existed only behind the standalone `installed_layer_report`
+ * CLI: `buildHostLimitRows`'s own docstring named "the install receipt" as the
+ * caller it was exported for, and that caller did not exist. A consumer whose
+ * layer is over budget learned it from the host, which is the notice the
+ * roadmap exists to remove.
+ *
+ * Global layers only, deliberately. The install writes `~/.claude/rules` and
+ * its siblings; a project layer is not what this run just changed, and folding
+ * one in would make the receipt's number disagree with the thing it is a
+ * receipt FOR.
+ *
+ * Never throws. A receipt that cannot be measured is silent rather than fatal —
+ * the deploy it describes has already happened correctly.
+ */
+export function installReceiptBudgetLines(packageRoot, home = os.homedir()) {
+    try {
+        const recorded = (() => {
+            try {
+                return readRecordedHashes(manifest_path(packageRoot), packageRoot);
+            }
+            catch {
+                return NO_RECORDED_HASHES;
+            }
+        })();
+        const layers = [];
+        for (const host of Object.keys(GLOBAL_RULE_DIRS).sort()) {
+            const dir = globalRuleLayerPath(host, home);
+            if (dir === null)
+                continue;
+            layers.push(readLayer(host, 'global', dir, recorded));
+        }
+        const rows = buildHostLimitRows(layers, loadHostInstructionLimits());
+        return rows.length === 0 ? [] : renderHostLimitRows(rows).map((l) => `  ${l}`);
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=installThinLayer.js.map

package/dist/install/installedRuleLinks.js

@@ -0,0 +1,176 @@
+/**
+ * Do the links inside an installed rule file resolve from where the install
+ * puts it?
+ *
+ * A rule body is authored in `src/rules/` and projected to
+ * `dist/agent-src/rules/`, where `](../guidelines/x.md)` resolves because the
+ * sibling directory is right there. The installer then copies a SUBSET of
+ * those sibling directories into the host's rule directory, so the same link
+ * resolves or does not depending on a list in `install.ts` that the rule
+ * author never sees. Nothing checked the two against each other.
+ *
+ * This module answers one question per link — resolved, or why not — against a
+ * deploy plan rather than against a materialised tree, so the audit costs a
+ * `statSync` per distinct target instead of a copy of 299 skills.
+ *
+ * Side-effect-free, no CLI entry, no `process.exit`.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Build a plan from `GLOBAL_DEPLOY_SOURCES`-shaped pairs.
+ *
+ * The empty destination (`cline` maps rules to the root) is deliberately kept:
+ * a rule installed at the root resolves `../x` differently, and silently
+ * dropping the entry would make this module answer a question about a layout
+ * that is not the one being installed.
+ */
+export function deployPlanFrom(pairs) {
+    const plan = new Map();
+    for (const [source, dest] of pairs)
+        plan.set(dest, source);
+    return plan;
+}
+/** Markdown inline links, minus the ones that are not a path into the tree. */
+export function relativeLinkTargets(markdown) {
+    const out = [];
+    for (const m of markdown.matchAll(/\]\(([^)\s]+)\)/g)) {
+        const target = m[1];
+        if (/^[a-z][a-z0-9+.-]*:/i.test(target))
+            continue; // http:, mailto:, etc.
+        if (target.startsWith('#'))
+            continue; // same-file anchor
+        if (target.startsWith('/'))
+            continue; // absolute — not ours to resolve
+        out.push(target);
+    }
+    return out;
+}
+/** Strip a trailing `#anchor`; a bare directory link keeps its trailing slash. */
+function withoutAnchor(target) {
+    const hash = target.indexOf('#');
+    return hash === -1 ? target : target.slice(0, hash);
+}
+/**
+ * Audit one link written in a rule that the install places at
+ * `<install-root>/<rulesDest>/<rule>.md`.
+ */
+export function auditLink(rule, target, rulesDest, plan, packageRoot) {
+    const bare = withoutAnchor(target);
+    // Resolve the link the way a reader does: from the installed file's own
+    // DIRECTORY — `rulesDest` is that directory, not the file — as a POSIX
+    // path relative to the install root. A sibling link (`[x](other.md)`, no
+    // `../`) therefore stays inside the rules directory, which is where the
+    // installer puts its sibling.
+    const fromDir = rulesDest === '' ? '.' : rulesDest;
+    const resolved = path.posix.normalize(path.posix.join(fromDir, bare));
+    if (resolved.startsWith('..')) {
+        return { rule, target, resolved_to: null, verdict: 'outside-install-root' };
+    }
+    const segments = resolved.split('/');
+    // Which deployed directory does this land in? Normally the first segment
+    // names it. When rules install at the install ROOT (`cline` maps them to
+    // `''`), there is no such segment: a sibling link like `](scope-control.md)`
+    // resolves to `scope-control.md`, whose first segment is a FILE NAME. Read
+    // literally that is `directory-not-deployed` for a file the install writes
+    // right beside the rule — 275 of cline's 523 links, every one of them fine.
+    // The `''` key exists in the plan precisely for this and could never be
+    // reached by a first-segment lookup.
+    const rootSource = plan.get('');
+    // The root entry answers for a BARE filename only. A link with a directory
+    // segment the plan does not carry is `directory-not-deployed`, the same as
+    // anywhere else — resolving it against the rules source would probe a path
+    // the install never writes and report `file-missing`, whose documented
+    // meaning ("the directory IS deployed") would then be false.
+    const useRoot = rootSource !== undefined && segments.length === 1;
+    const source = useRoot ? rootSource : plan.get(segments[0]);
+    const rest = useRoot ? segments : segments.slice(1);
+    if (source === undefined) {
+        return { rule, target, resolved_to: resolved, verdict: 'directory-not-deployed' };
+    }
+    // An empty `rest` means the link points at the deployed directory itself.
+    const onDisk = path.join(packageRoot, source, ...rest);
+    const exists = fs.existsSync(onDisk);
+    return {
+        rule,
+        target,
+        resolved_to: resolved,
+        verdict: exists ? 'resolved' : 'file-missing',
+    };
+}
+const EMPTY_COUNTS = () => ({
+    resolved: 0,
+    'outside-install-root': 0,
+    'directory-not-deployed': 0,
+    'file-missing': 0,
+});
+/**
+ * Audit every link in every rule the plan installs.
+ *
+ * `packageRoot` is the package checkout the installer copies FROM; the rule
+ * bodies are read from the plan's own rules source, so the audit cannot drift
+ * from what is shipped.
+ */
+export function auditInstalledRuleLinks(plan, packageRoot) {
+    const audits = [];
+    for (const [dest, source] of plan) {
+        if (!source.endsWith('/rules'))
+            continue;
+        const dir = path.join(packageRoot, source);
+        if (!fs.existsSync(dir))
+            continue;
+        const files = fs
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((e) => !e.isDirectory() && e.name.endsWith('.md'))
+            .map((e) => e.name)
+            .sort();
+        for (const file of files) {
+            const rule = file.replace(/\.md$/, '');
+            const body = fs.readFileSync(path.join(dir, file), 'utf8');
+            for (const target of relativeLinkTargets(body)) {
+                audits.push(auditLink(rule, target, dest, plan, packageRoot));
+            }
+        }
+    }
+    const counts = EMPTY_COUNTS();
+    for (const a of audits)
+        counts[a.verdict] += 1;
+    const grouped = new Map();
+    for (const a of audits) {
+        if (a.verdict === 'resolved')
+            continue;
+        const key = a.resolved_to === null ? a.target.replace(/[^/]*$/, '') : a.resolved_to.split('/')[0];
+        const row = grouped.get(key);
+        if (row)
+            row.count += 1;
+        else
+            grouped.set(key, { count: 1, verdict: a.verdict });
+    }
+    const by_directory = [...grouped.entries()]
+        .map(([directory, v]) => ({ directory, count: v.count, verdict: v.verdict }))
+        .sort((a, b) => b.count - a.count || a.directory.localeCompare(b.directory));
+    return { audits, counts, by_directory };
+}
+/**
+ * Standing-text cost of the rewrite option, in characters.
+ *
+ * Option A of this roadmap's step 1.2: leave the install plan alone and
+ * rewrite every link to an absolute package path. Each unresolved link then
+ * grows by the absolute prefix minus the `../` it replaces — and it grows
+ * INSIDE a rule body, which is the text the host loads as instructions.
+ *
+ * `prefixChars` is the installed package root's own length, which is a
+ * property of the machine, so the caller supplies it and the report says which
+ * value it used.
+ */
+export function rewriteOptionCost(report, prefixChars) {
+    const unresolved = report.audits.filter((a) => a.verdict !== 'resolved');
+    let total = 0;
+    for (const a of unresolved) {
+        // `../x` and `../../x` both become `<abs>/x`: the climb is replaced.
+        const climb = (a.target.match(/\.\.\//g) ?? []).length * 3;
+        total += prefixChars + 1 - climb;
+    }
+    return total;
+}
+//# sourceMappingURL=installedRuleLinks.js.map

package/dist/install/wizard-plan.js

@@ -59,6 +59,30 @@ export const USER_SCOPE_PATHS = {
 /**
  * Universal Anthropic-shaped skill bundle deployed to markdown-skills
  * tools. Mirrors `_CLAUDE_SKILL_BUNDLE` in the retired Python installer (ADR-200).
+ *
+ * NOT deploying `contexts/` and `guidelines/` here is a held decision, not an
+ * oversight — see the `rule-link-targets-change-the-frozen-install-abi` blocker
+ * on `road-to-rule-triggers-and-links-that-hold`.
+ *
+ * A rule is authored against the package tree and projected verbatim, so
+ * `](../guidelines/x.md)` resolves in `dist/agent-src/rules/` and then does
+ * not resolve in the install, because this table does not carry those two
+ * directories. Measured by `report_installed_rule_links` on 2026-10-03: 136 of
+ * 523 links in an installed Claude rule directory point nowhere, 112 of them
+ * into exactly those two. Adding them is the cheaper of the two repairs on the
+ * budget that is scarce — 0 standing characters against **5,152** for rewriting
+ * those same 112 links to absolute package paths, at a 48-character install
+ * prefix (the report prints the prefix it used; the figure scales with it).
+ *
+ * The totals were 160 of 550 when this was first measured and 158 of 545 on
+ * 2026-10-02; what fell since is the OTHER population — repo-tree link forms no
+ * install ever held — so the 112 this paragraph is about has not moved.
+ *
+ * It is held because this table is part of the FROZEN install ABI
+ * (`docs/contracts/install-layout.md`), and any change to it owes an
+ * `install_layout_version` bump plus a deprecation window: old and new shape
+ * side by side for a minor cycle, with in-place migration. That is a release
+ * commitment, not an implementation detail, so it is the owner's to make.
  */
 const CLAUDE_SKILL_BUNDLE = [
     ['dist/agent-src/rules', 'rules'],

package/dist/mcp/registry-manifest.json

@@ -1,15 +1,15 @@
 {
   "discovery": {
-    "artefact_count": 625,
+    "artefact_count": 627,
     "scanner_version": "de0a22b4ac4c"
   },
-  "generated_at": "2026-09-28",
+  "generated_at": "2026-10-05",
   "package": {
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) \u2014 every claim machine-checked, including the counts in these badges.",
     "homepage": "https://event4u-app.github.io/agent-config",
     "name": "@event4u/agent-config",
     "repository": "https://github.com/event4u-app/agent-config",
-    "version": "16.1.0"
+    "version": "16.3.0"
   },
   "registries": [
     {

package/dist/mcp/server.json

@@ -9,12 +9,12 @@
       "transport": {
         "type": "stdio"
       },
-      "version": "16.1.0"
+      "version": "16.3.0"
     }
   ],
   "repository": {
     "source": "github",
     "url": "https://github.com/event4u-app/agent-config"
   },
-  "version": "16.1.0"
+  "version": "16.3.0"
 }