vigiles 33.2.0 → 34.0.0

package/dist/setup-plan.js

@@ -10,7 +10,7 @@
  * on a prompt. See docs/agent-setup.md.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SHIPPED_SKILLS = exports.NUDGE_RULES = exports.WORKFLOW_RULES = exports.STRUCTURAL_RULES = void 0;
+exports.SHIPPED_SKILLS = exports.NUDGE_RULES = exports.WORKFLOW_RULES = void 0;
 exports.parseSetupArgs = parseSetupArgs;
 exports.defaultPlan = defaultPlan;
 exports.mergeProjectConfig = mergeProjectConfig;
@@ -18,9 +18,15 @@ exports.shouldPrompt = shouldPrompt;
 exports.collectSetupAnswers = collectSetupAnswers;
 exports.gateOnlyInvitation = gateOnlyInvitation;
 exports.planPluginInstall = planPluginInstall;
+exports.shouldRunGlobalInstall = shouldRunGlobalInstall;
 exports.codexPluginHooks = codexPluginHooks;
 exports.applyCodexPluginHooks = applyCodexPluginHooks;
+exports.adoptionState = adoptionState;
+exports.rerunScope = rerunScope;
+exports.missingVigilesDevDep = missingVigilesDevDep;
+exports.fullSetupFollowUps = fullSetupFollowUps;
 exports.resolvePlan = resolvePlan;
+const presets_js_1 = require("./core/presets.js");
 function flagValue(args, prefix) {
     return args.find((a) => a.startsWith(prefix))?.slice(prefix.length);
 }
@@ -47,6 +53,7 @@ function parseSetupArgs(args) {
         gha: args.includes("--no-gha") ? false : undefined,
         plugin: args.includes("--no-plugin") ? false : undefined,
         ciOnly: args.includes("--ci-only"),
+        full: args.includes("--full"),
     };
 }
 /** The non-interactive defaults: both pillars, CI, and the plugin. `scaffoldSpecs`
@@ -65,39 +72,6 @@ function defaultPlan(strict = false) {
         force: false,
     };
 }
-/**
- * Pure config-merge for what `vigiles init` writes to `.vigilesrc.json`: record
- * the `harness` if absent, add strict rule severities if `--strict`, NEVER
- * clobber an existing key. Returns the merged config, or `null` when nothing
- * changed (so the IO layer skips the write). The IO (read/parse/write + the
- * malformed-file guard) stays in cli.ts.
- */
-/**
- * The structural rules `init` gates BY DEFAULT (severity `error`, so a broken
- * surface fails `vigiles lint`). Every one is HIGH-PRECISION / FP-safe — it fires
- * only on a genuine defect (a never-available/typo'd tool, a subagent missing
- * `name`/`description`, a typo'd hook event, a dead hook script, a broken MCP
- * ref, two skills that collide in the selector) — so a well-formed plugin stays
- * green and catching real breakage out of the box never cries wolf.
- *
- * Deliberately EXCLUDES `require-instructions-spec` and the workflow-forcing rules:
- * those make a CLEAN repo fail (you simply haven't written the spec/test yet), so
- * they stay opt-in under `--strict` (progressive adoption — see
- * `STRICT_EXTRA_RULES`).
- *
- * This is the **`structural`** rule group (see research/install-enforcement-dx.md).
- */
-exports.STRUCTURAL_RULES = [
-    "subagent-tool-contract",
-    "subagent-frontmatter",
-    "hook-events",
-    "hook-script-exists",
-    "mcp-config",
-    "mcp-tool-resolves",
-    "mcp-hook-target-resolves",
-    "disallowed-tools-contract",
-    "description-overlap",
-];
 /**
  * The **`workflow`** group — the WORKFLOW-FORCING / opinionated tier `--strict`
  * gates, which a clean repo can still fail because you haven't done the work yet:
@@ -146,41 +120,53 @@ exports.NUDGE_RULES = [
     // than config. See docs/rules/doc-refs.md.
     "doc-refs",
 ];
+/**
+ * Pure config-merge for what `vigiles init` writes to `.vigilesrc.json`: record
+ * the harnesses if absent, gate the structural rules by EXTENDING the
+ * `vigiles:recommended` preset (never by writing each rule), add the workflow
+ * rules on `--strict`, and NEVER clobber an existing key or severity. Returns
+ * the merged config, or `null` when nothing changed (so the IO layer skips the
+ * write). The IO (read/parse/write + the malformed-file guard) stays in cli.ts.
+ *
+ * 🔴 THE PRESET, NOT NINE LINES (#338). Written lines are a snapshot of the
+ * structural group on the day `init` ran, so a repo adopted earlier never got a
+ * rule added to the group later; the preset is resolved by the loader on every
+ * run (`src/core/presets.ts`).
+ *
+ * `--report-only` is the exception and stays EXPLICIT: it promises that nothing
+ * fails CI, and extending a preset that later gains a rule at `error` would
+ * break that promise on an upgrade. So it writes the same rules at `warn`.
+ */
 function mergeProjectConfig(existing, opts) {
-    const config = { ...existing };
-    let changed = false;
     // The NESTED key (#240). `init` writes the declaration with no roots — a repo
     // whose surfaces sit where its harness reads them needs none, and a root is a
-    // fact only the owner knows. Writing the flat `harness`/`surfaceRoots` pair
-    // here would emit a config the loader now REFUSES, which is why this one line
-    // moved with the shape even though the rest of `init` did not.
-    if (config.harnesses === undefined) {
-        config.harnesses = Object.fromEntries(opts.harnesses.map((h) => [h, {}]));
-        changed = true;
-    }
-    // The rule gate belongs to the LINT layer — a test-only setup records the
-    // harness but writes no rules (honoring the positive-flag contract that
-    // `--test` selects only the test pillar).
-    if (opts.lint !== false) {
-        // Gate the FP-safe `structural` group by default; `--strict` adds the
-        // `workflow` group on top. `--report-only` is the orthogonal severity dial —
-        // it writes the SAME rule set at "warn" (nothing fails CI; the
-        // migration/observe mode). Never clobber a severity the user already set —
-        // only fill the undefined ones.
-        const severity = opts.reportOnly ? "warn" : "error";
-        const gate = opts.strict
-            ? [...exports.STRUCTURAL_RULES, ...exports.WORKFLOW_RULES]
-            : [...exports.STRUCTURAL_RULES];
-        const rules = { ...config.rules };
-        for (const r of gate) {
-            if (rules[r] === undefined) {
-                rules[r] = severity;
-                changed = true;
-            }
-        }
-        config.rules = rules;
-    }
-    return changed ? config : null;
+    // fact only the owner knows.
+    const harnesses = existing.harnesses === undefined
+        ? { harnesses: Object.fromEntries(opts.harnesses.map((h) => [h, {}])) }
+        : {};
+    const gate = opts.lint === false ? {} : lintGate(existing, opts);
+    const added = { ...harnesses, ...gate };
+    return Object.keys(added).length === 0 ? null : { ...existing, ...added };
+}
+/**
+ * The lint-layer keys `init` adds: `extends` and/or the `rules` it fills.
+ * Only the keys that CHANGE are returned, so an already-satisfied config
+ * yields `{}` and is not rewritten.
+ */
+function lintGate(existing, opts) {
+    const workflow = opts.strict ? exports.WORKFLOW_RULES : [];
+    const explicit = opts.reportOnly
+        ? [...presets_js_1.RECOMMENDED_RULES, ...workflow]
+        : workflow;
+    const severity = opts.reportOnly ? "warn" : "error";
+    const before = (existing.rules ?? {});
+    // Never clobber a severity the user already set — only fill the undefined ones.
+    const filled = Object.fromEntries(explicit.filter((r) => before[r] === undefined).map((r) => [r, severity]));
+    const rules = Object.keys(filled).length === 0 ? {} : { rules: { ...before, ...filled } };
+    const preset = opts.reportOnly || existing.extends !== undefined
+        ? {}
+        : { extends: presets_js_1.RECOMMENDED_PRESET };
+    return { ...preset, ...rules };
 }
 /**
  * Whether to drop into interactive prompts: a human at a TTY who passed neither
@@ -225,7 +211,7 @@ async function collectSetupAnswers(ask) {
     }
     const pillars = (await ask("Set up which pillars? [both/lint/test] (both): ", "both")).toLowerCase();
     const gha = isYesAnswer(await ask("Wire CI (GitHub Action)? [Y/n]: ", "y"));
-    const plugin = isYesAnswer(await ask("Install the Claude Code plugin (hooks + skills)? [Y/n]: ", "y"));
+    const plugin = isYesAnswer(await ask("Install vigiles's skills + hooks for your agent (skills linked into the repo, hooks via the Claude Code plugin)? [Y/n]: ", "y"));
     // Structural gating (broken tools/hooks/MCP/collisions) is always on. This asks
     // about the WORKFLOW tier — a spec per file + a test per surface — which a clean
     // repo can fail just for not having done the work yet, so it's the recommended
@@ -287,16 +273,8 @@ function gateOnlyInvitation(plan) {
     const gateOnly = !plan.plugin && !plan.scaffoldSpecs;
     if (!gateOnly)
         return null;
-    return "→ Want your agent to maintain this + measure whether your skills fire? Run `npx vigiles init` and choose 'full' (installs the skills). Optional — the gate above already works.";
+    return "→ Want your agent to maintain this + measure whether your skills fire? Run `npx vigiles init --full` and choose 'full' (installs the skills). Optional — the gate above already works.";
 }
-/** Per-harness install plan. `hasClaude` gates the auto-run `claude plugin` CLI
- * (else the same two steps are printed as `/plugin` slash commands).
- *
- * Both methods install GLOBALLY, never into the repo: Claude through its plugin
- * marketplace (~/.claude/plugins/), Codex through the cross-agent `skills` CLI
- * with `-g -y` (the global store ~/.agents/skills/, which Codex reads). Codex
- * gets the skills but NOT hooks — Codex hook wiring (.codex/config.toml [hooks])
- * is not automated yet. */
 /**
  * The SHIPPED consumer skills (the `skills/` dir, published via `plugin.json`) —
  * the ONLY ones a user's install should get. The cross-agent `skills` CLI would
@@ -314,70 +292,111 @@ exports.SHIPPED_SKILLS = [
     "strengthen",
     "test-harness",
 ];
+/**
+ * Per-harness install plan. `hasClaude` gates the auto-run `claude plugin` CLI
+ * (else the same two steps are printed as `/plugin` slash commands).
+ *
+ * TWO CARRIERS, by what each one reaches. The SKILLS are linked into the repo
+ * (`linkSkills`), so every clone and container has them after `npm install`. The
+ * GLOBAL installs reach one machine: Claude Code's plugin (~/.claude/plugins/)
+ * is still the only carrier of vigiles's Claude Code HOOKS, so it always runs;
+ * Codex's `skills` CLI install (~/.agents/skills/) carries skills only, so it
+ * runs only when the links could not be made (no `package.json` to install
+ * into). Codex's nudge hooks are written into `.codex/config.toml` directly.
+ *
+ * THE CODEX GLOBAL COMMAND. The cross-agent `skills` CLI with `-g -y` installs
+ * to the global store ~/.agents/skills/ (NOT the repo, and NOT ~/.codex/ —
+ * verified against the real CLI). It is scoped to the SHIPPED skills with `-s`
+ * — without it the `skills` CLI installs EVERY SKILL.md in the repo, leaking
+ * the contributor-only .claude/skills/ into the user's global store
+ * (#dogfood-I2; confirmed — the CLI's `-l` list shows 17 skills for this repo,
+ * incl. .claude/skills). The `-s` parser is SPACE-separated (it consumes
+ * consecutive non-dash args), NOT comma-separated — a comma list is read as one
+ * literal skill name, matches nothing, and the install exits 1 (verified against
+ * the real `skills@1.5.20` arg parser).
+ */
 function planPluginInstall(harnesses, opts) {
-    return harnesses.map((harness) => {
-        if (harness === "claude") {
-            return {
-                harness,
-                commands: opts.hasClaude
-                    ? [
-                        "claude plugin marketplace add zernie/vigiles",
-                        "claude plugin install vigiles@vigiles",
-                    ]
-                    : [],
-                successMessage: "✓ Installed the vigiles plugin (hooks + skills) into ~/.claude/plugins/",
-                manualSteps: [
-                    "/plugin marketplace add zernie/vigiles",
-                    "/plugin install vigiles@vigiles",
-                ],
-                notes: [
-                    "Installs globally to ~/.claude/plugins/ — nothing is added to your repo.",
-                ],
-                vendors: false,
-            };
-        }
-        if (harness === "codex") {
-            // The cross-agent `skills` CLI with `-g -y` installs to the global store
-            // ~/.agents/skills/ (NOT the repo, and NOT ~/.codex/ — verified against
-            // the real CLI). Skills install globally; the proactive NUDGE hooks
-            // (eval-lock + refs) are wired into the repo's .codex/config.toml by
-            // `init` (see codexPluginHooks / wireCodexHooks) — Codex config is
-            // repo-committed, so that's the idiomatic place.
-            // Scope to the SHIPPED skills with `-s` — without it the `skills` CLI
-            // installs EVERY SKILL.md in the repo, leaking the contributor-only
-            // .claude/skills/ into the user's global store (#dogfood-I2; confirmed —
-            // the CLI's `-l` list shows 17 skills for this repo, incl. .claude/skills).
-            // The `-s` parser is SPACE-separated (it consumes consecutive non-dash
-            // args), NOT comma-separated — a comma list is read as one literal skill
-            // name, matches nothing, and the install exits 1 (verified against the
-            // real `skills@1.5.20` arg parser).
-            const skillScope = `-s ${exports.SHIPPED_SKILLS.join(" ")}`;
-            return {
-                harness,
-                commands: [
-                    `npx --yes skills add zernie/vigiles -a codex ${skillScope} -g -y`,
-                ],
-                successMessage: "✓ Installed the vigiles skills into ~/.agents/skills/ (global, not vendored)",
-                manualSteps: [
-                    `npx skills add zernie/vigiles -a codex ${skillScope} -g -y`,
-                ],
-                notes: [
-                    "Codex reads AGENTS.md directly; the skills install globally to ~/.agents/skills/ (not the repo).",
-                    "The eval-lock + refs NUDGE hooks are wired into .codex/config.toml (repo-committed, the Codex norm).",
-                    "Still manual on Codex: the SessionStart lint summary + compile-on-edit/pre-edit guards (no harness-neutral entrypoint yet).",
-                ],
-                vendors: true,
-            };
-        }
+    return harnesses.map((harness) => ({
+        ...globalInstallFor(harness, opts),
+        ...skillCarriers(harness),
+    }));
+}
+/**
+ * How the skills and the hooks travel for one harness. Linking is on only where
+ * the vendor documents following a symlinked skill folder (quoted in
+ * `./skill-links.ts`); the global install "carries hooks" only for Claude Code,
+ * whose plugin is where its hooks live.
+ */
+function skillCarriers(harness) {
+    if (harness === "claude")
+        return { linkSkills: true, globalInstallCarriesHooks: true };
+    // eslint-disable-next-line local/no-harness-names -- init's per-harness install plan is keyed by harness name, like the global install beside it
+    if (harness === "codex")
+        return { linkSkills: true, globalInstallCarriesHooks: false };
+    return { linkSkills: false, globalInstallCarriesHooks: false };
+}
+/** The global install half of {@link planPluginInstall}, per harness. */
+function globalInstallFor(harness, opts) {
+    if (harness === "claude") {
         return {
             harness,
-            commands: [],
-            successMessage: "",
-            manualSteps: [],
-            notes: [`No plugin install path for harness '${harness}'.`],
+            commands: opts.hasClaude
+                ? [
+                    "claude plugin marketplace add zernie/vigiles",
+                    "claude plugin install vigiles@vigiles",
+                ]
+                : [],
+            successMessage: "✓ Installed the vigiles plugin (hooks + skills) into ~/.claude/plugins/",
+            manualSteps: [
+                "/plugin marketplace add zernie/vigiles",
+                "/plugin install vigiles@vigiles",
+            ],
+            notes: [
+                "The plugin installs globally to ~/.claude/plugins/ and carries the hooks (and a namespaced copy of the skills, listed as vigiles:<name>) on this machine only.",
+            ],
             vendors: false,
         };
-    });
+    }
+    if (harness === "codex") {
+        const skillScope = `-s ${exports.SHIPPED_SKILLS.join(" ")}`;
+        return {
+            harness,
+            commands: [
+                `npx --yes skills add zernie/vigiles -a codex ${skillScope} -g -y`,
+            ],
+            successMessage: "✓ Installed the vigiles skills into ~/.agents/skills/ (global, not vendored)",
+            manualSteps: [
+                `npx skills add zernie/vigiles -a codex ${skillScope} -g -y`,
+            ],
+            notes: [
+                "Codex reads AGENTS.md directly; the skills install globally to ~/.agents/skills/ (not the repo).",
+                "The eval-lock + refs NUDGE hooks are wired into .codex/config.toml (repo-committed, the Codex norm).",
+                "Still manual on Codex: the SessionStart lint summary + compile-on-edit/pre-edit guards (no harness-neutral entrypoint yet).",
+            ],
+            vendors: true,
+        };
+    }
+    return {
+        harness,
+        commands: [],
+        successMessage: "",
+        manualSteps: [],
+        notes: [`No plugin install path for harness '${harness}'.`],
+        vendors: false,
+    };
+}
+/**
+ * Run a plan's GLOBAL install, given whether the skills were linked into the
+ * repo? Skip it only when linked skills make it redundant — when it carries
+ * nothing but skills. Running it anyway would list every skill twice (Codex:
+ * "If two skills share the same `name`, Codex doesn't merge them; both can
+ * appear in skill selectors"). Claude Code's plugin carries the hooks, so it
+ * always runs; its skills are namespaced `vigiles:<name>` and load beside the
+ * linked `<name>` (a known, documented duplicate until the hooks move into the
+ * repo too).
+ */
+function shouldRunGlobalInstall(plan, skillsLinked) {
+    return plan.globalInstallCarriesHooks || !skillsLinked;
 }
 /**
  * vigiles's proactive nudges, wired into a Codex repo's `.codex/config.toml`.
@@ -436,6 +455,87 @@ function applyCodexPluginHooks(existing) {
     }
     return { ...existing, hooks };
 }
+/** {@link AdoptionState} from the two disk facts that decide it. */
+function adoptionState(facts) {
+    if (facts.hasConfig)
+        return { kind: "adopted", evidence: ".vigilesrc.json" };
+    const [spec] = facts.specs;
+    return spec === undefined
+        ? { kind: "fresh" }
+        : { kind: "adopted", evidence: spec };
+}
+/**
+ * Which setup a run performs: the full one, or the minimal re-run (#338).
+ *
+ * MINIMAL only when the repo is adopted AND the run named nothing that asks for
+ * more. A flag that selects or widens the setup (`--full`, `--strict`,
+ * `--ci-only`, `--report-only`, `--force`, `--target=`, a positive `--lint` /
+ * `--test`) is an explicit request and keeps today's behaviour; the narrowing
+ * flags (`--no-*`, `--harness=`, `--yes`) do not, because they can only make a
+ * run do less.
+ */
+function rerunScope(parsed, state) {
+    if (state.kind === "fresh")
+        return "full";
+    const asksForMore = parsed.full ||
+        parsed.strict ||
+        parsed.ciOnly ||
+        parsed.reportOnly ||
+        parsed.force ||
+        parsed.target !== undefined ||
+        parsed.lint === true ||
+        parsed.test === true;
+    return asksForMore ? "full" : "minimal";
+}
+/**
+ * The `devDependencies` a minimal re-run writes, or null to leave package.json
+ * alone. It ADDS vigiles when no dependency field declares it and never edits an
+ * existing declaration: rewriting `^33.3.0` to `^33` loosens a pin the owner
+ * chose, and moving it between fields is a decision, not a missing piece.
+ */
+function missingVigilesDevDep(pkg, spec) {
+    const declared = pkg.dependencies?.vigiles !== undefined ||
+        pkg.devDependencies?.vigiles !== undefined;
+    return declared ? null : { ...pkg.devDependencies, vigiles: spec };
+}
+/**
+ * The lines a minimal re-run prints about what it did NOT do: each thing a full
+ * setup would add here, then the flag that does it. Empty when nothing is
+ * missing, so a fully set-up repo is not told to run anything.
+ */
+function fullSetupFollowUps(gap) {
+    const configLine = {
+        missing: `write .vigilesrc.json with your harnesses and "extends": "${presets_js_1.RECOMMENDED_PRESET}" (structural rules fail CI)`,
+        "no-preset": `add "extends": "${presets_js_1.RECOMMENDED_PRESET}" to .vigilesrc.json (structural rules fail CI)`,
+        "has-preset": null,
+    };
+    const items = [
+        gap.workflow
+            ? "create .github/workflows/vigiles.yml (a CI workflow — new CI minutes)"
+            : null,
+        configLine[gap.config],
+        gap.harnessTest
+            ? "scaffold vigiles.harness.mjs (a starter harness test)"
+            : null,
+        gap.unspecced.length > 0
+            ? `write specs for ${String(gap.unspecced.length)} hand-written file(s): ${gap.unspecced.join(", ")}`
+            : null,
+        gap.generated
+            ? "generate .vigiles/generated.d.ts and .vigiles/schema.json"
+            : null,
+        ...gap.installs,
+        gap.devDep === null
+            ? null
+            : `set the vigiles devDependency to ${gap.devDep.to} (yours: ${gap.devDep.from})`,
+    ].filter((l) => l !== null);
+    return items.length === 0
+        ? []
+        : [
+            "A full setup would also:",
+            ...items.map((l) => `  - ${l}`),
+            "Run `npx vigiles init --full` for that (flags such as --no-gha still apply).",
+        ];
+}
 /**
  * Resolve the final plan: defaults, then flags, then interactive answers (each
  * layer overrides the previous only where it has an opinion). `--target` pins a

package/dist/skill-links.d.ts

@@ -0,0 +1,183 @@
+/** The package whose skills are linked. */
+export declare const VIGILES_PACKAGE = "vigiles";
+/** What occupies `<skills home>/<name>` today, as the IO edge observed it. */
+export type SkillEntry = {
+    readonly kind: "missing";
+} | {
+    readonly kind: "link";
+    /** The link's stored target, exactly as `readlink` returns it. */
+    readonly target: string;
+    /** Where it resolves, or null when it dangles. */
+    readonly resolvesTo: string | null;
+} | {
+    readonly kind: "directory";
+} | {
+    readonly kind: "file";
+};
+/** What `init` should do about one skill. */
+export type SkillLinkDecision = {
+    readonly name: string;
+    /** `replace`: an earlier `init`'s link that now points at the wrong place. */
+    readonly action: "create" | "replace";
+    readonly target: string;
+} | {
+    readonly name: string;
+    readonly action: "keep";
+} | {
+    readonly name: string;
+    readonly action: "refuse";
+    readonly reason: string;
+};
+/** The link `init` wants for one skill. */
+export interface WantedLink {
+    /** The relative target to write (and to recognise on a re-run). */
+    readonly target: string;
+    /** The real path of the shipped skill, or null while it is not installed. */
+    readonly real: string | null;
+}
+/**
+ * Decide one entry. A link with OUR target is ours even while it dangles — that
+ * is exactly how a committed link looks in a clone that has not run
+ * `npm install` yet, and calling it foreign would make re-running `init` noisy
+ * in precisely the place it is meant to help.
+ */
+export declare function decideSkillLink(name: string, entry: SkillEntry, want: WantedLink): SkillLinkDecision;
+/** Where the package is, as the project spells it. */
+export type PackageSite = 
+/** Installed: `<ancestor>/node_modules/vigiles`, inside the repository. */
+{
+    readonly kind: "installed";
+    readonly dir: string;
+}
+/** Not installed yet: where npm puts the devDependency `init` declares. */
+ | {
+    readonly kind: "expected";
+    readonly dir: string;
+}
+/**
+ * Not installed, and the project is a member of a workspace: npm and yarn
+ * hoist its dependencies to the workspace ROOT's `node_modules`, pnpm keeps
+ * them in the member's own, and a hoist can be refused by a version
+ * conflict. Which one happens is decided by the install, so no link is made
+ * before it — a guessed link can dangle for good.
+ */
+ | {
+    readonly kind: "unsure";
+    readonly reason: string;
+};
+/** What the walk may ask of the filesystem. */
+export interface PackageProbe {
+    /** Is `dir` an installed vigiles package (its `package.json` names it)? */
+    readonly isPackage: (dir: string) => boolean;
+    /** Is `dir` the repository root (it holds `.git`)? The walk stops there. */
+    readonly isRepoRoot: (dir: string) => boolean;
+    /** Is `dir` a workspace root (`workspaces` in package.json, or pnpm-workspace.yaml)? */
+    readonly isWorkspaceRoot: (dir: string) => boolean;
+}
+/**
+ * Node's own lookup — the first `node_modules/vigiles` up the tree — bounded by
+ * the repository root, because a committed link that leaves the repository is a
+ * link only this machine can follow.
+ */
+export declare function locatePackage(project: string, probe: PackageProbe): PackageSite;
+/**
+ * Is the real path `path` the project's own real path or somewhere under it?
+ * Both must be physical (symlink-free), or a link could pass for a child.
+ */
+export declare function isWithinProject(project: string, path: string): boolean;
+/** The facts that decide whether linking makes sense at all here. */
+export interface LinkFacts {
+    /** The project IS vigiles — its skills are the plugin's own `skills/`. */
+    readonly isVigilesItself: boolean;
+    /** `package.json` declares vigiles (so `npm install` will put it in node_modules). */
+    readonly dependsOnVigiles: boolean;
+    /** The package already resolves from the project. */
+    readonly installed: boolean;
+}
+/**
+ * Why NOT to link, or null to go ahead. A link into a `node_modules/vigiles`
+ * that no install will ever create is a dangling link committed to the repo — a
+ * worse state than no link, because it looks like the job was done.
+ */
+export declare function linkPrecondition(facts: LinkFacts): string | null;
+/** Everything {@link planSkillLinks} needs, observed by the IO edge. */
+export interface SkillLinkInput {
+    /** The skills the package ships. */
+    readonly names: readonly string[];
+    readonly site: Exclude<PackageSite, {
+        kind: "unsure";
+    }>;
+    /**
+     * The skills home as it PHYSICALLY exists (`.claude` may itself be a link).
+     * A relative link target resolves against the directory that holds the link.
+     */
+    readonly physicalHome: string;
+    readonly entries: (name: string) => SkillEntry;
+    /** The real path of the installed skill, or null. */
+    readonly realOf: (name: string) => string | null;
+}
+/** The decisions, and whether the links will dangle until `npm install`. */
+export interface SkillLinkPlan {
+    readonly pending: boolean;
+    readonly decisions: readonly SkillLinkDecision[];
+}
+/**
+ * A link target as it is committed: `/` separators on every OS. `relative()` on
+ * Windows yields `..\\..\\node_modules\\…`, and a clone on Linux or macOS
+ * reads those backslashes as ordinary filename characters, so the link dangles.
+ */
+export declare function portableTarget(target: string, separator?: string): string;
+export declare function planSkillLinks(input: SkillLinkInput): SkillLinkPlan;
+/** The three filesystem calls that write a link; the IO edge passes the real ones. */
+export interface LinkIo {
+    readonly symlink: (target: string, path: string) => void;
+    readonly rename: (from: string, to: string) => void;
+    readonly unlink: (path: string) => void;
+}
+/** Where a replacement link is built before it takes the old one's place. */
+export declare function relinkTempPath(entry: string): string;
+/**
+ * Write the link `decision` asks for. A `replace` never leaves a gap: the new
+ * link is built under a temporary name beside the old one and renamed over it,
+ * which is atomic. Removing the old link first would lose it for good when the
+ * new one cannot be created (a Windows account without the symlink privilege,
+ * a full disk) — a skill that worked yesterday gone, and only a warning to show
+ * for it. Any failure leaves the old link in place and throws.
+ */
+export declare function writeSkillLink(io: LinkIo, entry: string, target: string, action: "create" | "replace"): void;
+/** Why a `symlink` call failed, with the fix when there is a known one. */
+export declare function linkFailureReason(code: string, message: string): string;
+/** One skill's result after the IO ran. */
+export type SkillLinkResult = {
+    readonly name: string;
+    readonly status: "created" | "relinked" | "present";
+} | {
+    readonly name: string;
+    readonly status: "skipped";
+    readonly reason: string;
+};
+/** What `init` did about the skills for one harness. */
+export type SkillLinkOutcome = {
+    readonly kind: "linked";
+    /** Repo-relative skills home, e.g. `.claude/skills`. */
+    readonly home: string;
+    /**
+     * The same home with every symlink resolved, repo-relative with `/`.
+     * Git refuses a pathspec that runs through a symlink, so the commit hint
+     * names this one.
+     */
+    readonly physicalHome: string;
+    readonly pending: boolean;
+    readonly results: readonly SkillLinkResult[];
+} | {
+    readonly kind: "not-linked";
+    readonly reason: string;
+};
+/** At least one shipped skill now reaches the agent through a link. */
+export declare function skillLinksUsable(outcome: SkillLinkOutcome): boolean;
+/**
+ * The lines `init` prints. Skipped skills are named one by one: the user loses
+ * that skill, and the reason is theirs to act on.
+ */
+export declare function formatSkillLinks(outcome: SkillLinkOutcome): readonly string[];
+//# sourceMappingURL=skill-links.d.ts.map