vigiles 33.2.0 → 34.0.0

package/dist/cli-main.js

@@ -27,6 +27,7 @@ const generate_harness_js_1 = require("./core/generate-harness.js");
 const capability_diff_js_1 = require("./core/capability-diff.js");
 const validate_js_1 = require("./core/validate.js");
 const eval_lock_js_1 = require("./eval-lock.js");
+const zod_1 = require("zod");
 const cli_flags_js_1 = require("./cli-flags.js");
 const cli_commands_js_1 = require("./cli-commands.js");
 const cli_flag_check_js_1 = require("./cli-flag-check.js");
@@ -39,11 +40,13 @@ const frame_js_1 = require("./core/frame.js");
 const surface_discovery_js_1 = require("./core/surface-discovery.js");
 const scan_trigger_suggest_js_1 = require("./scan-trigger-suggest.js");
 const install_reader_js_1 = require("./core/install-reader.js");
+const skill_links_js_1 = require("./skill-links.js");
 const plugin_declaration_js_1 = require("./plugin-declaration.js");
 const local_files_tracked_js_1 = require("./local-files-tracked.js");
 const local_files_js_1 = require("./local-files.js");
 const scan_behavioral_js_1 = require("./scan-behavioral.js");
 const adapter_registry_js_1 = require("./adapter-registry.js");
+const layout_js_1 = require("./core/layout.js");
 const skill_harness_js_1 = require("./skill-harness.js");
 const leaderboard_js_1 = require("./leaderboard.js");
 const optimize_js_1 = require("./optimize.js");
@@ -2634,6 +2637,9 @@ function vigilesWorkflow(plan, harnesses, hasPackageJson) {
       - uses: actions/setup-node@v4
         with:
           node-version: "20"
+      # No \`version:\` on purpose: the Action runs the vigiles your
+      # package.json declares, so CI and a local \`npx vigiles\` cannot
+      # drift onto two different pins.
       - uses: zernie/vigiles@v1
 `
         : "";
@@ -3034,6 +3040,9 @@ function redirectSyncToolTargets(cwd, targets) {
         `staling the integrity hash.`);
     return out;
 }
+/** The two files `init`'s lint layer generates under `.vigiles/`. */
+const GENERATED_TYPES = ".vigiles/generated.d.ts";
+const GENERATED_SCHEMA = ".vigiles/schema.json";
 /** Pillar 1 — specs + types + schema + compile. Scaffolds a spec for every
  * instruction file (so `--lint` always delivers a spec), but never compiles
  * OVER a hand-written file — that is left to the adopt-spec skill. */
@@ -3079,7 +3088,7 @@ async function setupPillar1(detected, targetValue, harnesses) {
     const outDir = (0, node_path_1.resolve)(cwd, ".vigiles");
     if (!(0, node_fs_1.existsSync)(outDir))
         (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
-    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(cwd, ".vigiles/generated.d.ts"), typesResult.dts);
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(cwd, GENERATED_TYPES), typesResult.dts);
     for (const l of typesResult.linters) {
         console.log(`  ${l.linter}: ${String(l.rules.length)} rules`);
     }
@@ -3087,14 +3096,14 @@ async function setupPillar1(detected, targetValue, harnesses) {
         console.log(`  npm scripts: ${String(typesResult.scripts.length)}`);
     }
     console.log("✓ Generated .vigiles/generated.d.ts");
-    written.push(".vigiles/generated.d.ts");
+    written.push(GENERATED_TYPES);
     const schemaResult = (0, generate_schema_js_1.generateSchema)({
         basePath: cwd,
         linters: (0, validate_js_1.loadConfig)().linters,
     });
-    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(cwd, ".vigiles/schema.json"), schemaResult.json);
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(cwd, GENERATED_SCHEMA), schemaResult.json);
     console.log("✓ Generated .vigiles/schema.json (YAML-LSP frontmatter schema)");
-    written.push(".vigiles/schema.json");
+    written.push(GENERATED_SCHEMA);
     // Compile — but NEVER overwrite an existing hand-written file during `init`:
     // we compile only GREENFIELD targets (the file doesn't exist yet) and targets
     // we already manage (carry our hash). An ADOPTED file is left untouched — the
@@ -3177,29 +3186,226 @@ function reportInstall(plan, outcome) {
 }
 /**
  * Install vigiles's skills/hooks for the chosen harness(es) via the per-harness
- * `planPluginInstall` decision — Claude Code through the GLOBAL plugin
- * marketplace (nothing vendored into the repo), Codex via AGENTS.md-direct (no
- * global store). The decision is pure and unit-tested; this is the thin IO.
+ * `planPluginInstall` decision. Two carriers: the SKILLS are linked into the
+ * repo (`linkVigilesSkills`), so every clone and container has them after
+ * `npm install`; the GLOBAL install runs where it carries something the links
+ * cannot (`shouldRunGlobalInstall` — Claude Code's plugin carries the hooks).
+ * The decisions are pure and unit-tested; this is the thin IO.
+ *
+ * Returns the links it created or relinked, for the commit hint.
  */
 function installPlugins(harnesses) {
     const { execSync: exec } = require("node:child_process");
     const plans = (0, setup_plan_js_1.planPluginInstall)(harnesses, {
         hasClaude: harnesses.includes("claude") && harnessBinaryPresent("claude"),
     });
-    for (const plan of plans) {
+    const written = plans.flatMap((plan) => {
         console.log("");
-        reportInstall(plan, runInstall(plan, exec));
-    }
+        const home = plan.linkSkills ? harnessSkillsHome(plan.harness) : null;
+        const outcome = home === null ? null : linkVigilesSkills(home, process.cwd());
+        if (outcome !== null)
+            (0, skill_links_js_1.formatSkillLinks)(outcome).forEach((l) => {
+                console.log(l);
+            });
+        const linked = outcome !== null && (0, skill_links_js_1.skillLinksUsable)(outcome);
+        if ((0, setup_plan_js_1.shouldRunGlobalInstall)(plan, linked))
+            reportInstall(plan, runInstall(plan, exec));
+        else
+            console.log(`  No global ${plan.harness} skills install — the linked skills replace it, in every clone.`);
+        return outcome === null ? [] : changedLinks(outcome);
+    });
     // Claude Code gets its hooks from the global marketplace plugin; Codex has no
     // global store, so wire vigiles's proactive nudge hooks into the repo's
     // .codex/config.toml directly (the idiomatic, repo-committed place).
     if (harnesses.includes("codex"))
         wireCodexHooks();
     // Claude Code additionally gets a committed DECLARATION, so a collaborator who
-    // clones and never runs `init` is told the project wants this plugin instead
-    // of hitting the silence that costs a day. It does not install anything.
+    // clones and never runs `init` is told the project wants this plugin (its
+    // hooks) instead of silence. It does not install anything.
     if (harnesses.includes("claude"))
         declareVigilesPlugin();
+    return written;
+}
+/** The repo-relative skills home of the harness `init` calls `name`, or null. */
+function harnessSkillsHome(name) {
+    const adapter = (0, adapter_registry_js_1.getAdapter)(name);
+    return adapter === undefined ? null : (0, layout_js_1.skillsHome)(adapter.layout);
+}
+/** The repo-relative paths of the links this run created or rewrote — the ones git sees change. */
+function changedLinks(outcome) {
+    return outcome.kind === "linked"
+        ? outcome.results
+            .filter((r) => r.status === "created" || r.status === "relinked")
+            .map((r) => `${outcome.physicalHome}/${r.name}`)
+        : [];
+}
+/** The manifest file name the skill-linking code reads. */
+const PACKAGE_JSON = "package.json";
+/** One top-level field of `<dir>/package.json`, or undefined. Never throws. */
+function packageField(dir, field) {
+    try {
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, PACKAGE_JSON), "utf-8"));
+        return typeof pkg === "object" && pkg !== null
+            ? Object.entries(pkg).find(([k]) => k === field)?.[1]
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `package.json`'s `name`, or null. Never throws. */
+function packageNameAt(dir) {
+    const name = packageField(dir, "name");
+    return typeof name === "string" ? name : null;
+}
+/** A thrown value's message. */
+function errorText(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/** A path's real location, or null when it does not resolve. Never throws. */
+function realOrNull(path) {
+    try {
+        return (0, node_fs_1.realpathSync)(path);
+    }
+    catch {
+        return null;
+    }
+}
+/** What occupies `path`, for `planSkillLinks`. */
+function observeSkillEntry(path) {
+    const st = (0, node_fs_1.lstatSync)(path, { throwIfNoEntry: false });
+    if (st === undefined)
+        return { kind: "missing" };
+    if (st.isSymbolicLink())
+        return {
+            kind: "link",
+            target: (0, node_fs_1.readlinkSync)(path),
+            resolvesTo: realOrNull(path),
+        };
+    return st.isDirectory() ? { kind: "directory" } : { kind: "file" };
+}
+const LINK_IO = {
+    // "dir" matters only on Windows, where a directory link must say so.
+    symlink: (target, path) => {
+        (0, node_fs_1.symlinkSync)(target, path, "dir");
+    },
+    rename: node_fs_1.renameSync,
+    unlink: node_fs_1.unlinkSync,
+};
+/** Carry out one decision. A failed `symlink` is reported, never thrown. */
+function applySkillLink(decision, absHome) {
+    switch (decision.action) {
+        case "keep":
+            return { name: decision.name, status: "present" };
+        case "refuse":
+            return {
+                name: decision.name,
+                status: "skipped",
+                reason: decision.reason,
+            };
+        case "create":
+        case "replace":
+            try {
+                // Only a link `decideSkillLink` proved ours is ever replaced.
+                (0, skill_links_js_1.writeSkillLink)(LINK_IO, (0, node_path_1.join)(absHome, decision.name), decision.target, decision.action);
+                return {
+                    name: decision.name,
+                    status: decision.action === "replace" ? "relinked" : "created",
+                };
+            }
+            catch (e) {
+                const code = e instanceof Error && "code" in e && typeof e.code === "string"
+                    ? e.code
+                    : "";
+                return {
+                    name: decision.name,
+                    status: "skipped",
+                    reason: (0, skill_links_js_1.linkFailureReason)(code, errorText(e)),
+                };
+            }
+    }
+}
+/**
+ * Why `init` must not write under `absHome`, or null when it may. `.claude` or
+ * its `skills` can be a link to a dotfiles directory outside the repo; creating
+ * the home would follow it and put links where no commit of this repo reaches.
+ * What `mkdir -p` would write through is the nearest part of the path that
+ * already exists, so that is the part judged.
+ */
+function homeEscape(project, home, absHome) {
+    const nearest = (p) => (0, node_fs_1.lstatSync)(p, { throwIfNoEntry: false }) === undefined
+        ? nearest((0, node_path_1.dirname)(p))
+        : p;
+    const anchor = nearest(absHome);
+    const real = realOrNull(anchor);
+    if (real === null)
+        return `${(0, node_path_1.relative)(project, anchor)} is a link that does not resolve, so ${home} cannot be created`;
+    return (0, skill_links_js_1.isWithinProject)(project, real)
+        ? null
+        : `${home} leads to ${real}, outside the repository, and a link written there would not travel with a clone`;
+}
+/** The outcome when `init` makes no links, with the reason it prints. */
+function notLinked(reason) {
+    return { kind: "not-linked", reason };
+}
+/**
+ * Link vigiles's shipped skills into `home` (repo-relative) — the IO half of
+ * `src/skill-links.ts`, which decides everything: where the package is, what
+ * each entry becomes, and what the report says.
+ */
+function linkVigilesSkills(home, cwd) {
+    // Physical, so the relative target computed against the (physical) skills
+    // home is right even when the checkout sits under a symlink (macOS /tmp).
+    const project = (0, node_fs_1.realpathSync)(cwd);
+    const site = (0, skill_links_js_1.locatePackage)(project, {
+        isPackage: (dir) => packageNameAt(dir) === skill_links_js_1.VIGILES_PACKAGE,
+        isRepoRoot: (dir) => (0, node_fs_1.existsSync)((0, node_path_1.join)(dir, ".git")),
+        isWorkspaceRoot: (dir) => (0, node_fs_1.existsSync)((0, node_path_1.join)(dir, "pnpm-workspace.yaml")) ||
+            packageField(dir, "workspaces") !== undefined,
+    });
+    const pkgText = (0, node_fs_1.existsSync)((0, node_path_1.join)(project, PACKAGE_JSON))
+        ? (0, node_fs_1.readFileSync)((0, node_path_1.join)(project, PACKAGE_JSON), "utf-8")
+        : null;
+    const blocked = (0, skill_links_js_1.linkPrecondition)({
+        isVigilesItself: packageNameAt(project) === skill_links_js_1.VIGILES_PACKAGE,
+        dependsOnVigiles: pkgText !== null && (0, install_reader_js_1.declaresVigilesDependency)(pkgText),
+        installed: site.kind === "installed",
+    });
+    if (blocked !== null)
+        return notLinked(blocked);
+    if (site.kind === "unsure")
+        return notLinked(site.reason);
+    // Names from the installed package when there is one, else from this CLI's
+    // own — the version `init` just declared as the devDependency.
+    const source = site.kind === "installed" ? site.dir : selfRoot();
+    const names = setup_plan_js_1.SHIPPED_SKILLS.filter((n) => (0, node_fs_1.existsSync)((0, node_path_1.join)(source, "skills", n, "SKILL.md")));
+    if (names.length === 0)
+        return notLinked(`no shipped skills found under ${(0, node_path_1.join)(source, "skills")}`);
+    const absHome = (0, node_path_1.resolve)(project, home);
+    const escape = homeEscape(project, home, absHome);
+    if (escape !== null)
+        return notLinked(escape);
+    try {
+        (0, node_fs_1.mkdirSync)(absHome, { recursive: true });
+    }
+    catch (e) {
+        return notLinked(`cannot create ${home}: ${errorText(e)}`);
+    }
+    const physicalHome = (0, node_fs_1.realpathSync)(absHome);
+    const plan = (0, skill_links_js_1.planSkillLinks)({
+        names,
+        site,
+        physicalHome,
+        entries: (n) => observeSkillEntry((0, node_path_1.join)(absHome, n)),
+        realOf: (n) => realOrNull((0, node_path_1.join)(site.dir, "skills", n)),
+    });
+    return {
+        kind: "linked",
+        home,
+        physicalHome: (0, skill_links_js_1.portableTarget)((0, node_path_1.relative)(project, physicalHome)),
+        pending: plan.pending,
+        results: plan.decisions.map((d) => applySkillLink(d, absHome)),
+    };
 }
 /**
  * Write the project-level plugin declaration into `.claude/settings.json`.
@@ -3208,8 +3414,9 @@ function installPlugins(harnesses) {
  * collaborator: an external-source plugin declared project-level does not load
  * until each person installs it on their own machine (the boundary is
  * deliberate — plugins run arbitrary code with the user's privileges). What it
- * buys is that Claude Code then PROMPTS them with the install command, instead
- * of the silence a fresh clone gets today. Silent absence → a prompt.
+ * buys is that Claude Code then PROMPTS them with the install command — for the
+ * HOOKS, which only the plugin carries. The skills reach them through the
+ * committed links (`linkVigilesSkills`), with or without the plugin.
  *
  * MERGES, never clobbers: this file holds the user's hooks, permissions and
  * other plugins. The merge rules are the pure, unit-tested
@@ -3249,8 +3456,9 @@ function declareVigilesPlugin() {
     (0, node_fs_1.writeFileSync)(path, JSON.stringify(edit.settings, null, 2) + "\n");
     console.log("✓ Declared the vigiles plugin in .claude/settings.json (commit it)\n" +
         "  This does NOT install it for anyone else — Claude Code will PROMPT a\n" +
-        "  collaborator to run `claude plugin install vigiles@vigiles`, instead of\n" +
-        "  the silence a fresh clone gets today.\n" +
+        "  collaborator to run `claude plugin install vigiles@vigiles`, which is how\n" +
+        "  they get the hooks. The skills don't wait for it: they come with the\n" +
+        "  linked .claude/skills/ entries.\n" +
         "  Nothing is vendored: the entry is a reference; the plugin still lives in\n" +
         "  the global cache, one copy shared across your repos.");
 }
@@ -3408,8 +3616,24 @@ function printSetupSummary(opts) {
         console.log(`\n  Commit:\n    git add ${files.join(" ")} && git commit -m "Add vigiles"`);
     }
 }
+/** The project config file `init` reads and writes. */
+const VIGILESRC = ".vigilesrc.json";
 async function setup(args) {
     const parsed = (0, setup_plan_js_1.parseSetupArgs)(args);
+    // An already-adopted repo gets the MINIMAL re-run unless a flag asks for more
+    // (#338): re-running `init` to pick up one new piece must not also wire CI,
+    // widen the rules, scaffold files or rewrite a pin. Decided from disk, before
+    // any prompt — the minimal run asks nothing.
+    const state = (0, setup_plan_js_1.adoptionState)({
+        hasConfig: (0, node_fs_1.existsSync)((0, node_path_1.resolve)(process.cwd(), VIGILESRC)),
+        specs: detectProject()
+            .instructionFiles.filter((f) => f.hasSpec)
+            .map((f) => `${f.path}.spec.ts`),
+    });
+    if ((0, setup_plan_js_1.rerunScope)(parsed, state) === "minimal" && state.kind === "adopted") {
+        minimalRerun(parsed, state);
+        return;
+    }
     // Plan: defaults → flags → interactive prompts (only a human at a TTY).
     let plan = (0, setup_plan_js_1.resolvePlan)(parsed);
     const prompted = (0, setup_plan_js_1.shouldPrompt)(parsed, process.stdin.isTTY ?? false);
@@ -3460,10 +3684,9 @@ async function setup(args) {
         console.log("");
         written.push(...wireGha(plan, harnesses));
     }
-    // Plugin/skill install — per-harness (Claude marketplace / Codex direct).
-    if (plan.plugin) {
-        installPlugins(harnesses);
-    }
+    // Skills linked into the repo + the per-harness global install (Claude
+    // marketplace for the hooks / Codex only when nothing could be linked).
+    const linkedSkills = plan.plugin ? installPlugins(harnesses) : [];
     // Agent-specific guidance.
     if (targets.includes("AGENTS.md")) {
         console.log("\n  Codex / Copilot reads AGENTS.md directly — no hooks needed.");
@@ -3483,7 +3706,14 @@ async function setup(args) {
         lint: plan.lint,
         written,
     });
-    printSetupSummary({ plan, strict, targets, adopted, written });
+    printSetupSummary({
+        plan,
+        strict,
+        targets,
+        adopted,
+        // The skill links the plugin step created, so the commit hint names them.
+        written: [...written, ...linkedSkills],
+    });
     // Surface the OTHER mode so both directions are discoverable — the two branches
     // are mutually exclusive (a run is either gate-only or full):
     //   • a gate-only setup → a ONE-LINE nudge to graduate to the full layer;
@@ -3500,6 +3730,152 @@ async function setup(args) {
         console.log("\nℹ Ran the standard setup. Already have a harness, or not a JS/Python repo, and want only the CI integrity gate (nothing installed)? Re-run `npx vigiles init --ci-only`.");
     }
 }
+/**
+ * The minimal re-run on an adopted repo (#338): add what is missing AND safe and
+ * local — the skill links and a missing devDependency — then say what a full
+ * setup would add and the flag that does it. It writes NOTHING else: no CI
+ * workflow, no `.vigilesrc.json` edit, no harness/schema scaffold, no spec for a
+ * hand-written file, no edit to an existing version pin, no global install.
+ * The decisions are pure (`setup-plan.ts`); this is the IO.
+ */
+function minimalRerun(parsed, state) {
+    const plan = (0, setup_plan_js_1.resolvePlan)(parsed);
+    const detected = detectProject();
+    const harnesses = resolveHarnesses(parsed, detected, (0, adapter_registry_js_1.declaredHarnessNames)((0, validate_js_1.loadConfig)().harnesses));
+    console.log(`vigiles is already set up here (found ${state.evidence}) — adding only what is missing.\n`);
+    printDetection(detected, harnesses);
+    const links = plan.plugin ? linkSkillsOnly(harnesses) : [];
+    const devDep = plan.lint || plan.test ? addMissingVigilesDevDep() : [];
+    const written = [...links, ...devDep];
+    if (written.length === 0)
+        console.log("\nNothing was missing.");
+    const followUps = (0, setup_plan_js_1.fullSetupFollowUps)(fullSetupGap(plan, detected, harnesses));
+    if (followUps.length > 0)
+        console.log(`\n${followUps.join("\n")}`);
+    if (written.length > 0)
+        console.log(`\n  Commit:\n    git add ${written.join(" ")} && git commit -m "Update vigiles"`);
+}
+/**
+ * Link the shipped skills for each harness that links them — the safe, local
+ * half of `installPlugins`, without the global install or config wiring.
+ * Returns the links created or rewritten.
+ */
+function linkSkillsOnly(harnesses) {
+    return (0, setup_plan_js_1.planPluginInstall)(harnesses, { hasClaude: false }).flatMap((plan) => {
+        const home = plan.linkSkills ? harnessSkillsHome(plan.harness) : null;
+        if (home === null)
+            return [];
+        const outcome = linkVigilesSkills(home, process.cwd());
+        console.log("");
+        (0, skill_links_js_1.formatSkillLinks)(outcome).forEach((l) => {
+            console.log(l);
+        });
+        return changedLinks(outcome);
+    });
+}
+/** Add vigiles to `devDependencies` only when nothing declares it. */
+function addMissingVigilesDevDep() {
+    const pkgPath = (0, node_path_1.resolve)(process.cwd(), PACKAGE_JSON);
+    if (!(0, node_fs_1.existsSync)(pkgPath))
+        return [];
+    const pkg = readPackageJson(pkgPath);
+    if (pkg === null || pkg.name === "vigiles")
+        return [];
+    const spec = vigilesDepSpec();
+    const devDependencies = (0, setup_plan_js_1.missingVigilesDevDep)(pkg, spec);
+    if (devDependencies === null)
+        return [];
+    (0, node_fs_1.writeFileSync)(pkgPath, JSON.stringify({ ...pkg, devDependencies }, null, 2) + "\n");
+    console.log(`\n✓ Added vigiles@${spec} to devDependencies — run \`npm install\` to fetch it`);
+    return [PACKAGE_JSON];
+}
+/**
+ * The fields of package.json the dependency decisions read. LOOSE on purpose:
+ * every other key is carried through untouched, because the result is written
+ * back and a re-run must not drop a field it never looked at.
+ */
+const packageDepsSchema = zod_1.z.looseObject({
+    name: zod_1.z.string().optional(),
+    dependencies: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional(),
+    devDependencies: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional(),
+});
+/** package.json parsed for its dependency fields; null when unreadable. */
+function readPackageJson(path) {
+    try {
+        const parsed = packageDepsSchema.safeParse(JSON.parse((0, node_fs_1.readFileSync)(path, "utf-8")));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * What a full setup would add here, read from disk — the input to the
+ * follow-up lines. It mirrors the full path's own conditions (the plan's
+ * layers, the existence checks those steps make), so the list names what
+ * `--full` would actually do rather than everything it could.
+ */
+function fullSetupGap(plan, detected, harnesses) {
+    const cwd = process.cwd();
+    const has = (rel) => (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, rel));
+    const config = readProjectConfig((0, node_path_1.resolve)(cwd, VIGILESRC));
+    const pillar1 = plan.lint && plan.scaffoldSpecs;
+    const unspecced = pillar1
+        ? [
+            ...determineTargets(detected, undefined, [...harnesses]),
+            ...discoverAdoptableSurfaces(cwd),
+        ].filter((t, i, all) => all.indexOf(t) === i && !has(`${t}.spec.ts`))
+        : [];
+    const pkg = has(PACKAGE_JSON)
+        ? readPackageJson((0, node_path_1.resolve)(cwd, PACKAGE_JSON))
+        : null;
+    const declared = pkg?.devDependencies?.vigiles ?? pkg?.dependencies?.vigiles ?? null;
+    const spec = vigilesDepSpec();
+    return {
+        workflow: plan.gha && !has(".github/workflows/vigiles.yml"),
+        config: configGap(config, plan.lint),
+        harnessTest: plan.test && !has("vigiles.harness.mjs"),
+        unspecced,
+        generated: pillar1 && !(has(GENERATED_TYPES) && has(GENERATED_SCHEMA)),
+        installs: plan.plugin ? fullInstallLines(harnesses) : [],
+        devDep: declared !== null && declared !== spec && pkg?.name !== "vigiles"
+            ? { from: declared, to: spec }
+            : null,
+    };
+}
+/** Where `.vigilesrc.json` stands against the preset a full setup writes. */
+function configGap(config, lint) {
+    if (config === null)
+        return "missing";
+    return config.extends === undefined && lint ? "no-preset" : "has-preset";
+}
+/** `.vigilesrc.json` as a plain object, or null when absent or unreadable. */
+function readProjectConfig(path) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    try {
+        const raw = JSON.parse((0, node_fs_1.readFileSync)(path, "utf-8"));
+        return typeof raw === "object" && raw !== null && !Array.isArray(raw)
+            ? { ...raw }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The per-machine installs and config wiring the full plugin step would run. */
+function fullInstallLines(harnesses) {
+    return (0, setup_plan_js_1.planPluginInstall)(harnesses, { hasClaude: true }).flatMap((plan) => [
+        ...(plan.globalInstallCarriesHooks && plan.commands.length > 0
+            ? [
+                `install the ${plan.harness} plugin for this machine (${plan.commands.join(" && ")}) and declare it in the project settings`,
+            ]
+            : []),
+        ...(plan.vendors
+            ? [`wire vigiles's nudge hooks into the ${plan.harness} config`]
+            : []),
+    ]);
+}
 /** Canonical, de-duplicated harness names — the keys `harnesses` gets. */
 function harnessConfigKeys(harnesses) {
     return [...new Set(harnesses.map(adapter_registry_js_1.normalizeHarnessName))];
@@ -5239,6 +5615,10 @@ function capabilitiesOfReport(report, dialect) {
 const COMMAND_HELP = {
     init: {
         usage: "  vigiles init [flags]       Set up this repo — specs, plugin, and CI.",
+        detail: [
+            "  Already set up? A re-run only adds what is missing (skill links, the devDependency);",
+            "  --full                     run the whole setup again",
+        ],
     },
     compile: { usage: "  vigiles compile [files...] Compile .spec.ts → .md" },
     eject: {

package/dist/core/adapter.d.ts

@@ -182,6 +182,13 @@ export interface InstallReader {
      * outside its own surface.
      */
     readonly repo: (repoRelative: string) => string | null;
+    /**
+     * The stored target of a repo SYMLINK (what `readlink` returns), or null when
+     * the path is not a link, is missing, or is NOT a path this adapter claims.
+     * It answers the one question `repo` cannot: a committed link whose target is
+     * not installed yet reads as null through `repo`, exactly like no link at all.
+     */
+    readonly repoLink: (repoRelative: string) => string | null;
     /**
      * A file under the user's HOME, or null. This is a read of the MACHINE, never
      * of the repository — the plugin-install record lives there — and everything