vigiles 33.1.0 → 33.3.0

package/README.md

@@ -235,8 +235,9 @@ The **hooks** keep it honest in-loop — nudging the agent to tag a linter-rule
 
 - **Both lint and test** by default; scope with `--lint` / `--test`.
 - **Already have a CLAUDE.md / AGENTS.md, skills, or subagents? `audit` and `lint` read them as-is** — nothing is moved or rewritten. For the structural rules that want a typed spec, `init` sets one up **non-destructively** (`eject` undoes it).
-- Adds `vigiles` to `devDependencies`; installs the Claude Code plugin (skills + hooks) via the marketplace — globally, never vendored.
-- Declares that plugin in your repo's `.claude/settings.json` (`extraKnownMarketplaces` + `enabledPlugins`, merged into whatever is already there). This is a **reference, not content** — nothing is vendored, and it does **not** install the plugin for a teammate: an external-source plugin declared project-level [doesn't load until each person installs it](https://code.claude.com/docs/en/discover-plugins#configure-team-marketplaces). What it buys is that Claude Code **prompts** them with the install command, instead of a fresh clone silently having the npm package and none of its skills.
+- Adds `vigiles` to `devDependencies` and **links its skills into your repo**: one relative symlink per skill, `.claude/skills/<name>` → `node_modules/vigiles/skills/<name>` (`.agents/skills/` for Codex). Commit them — every clone and every fresh container then has the skills as soon as `npm install` has run. A skill of yours with the same name is never replaced; `init` names the one you didn't get.
+- Installs the Claude Code plugin via the marketplace — globally, never vendored — because it carries the **hooks**. That install is per machine; its copy of the skills is listed as `vigiles:<name>` next to the linked `<name>` (same files).
+- Declares that plugin in your repo's `.claude/settings.json` (`extraKnownMarketplaces` + `enabledPlugins`, merged into whatever is already there). This is a **reference, not content**, and it does **not** install the plugin for a teammate: an external-source plugin declared project-level [doesn't load until each person installs it](https://code.claude.com/docs/en/discover-plugins#configure-team-marketplaces). What it buys is that Claude Code **prompts** them with the install command for the hooks.
 - Wires CI as a `zernie/vigiles@v1` workflow (needs only read + PR-comment permissions) that posts a sticky PR comment + a `valid` output.
 
 Targets Claude Code and Codex out of the box, or [your own harness](docs/authoring-an-adapter.md). Prefer to write tests yourself? JS **or** TS (`*.harness.{mjs,ts}`) — run with `npx vigiles test`.

package/dist/adapter-conformance.js

@@ -21,6 +21,19 @@ const event_capability_js_1 = require("./core/event-capability.js");
 const dialect_js_1 = require("./core/dialect.js");
 const layout_js_1 = require("./core/layout.js");
 const tmp_root_js_1 = require("./core/tmp-root.js");
+/** Every optional path a layout names, with the field it sits in. */
+function optionalPaths(layout) {
+    return [
+        ["rulesDir", layout.rulesDir],
+        ["outputStyles.dir", layout.outputStyles?.dir],
+        ["hookScriptsDir", layout.hookScriptsDir],
+        ["hooksConventionPath", layout.hooksConventionPath],
+        ["userSurfaceRoot", layout.userSurfaceRoot],
+        ["surfaces.skill", layout.surfaces.skill],
+        ["surfaces.agent", layout.surfaces.agent],
+        ["surfaces.command", layout.surfaces.command],
+    ];
+}
 /** Check an adapter against the port contracts; returns the (possibly empty) failure list. */
 function checkAdapterConformance(adapter) {
     const failures = [];
@@ -76,16 +89,7 @@ function checkAdapterConformance(adapter) {
     // second spelling of absent" rule is a test for every optional path. An
     // absent key already means "this harness has no such thing"; `""` would be a
     // second one, and every reader would have to remember to test for both.
-    const optionalPaths = [
-        ["rulesDir", adapter.layout.rulesDir],
-        ["hookScriptsDir", adapter.layout.hookScriptsDir],
-        ["hooksConventionPath", adapter.layout.hooksConventionPath],
-        ["userSurfaceRoot", adapter.layout.userSurfaceRoot],
-        ["surfaces.skill", adapter.layout.surfaces.skill],
-        ["surfaces.agent", adapter.layout.surfaces.agent],
-        ["surfaces.command", adapter.layout.surfaces.command],
-    ];
-    for (const [field, value] of optionalPaths)
+    for (const [field, value] of optionalPaths(adapter.layout))
         need(value === undefined || value.length > 0, `layout.${field} is "" — absence is spelled by omitting the key, never by an empty string`);
     // A7: `hooksConventionPath` names a FILE, and every reader treats it as one
     // (dirname it, parse it, round-trip it). `opencodeLayout` used to name the

package/dist/adapter.d.ts

@@ -18,6 +18,8 @@
 export type { HarnessAdapter, AdapterCapabilities } from "./core/adapter.js";
 export type { HarnessDialect } from "./core/dialect.js";
 export type { PluginLayout, SurfaceDirs, SurfaceKind } from "./core/layout.js";
+export type { OutputStyle, OutputStyleRules } from "./core/output-style.js";
+export type { ModelRequest } from "./core/harness-driver.js";
 export { executableSourceDirs, materializePrefix, surfaceDirs, } from "./core/layout.js";
 /**
  * The instruction-chain vocabulary `PluginLayout.instructionChain` speaks.
@@ -39,7 +41,7 @@ export { EMPTY_CHAIN } from "./core/instruction-chain.js";
  */
 export type { SettingsCodec } from "./core/settings-codec.js";
 export { jsonSettingsCodec, tomlSettingsCodec } from "./core/settings-codec.js";
-export type { HarnessRuntime } from "./core/runtime.js";
+export type { HarnessRuntime, RunEnvPolicy } from "./core/runtime.js";
 export type { HookProtocol } from "./core/hook-protocol.js";
 export type { ModelMock } from "./core/model-mock.js";
 /**

package/dist/adapters/claude-code/layout.js

@@ -15,6 +15,7 @@ const layout_js_1 = require("../../core/layout.js");
 const instruction_chain_js_1 = require("../../core/instruction-chain.js");
 const settings_codec_js_1 = require("../../core/settings-codec.js");
 const instruction_chain_js_2 = require("./instruction-chain.js");
+const output_style_js_1 = require("./output-style.js");
 exports.claudeCodeLayout = {
     name: "claude-code",
     manifestPath: ".claude-plugin/plugin.json",
@@ -30,6 +31,8 @@ exports.claudeCodeLayout = {
     userSurfaceRoot: ".claude",
     // `.claude/rules/*.md` — path-scoped project instructions (see PluginLayout).
     rulesDir: "rules",
+    // `.claude/output-styles/**/*.md` — see output-style.ts for how a style is named and selected.
+    outputStyles: output_style_js_1.claudeCodeOutputStyles,
     // `.claude/settings.local.json` — the per-machine layer, gitignored by
     // `init`. Declared because only this adapter knows the word; Codex and
     // OpenCode name none, so none is synthesized for them.

package/dist/adapters/claude-code/output-style.d.ts

@@ -0,0 +1,3 @@
+import type { OutputStyleRules } from "../../core/output-style.js";
+export declare const claudeCodeOutputStyles: OutputStyleRules;
+//# sourceMappingURL=output-style.d.ts.map

package/dist/adapters/claude-code/output-style.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCodeOutputStyles = void 0;
+/**
+ * How Claude Code keeps output styles and switches one on. Every rule here was
+ * measured on Claude Code 2.1.291; the tests beside this file hold the cases.
+ */
+const node_path_1 = require("node:path");
+// `yaml` is the lazy loader: this module hangs off the layout, which is on the
+// hook path, so a top-level `js-yaml` import would load into every hook decision.
+const frontmatter_read_js_1 = require("../../core/frontmatter-read.js");
+/** Claude Code puts this line, then the body, into the first user message. */
+const HEADER = "# Output Style: ";
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** YAML as Claude Code reads it: the core schema, and a repeated key keeps the last value. */
+const parse = (block) => {
+    try {
+        const { CORE_SCHEMA, load } = (0, frontmatter_read_js_1.yaml)();
+        const value = load(block, { schema: CORE_SCHEMA, json: true });
+        if (value === null || value === undefined)
+            return {};
+        return isRecord(value) ? value : null;
+    }
+    catch (e) {
+        if (e instanceof (0, frontmatter_read_js_1.yaml)().YAMLException)
+            return null;
+        throw e;
+    }
+};
+/** `name: Status: Block` is not YAML, but Claude Code takes the rest of the line. */
+const quoteColonValues = (block) => block
+    .split("\n")
+    .map((line) => {
+    const m = /^([A-Za-z0-9_-]+): (.*)$/.exec(line.replace(/\r$/, ""));
+    if (m === null)
+        return line;
+    const [, key = "", value = ""] = m;
+    const needsQuotes = /: |:$/.test(value) && !/^["'[{|>]/.test(value);
+    return needsQuotes ? `${key}: ${JSON.stringify(value)}` : line;
+})
+    .join("\n");
+const readBlock = (block) => parse(block) ?? parse(quoteColonValues(block));
+/** A declared name if there is one, else the file name; null when unknowable. */
+const nameFrom = (text, stem) => {
+    const { block } = (0, frontmatter_read_js_1.readFrontmatter)(text);
+    if (block === null)
+        return stem;
+    const data = readBlock(block);
+    if (data === null)
+        return null;
+    const name = data["name"];
+    if (typeof name === "string")
+        return name === "" ? stem : name;
+    if (typeof name === "number" || typeof name === "boolean")
+        return String(name);
+    return name === null || name === undefined ? stem : null;
+};
+const squash = (s) => s.replace(/\s+/g, " ").trim();
+const read = (path, text) => ({
+    path,
+    name: nameFrom(text, (0, node_path_1.basename)(path).replace(/\.md$/, "")),
+    body: (0, frontmatter_read_js_1.frontmatterBody)(text).trim(),
+});
+/** The header and the whole body, in the system prompt or in any message. */
+const reached = (style, request) => {
+    if (style.name === null)
+        return false;
+    const probe = squash(`${HEADER}${style.name}\n${style.body}`);
+    return [request.system, ...request.messages.map((m) => m.text)].some((text) => squash(text).includes(probe));
+};
+exports.claudeCodeOutputStyles = {
+    dir: "output-styles",
+    isStyleFile: (pathInDir) => pathInDir.endsWith(".md"),
+    read,
+    select: (name) => ({ outputStyle: name }),
+    // A user-wide `outputStyle` in `~/.claude/settings.json` loads in every
+    // project; the project's own `default` wins over it (measured on 2.1.292).
+    selectNone: { outputStyle: "default" },
+    reached,
+};
+//# sourceMappingURL=output-style.js.map

package/dist/adapters/claude-code/replies.d.ts

@@ -0,0 +1,14 @@
+/** Whether the model answered at all: any `assistant` event, subagents included. */
+export declare function reachedModel(streamJson: string): boolean;
+/**
+ * The main agent's replies, one per message that ended a turn. A message
+ * streamed as several events (one per content block) is joined under its
+ * `message.id`. Left out: a subagent's messages (a non-null
+ * `parent_tool_use_id`); a message that also calls a tool, whose text is
+ * narration on the way to the call (measured on Claude Code 2.1.292: the
+ * narration and the `tool_use` share one id); a message with no text.
+ * `undefined` when the output is not a stream, so a check can say the run
+ * was not streamed instead of reading "no replies".
+ */
+export declare function parseReplies(streamJson: string): readonly string[] | undefined;
+//# sourceMappingURL=replies.d.ts.map

package/dist/adapters/claude-code/replies.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reachedModel = reachedModel;
+exports.parseReplies = parseReplies;
+/**
+ * Every reply the agent ended a turn with, in order — read off Claude Code's
+ * `--output-format stream-json`. The `result` event carries only the LAST one,
+ * so a reply a Stop hook made the agent follow up on was invisible to a test,
+ * and with it anything that reply printed (a second status footer, measured on
+ * Claude Code 2.1.291: two `assistant` events, one `result` holding the second).
+ */
+const zod_1 = require("zod");
+/** The parts of an `assistant` stream line this reads; the rest is ignored. */
+const AssistantLineSchema = zod_1.z.object({
+    type: zod_1.z.literal("assistant"),
+    parent_tool_use_id: zod_1.z.string().nullish(),
+    message: zod_1.z.object({
+        id: zod_1.z.string().optional(),
+        content: zod_1.z.array(zod_1.z.unknown()),
+    }),
+});
+const TextBlock = zod_1.z.object({ type: zod_1.z.literal("text"), text: zod_1.z.string() });
+const textOf = (content) => content
+    .map((block) => TextBlock.safeParse(block))
+    .flatMap((r) => (r.success ? [r.data.text] : []))
+    .join("");
+const parseJson = (line) => {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+};
+const parseLine = (line) => {
+    const r = AssistantLineSchema.safeParse(parseJson(line));
+    return r.success ? r.data : null;
+};
+/** A stream-json run opens with a `system` event; plain `json` output has none. */
+const StreamStartSchema = zod_1.z.object({ type: zod_1.z.literal("system") });
+const isStream = (lines) => lines.some((l) => StreamStartSchema.safeParse(parseJson(l)).success ||
+    parseLine(l) !== null);
+const ToolUseBlock = zod_1.z.object({ type: zod_1.z.literal("tool_use") });
+/** Whether the model answered at all: any `assistant` event, subagents included. */
+function reachedModel(streamJson) {
+    return streamJson.split("\n").some((l) => parseLine(l) !== null);
+}
+/**
+ * The main agent's replies, one per message that ended a turn. A message
+ * streamed as several events (one per content block) is joined under its
+ * `message.id`. Left out: a subagent's messages (a non-null
+ * `parent_tool_use_id`); a message that also calls a tool, whose text is
+ * narration on the way to the call (measured on Claude Code 2.1.292: the
+ * narration and the `tool_use` share one id); a message with no text.
+ * `undefined` when the output is not a stream, so a check can say the run
+ * was not streamed instead of reading "no replies".
+ */
+function parseReplies(streamJson) {
+    const lines = streamJson.split("\n");
+    if (!isStream(lines))
+        return undefined;
+    const events = lines.map(parseLine).flatMap((e, i) => e !== null && (e.parent_tool_use_id ?? null) === null
+        ? [
+            {
+                id: e.message.id ?? `#${String(i)}`,
+                text: textOf(e.message.content),
+                callsTool: e.message.content.some((b) => ToolUseBlock.safeParse(b).success),
+            },
+        ]
+        : []);
+    const ids = [...new Set(events.map((e) => e.id))];
+    return ids
+        .map((id) => events.filter((e) => e.id === id))
+        .filter((parts) => !parts.some((e) => e.callsTool))
+        .map((parts) => parts.map((e) => e.text).join(""))
+        .filter((text) => text !== "");
+}
+//# sourceMappingURL=replies.js.map

package/dist/adapters/claude-code/runtime.js

@@ -2,6 +2,75 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.claudeCodeRuntime = void 0;
 exports.mockModelEnv = mockModelEnv;
+/**
+ * What a child `claude` run may inherit from its caller. The runners apply it
+ * through `src/core/run-env.ts`; this object is the only place the names live.
+ *
+ * `keep` — auth and backend selection only, as an allowlist. It replaced a
+ * `CLAUDE_*` prefix pass-through, which carried the parent session's identity
+ * into every scrubbed run. Measured 2026-10-07 on 2.1.292: a child started with
+ * the parent's session variables ran as the parent session, and a host-brokered
+ * child (`ANTHROPIC_BASE_URL`) authenticated with NO `CLAUDE_*` variable at all.
+ * Every `CLAUDE_*` name below is one the prefix used to carry and that selects
+ * or supplies credentials (each is referenced by the 2.1.292 binary).
+ * `CLAUDE_CONFIG_DIR` is left out on purpose: it points the child at the real
+ * config directory (settings, hooks, sessions, tasks) that the throwaway HOME
+ * exists to hide.
+ *
+ * `sessionIdentity` — the parent session. The first six were observed in a live
+ * session's env on 2026-10-07; the rest are session-identifying names present
+ * in the 2.1.292 binary, removed by name rather than by a measured effect.
+ */
+const claudeCodeRunEnv = {
+    keep: [
+        // Anthropic API auth + endpoint.
+        "ANTHROPIC_API_KEY",
+        "ANTHROPIC_BASE_URL",
+        "ANTHROPIC_AUTH_TOKEN",
+        "ANTHROPIC_MODEL",
+        // Carried over from the earlier list; not referenced by the 2.1.292 binary.
+        "ANTHROPIC_API_URL",
+        "ANTHROPIC_DEFAULT_HEADERS",
+        // Subscription token (`claude setup-token`) and client certificates.
+        "CLAUDE_CODE_OAUTH_TOKEN",
+        "CLAUDE_CODE_API_KEY_HELPER_TTL_MS",
+        "CLAUDE_CODE_CLIENT_CERT",
+        "CLAUDE_CODE_CLIENT_KEY",
+        "CLAUDE_CODE_CLIENT_KEY_PASSPHRASE",
+        // Cloud backends: the switch, the auth skip, and region/profile — never
+        // the secret-shaped AWS_* access keys.
+        "CLAUDE_CODE_USE_BEDROCK",
+        "CLAUDE_CODE_USE_VERTEX",
+        "CLAUDE_CODE_USE_FOUNDRY",
+        "CLAUDE_CODE_SKIP_BEDROCK_AUTH",
+        "CLAUDE_CODE_SKIP_VERTEX_AUTH",
+        "CLAUDE_CODE_SKIP_FOUNDRY_AUTH",
+        "AWS_REGION",
+        "AWS_DEFAULT_REGION",
+        "AWS_PROFILE",
+        "CLOUD_ML_REGION",
+        "GOOGLE_CLOUD_PROJECT",
+        "GOOGLE_APPLICATION_CREDENTIALS",
+    ],
+    keepHomeFiles: [".claude/.credentials.json"],
+    sessionIdentity: [
+        "CLAUDE_CODE_SESSION_ID",
+        "CLAUDE_CODE_REMOTE_SESSION_ID",
+        "CLAUDE_CODE_CHILD_SESSION",
+        "CLAUDE_CODE_MESSAGING_SOCKET",
+        "CLAUDE_CODE_MESSAGING_TOKEN",
+        "CLAUDE_SESSION_INGRESS_TOKEN_FILE",
+        "CLAUDE_SESSION_ID",
+        "CLAUDE_CODE_SESSION_ACCESS_TOKEN",
+        "CLAUDE_CODE_REMOTE_SESSION_UUID",
+        "CLAUDE_CODE_HOST_SESSION_ID",
+        "CLAUDE_CODE_CLOUD_SESSION_ID",
+        "CLAUDE_CODE_BRIDGE_SESSION_ID",
+        "CLAUDE_RUNNER_SESSION_ID",
+        "CLAUDE_RUNNER_SESSION_UUID",
+        "CLAUDE_PID",
+    ],
+};
 exports.claudeCodeRuntime = {
     name: "claude-code",
     agentBinary: "claude",
@@ -34,6 +103,7 @@ exports.claudeCodeRuntime = {
         const m = /(\d+)\.(\d+)\.\d+/.exec(raw);
         return m ? `${m[1]}.${m[2]}` : raw.trim();
     },
+    runEnv: claudeCodeRunEnv,
 };
 /**
  * Build the spawn env that points the agent CLI at the mock model: the caller's

package/dist/adapters/claude-code/skill-reachability.d.ts

@@ -4,10 +4,15 @@
  * vigiles publishes six user-facing skills (`SHIPPED_SKILLS`) — the teaching
  * surface. `test-harness` alone answers "which testing tier do I want?", the
  * question this project's docs are otherwise organized around. They reach the
- * agent through the GLOBAL plugin install (`vigiles init`, or
- * `claude plugin marketplace add zernie/vigiles` + `claude plugin install
- * vigiles@vigiles`), which lands in `~/.claude/plugins/` — deliberately never
- * vendored into the repo (`docs/agent-setup.md`).
+ * agent two ways (`docs/agent-setup.md`):
+ *
+ * - the LINKS `vigiles init` commits into `.claude/skills/` (one relative
+ *   symlink per skill into `node_modules/vigiles/skills/`, `src/skill-links.ts`)
+ *   — a fact about the REPOSITORY, so every clone and container has them once
+ *   `npm install` has run;
+ * - the GLOBAL plugin install (`claude plugin install vigiles@vigiles`, into
+ *   `~/.claude/plugins/`) — a fact about ONE machine, namespaced
+ *   `vigiles:<name>`.
  *
  * The failure this module makes loud: `npm install vigiles` ALSO puts those
  * skills on disk, at `node_modules/vigiles/skills/` (they are in package.json's
@@ -46,9 +51,10 @@
  * Shape follows `./dialect-drift.ts`: pure parsers + a best-effort local read
  * that NEVER throws + a formatter that returns null when there is nothing to
  * say, so `vigiles audit` can print it without a new verb, flag, or failure mode.
- * It is ADVISORY — it never touches the audit score, because reachability is a
- * property of the machine (is the plugin installed?), not of the repo, and a
- * score that moved between a laptop and CI for identical source would be a lie.
+ * It is ADVISORY — it never touches the audit score, because reachability is
+ * partly a property of the machine (is the plugin installed? has `npm install`
+ * run?), and a score that moved between a laptop and CI for identical source
+ * would be a lie.
  */
 import type { InstallReader } from "../../core/adapter.js";
 /** The plugin id `claude plugin install` records — `<plugin>@<marketplace>`. */
@@ -61,7 +67,7 @@ export declare const VIGILES_PLUGIN_ID = "vigiles@vigiles";
 export type ReachabilitySource = 
 /** `~/.claude/plugins/installed_plugins.json` — what `claude plugin install` writes. */
 "global-plugin"
-/** The skills vendored into the repo's own `.claude/skills/` (standalone config, always loaded). */
+/** The repo's own `.claude/skills/<name>/SKILL.md` resolves — a link `init` made, or a copy. */
  | "repo-skills";
 /** The advisory: can the agent see vigiles's skills from this repo? */
 export interface SkillReachability {
@@ -82,6 +88,18 @@ export interface SkillReachability {
      * nothing stranded if they are wired) or when the package isn't installed yet.
      */
     readonly strandedSkills: readonly string[];
+    /**
+     * Shipped skills whose `.claude/skills/<name>` entry is a LINK that does not
+     * resolve: the links came with `git clone`, the package they point into did
+     * not. The fix is `npm install`, not re-linking.
+     */
+    readonly danglingLinks: readonly string[];
+    /**
+     * Skills the package ships that the repo has not linked while it HAS linked
+     * others — the state after an upgrade adds a skill. Empty unless at least one
+     * shipped skill resolves in the repo.
+     */
+    readonly unlinkedSkills: readonly string[];
 }
 /**
  * Does the global registry record a live install of the vigiles plugin? Pure over
@@ -101,25 +119,28 @@ export declare function hasEnabledPlugin(settingsJson: string): boolean;
  * reader performs degrades to "not found".
  *
  * 🔴 IT READS THROUGH A REPO-BOUND {@link InstallReader}, NOT `node:fs`. Two of
- * its five reads are of files NO adapter claims (`package.json`, vigiles's own
+ * its reads are of files NO adapter claims (`package.json`, vigiles's own
  * package under `node_modules`), so the domain performs those and passes the
  * ANSWER; the rest go through a reader that refuses any path this adapter does
- * not claim. That is why this module no longer imports `node:fs` at all.
+ * not claim. That is why this module does not import `node:fs` at all.
  *
- * ⚠️ ONE MEASURED CHANGE, NAMED BECAUSE IT IS A CHANGE: the repo-vendored check
- * used to ENUMERATE `.claude/skills/` and compare directory names. Enumeration
- * is precisely what the reader exists to prevent, and it is not needed here —
- * the names being looked for are a fixed list — so each shipped skill is probed
- * for its own `SKILL.md` instead. The narrow difference: a directory named after
- * a shipped skill but holding no `SKILL.md` used to count as reachable and no
- * longer does. It was never loadable by the agent, which is the question asked.
+ * Each shipped skill is probed for its own `SKILL.md` rather than by listing
+ * `.claude/skills/` — enumeration is what the reader exists to prevent, and the
+ * names are known: the installed package's when it is installed, else the
+ * shipped list. A directory named after a shipped skill but holding no
+ * `SKILL.md` is not reachable; it was never loadable by the agent.
  */
 export declare function checkSkillReachability(read: InstallReader): SkillReachability | null;
 /**
- * The warning for an un-wired repo, or null when there is nothing to say
- * (reachable, or the check did not apply). Names the skill the user most likely
- * went looking for, says where the copies are stranded when they exist, and ends
- * on a command that fixes it.
+ * The advisory, or null when there is nothing to say. Most specific state
+ * first, each ending on the command that fixes it:
+ *
+ * 1. links that dangle — `npm install`;
+ * 2. nothing reaches the agent — link them (per repo), or install the plugin
+ *    (per machine);
+ * 3. only this machine's plugin reaches it — a fresh clone or container will
+ *    not have them. Not a failure; said in one line;
+ * 4. some linked, some not (an upgrade added one) — link the rest.
  */
 export declare function formatSkillReachability(r: SkillReachability | null): string | null;
 //# sourceMappingURL=skill-reachability.d.ts.map

package/dist/adapters/claude-code/skill-reachability.js

@@ -6,6 +6,9 @@ exports.hasEnabledPlugin = hasEnabledPlugin;
 exports.checkSkillReachability = checkSkillReachability;
 exports.formatSkillReachability = formatSkillReachability;
 const setup_plan_js_1 = require("../../setup-plan.js");
+const layout_js_1 = require("../../core/layout.js");
+const skill_link_target_js_1 = require("../../core/skill-link-target.js");
+const layout_js_2 = require("./layout.js");
 /** The plugin id `claude plugin install` records — `<plugin>@<marketplace>`. */
 exports.VIGILES_PLUGIN_ID = "vigiles@vigiles";
 /**
@@ -36,6 +39,10 @@ function hasEnabledPlugin(settingsJson) {
         return false;
     }
 }
+/** Where this harness keeps a repo's skills — the layout's answer, not a literal. */
+const SKILLS_HOME = (0, layout_js_1.skillsHome)(layout_js_2.claudeCodeLayout) ?? ".claude/skills";
+/** The per-repo fix, printed wherever the repo itself lacks the links. */
+const LINK_FIX = "npx vigiles init — links each skill into .claude/skills/ (relative links into node_modules; commit them), and leaves any skill you already have alone";
 /**
  * Best-effort, read-local reachability check for `vigiles audit`. Returns null
  * when the question does not apply — the repo does not depend on vigiles, or IS
@@ -43,54 +50,110 @@ function hasEnabledPlugin(settingsJson) {
  * reader performs degrades to "not found".
  *
  * 🔴 IT READS THROUGH A REPO-BOUND {@link InstallReader}, NOT `node:fs`. Two of
- * its five reads are of files NO adapter claims (`package.json`, vigiles's own
+ * its reads are of files NO adapter claims (`package.json`, vigiles's own
  * package under `node_modules`), so the domain performs those and passes the
  * ANSWER; the rest go through a reader that refuses any path this adapter does
- * not claim. That is why this module no longer imports `node:fs` at all.
+ * not claim. That is why this module does not import `node:fs` at all.
  *
- * ⚠️ ONE MEASURED CHANGE, NAMED BECAUSE IT IS A CHANGE: the repo-vendored check
- * used to ENUMERATE `.claude/skills/` and compare directory names. Enumeration
- * is precisely what the reader exists to prevent, and it is not needed here —
- * the names being looked for are a fixed list — so each shipped skill is probed
- * for its own `SKILL.md` instead. The narrow difference: a directory named after
- * a shipped skill but holding no `SKILL.md` used to count as reachable and no
- * longer does. It was never loadable by the agent, which is the question asked.
+ * Each shipped skill is probed for its own `SKILL.md` rather than by listing
+ * `.claude/skills/` — enumeration is what the reader exists to prevent, and the
+ * names are known: the installed package's when it is installed, else the
+ * shipped list. A directory named after a shipped skill but holding no
+ * `SKILL.md` is not reachable; it was never loadable by the agent.
  */
 function checkSkillReachability(read) {
     if (!read.repoDependsOnVigiles)
         return null;
-    const sources = [];
-    const installed = read.home(".claude/plugins/installed_plugins.json");
-    if (installed !== null && hasGlobalPluginInstall(installed))
-        sources.push("global-plugin");
-    // Vendored copies: only vigiles's OWN skill names count. A repo with 38
-    // unrelated skills in `.claude/skills/` is still un-wired.
-    if (setup_plan_js_1.SHIPPED_SKILLS.some((s) => read.repo(`.claude/skills/${s}/SKILL.md`)))
-        sources.push("repo-skills");
+    const shipped = read.vendoredSkillNames.length > 0
+        ? read.vendoredSkillNames
+        : setup_plan_js_1.SHIPPED_SKILLS;
+    const { inRepo, dangling } = repoSkillState(read, shipped);
+    const sources = reachabilitySources(read, inRepo);
     const reachable = sources.length > 0;
     // A project declaration is NOT a source — it makes Claude Code prompt for an
     // install, it does not perform one. Only meaningful while unreachable.
     const settings = read.repo(".claude/settings.json");
-    const declaredNotInstalled = !reachable && settings !== null && hasEnabledPlugin(settings);
     const vendored = new Set(read.vendoredSkillNames);
     return {
         reachable,
         sources,
-        declaredNotInstalled,
+        declaredNotInstalled: !reachable && settings !== null && hasEnabledPlugin(settings),
         strandedSkills: reachable
             ? []
             : setup_plan_js_1.SHIPPED_SKILLS.filter((s) => vendored.has(s)),
+        danglingLinks: dangling,
+        unlinkedSkills: inRepo.length > 0
+            ? shipped.filter((s) => !inRepo.includes(s) && !dangling.includes(s))
+            : [],
+    };
+}
+/** Which shipped skills resolve in the repo, and which are links that dangle. */
+function repoSkillState(read, shipped) {
+    const resolves = (s) => read.repo(`${SKILLS_HOME}/${s}/SKILL.md`) !== null;
+    return {
+        inRepo: shipped.filter(resolves),
+        dangling: shipped.filter((s) => !resolves(s) && isOurLink(read.repoLink(`${SKILLS_HOME}/${s}`), s)),
     };
 }
 /**
- * The warning for an un-wired repo, or null when there is nothing to say
- * (reachable, or the check did not apply). Names the skill the user most likely
- * went looking for, says where the copies are stranded when they exist, and ends
- * on a command that fixes it.
+ * A link `vigiles init` wrote (into `node_modules/vigiles/skills/<name>`). A
+ * dangling link that only shares a shipped skill's NAME is the user's own, and
+ * "run npm install" would be advice about the wrong thing.
+ */
+function isOurLink(target, name) {
+    return target !== null && (0, skill_link_target_js_1.isVigilesSkillTarget)(target, name);
+}
+/** The sources that resolved, in check order. */
+function reachabilitySources(read, inRepo) {
+    const installed = read.home(".claude/plugins/installed_plugins.json");
+    return [
+        ...(installed !== null && hasGlobalPluginInstall(installed)
+            ? ["global-plugin"]
+            : []),
+        // Only vigiles's OWN skill names count. A repo with 38 unrelated skills in
+        // `.claude/skills/` is still un-wired.
+        ...(inRepo.length > 0 ? ["repo-skills"] : []),
+    ];
+}
+/**
+ * The advisory, or null when there is nothing to say. Most specific state
+ * first, each ending on the command that fixes it:
+ *
+ * 1. links that dangle — `npm install`;
+ * 2. nothing reaches the agent — link them (per repo), or install the plugin
+ *    (per machine);
+ * 3. only this machine's plugin reaches it — a fresh clone or container will
+ *    not have them. Not a failure; said in one line;
+ * 4. some linked, some not (an upgrade added one) — link the rest.
  */
 function formatSkillReachability(r) {
-    if (!r || r.reachable)
+    if (!r)
         return null;
+    if (r.danglingLinks.length > 0)
+        return formatDangling(r);
+    if (!r.reachable)
+        return formatUnreachable(r);
+    if (!r.sources.includes("repo-skills"))
+        return (`ℹ vigiles's skills reach your agent only through this machine's plugin ` +
+            `install (~/.claude/plugins/), so a fresh clone or container won't have ` +
+            `them.\n  Fix (per repo): ${LINK_FIX}`);
+    if (r.unlinkedSkills.length > 0)
+        return (`⚠ ${String(r.unlinkedSkills.length)} of vigiles's skills aren't linked ` +
+            `into ${SKILLS_HOME}/: ${r.unlinkedSkills.join(", ")}.\n  Fix: ${LINK_FIX}`);
+    return null;
+}
+/** Links that came with the clone, into a package that did not. */
+function formatDangling(r) {
+    const plugin = r.sources.includes("global-plugin")
+        ? " This machine's plugin install still provides them as vigiles:<name>."
+        : "";
+    return (`⚠ ${String(r.danglingLinks.length)} of vigiles's skills are linked into ` +
+        `${SKILLS_HOME}/ but the links don't resolve here — node_modules/vigiles ` +
+        `isn't installed.${plugin}\n` +
+        `  Fix: npm install (a session that started before it may need /reload-skills or a restart)`);
+}
+/** Nothing reaches the agent: the per-repo fix first, the per-machine one second. */
+function formatUnreachable(r) {
     const stranded = r.strandedSkills.length > 0
         ? ` ${String(r.strandedSkills.length)} of them are sitting in ` +
             `node_modules/vigiles/skills/, which the agent never scans.`
@@ -100,12 +163,12 @@ function formatSkillReachability(r) {
             `project declaration doesn't install it — Claude Code loads an ` +
             `external-source plugin only once each collaborator installs it on their ` +
             `own machine.`
-        : `This repo depends on vigiles, but its plugin isn't installed.`;
+        : `This repo depends on vigiles, but it does not link vigiles's skills and the plugin isn't installed here.`;
     return (`⚠ vigiles's skills are NOT reachable by your agent here. ${why} So the ` +
         `shipped skills (${setup_plan_js_1.SHIPPED_SKILLS.join(", ")}) can't be selected — ` +
         `including test-harness, which picks the testing tier for you.${stranded}\n` +
-        `  Fix (per machine): claude plugin marketplace add zernie/vigiles && ` +
-        `claude plugin install ${exports.VIGILES_PLUGIN_ID}\n` +
-        `  (or run \`vigiles init\`, which does both)`);
+        `  Fix (per repo, reaches every clone): ${LINK_FIX}\n` +
+        `  Or per machine: claude plugin marketplace add zernie/vigiles && ` +
+        `claude plugin install ${exports.VIGILES_PLUGIN_ID}`);
 }
 //# sourceMappingURL=skill-reachability.js.map