@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/_lib/skill_materialisation_lock.ts

@@ -0,0 +1,149 @@
+/**
+ * The materialisation lock, and removal from it — the half of
+ * `road-to-skills-that-arrive-when-called` 4.3/4.5 that the `session_start`
+ * collect needs.
+ *
+ * WHY THIS IS ITS OWN FILE. 4.4 puts collection in the `session_start` read,
+ * which runs inside the hook dispatcher bundle — a bundle with a measured
+ * ceiling that every hook event on every host pays for. The materialiser
+ * reaches the staged runtime and the host built-in table, so importing it from
+ * a hook would carry both into that bundle. Splitting the lock out keeps ONE
+ * reader of the lock format (a second reader written "just for the hook" is how
+ * two formats drift apart) while the writer-side machinery — payload
+ * inspection, hashing, placement — stays out of the bundle entirely.
+ *
+ * Imports are `node:fs`, `node:path` and the atomic write, all of which the
+ * bundle already carries.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { atomicWriteFile } from '../../install/atomic.js';
+
+export const LOCK_BASENAME = 'materialised-skills.json';
+export const STORE_DIRNAME = 'materialised';
+
+export interface LockEntry {
+    host: string;
+    name: string;
+    /** The host skills root the symlink was placed under. */
+    root: string;
+    /** Content hash of the projected folder. */
+    sha256: string;
+}
+
+export interface Lock {
+    schema_version: 1;
+    entries: LockEntry[];
+}
+
+export function sortEntries(entries: readonly LockEntry[]): LockEntry[] {
+    return [...entries].sort((a, b) =>
+        a.root === b.root ? (a.name < b.name ? -1 : a.name > b.name ? 1 : 0) : a.root < b.root ? -1 : 1,
+    );
+}
+
+/**
+ * One path segment: `release` joins `host` and `name` into a recursive delete,
+ * so a lock row from a synced dotfile or a corrupted write must not be able to
+ * climb out of the store with `..` or a separator.
+ */
+function isSegment(s: string): boolean {
+    return s !== '' && s !== '.' && s !== '..' && !/[/\\\0]/.test(s);
+}
+
+export function loadLock(file: string): Lock {
+    try {
+        const data = JSON.parse(fs.readFileSync(file, 'utf-8')) as Partial<Lock>;
+        if (!data || !Array.isArray(data.entries)) return { schema_version: 1, entries: [] };
+        const entries = data.entries.filter(
+            (e): e is LockEntry =>
+                !!e && typeof e.host === 'string' && typeof e.name === 'string' &&
+                typeof e.root === 'string' && typeof e.sha256 === 'string' &&
+                isSegment(e.host) && isSegment(e.name),
+        );
+        return { schema_version: 1, entries: sortEntries(entries) };
+    } catch {
+        return { schema_version: 1, entries: [] };
+    }
+}
+
+export function saveLock(file: string, lock: Lock): void {
+    if (lock.entries.length === 0) {
+        fs.rmSync(file, { force: true });
+        return;
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    atomicWriteFile(file, `${JSON.stringify({ schema_version: 1, entries: sortEntries(lock.entries) }, null, 2)}\n`);
+}
+
+/** Names this lock holds for one host root. */
+export function materialisedNames(lockFile: string, hostSkillsRoot: string): string[] {
+    const want = path.resolve(hostSkillsRoot);
+    return loadLock(lockFile)
+        .entries.filter((e) => path.resolve(e.root) === want)
+        .map((e) => e.name)
+        .sort();
+}
+
+export interface ReleaseResult {
+    removed: string[];
+    /** Entries the lock names whose host side is not our link — left in place. */
+    kept_foreign: string[];
+}
+
+/**
+ * Remove exactly the named entries, and only when the lock claims them.
+ *
+ * The host link goes first and the store second, which is the order 0.2 (b)
+ * makes safe: a live session that already resolved the skill keeps working
+ * while its target exists, so a collection that loses a race degrades to a
+ * listing change rather than to a broken session.
+ */
+export function release(
+    lockFile: string,
+    hostSkillsRoot: string,
+    names: Iterable<string>,
+    storeDir: string = path.join(path.dirname(lockFile), STORE_DIRNAME),
+): ReleaseResult {
+    const lock = loadLock(lockFile);
+    const want = new Set(names);
+    const root = path.resolve(hostSkillsRoot);
+    const result: ReleaseResult = { removed: [], kept_foreign: [] };
+    const keep: LockEntry[] = [];
+    for (const e of lock.entries) {
+        if (path.resolve(e.root) !== root || !want.has(e.name)) {
+            keep.push(e);
+            continue;
+        }
+        const dest = path.join(e.root, e.name);
+        let ours = true;
+        try {
+            // Only a symlink this package placed is ours to remove: one that
+            // points into the store. A real directory, or a link elsewhere, is
+            // somebody else's, and the lock being stale does not make it ours.
+            ours =
+                fs.lstatSync(dest).isSymbolicLink() &&
+                path.resolve(path.dirname(dest), fs.readlinkSync(dest)).startsWith(path.resolve(storeDir) + path.sep);
+        } catch {
+            ours = true; // already gone; dropping the row is the repair
+        }
+        if (!ours) {
+            result.kept_foreign.push(e.name);
+            keep.push(e);
+            continue;
+        }
+        try {
+            fs.rmSync(dest, { force: true });
+            fs.rmSync(path.join(storeDir, e.host, e.name), { recursive: true, force: true });
+        } catch {
+            /* a vanished entry is the state we wanted */
+        }
+        result.removed.push(e.name);
+    }
+    saveLock(lockFile, { schema_version: 1, entries: keep });
+    result.removed.sort();
+    result.kept_foreign.sort();
+    return result;
+}

package/src/scripts/_lib/skill_materialisation_triggers.ts

@@ -0,0 +1,96 @@
+/**
+ * What makes a skill arrive — `road-to-skills-that-arrive-when-called` 4.2.
+ *
+ * THE WHOLE POINT IS THE NEGATIVE. A skill is materialised when a deterministic
+ * package entry point NAMES it, and never when a model guesses it might be
+ * useful. ADR-263 records skills here as explicitly invoked reference material,
+ * and the activation census counted zero model invocations over 30 sessions —
+ * so "the model thought of it" is not a trigger this package has, and inventing
+ * one would be the single change that turns an on-demand install into an
+ * unbounded one.
+ *
+ * THREE KINDS, AND EACH ONE IS AN ENTRY POINT THAT ALREADY EXISTS (K6: no new
+ * verbs):
+ *
+ *   `command-expanded`  a command or skill body was expanded and its `skills:`
+ *                       / `requires_skills:` frontmatter names the skill. This
+ *                       is the edge data `report_skill_menu_census` already
+ *                       walks, and the same closure 6.3 taught the installer.
+ *   `search-read`       a search answer was READ — not merely returned. A
+ *                       ranked list is a pointer; the read is the commitment,
+ *                       so the row the caller opened is the trigger and the
+ *                       other nine rows are not.
+ *   `called-by-name`    the name was typed, by the user or by a command.
+ *
+ * A fourth value exists only to be refused: `model-suggested` is accepted by the
+ * type so a caller cannot smuggle one in under another label, and
+ * {@link triggeredNames} returns nothing for it.
+ */
+
+export type TriggerKind = 'command-expanded' | 'search-read' | 'called-by-name' | 'model-suggested';
+
+export interface Trigger {
+    kind: TriggerKind;
+    /**
+     * Names the trigger carries. For `command-expanded` these are the declared
+     * dependencies of the artefact that expanded; for `search-read` the single
+     * row that was read; for `called-by-name` the one name.
+     */
+    names: readonly string[];
+    /** The artefact that produced the trigger, for the refusal message. */
+    source?: string;
+}
+
+/** Trigger kinds that may materialise. `model-suggested` is deliberately absent. */
+export const DETERMINISTIC_KINDS: ReadonlySet<TriggerKind> = new Set<TriggerKind>([
+    'command-expanded',
+    'search-read',
+    'called-by-name',
+]);
+
+/**
+ * The names a trigger may materialise: sorted, de-duplicated, empty for a
+ * non-deterministic kind.
+ *
+ * `installed` is the set already on disk — a name that is already there is not
+ * a materialisation candidate, so the common case does no work at all.
+ */
+export function triggeredNames(trigger: Trigger, installed: ReadonlySet<string>): string[] {
+    if (!DETERMINISTIC_KINDS.has(trigger.kind)) return [];
+    const out = new Set<string>();
+    for (const n of trigger.names) {
+        const name = n.trim();
+        if (name === '' || installed.has(name)) continue;
+        out.add(name);
+    }
+    return [...out].sort();
+}
+
+/**
+ * Declared skill dependencies of one artefact's frontmatter.
+ *
+ * Both keys, because 6.3's closure keeps both and a trigger that read only one
+ * of them would materialise a different set than the installer keeps.
+ */
+export function declaredSkills(frontmatter: string): string[] {
+    const out = new Set<string>();
+    for (const key of ['skills', 'requires_skills']) {
+        // `key: [a, b]` and a block list both occur in this tree.
+        const inline = new RegExp(`^${key}:[ \\t]*\\[([^\\]]*)\\]`, 'm').exec(frontmatter);
+        if (inline !== null) {
+            for (const part of inline[1]!.split(',')) {
+                const v = part.trim().replace(/^["']|["']$/g, '');
+                if (v !== '') out.add(v);
+            }
+            continue;
+        }
+        const block = new RegExp(`^${key}:[ \\t]*\\n((?:[ \\t]*-[ \\t]*.*\\n?)+)`, 'm').exec(frontmatter);
+        if (block !== null) {
+            for (const line of block[1]!.split('\n')) {
+                const m = /^[ \t]*-[ \t]*(.+?)[ \t]*$/.exec(line);
+                if (m) out.add(m[1]!.replace(/^["']|["']$/g, ''));
+            }
+        }
+    }
+    return [...out].sort();
+}

package/src/scripts/_lib/skill_origin.ts

@@ -9,6 +9,7 @@
  * loads on every dispatch, under a ceiling `check_hook_bundle_composition` holds.
  * So the primitives live here, importing only the manifest reader, and the census
  * re-exports them — one definition, two call sites, no second module graph.
+ * (`user_global_paths` is the one other import: it locates the deploy inventory.)
  *
  * ORIGIN IS READ FROM A CLAIM RECORD, NEVER INFERRED FROM A ROOT. The temptation
  * is to call `~/.claude/skills` foreign and the workspace ours. That is wrong in
@@ -26,6 +27,7 @@ import * as path from 'node:path';
 import { parse as parseYaml } from 'yaml';
 
 import { manifest_path } from './installed_tools.js';
+import { write_target } from './user_global_paths.js';
 
 /**
  * Where a RANKED skill came from — a question about AUTHORSHIP.
@@ -94,7 +96,10 @@ export function splitQualifiedName(qualified: string): { origin: SkillOrigin; na
  * budget this whole module was split out to protect. The `~` expansion below is
  * the same one all three use.
  */
-export function packageClaimedPaths(projectRoot: string): ReadonlySet<string> | null {
+export function packageClaimedPaths(
+    projectRoot: string,
+    inventoryFile: string = process.env['AGENT_CONFIG_DEPLOY_INVENTORY'] || write_target('deployed-files.json'),
+): ReadonlySet<string> | null {
     const manifest = manifest_path(projectRoot);
     let doc: unknown;
     try {
@@ -118,6 +123,21 @@ export function packageClaimedPaths(projectRoot: string): ReadonlySet<string> |
             out.add(path.resolve(projectRoot, _expanduser(raw)));
         }
     }
+    // A global entry records no files[]: the user-scoped deploy inventory is
+    // where its paths live (`global_deploy_inventory.ts`), so it claims them.
+    try {
+        const inv = JSON.parse(fs.readFileSync(_expanduser(inventoryFile), 'utf-8')) as {
+            tools?: Record<string, { anchor?: unknown; files?: unknown }>;
+        };
+        for (const t of Object.values(inv.tools ?? {})) {
+            if (typeof t?.anchor !== 'string' || !Array.isArray(t.files)) continue;
+            for (const rel of t.files) {
+                if (typeof rel === 'string') out.add(path.resolve(_expanduser(t.anchor), rel));
+            }
+        }
+    } catch {
+        // No inventory: the lock's own claims are the whole answer.
+    }
     return out;
 }
 

package/src/scripts/_lib/skill_reach.ts

@@ -0,0 +1,342 @@
+/**
+ * Skill reach for `agent-config doctor --check skill-reach`.
+ *
+ * `road-to-skills-that-arrive-when-called` 2.2 and 2.3. Every authored skill
+ * lands in exactly one of six buckets on the first host, and the six sum to the
+ * authored count — a silent subset is a number that does not add up, not a
+ * feeling. The partition was set by an AI council on 2026-10-18 (both seats):
+ *
+ *   installed, by listing state (in the host root, `~/.claude/skills`):
+ *     described     listed with its description
+ *     name-only     listed by name only (`skillOverrides: name-only`)
+ *     unlisted      installed but kept off the model listing (`off`,
+ *                   `user-invocable-only`)
+ *   not installed, by the BEST available path:
+ *     reachable-not-installed   a path carries every declared property the host
+ *                               would have applied
+ *     degraded                  a path exists, and every one drops at least one
+ *     unreachable               no path exists
+ *
+ * `installed` is printed as the subtotal of the first three, never as a seventh
+ * bucket.
+ *
+ * WHAT "DROPS" MEANS — 2.3, "degraded is never called reach". Two paths exist:
+ *
+ *   shell  `route:explain --skills` ranks the installed package's projection and
+ *          the agent reads that SKILL.md as text. Everything reaches the model as
+ *          text, but a key the HOST applies (allowed-tools, model, effort, context,
+ *          user-invocable, ...) is not applied by anyone. A skill declaring one is
+ *          degraded on this path.
+ *   mcp    the MCP read carries only `CARRIED_KEYS` whole; any other declared key
+ *          is dropped (`semantic-parity-census`).
+ *
+ * The host-applied set is the host's own documented key list
+ * (`src/config/host-skill-frontmatter-keys.json`) minus the keys that only
+ * describe a skill and change nothing about how it runs.
+ *
+ * A report, never a refusal: the check returns `warn` only when the buckets fail
+ * to sum, which would be this module's defect, not the install's.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { CARRIED_KEYS } from './body_portable.js';
+import { FINDER_NAME, finderRoutes, readFinderIndex } from './codex_skill_finder.js';
+import { resolvePackageRoot } from './package_root.js';
+import { declaredSkills } from './skill_materialisation_triggers.js';
+import type { WiringCheck } from './runtime_wiring_checks.js';
+
+export const REACH_BUCKETS = [
+    'described',
+    'name-only',
+    'unlisted',
+    'reachable-not-installed',
+    'degraded',
+    'unreachable',
+] as const;
+export type ReachBucket = (typeof REACH_BUCKETS)[number];
+
+/** Host keys that describe a skill; reading them as text loses nothing. */
+const DESCRIPTIVE_HOST_KEYS: ReadonlySet<string> = new Set([
+    'name',
+    'description',
+    'when_to_use',
+    'argument-hint',
+    'arguments',
+    'license',
+    'metadata',
+    'compatibility',
+]);
+
+export interface SkillReachInput {
+    /** Top-level frontmatter keys the projected SKILL.md declares. */
+    keys: readonly string[];
+    installed: boolean;
+    /** The host's `skillOverrides` value for this name, when one is set. */
+    override?: string;
+    /**
+     * Installed and unlisted, and a listed entry routes to it — on the second
+     * host, the finder (`second-host-unlisted-reachability`, remedy (a)). Such a
+     * skill is reached the way a not-installed one is: one listed invocation,
+     * then a read. So it is classified by the same path rule, never as listed.
+     */
+    routed?: boolean;
+    /** A skill it declares (`skills:` / `requires_skills:`) is absent from the authored set. */
+    missingDeps?: boolean;
+}
+
+export interface ReachPaths {
+    shell: boolean;
+    mcp: boolean;
+}
+
+/** Keys of `keys` the host applies and a text read therefore leaves unapplied. */
+export function hostAppliedKeys(keys: readonly string[], hostKeys: ReadonlySet<string>): string[] {
+    return keys.filter((k) => hostKeys.has(k) && !DESCRIPTIVE_HOST_KEYS.has(k));
+}
+
+/** One skill, one bucket. Pure; the caller supplies every observation. */
+export function classifySkillReach(
+    s: SkillReachInput,
+    paths: ReachPaths,
+    hostKeys: ReadonlySet<string>,
+): ReachBucket {
+    if (s.installed) {
+        if (s.override === 'name-only') return 'name-only';
+        const unlisted = s.override === 'off' || s.override === 'user-invocable-only';
+        if (unlisted && !s.routed) return 'unlisted';
+        if (!unlisted) return 'described';
+    }
+    // A path that reaches a skill whose declared dependency is missing reaches
+    // it without everything it relies on: degraded, never reach.
+    if (s.missingDeps && (paths.shell || paths.mcp)) return 'degraded';
+    if (paths.shell && hostAppliedKeys(s.keys, hostKeys).length === 0) return 'reachable-not-installed';
+    if (paths.mcp && s.keys.every((k) => CARRIED_KEYS.includes(k))) return 'reachable-not-installed';
+    if (paths.shell || paths.mcp) return 'degraded';
+    return 'unreachable';
+}
+
+/** Top-level keys of a markdown file's frontmatter block, in order. */
+export function frontmatterKeys(text: string): string[] {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    if (m === null) return [];
+    const out: string[] = [];
+    for (const line of (m[1] as string).split(/\r?\n/)) {
+        const k = /^([A-Za-z_][\w-]*):/.exec(line);
+        if (k !== null) out.push(k[1] as string);
+    }
+    return out;
+}
+
+/**
+ * A host's documented skill keys, from the committed key list. Throws when the
+ * host has no row: an empty set would classify every skill on that host as
+ * reachable, which is the one answer an unknown must never produce.
+ */
+export function loadHostKeys(packageRoot: string, host = 'claude-code'): Set<string> {
+    const file = path.join(packageRoot, 'src', 'config', 'host-skill-frontmatter-keys.json');
+    const data = JSON.parse(fs.readFileSync(file, 'utf-8')) as { hosts: Array<{ host: string; keys: string[] }> };
+    const row = data.hosts.find((h) => h.host === host);
+    if (row === undefined) throw new Error(`no row for host ${host} in ${file}`);
+    return new Set(row.keys);
+}
+
+function skillNames(root: string): string[] {
+    try {
+        return fs
+            .readdirSync(root)
+            .filter((n) => fs.existsSync(path.join(root, n, 'SKILL.md')))
+            .sort();
+    } catch {
+        return [];
+    }
+}
+
+function readOverrides(settingsPath: string): Record<string, string> {
+    try {
+        const data = JSON.parse(fs.readFileSync(settingsPath, 'utf-8')) as Record<string, unknown>;
+        const v = data['skillOverrides'];
+        if (typeof v !== 'object' || v === null || Array.isArray(v)) return {};
+        const out: Record<string, string> = {};
+        for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
+            if (typeof val === 'string') out[k] = val;
+        }
+        return out;
+    } catch {
+        return {};
+    }
+}
+
+export interface ReachCensus {
+    authored: number;
+    counts: Record<ReachBucket, number>;
+    installed: number;
+    sums: boolean;
+}
+
+/**
+ * Partition the projection at `projectionRoot` against the host root and the
+ * host settings file. `paths.shell` is true whenever the projection is readable:
+ * the shell search path ranks exactly that tree.
+ */
+export function reachCensus(opts: {
+    projectionRoot: string;
+    hostRoot: string;
+    settingsPath: string;
+    hostKeys: ReadonlySet<string>;
+    mcp: boolean;
+    /**
+     * The host's listing override for one name, when the host does not keep it
+     * in a settings file.
+     *
+     * The first host writes `skillOverrides` into its settings; the second host
+     * has no such setting and a skill leaves its listing by carrying a policy
+     * file instead (4.1). Same bucket, different place to look — so the LOOKUP
+     * is the seam, not a second census.
+     */
+    overrideOf?: (name: string) => string | undefined;
+    /** Whether a listed entry routes to an unlisted `name`. Absent: nothing does. */
+    routedOf?: (name: string) => boolean;
+}): ReachCensus {
+    const authoredNames = skillNames(opts.projectionRoot);
+    const authored = new Set(authoredNames);
+    const installed = new Set(skillNames(opts.hostRoot));
+    const overrides = opts.overrideOf ? {} : readOverrides(opts.settingsPath);
+    const paths: ReachPaths = { shell: authoredNames.length > 0, mcp: opts.mcp };
+    const counts = Object.fromEntries(REACH_BUCKETS.map((b) => [b, 0])) as Record<ReachBucket, number>;
+    for (const name of authoredNames) {
+        const text = fs.readFileSync(path.join(opts.projectionRoot, name, 'SKILL.md'), 'utf-8');
+        const input: SkillReachInput = { keys: frontmatterKeys(text), installed: installed.has(name) };
+        const ov = opts.overrideOf ? opts.overrideOf(name) : overrides[name];
+        if (ov !== undefined) input.override = ov;
+        if (opts.routedOf?.(name)) input.routed = true;
+        const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+        if (fm && declaredSkills(fm[1] as string).some((d) => !authored.has(d))) input.missingDeps = true;
+        counts[classifySkillReach(input, paths, opts.hostKeys)] += 1;
+    }
+    const total = REACH_BUCKETS.reduce((n, b) => n + counts[b], 0);
+    return {
+        authored: authoredNames.length,
+        counts,
+        installed: counts.described + counts['name-only'] + counts.unlisted,
+        sums: total === authoredNames.length,
+    };
+}
+
+export function renderReach(c: ReachCensus, hostRootLabel: string, host = 'claude-code'): string {
+    return (
+        `${host} (${hostRootLabel}): installed ${c.installed} (described ${c.counts.described} · ` +
+        `name-only ${c.counts['name-only']} · unlisted ${c.counts.unlisted}) · ` +
+        `reachable-not-installed ${c.counts['reachable-not-installed']} · degraded ${c.counts.degraded} · ` +
+        `unreachable ${c.counts.unreachable} — of ${c.authored} authored`
+    );
+}
+
+/** The doctor check. `home` and `packageRoot` are seams for tests. */
+export function checkSkillReach(
+    opts: { home?: string; packageRoot?: string; mcp?: boolean } = {},
+): WiringCheck {
+    const id = 'skill-reach';
+    const packageRoot = opts.packageRoot ?? resolvePackageRoot(import.meta.url);
+    const home = opts.home ?? os.homedir();
+    const projectionRoot = path.join(packageRoot, 'dist', 'agent-src', 'skills');
+    if (skillNames(projectionRoot).length === 0) {
+        return { id, status: 'skipped', message: `no skill projection at ${projectionRoot}`, remedy: '' };
+    }
+    let hostKeys: Set<string>;
+    let specKeys: Set<string>;
+    try {
+        hostKeys = loadHostKeys(packageRoot);
+        specKeys = loadHostKeys(packageRoot, 'agent-skills-spec');
+    } catch (e) {
+        return { id, status: 'skipped', message: `host skill-key list unusable: ${(e as Error).message}`, remedy: '' };
+    }
+    const mcp = opts.mcp ?? false;
+
+    // AC-1 reads "every host with native skills", so the check reports a row
+    // per such host rather than one row for the first one. The second host
+    // appears only once something is installed there: a row of zeros for a host
+    // nobody installed would read as a finding.
+    const rows: Array<{ host: string; label: string; c: ReachCensus }> = [];
+    rows.push({
+        host: 'claude-code',
+        label: '~/.claude/skills',
+        c: reachCensus({
+            projectionRoot,
+            hostRoot: path.join(home, '.claude', 'skills'),
+            settingsPath: path.join(home, '.claude', 'settings.json'),
+            hostKeys,
+            mcp,
+        }),
+    });
+    const codexRoot = path.join(home, '.codex', 'skills');
+    if (skillNames(codexRoot).filter((n) => n !== FINDER_NAME).length > 0) {
+        const codexDirs = [codexRoot, path.join(home, '.agents', 'skills')];
+        const finderIndex = readFinderIndex(path.join(codexRoot, FINDER_NAME, 'SKILL.md'));
+        rows.push({
+            host: 'codex',
+            label: '~/.codex/skills',
+            c: reachCensus({
+                projectionRoot,
+                hostRoot: codexRoot,
+                settingsPath: '',
+                hostKeys: specKeys,
+                mcp,
+                // 4.1: a skill outside the resident set carries a policy file
+                // that takes it out of the listing. `off` is the bucket's own
+                // vocabulary — installed and not listed.
+                //
+                // Unlisted alone is NOT reach on this host: probe row
+                // `unlisted-skill-not-in-model-list` (two-armed) has the model
+                // not seeing a policy-disabled skill and answering
+                // `UNAVAILABLE` when asked to invoke it. What reaches it is the
+                // finder — a listed entry indexing every unlisted name
+                // (`second-host-unlisted-reachability`, remedy (a), AI council
+                // 2026-10-20). So an unlisted skill the finder routes to is
+                // classified by the path rule, against the keys THIS host
+                // applies; one it does not route to stays `unlisted`, and the
+                // check warns on it below.
+                overrideOf: (name) =>
+                    fs.existsSync(path.join(codexRoot, name, 'agents', 'openai.yaml')) ? 'off' : undefined,
+                routedOf: (name) => finderRoutes(finderIndex, name, codexDirs),
+            }),
+        });
+    }
+
+    const message = rows.map((r) => renderReach(r.c, r.label, r.host)).join('; ');
+    const notSumming = rows.filter((r) => !r.c.sums).map((r) => r.host);
+    if (notSumming.length > 0) {
+        return {
+            id,
+            status: 'warn',
+            message: `${message} — the buckets do not sum for ${notSumming.join(', ')}`,
+            remedy: 'report this as a defect',
+        };
+    }
+    // AC-1's own condition, as a verdict rather than as a number a reader has
+    // to notice: a skill no path reaches on a host that has native skills is
+    // the defect this whole roadmap is about.
+    // On the second host `unlisted` means no listed entry routes to the skill —
+    // the model cannot see it (`unlisted-skill-not-in-model-list`). That is
+    // the same defect as `unreachable`, reported under its own name.
+    const unreachable = rows
+        .filter((r) => r.c.counts.unreachable > 0 || (r.host === 'codex' && r.c.counts.unlisted > 0))
+        .map((r) => r.host);
+    if (unreachable.length > 0) {
+        return {
+            id,
+            status: 'warn',
+            message: `${message} — unreachable skills on ${unreachable.join(', ')}`,
+            remedy: 'install the skill, or give the host a retrieval path that carries its declared keys',
+        };
+    }
+    return {
+        id,
+        status: 'ok',
+        message,
+        remedy: rows.some((r) => r.c.counts.degraded > 0)
+            ? 'a degraded skill is reachable as text only; the host keys it declares are not applied'
+            : '',
+    };
+}

package/src/scripts/_lib/source_shape.ts

@@ -103,8 +103,13 @@ const SOURCE_HEADER_RE = /^\s*(?:>\s*)?\*\*Source\*?\*?:?\*{0,2}\s*:?\s*(\S.*)$/
 /** A quoted inbox directory. Terminated by `/`, so a bare mention of the parent is not a hit. */
 const TMP_QUOTE_RE = /agents\/tmp(?:\.old)?\/([A-Za-z0-9._-]+)\//g;
 
-/** A GitHub repository URL, scheme-optional. */
-const GITHUB_URL_RE = /(?:https?:\/\/)?(?:www\.)?github\.com\/([A-Za-z0-9][A-Za-z0-9-]{0,38})\/([A-Za-z0-9][A-Za-z0-9._-]{0,99})/g;
+/**
+ * A GitHub repository URL, scheme-optional. The lookbehind excuses only the
+ * documentation host, whose `docs.github.com/en/copilot` would otherwise read as
+ * owner `en`, repo `copilot`. Every other subdomain (`api.`, `gist.`,
+ * `codeload.`) still flags the line, as it did before.
+ */
+const GITHUB_URL_RE = /(?<!docs\.)(?:https?:\/\/)?(?:www\.)?github\.com\/([A-Za-z0-9][A-Za-z0-9-]{0,38})\/([A-Za-z0-9][A-Za-z0-9._-]{0,99})/g;
 
 export interface SlugAllowlist {
     /** GitHub owners whose repos may be named openly (own org, integrated tools). */

package/src/scripts/_lib/sqlite_guard.ts

@@ -7,7 +7,7 @@
 // copies of the same lazy-import + warning-silencer dance.
 //
 // `node:sqlite` ships from Node 22.5 (experimental on 22.x, stable/silent on
-// >= 23); the package's supported floor is `>=20.11` (package.json
+// >= 23); the package's supported floor is `>=22.6` (package.json
 // `engines`), so every caller MUST treat this module's failure modes as
 // expected, not exceptional — lazy import + graceful fallback, never a hard
 // dependency (ADR-129).