vigiles 33.2.0 → 34.0.0

package/dist/plugin-declaration.d.ts

@@ -17,12 +17,12 @@
  * boundary is deliberate: plugins "can execute arbitrary code on your machine
  * with your user privileges", so a repo is not allowed to install one for you.
  *
- * The declaration buys exactly one thing, and it is worth having: a collaborator
- * who clones the repo and never runs `vigiles init` currently gets **silence** —
- * the package is in `node_modules`, its six skills are unreachable, and nothing
- * says so. With the declaration, Claude Code tells them the project wants this
- * plugin and prints the command that installs it. **Silent absence becomes a
- * prompt.** It does not become a working install.
+ * The declaration buys exactly one thing: a collaborator who clones the repo is
+ * told the project wants this plugin, with the command that installs it.
+ * **Silent absence becomes a prompt.** It does not become a working install. What
+ * the plugin adds on their machine is the HOOKS; the SKILLS do not depend on it
+ * any more — `init` links them into `.claude/skills/` (`./skill-links.ts`), and
+ * the links travel with the clone.
  *
  * Nothing is vendored: what lands in the repo is a *reference* (a marketplace
  * source plus an enabled flag). The plugin content still lives in the global

package/dist/plugin-declaration.js

@@ -18,12 +18,12 @@
  * boundary is deliberate: plugins "can execute arbitrary code on your machine
  * with your user privileges", so a repo is not allowed to install one for you.
  *
- * The declaration buys exactly one thing, and it is worth having: a collaborator
- * who clones the repo and never runs `vigiles init` currently gets **silence** —
- * the package is in `node_modules`, its six skills are unreachable, and nothing
- * says so. With the declaration, Claude Code tells them the project wants this
- * plugin and prints the command that installs it. **Silent absence becomes a
- * prompt.** It does not become a working install.
+ * The declaration buys exactly one thing: a collaborator who clones the repo is
+ * told the project wants this plugin, with the command that installs it.
+ * **Silent absence becomes a prompt.** It does not become a working install. What
+ * the plugin adds on their machine is the HOOKS; the SKILLS do not depend on it
+ * any more — `init` links them into `.claude/skills/` (`./skill-links.ts`), and
+ * the links travel with the clone.
  *
  * Nothing is vendored: what lands in the repo is a *reference* (a marketplace
  * source plus an enabled flag). The plugin content still lives in the global

package/dist/setup-plan.d.ts

@@ -16,7 +16,10 @@ export interface SetupPlan {
     test: boolean;
     /** Wire CI (the `zernie/vigiles@v1` Action; creates a workflow if none). */
     gha: boolean;
-    /** Install the Claude Code plugin (hooks + skills). */
+    /**
+     * Install vigiles's skills + hooks for the agent: the skills LINKED into the
+     * repo (every clone), the Claude Code hooks via the per-machine plugin.
+     */
     plugin: boolean;
     /**
      * Adopt/scaffold the instruction file(s) into typed `.spec.ts` (the compiled
@@ -74,6 +77,11 @@ export interface ParsedSetupArgs {
      * DISCOVERY row of `cohesive-feature-delivery`.
      */
     ciOnly: boolean;
+    /**
+     * `--full` — run the whole setup even on a repo that already uses vigiles.
+     * Without it, a re-run there is the minimal one (see {@link rerunScope}).
+     */
+    full: boolean;
 }
 /** Parse `init` args into the choices the user pinned. The two pillars are
  * selected with `--lint` / `--test`. */
@@ -84,29 +92,6 @@ export declare function parseSetupArgs(args: readonly string[]): ParsedSetupArgs
  * raw files WITHOUT scaffolding a spec (gate-first-adoption). Non-interactive
  * behaviour is unchanged: bare `init` (lint on) scaffolds as before. */
 export declare function defaultPlan(strict?: boolean): SetupPlan;
-/**
- * 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).
- */
-export declare const STRUCTURAL_RULES: readonly ["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:
@@ -132,7 +117,24 @@ export declare const WORKFLOW_RULES: readonly ["require-instructions-spec", "unt
  * (research/install-enforcement-dx.md).
  */
 export declare const NUDGE_RULES: readonly ["skill-description-budget", "frontmatter-valid", "skill-frontmatter", "prefer-compiled-hooks", "unmarked-refs", "lethal-trifecta", "skill-resource-resolves", "skill-missing-fence", "plugin-dir-layout", "delegation-trifecta", "hook-block-ineffective", "hook-matcher", "doc-refs"];
-export declare function mergeProjectConfig(existing: Record<string, unknown>, opts: {
+/**
+ * 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`.
+ */
+export declare function mergeProjectConfig(existing: Readonly<Record<string, unknown>>, opts: Readonly<{
     /** Canonical harness names this repo targets, in the order to declare them. */
     harnesses: readonly string[];
     strict: boolean;
@@ -141,7 +143,7 @@ export declare function mergeProjectConfig(existing: Record<string, unknown>, op
      * concern, so a test-only setup (`init --test` / `--no-lint`) records the
      * harness but writes NO lint rules. */
     lint?: boolean;
-}): Record<string, unknown> | null;
+}>): Record<string, unknown> | null;
 /**
  * Whether to drop into interactive prompts: a human at a TTY who passed neither
  * `--yes` nor an explicit `--target`, and who hasn't already pinned every choice
@@ -193,15 +195,18 @@ export interface InstallPlan {
     notes: string[];
     /** Whether this method writes files into the consumer's repo (vendoring). */
     vendors: boolean;
+    /**
+     * Link the package's shipped skills into the repo's skills home
+     * (`src/skill-links.ts`). True only where the vendor documents following a
+     * symlinked skill folder — a link the harness skips is a silent absence.
+     */
+    linkSkills: boolean;
+    /**
+     * The global install carries HOOKS as well as skills, so linked skills do not
+     * replace it (see {@link shouldRunGlobalInstall}).
+     */
+    globalInstallCarriesHooks: boolean;
 }
-/** 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
@@ -212,9 +217,43 @@ export interface InstallPlan {
  * dogfood test in `src/adapters/claude-code/skills-dogfood.test.ts`.
  */
 export declare const SHIPPED_SKILLS: readonly ["adopt-spec", "debug-my-harness", "edit-spec", "linter-docs", "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).
+ */
 export declare function planPluginInstall(harnesses: readonly string[], opts: {
     hasClaude: boolean;
 }): InstallPlan[];
+/**
+ * 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).
+ */
+export declare function shouldRunGlobalInstall(plan: Readonly<Pick<InstallPlan, "globalInstallCarriesHooks">>, skillsLinked: boolean): boolean;
 /** One vigiles-managed Codex hook: a `[[hooks.<event>]]` entry. */
 export interface CodexPluginHook {
     readonly event: string;
@@ -252,6 +291,75 @@ export declare function codexPluginHooks(): CodexPluginHook[];
  * (and every other config key) untouched. Returns a new object.
  */
 export declare function applyCodexPluginHooks(existing: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Whether this repo already uses vigiles, decided from what is ON DISK.
+ *
+ * 🔴 THE SIGNAL IS `.vigilesrc.json` OR A SPEC NEXT TO AN INSTRUCTION FILE, and
+ * deliberately NOT a `vigiles` devDependency: the documented first step on a new
+ * repo can be `npm i -D vigiles` followed by `npx vigiles init`, and that run
+ * must still be the full setup. Every `init` writes `.vigilesrc.json` (it records
+ * the harnesses even on a test-only run), and a hand-written one means the owner
+ * has already configured vigiles. A spec beside `CLAUDE.md`/`AGENTS.md` covers a
+ * repo adopted before the config file existed.
+ */
+export type AdoptionState = {
+    readonly kind: "fresh";
+} | {
+    readonly kind: "adopted";
+    readonly evidence: string;
+};
+/** {@link AdoptionState} from the two disk facts that decide it. */
+export declare function adoptionState(facts: Readonly<{
+    hasConfig: boolean;
+    specs: readonly string[];
+}>): AdoptionState;
+/**
+ * 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.
+ */
+export declare function rerunScope(parsed: Readonly<ParsedSetupArgs>, state: AdoptionState): "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.
+ */
+export declare function missingVigilesDevDep(pkg: Readonly<{
+    dependencies?: Readonly<Record<string, string>>;
+    devDependencies?: Readonly<Record<string, string>>;
+}>, spec: string): Readonly<Record<string, string>> | null;
+/** What a full setup would add on an adopted repo — the facts that decide it. */
+export interface FullSetupGap {
+    /** `.github/workflows/vigiles.yml` is absent (and CI wiring is not opted out). */
+    readonly workflow: boolean;
+    /** `.vigilesrc.json`: absent, present without the preset, or already extending it. */
+    readonly config: "missing" | "no-preset" | "has-preset";
+    /** `vigiles.harness.mjs` is absent (and the test layer is not opted out). */
+    readonly harnessTest: boolean;
+    /** Instruction files and surfaces a full setup would adopt into a spec. */
+    readonly unspecced: readonly string[];
+    /** `.vigiles/generated.d.ts` / `.vigiles/schema.json` would be created. */
+    readonly generated: boolean;
+    /** The global plugin install / hook wiring a full setup would run, one line each. */
+    readonly installs: readonly string[];
+    /** The devDependency rewrite a full setup would make, if any. */
+    readonly devDep: Readonly<{
+        from: string;
+        to: string;
+    }> | null;
+}
+/**
+ * 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.
+ */
+export declare function fullSetupFollowUps(gap: FullSetupGap): readonly string[];
 /**
  * Resolve the final plan: defaults, then flags, then interactive answers (each
  * layer overrides the previous only where it has an opinion). `--target` pins a