vigiles 7.0.0 → 8.0.0

package/dist/setup-plan.d.ts

@@ -27,6 +27,10 @@ export interface SetupPlan {
 export interface ParsedSetupArgs {
     target?: string;
     strict: boolean;
+    /** `--report-only` — write the gating rules at "warn" (nothing fails CI). The
+     * orthogonal severity dial; composes with `--strict` (which rules) by setting
+     * their severity. */
+    reportOnly: boolean;
     yes: boolean;
     /** `--force` — rewrite a stale CI workflow in place. */
     force: boolean;
@@ -51,9 +55,52 @@ export declare function defaultPlan(strict?: boolean): SetupPlan;
  * 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:
+ * a spec per instruction file (`require-instructions-spec`), a test/eval per
+ * surface (`untested-*`). Opt-in by design (the smooth-adoption on-ramp). The
+ * Clippy-`pedantic` / TS-`strict` analog — ONE opinionated opt-in.
+ *
+ * NB `frontmatter-valid` / `skill-frontmatter` live in the `nudge` group, not
+ * here: they're acknowledged-noisy recommendations we never gate on (see
+ * research/install-enforcement-dx.md).
+ */
+export declare const WORKFLOW_RULES: readonly ["require-instructions-spec", "untested-skill", "untested-subagent", "untested-hook"];
+/**
+ * The **`nudge`** group — recommendations / acknowledged-noisy checks that NEVER
+ * gate (not even under `--strict`): `frontmatter-valid` (js-yaml is stricter than
+ * CC's loader), `skill-frontmatter` (skills load without it) and `unmarked-refs`
+ * (the undecidable-plaintext nudge) sit at `warn`; `prefer-compiled-hooks` defaults
+ * OFF (a recommendation that shouldn't fire unasked — the shell lane stays
+ * first-class). `init` does not write these — they keep their own default
+ * severities. Named for the group taxonomy (research/install-enforcement-dx.md).
+ */
+export declare const NUDGE_RULES: readonly ["frontmatter-valid", "skill-frontmatter", "prefer-compiled-hooks", "unmarked-refs"];
 export declare function mergeProjectConfig(existing: Record<string, unknown>, opts: {
     harness: string | string[];
     strict: boolean;
+    reportOnly?: boolean;
+    /** Whether the LINT pillar is on (default true). The rule gate is a lint-layer
+     * concern, so a test-only setup (`init --test` / `--no-lint`) records the
+     * harness but writes NO lint rules. */
+    lint?: boolean;
 }): Record<string, unknown> | null;
 /**
  * Whether to drop into interactive prompts: a human at a TTY who passed neither
@@ -62,7 +109,18 @@ export declare function mergeProjectConfig(existing: Record<string, unknown>, op
  */
 export declare function shouldPrompt(parsed: ParsedSetupArgs, isTTY: boolean): boolean;
 /** Interactive answers (only the fields the prompts cover). */
-export type SetupAnswers = Partial<Pick<SetupPlan, "lint" | "test" | "gha" | "plugin">>;
+export type SetupAnswers = Partial<Pick<SetupPlan, "lint" | "test" | "gha" | "plugin" | "strict">>;
+/** Ask one question with a default — injected so the interactive Q&A is pure +
+ *  unit-testable (a fake `ask` scripts answers; no TTY, no readline). */
+export type AskFn = (question: string, def: string) => Promise<string>;
+/**
+ * The interactive setup Q&A as PURE logic over an injected `ask` — the prompts,
+ * their defaults, and the answer→`SetupAnswers` mapping. The IO shell (readline)
+ * lives in `cli.ts`'s `promptSetup`, which just supplies a real `ask`. Keeping
+ * this here means the fragile interactive path is unit-tested deterministically
+ * (the questions can't silently break) without a terminal.
+ */
+export declare function collectSetupAnswers(ask: AskFn): Promise<SetupAnswers>;
 /**
  * How to install vigiles's skills/hooks for ONE harness — the deterministic
  * decision behind the IO in cli.ts, so a CI test asserts WHICH commands an

package/dist/setup-plan.js

@@ -10,10 +10,12 @@
  * on a prompt. See docs/agent-setup.md.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.NUDGE_RULES = exports.WORKFLOW_RULES = exports.STRUCTURAL_RULES = void 0;
 exports.parseSetupArgs = parseSetupArgs;
 exports.defaultPlan = defaultPlan;
 exports.mergeProjectConfig = mergeProjectConfig;
 exports.shouldPrompt = shouldPrompt;
+exports.collectSetupAnswers = collectSetupAnswers;
 exports.planPluginInstall = planPluginInstall;
 exports.resolvePlan = resolvePlan;
 function flagValue(args, prefix) {
@@ -33,6 +35,7 @@ function parseSetupArgs(args) {
     return {
         target: flagValue(args, "--target="),
         strict: args.includes("--strict"),
+        reportOnly: args.includes("--report-only"),
         yes: args.includes("--yes") || args.includes("-y"),
         force: args.includes("--force"),
         lint: boolFlag(args, "lint"),
@@ -60,6 +63,64 @@ function defaultPlan(strict = false) {
  * 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:
+ * a spec per instruction file (`require-instructions-spec`), a test/eval per
+ * surface (`untested-*`). Opt-in by design (the smooth-adoption on-ramp). The
+ * Clippy-`pedantic` / TS-`strict` analog — ONE opinionated opt-in.
+ *
+ * NB `frontmatter-valid` / `skill-frontmatter` live in the `nudge` group, not
+ * here: they're acknowledged-noisy recommendations we never gate on (see
+ * research/install-enforcement-dx.md).
+ */
+exports.WORKFLOW_RULES = [
+    "require-instructions-spec",
+    "untested-skill",
+    "untested-subagent",
+    "untested-hook",
+];
+/**
+ * The **`nudge`** group — recommendations / acknowledged-noisy checks that NEVER
+ * gate (not even under `--strict`): `frontmatter-valid` (js-yaml is stricter than
+ * CC's loader), `skill-frontmatter` (skills load without it) and `unmarked-refs`
+ * (the undecidable-plaintext nudge) sit at `warn`; `prefer-compiled-hooks` defaults
+ * OFF (a recommendation that shouldn't fire unasked — the shell lane stays
+ * first-class). `init` does not write these — they keep their own default
+ * severities. Named for the group taxonomy (research/install-enforcement-dx.md).
+ */
+exports.NUDGE_RULES = [
+    "frontmatter-valid",
+    "skill-frontmatter",
+    "prefer-compiled-hooks",
+    "unmarked-refs",
+];
 function mergeProjectConfig(existing, opts) {
     const config = { ...existing };
     let changed = false;
@@ -67,13 +128,23 @@ function mergeProjectConfig(existing, opts) {
         config.harness = opts.harness;
         changed = true;
     }
-    if (opts.strict) {
+    // 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 };
-        // `require-skill-spec` is deprecated (skills can be hand-written), so --strict
-        // no longer promotes it; it tightens only `require-spec` (instruction files).
-        for (const r of ["require-spec"]) {
+        for (const r of gate) {
             if (rules[r] === undefined) {
-                rules[r] = "error";
+                rules[r] = severity;
                 changed = true;
             }
         }
@@ -93,6 +164,31 @@ function shouldPrompt(parsed, isTTY) {
     const allPinned = pillarsPinned && parsed.gha !== undefined && parsed.plugin !== undefined;
     return !allPinned;
 }
+const isYesAnswer = (s) => /^y(es)?$/i.test(s);
+/**
+ * The interactive setup Q&A as PURE logic over an injected `ask` — the prompts,
+ * their defaults, and the answer→`SetupAnswers` mapping. The IO shell (readline)
+ * lives in `cli.ts`'s `promptSetup`, which just supplies a real `ask`. Keeping
+ * this here means the fragile interactive path is unit-tested deterministically
+ * (the questions can't silently break) without a terminal.
+ */
+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"));
+    // 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
+    // default a human opts OUT of (never forced on a silent run).
+    const strict = isYesAnswer(await ask("Also enforce specs + a test per surface (recommended)? [Y/n]: ", "y"));
+    return {
+        lint: pillars !== "test",
+        test: pillars !== "lint" && pillars !== "verify",
+        gha,
+        plugin,
+        strict,
+    };
+}
 /**
  * Apply the pillar flags. A positive flag (`--lint` and/or `--test`) is an
  * explicit SELECTION — enable exactly the named pillars. Otherwise default to
@@ -118,6 +214,8 @@ function applyAnswers(plan, answers) {
         plan.gha = answers.gha;
     if (answers.plugin !== undefined)
         plan.plugin = answers.plugin;
+    if (answers.strict !== undefined)
+        plan.strict = answers.strict;
 }
 /** Per-harness install plan. `hasClaude` gates the auto-run `claude plugin` CLI
  * (else the same two steps are printed as `/plugin` slash commands).

package/hooks/post-edit.sh

@@ -19,7 +19,7 @@ BASENAME=$(basename "$FILE")
 case "$BASENAME" in
   eslint.config.*|.eslintrc*|.stylelintrc*|.rubocop.yml|pyproject.toml|Cargo.toml|package.json)
     if command -v npx &>/dev/null && [ -f "package.json" ]; then
-      npx vigiles generate-types 2>&1 || true
+      npx vigiles generate types 2>&1 || true
     fi
     ;;
 esac

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "7.0.0",
+  "version": "8.0.0",
   "description": "Lint & test the harness your AI agent runs on — verify the references in your CLAUDE.md / AGENTS.md and test that your hooks and skills actually work.",
   "keywords": [
     "claude-code",

package/skills/adopt-spec/SKILL.md

@@ -7,7 +7,7 @@ argument-hint: <path to CLAUDE.md, defaults to CLAUDE.md>
 
 Start a typed `CLAUDE.md.spec.ts` from an existing hand-written CLAUDE.md (or AGENTS.md). This is the non-destructive adoption path — you keep your existing instruction file as the starting point and get type safety going forward.
 
-> **Don't need full TypeScript?** A typed spec is the deepest commitment level. If the user only wants verified rules without a build step, point them at markdown mode first: inline `<!-- vigiles:enforce ... -->` comments (Level 0) or a `vigiles:` YAML frontmatter block with `vigiles generate-schema` for editor autocomplete (Level 1). Both are verified by `vigiles lint` with the same engine as a spec. See `docs/markdown-mode.md`. Adopt a spec only when they want compiler-grade guarantees.
+> **Faithful by default, and reversible.** Adoption is non-destructive: the goal is a spec that compiles back to the user's existing file as closely as possible — preserve every rule, command, key file, and prose section. Don't upgrade `guidance()` to `enforce()` here; that's a separate, opt-in step (the `strengthen` skill). And it's never a one-way door — `vigiles eject <file>` hands the file back as plain hand-owned markdown anytime. For the lightest touch with no spec at all, inline `<!-- vigiles:enforce ... -->` comments are verified by `vigiles lint` with the same engine.
 
 ## Instructions
 
@@ -100,9 +100,9 @@ Show the user:
 2. How many rules were converted (enforce vs guidance vs TODO)
 3. How many file/cmd refs were added for stale reference detection
 4. The command to compile: `npx vigiles compile`
-5. The command to verify: `npx vigiles check`
+5. The command to verify: `npx vigiles lint`
 
-Ask if they want you to write the file. If yes, also suggest adding to `.gitignore` or updating CI to run `vigiles compile` and `vigiles check`.
+Ask if they want you to write the file. If yes, also suggest adding to `.gitignore` or updating CI to run `vigiles compile` and `vigiles lint`.
 
 ### Step 6: Optional — Set Up CI
 
@@ -111,14 +111,14 @@ If the user wants CI integration, suggest adding to their GitHub Actions workflo
 ```yaml
 - name: Compile specs
   run: npx vigiles compile
-- name: Verify integrity
-  run: npx vigiles check
+- name: Verify references + integrity
+  run: npx vigiles lint
 ```
 
 Or using the vigiles GitHub Action:
 
 ```yaml
-- uses: zernie/vigiles@main
+- uses: zernie/vigiles@v1
   with:
-    command: check
+    command: lint
 ```

package/skills/linter-docs/eslint.md

@@ -365,7 +365,7 @@ If two rules try to fix the same range of code, ESLint drops both fixes. Avoid t
 ### Monorepo considerations
 
 - ESLint flat config is resolved from `cwd`, not from the file being linted. In a monorepo, set `cwd` to the package root, not the workspace root.
-- `vigiles generate-types` discovers ESLint rules using `calculateConfigForFile("dummy.js")` from the project `basePath`. If your monorepo has different configs per package, run `generate-types` from each package root.
+- `vigiles generate types` discovers ESLint rules using `calculateConfigForFile("dummy.js")` from the project `basePath`. If your monorepo has different configs per package, run `generate types` from each package root.
 - Plugin rules must be installed in the `node_modules` visible from the config file's location. Hoisted deps in a monorepo can cause "plugin not found" errors — install them in the package's own `devDependencies`.
 
 ## Mapping PR Feedback to Rule Strategy

package/skills/strengthen/SKILL.md

@@ -20,7 +20,7 @@ Default to interactive if the user doesn't specify.
 
 ### Step 1: Discover What's Installed
 
-Run `npx vigiles generate-types` to get the full list of enabled linter rules in the project. Read `.vigiles/generated.d.ts` to see every rule available across all detected linters.
+Run `npx vigiles generate types` to get the full list of enabled linter rules in the project. Read `.vigiles/generated.d.ts` to see every rule available across all detected linters.
 
 Note which linter prefixes appear in the generated types (e.g., `EslintRule`, `RuffRule`). You'll only need reference docs for detected linters.