@event4u/agent-config 14.21.0 → 14.22.0

package/src/scripts/_lib/packed_binary_predicate.ts

@@ -0,0 +1,225 @@
+/**
+ * Binary-payload eligibility — the mechanically verified predicate that
+ * reopened the `binary` class.
+ *
+ * WHAT THIS IS, SAID PLAINLY.
+ *
+ * `f573d628c` closed `binary` as a hard zero on 2026-09-07. This REOPENS it,
+ * 24 hours later, and that IS A WEAKENING OF A CONTROL. An AI council
+ * (2026-09-08, 2 seats, unanimous, deep tier) authorised it, and one seat
+ * explicitly refused the framing that this is merely "correcting an
+ * over-generalisation" — that distinction is cosmetic. The control was closed
+ * for the wrong reason, so reopening it is a weakening: justified, and still a
+ * weakening. It is written down here rather than softened because a control
+ * that gets quietly relaxed is worse than one that never existed.
+ *
+ * WHY THE CLOSURE WAS WRONG.
+ *
+ * Decision A over-generalised. Its reasoning was "the three observed binaries
+ * are unused, therefore no binary can ever be required" — an invalid
+ * generalisation from an observed sample to a universal rule. The vendored
+ * tree-sitter grammars are the direct counterexample: bytes the production path
+ * loads and the engine requires. A textual placeholder was lossless for three
+ * PNGs nothing decoded; for a grammar it does not degrade a fixture, it breaks
+ * the engine.
+ *
+ * WHAT REPLACES THE HARD ZERO — AND WHAT DOES NOT.
+ *
+ * Not a prose exception. A binary is admitted only when EVERY condition below
+ * is verified mechanically, on the bytes that are actually in the tarball:
+ *
+ *   1. exactly one manifest entry for the path
+ *   2. no wildcard or directory grant anywhere in the manifest
+ *   3. the packed tarball really contains the path
+ *   4. sha256(bytes) equals the manifest hash
+ *   5. size equals the manifest size
+ *   6. kind is `tree-sitter-wasm-grammar`
+ *   7. WASM magic and version are valid
+ *   8. the PRODUCTION loader reports the manifest's grammar_id
+ *   9. the PRODUCTION loader reports the manifest's ABI
+ *  10. a defined invalid-header mutation of the bytes is REJECTED
+ *  11. a defined unsupported-ABI expectation is REJECTED
+ *
+ * 8 and 9 go through `probeGrammarFile`, the engine's own loader, deliberately:
+ * a second implementation inside the gate could accept bytes the engine
+ * rejects, which is exactly the gap that would let a broken grammar ship while
+ * the gate called it valid.
+ *
+ * 10 and 11 run on every invocation, not in a separate test, because a
+ * predicate whose refusals nobody exercises is a predicate nobody has checked.
+ *
+ * `archive` IS NOT REOPENED.
+ *
+ * This collision produced evidence about grammars and none whatsoever about
+ * archives. `archive` stays a hard zero with no manifest path, and this module
+ * offers none.
+ *
+ * ELIGIBILITY NEVER TOUCHES THE MEASUREMENT.
+ *
+ * The gate reports `observed` as the true count and byte total on every run.
+ * Compliance is `observed <= allowed`, where `allowed` is the number of entries
+ * that passed every condition above — never `observed` minus something excused.
+ * A file that fails one condition lowers `allowed`; it never disappears from
+ * `observed`.
+ */
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** One manifest row. Path-exact; `why` is documentation, never a condition. */
+export interface PackedBinaryEntry {
+    readonly path: string;
+    readonly sha256: string;
+    readonly size: number;
+    readonly kind: string;
+    readonly grammar_id: string;
+    readonly abi: number;
+    readonly why?: string;
+}
+
+export interface PackedBinaryManifest {
+    readonly schema_version: number;
+    readonly entries: readonly PackedBinaryEntry[];
+}
+
+/** The one kind this predicate knows how to verify. */
+export const VERIFIABLE_KIND = 'tree-sitter-wasm-grammar';
+
+/** What the production loader reported for a file. */
+export interface GrammarProbe {
+    readonly abi: number;
+    readonly grammar_id: string;
+}
+
+/** A per-file verdict, with the failing condition named. */
+export interface EligibilityVerdict {
+    readonly path: string;
+    readonly eligible: boolean;
+    /** Every condition that failed, in predicate order. Empty iff eligible. */
+    readonly failures: readonly string[];
+}
+
+/** WASM preamble: `\0asm` followed by little-endian version 1. */
+const WASM_MAGIC = [0x00, 0x61, 0x73, 0x6d] as const;
+const WASM_VERSION = [0x01, 0x00, 0x00, 0x00] as const;
+
+/**
+ * Condition 7, on its own so the header mutation in condition 10 has something
+ * specific to defeat.
+ */
+export function wasmMagicAndVersionValid(bytes: Uint8Array): boolean {
+    if (bytes.length < 8) return false;
+    for (let i = 0; i < 4; i += 1) if (bytes[i] !== WASM_MAGIC[i]) return false;
+    for (let i = 0; i < 4; i += 1) if (bytes[4 + i] !== WASM_VERSION[i]) return false;
+    return true;
+}
+
+/**
+ * The DEFINED invalid-header mutation for condition 10.
+ *
+ * One byte of the magic, flipped. Deliberately NOT `corrupt(bytes)`: arbitrary
+ * corruption can land in a custom section and leave a still-valid module, or
+ * hit padding and change nothing, so a test built on it can pass while proving
+ * nothing. This targets a property the predicate actually validates.
+ */
+export function definedInvalidHeaderMutation(bytes: Uint8Array): Uint8Array {
+    const out = Uint8Array.from(bytes);
+    if (out.length > 1) out[1] = (out[1] as number) ^ 0xff;
+    return out;
+}
+
+/**
+ * The DEFINED unsupported-ABI expectation for condition 11.
+ *
+ * The ABI is not a byte at a known offset — it is what the loader reports after
+ * parsing the module — so this mutates the EXPECTATION rather than the bytes:
+ * an entry claiming an ABI the grammar does not have must be refused. Same
+ * validated property, targeted from the side where it can be stated exactly.
+ */
+export function definedUnsupportedAbiEntry(entry: PackedBinaryEntry): PackedBinaryEntry {
+    return { ...entry, abi: entry.abi + 1 };
+}
+
+/** Condition 2, evaluated over the whole manifest rather than per file. */
+export function wildcardGrants(manifest: PackedBinaryManifest): string[] {
+    return manifest.entries
+        .filter((e) => e.path.includes('*') || e.path.includes('?') || e.path.endsWith('/'))
+        .map((e) => e.path);
+}
+
+/** Paths carrying more than one row — condition 1's uniqueness half. */
+export function duplicatePaths(manifest: PackedBinaryManifest): string[] {
+    const seen = new Map<string, number>();
+    for (const e of manifest.entries) seen.set(e.path, (seen.get(e.path) ?? 0) + 1);
+    return [...seen.entries()].filter(([, n]) => n > 1).map(([p]) => p);
+}
+
+/**
+ * Evaluate every condition for one packed file.
+ *
+ * `probe` is injected so the caller decides how the production loader is
+ * reached — in the gate it is a child process, in a test it can be a stub that
+ * returns a wrong ABI. `null` means the loader could not answer, which fails
+ * conditions 8 and 9 rather than passing them by default.
+ */
+export function evaluateEntry(options: {
+    readonly filePath: string;
+    readonly packedPaths: ReadonlySet<string>;
+    readonly manifest: PackedBinaryManifest;
+    readonly bytes: Uint8Array | null;
+    readonly probe: GrammarProbe | null;
+}): EligibilityVerdict {
+    const { filePath, packedPaths, manifest, bytes, probe } = options;
+    const failures: string[] = [];
+
+    const rows = manifest.entries.filter((e) => e.path === filePath);
+    if (rows.length === 0) failures.push('no manifest entry for this path');
+    if (rows.length > 1) failures.push('more than one manifest entry for this path');
+    const wild = wildcardGrants(manifest);
+    if (wild.length > 0) failures.push(`manifest carries wildcard or directory grants: ${wild.join(', ')}`);
+    if (!packedPaths.has(filePath)) failures.push('path is not in the packed tarball');
+
+    const entry = rows[0];
+    if (entry === undefined) return { path: filePath, eligible: false, failures };
+
+    if (bytes === null) {
+        failures.push('bytes could not be read');
+        return { path: filePath, eligible: false, failures };
+    }
+    const digest = createHash('sha256').update(bytes).digest('hex');
+    if (digest !== entry.sha256) failures.push(`sha256 mismatch: ${digest} != ${entry.sha256}`);
+    if (bytes.length !== entry.size) failures.push(`size mismatch: ${String(bytes.length)} != ${String(entry.size)}`);
+    if (entry.kind !== VERIFIABLE_KIND) failures.push(`kind is not ${VERIFIABLE_KIND}: ${entry.kind}`);
+    if (!wasmMagicAndVersionValid(bytes)) failures.push('WASM magic or version invalid');
+
+    if (probe === null) {
+        failures.push('the production loader could not read this file');
+    } else {
+        if (probe.grammar_id !== entry.grammar_id) {
+            failures.push(`grammar_id mismatch: loader says ${probe.grammar_id}, manifest says ${entry.grammar_id}`);
+        }
+        if (probe.abi !== entry.abi) {
+            failures.push(`ABI mismatch: loader says ${String(probe.abi)}, manifest says ${String(entry.abi)}`);
+        }
+    }
+
+    // Conditions 10 and 11 — the predicate refusing what it must refuse. Run
+    // here, on every invocation, so a refusal path is never merely asserted in
+    // a test somebody can skip.
+    if (wasmMagicAndVersionValid(definedInvalidHeaderMutation(bytes))) {
+        failures.push('self-check failed: a defined invalid-header mutation was NOT rejected');
+    }
+    if (probe !== null && probe.abi === definedUnsupportedAbiEntry(entry).abi) {
+        failures.push('self-check failed: a defined unsupported-ABI expectation was NOT rejected');
+    }
+
+    return { path: filePath, eligible: failures.length === 0, failures };
+}
+
+/** Read and shape-check the manifest. Throws rather than degrading to empty. */
+export function loadManifest(repoRoot: string): PackedBinaryManifest {
+    const p = path.join(repoRoot, 'src', 'config', 'packed-binary-manifest.json');
+    const raw = JSON.parse(fs.readFileSync(p, 'utf-8')) as PackedBinaryManifest;
+    if (!Array.isArray(raw.entries)) throw new Error(`packed-binary-manifest: entries must be an array (${p})`);
+    return raw;
+}

package/src/scripts/_lib/pin_resolver.ts

@@ -253,10 +253,23 @@ function _parse_cli(argv: string[]): { cwd: string; installed: string; forward:
 }
 
 // Script entry — mirrors the Python `if __name__ == "__main__"` block.
+// `build:delegate-aux` bundles this file with `--splitting`, which can move the
+// module body into a shared chunk: `import.meta.url` then names the CHUNK, the
+// URL comparison below never matches, and the entry silently no-ops. Inside that
+// bundle the invoked file name is the reliable signal (same pattern as
+// src/scripts/_cli/cmd_migrate.ts). Defined by that build only.
+declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean | undefined;
 function _isCliEntry(): boolean {
     if (process.argv[1] === undefined) {
         return false;
     }
+    if (typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' && __AGENT_CONFIG_CLI_DELEGATE__) {
+        // A miss falls THROUGH to the URL comparison below, which is the
+        // symlinked-invocation case that fallback exists for.
+        if (path.basename(process.argv[1], '.js') === 'pin_resolver') {
+            return true;
+        }
+    }
     const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
     if (import.meta.url === argvUrl) {
         return true;

package/src/scripts/_lib/regression_neighbourhood.ts

@@ -18,7 +18,7 @@
  * of them resolves here, so the substitution is STATED rather than hidden.
  *
  *   · `agent-config code-graph` — the native code-graph engine (ADR-124). It
- *     ships `hooks.code_graph.enabled: false`
+ *     shipped `hooks.code_graph.enabled: false` (a flag retired 2026-09-07)
  *     (`src/config/agent-settings.template.yml:1373-1374`), and
  *     `agent-config code-graph detect` in this checkout answers
  *     `no code-graph source detected`. There is no index to select against.

package/src/scripts/_lib/retired_status.ts

@@ -0,0 +1,74 @@
+/**
+ * Roadmap `status:` values this repository has RETIRED, and the diagnostic a
+ * reader gets when one survives in a file.
+ *
+ * `status: carrier` was deleted by ADR-262. It had two jobs welded together: a
+ * structural one (this roadmap is the live destination of an archived parent's
+ * `[~]` carries) and an authority one (an autonomous run may not act on it
+ * until a human flips it to `ready`). The second was authored by the repository
+ * about its own maintainer, was enforced by nothing, and contradicted the drain
+ * command's own FORBIDDEN NON-HALT REASONS. The first is a property of the
+ * deferral EDGES, which `lint_deferral_integrity` already verifies from both
+ * ends, so nothing was left for a node-level status to carry.
+ *
+ * Deleting a vocabulary term silently is the failure this module exists to
+ * prevent: an old file would keep a value nothing reads, and the next author
+ * would infer a meaning from its presence. So a retired value is REJECTED with
+ * a migration diagnostic rather than ignored.
+ *
+ * The read is frontmatter-scoped on purpose, and that is inherited rather than
+ * newly decided: a fenced `status: carrier` inside a roadmap documenting the
+ * syntax is not a declaration, and a body-wide match turned exactly that into a
+ * hard failure before a review caught it.
+ */
+
+/** Retired `status:` values, mapped to the record that retired each one. */
+export const RETIRED_STATUS_VALUES: ReadonlyMap<string, string> = new Map([
+    ['carrier', 'ADR-262'],
+]);
+
+/** The leading `---\n…\n---` block, or null when the text carries none. */
+export function frontmatterBlock(text: string): string | null {
+    const m = /^---\n([\s\S]*?)\n---/.exec(text);
+    return m === null ? null : (m[1] ?? '');
+}
+
+/** The frontmatter `status:` value, lower-cased, or null when absent. */
+export function frontmatterStatus(text: string | null | undefined): string | null {
+    if (text === null || text === undefined) {
+        return null;
+    }
+    const fm = frontmatterBlock(text);
+    if (fm === null) {
+        return null;
+    }
+    const m = /^status:[ \t]*([A-Za-z-]+)[ \t]*$/m.exec(fm);
+    return m === null ? null : (m[1] ?? '').toLowerCase();
+}
+
+/**
+ * The retired value this text declares, or null when it declares none.
+ *
+ * Returns the value rather than a boolean so the caller can name it in the
+ * diagnostic — "status: carrier is retired" is actionable, "invalid status" is
+ * not.
+ */
+export function declaresRetiredStatus(text: string | null | undefined): string | null {
+    const status = frontmatterStatus(text);
+    if (status === null) {
+        return null;
+    }
+    return RETIRED_STATUS_VALUES.has(status) ? status : null;
+}
+
+/** The migration diagnostic for a retired value. Names the record and the fix. */
+export function retiredStatusDiagnostic(value: string): string {
+    const record = RETIRED_STATUS_VALUES.get(value) ?? 'a decision record';
+    return (
+        `declares the retired \`status: ${value}\`, deleted by ${record}. ` +
+        'A `status:` value no longer decides whether an autonomous run may act on ' +
+        'a roadmap. Use `status: ready` and put any genuine human-ACTION gate in a ' +
+        '`## Blockers` entry, or park the file under `agents/roadmaps/later/` with ' +
+        'an `entry_condition`. Both are read by a gate; a status is not.'
+    );
+}

package/src/scripts/_lib/skill_catalogue.ts

@@ -75,40 +75,146 @@
  */
 
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 
-/** Catalogue roots tried in order; the first that exists wins. */
-export const DEFAULT_CATALOGUE_ROOTS = ['.claude/skills', 'src/skills'] as const;
+/**
+ * Catalogue roots under the WORKSPACE, in precedence order.
+ *
+ * `src/skills` is the authored tree and exists only in a maintainer checkout.
+ * `.claude/skills` is the project-scope projection — a consumer's own skills
+ * live there, and so do this repository's flat-command wrappers.
+ */
+export const PROJECT_CATALOGUE_ROOTS = ['src/skills', '.claude/skills'] as const;
+
+/**
+ * The catalogue root under the user's HOME — what the host itself delivers.
+ *
+ * Home-relative rather than workspace-relative, which is why it cannot live in
+ * the list above: `~/.claude/skills` is one directory for every project on the
+ * machine, and on a consumer machine it is where `agent-config install` puts the
+ * shipped skills.
+ */
+export const HOST_CATALOGUE_ROOT = '.claude/skills';
+
+/**
+ * The PROJECTION root, on its own, for the consumers that need exactly it.
+ *
+ * `capture_skill_catalogue` compares what a host DELIVERED against what was
+ * PROJECTED, so the authored tree is the wrong answer for it even though the
+ * ranker wants the authored tree first. Both questions were sharing
+ * `DEFAULT_CATALOGUE_ROOTS` and the 2026-09-07 reorder silently changed the
+ * second one — the finding a neutral review returned the same day. One constant
+ * for two questions is the defect; this is the second question, named.
+ */
+export const PROJECTION_CATALOGUE_ROOT = '.claude/skills';
 
 /**
- * First existing catalogue root under `workspaceRoot`, or `null`.
+ * Every root the resolver looks at, as human-readable LABELS.
+ *
+ * **Labels, never path inputs — this changed on 2026-09-07.**
+ *
+ * It used to be the resolver's own candidate list and callers joined it onto a
+ * root. It now carries a `~/`-prefixed entry, which `path.join(repo, ...)` turns
+ * into `<repo>/~/.claude/skills` — a candidate that can never exist. Use
+ * {@link resolveSkillCatalogueRoots} to RESOLVE and this list only to REPORT
+ * what was searched.
+ *
+ * For the `searched:` / `tried:` fields of the no-catalogue answers only — a
+ * reader needs to know `~` was consulted, and an absolute home path in a
+ * machine-readable payload is both noise and a small privacy leak.
+ */
+export const DEFAULT_CATALOGUE_ROOTS = [
+    ...PROJECT_CATALOGUE_ROOTS,
+    `~/${HOST_CATALOGUE_ROOT}`,
+] as const;
+
+/**
+ * EVERY readable, non-empty catalogue root, in precedence order.
+ *
+ * Shared by the `skill-route` concern and the `suggest_skill_for_task` MCP
+ * handler on purpose: two resolvers over one catalogue is how a ranker and the
+ * tool that exposes it start ranking different trees.
+ *
+ * **Why a LIST, and not the first hit — owner decision, 2026-09-07.**
+ *
+ * This returned one root and stopped at the first match, which made the ranker
+ * see one tree and the session see another. A consumer project can carry its own
+ * skills in `<project>/.claude/skills` while the shipped catalogue sits in
+ * `~/.claude/skills`; first-hit-wins ranked the smaller of the two and reported
+ * the result as if it were the catalogue. Ranking the UNION ranks what the
+ * session can actually reach, which is the only set the answer is about.
+ *
+ * **The order, and what it is for.**
  *
- * `.claude/skills` before `src/skills` because a CONSUMER install carries the
- * former and only a maintainer checkout carries the latter. Shared by the
- * `skill-route` concern and the `suggest_skill_for_task` MCP handler on
- * purpose: two resolvers over one catalogue is how a ranker and the tool that
- * exposes it start ranking different trees.
+ * Precedence applies to a NAME COLLISION, never to which roots are read:
+ *
+ *   1. `src/skills` — the authored tree. In this repository it is the truth, and
+ *      a maintainer editing a skill must see their edit ranked, not the
+ *      projection of the last `generate-tools` run.
+ *   2. `<project>/.claude/skills` — project scope beats machine scope, the same
+ *      direction every other per-project override in this suite takes.
+ *   3. `~/${HOST_CATALOGUE_ROOT}` — the host-global catalogue.
+ *
+ * **The two defects this replaced, both real.**
+ *
+ * It used to try `.claude/skills` FIRST, "because a CONSUMER install carries the
+ * former and only a maintainer checkout carries the latter". The premise was
+ * right and the conclusion did not follow: a consumer has no `src/skills`, so
+ * reading it first costs one `existsSync`.
+ *
+ * The ADR-236 amendment of 2026-09-07 turned that order into a live defect. The
+ * project layer now withholds every skill `~/.claude/skills` carries, so this
+ * repository's `.claude/skills` holds only the ~49 flat-command WRAPPERS —
+ * non-empty, so the old order resolved it, and each wrapper carries a `SKILL.md`,
+ * so nothing downstream could tell it was not the catalogue. Measured the same
+ * day: the `skill-route` hook ranked over 49 command wrappers instead of 299
+ * skills. Under the union those wrappers are still ranked, which is correct —
+ * they are reachable — but they no longer displace the catalogue.
+ *
+ * The non-empty guard keeps its own separate job: an EMPTY root read as a match
+ * made the ranker report an empty catalogue as an empty RESULT, the silent
+ * failure `road-to-inbox-harvest-2026-08-f-skill-selection-evidence` is about.
+ * Measured in that run: a worktree that had never run `generate-tools` ranked
+ * zero skills and exited 0 on a task that scores 47 against `src/skills`.
+ *
+ * @param home override for the user's home; production callers omit it.
  */
-export function resolveSkillsRoot(workspaceRoot: string): string | null {
-    for (const candidate of DEFAULT_CATALOGUE_ROOTS) {
-        const abs = path.join(workspaceRoot, candidate);
+export function resolveSkillCatalogueRoots(workspaceRoot: string, home?: string): string[] {
+    const userHome = home ?? process.env['HOME'] ?? os.homedir();
+    const candidates = [
+        ...PROJECT_CATALOGUE_ROOTS.map((c) => path.join(workspaceRoot, c)),
+        path.join(userHome, HOST_CATALOGUE_ROOT),
+    ];
+    const roots: string[] = [];
+    const seen = new Set<string>();
+    for (const abs of candidates) {
+        // A workspace that IS the home directory would offer `~/.claude/skills`
+        // twice and rank every skill in it twice. Cheap to exclude, and the
+        // duplicate would be invisible in the output.
+        if (seen.has(abs)) continue;
+        seen.add(abs);
         try {
             if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) continue;
-            // NON-EMPTY, and that qualifier is the whole fix. `.claude/skills`
-            // is a gitignored projection, so in a fresh worktree it EXISTS and
-            // holds nothing — and an empty root resolved as a match makes the
-            // ranker report an empty catalogue as an empty RESULT, which is the
-            // silent failure `road-to-inbox-harvest-2026-08-f-skill-selection-evidence`
-            // is about, arriving through a second door. Measured in that run: a
-            // worktree that had never run `generate-tools` ranked zero skills
-            // and exited 0 on a task that scores 47 against `src/skills`.
             if (fs.readdirSync(abs).length === 0) continue;
-            return abs;
+            roots.push(abs);
         } catch {
             // Unreadable candidate is not a match; try the next.
         }
     }
-    return null;
+    return roots;
+}
+
+/**
+ * The highest-precedence root, or `null` when none is readable.
+ *
+ * Kept for the surfaces that genuinely name ONE directory — a report line, a
+ * `skills_root` field. Anything that RANKS should take
+ * {@link resolveSkillCatalogueRoots} instead: ranking the first root only is the
+ * defect that function exists to remove.
+ */
+export function resolveSkillsRoot(workspaceRoot: string, home?: string): string | null {
+    return resolveSkillCatalogueRoots(workspaceRoot, home)[0] ?? null;
 }
 
 /** Where observations accumulate. Append-only, one JSON object per line. */
@@ -223,6 +329,35 @@ function descriptionOf(frontmatter: string): string {
  * the order a host listing follows and therefore the order a positional
  * hypothesis is measured against.
  */
+/**
+ * The catalogue as the RANKER sees it — every readable root, first name winning.
+ *
+ * Added 2026-09-07 after a second neutral review. `capture_skill_catalogue`'s D-4
+ * join says it reads "the catalogue the runtime ranker reads", and once the ranker
+ * moved to the union a single-root read stopped being that. Worse, the root the
+ * capture had been pointed at — `.claude/skills` — is the one the ADR-236
+ * amendment EMPTIED of skills: the join then read 49 command wrappers as the
+ * catalogue and published `pointableBare: 0` against `unpointableBare: 16`, a
+ * clean-looking verdict off the wrong tree, with the empty-guard silent because
+ * 49 is not 0.
+ *
+ * Positions are re-derived over the merged list, because a position is a property
+ * of the catalogue the host is shown, not of the root a name came from.
+ */
+export function readCatalogueAcross(roots: readonly string[]): CatalogueEntry[] {
+    const seen = new Set<string>();
+    const merged: CatalogueEntry[] = [];
+    for (const root of roots) {
+        for (const entry of readProjectedCatalogue(root)) {
+            if (seen.has(entry.name)) continue;
+            seen.add(entry.name);
+            merged.push(entry);
+        }
+    }
+    merged.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return merged.map((e, i) => ({ ...e, position: i + 1 }));
+}
+
 export function readProjectedCatalogue(root: string): CatalogueEntry[] {
     // Membership is decided by "does <name>/SKILL.md resolve", never by
     // `Dirent.isDirectory()`. The host-facing projection is a tree of SYMLINKS