vigiles 39.0.0 → 39.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/action.yml +18 -0
  2. package/dist/adapters/claude-code/dialect.js +5 -0
  3. package/dist/audit-report.d.ts +14 -1
  4. package/dist/audit-report.js +21 -5
  5. package/dist/audit-report.template.html +33 -28
  6. package/dist/audit-score.d.ts +4 -1
  7. package/dist/audit-score.js +3 -1
  8. package/dist/audit-verdict.d.ts +3 -1
  9. package/dist/cli-flag-check.d.ts +1 -1
  10. package/dist/cli-flag-check.js +5 -1
  11. package/dist/cli-flags.d.ts +1 -1
  12. package/dist/cli-main.js +153 -72
  13. package/dist/core/CLAUDE.md.spec.js +2 -2
  14. package/dist/core/adopt.js +32 -8
  15. package/dist/core/apply-rules.d.ts +71 -0
  16. package/dist/core/apply-rules.js +48 -0
  17. package/dist/core/compile.d.ts +1 -1
  18. package/dist/core/compile.js +47 -14
  19. package/dist/core/config-migrations.d.ts +69 -0
  20. package/dist/core/config-migrations.js +145 -0
  21. package/dist/core/config-schema.d.ts +163 -187
  22. package/dist/core/config-schema.js +185 -345
  23. package/dist/core/dialect.d.ts +1 -1
  24. package/dist/core/dialect.js +2 -0
  25. package/dist/core/linter-adapter.d.ts +1 -1
  26. package/dist/core/presets.d.ts +31 -46
  27. package/dist/core/presets.js +25 -51
  28. package/dist/core/rule.d.ts +213 -0
  29. package/dist/core/rule.js +37 -0
  30. package/dist/core/skill-resources.d.ts +85 -15
  31. package/dist/core/skill-resources.js +63 -37
  32. package/dist/core/spec.d.ts +17 -0
  33. package/dist/core/types.d.ts +12 -314
  34. package/dist/core/validate.d.ts +13 -12
  35. package/dist/core/validate.js +29 -28
  36. package/dist/doc-commands.d.ts +2 -2
  37. package/dist/optimize.d.ts +2 -1
  38. package/dist/overrides.d.ts +13 -9
  39. package/dist/overrides.js +1 -1
  40. package/dist/rules/CLAUDE.md.spec.d.ts +3 -0
  41. package/dist/rules/CLAUDE.md.spec.js +22 -0
  42. package/dist/rules/groups.d.ts +32 -0
  43. package/dist/rules/groups.js +27 -0
  44. package/dist/rules/index.d.ts +412 -0
  45. package/dist/{core/rule-meta.js → rules/index.js} +301 -209
  46. package/dist/rules/skill-resource-resolves.d.ts +36 -0
  47. package/dist/rules/skill-resource-resolves.js +51 -0
  48. package/dist/run-hook.d.ts +1 -1
  49. package/dist/scan-core.d.ts +7 -9
  50. package/dist/scan-core.js +7 -10
  51. package/dist/scan-files.js +1 -4
  52. package/dist/scan.d.ts +11 -16
  53. package/dist/scan.js +31 -8
  54. package/dist/score-core.js +3 -9
  55. package/dist/setup-plan.d.ts +6 -26
  56. package/dist/setup-plan.js +27 -60
  57. package/dist/skill-harness.d.ts +3 -1
  58. package/dist/skill-harness.js +5 -2
  59. package/dist/vigilesrc.schema.json +18 -3
  60. package/package.json +2 -2
  61. package/packages/eslint-config/index.mjs +61 -0
  62. package/dist/core/rule-meta.d.ts +0 -94
@@ -1,6 +1,7 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.skillResourceIssues = skillResourceIssues;
4
+ exports.repoRootOnlyAdvice = repoRootOnlyAdvice;
4
5
  /**
5
6
  * vigiles — SKILL bundled-resource resolution (the cross-reference moat applied
6
7
  * to a SKILL.md body).
@@ -308,51 +309,76 @@ function candidateFor(ref, line) {
308
309
  */
309
310
  const DISABLE_RE = /<!--\s*vigiles-disable\s+skill-resource-resolves\s*-->/;
310
311
  /**
311
- * The bundled-resource references in a SKILL.md body that don't resolve on disk
312
- * under `skillDir`. Pure + FP-safe (see the module header). `skillDir` is the
313
- * directory the SKILL.md itself lives in (resources are bundled beside it).
312
+ * Look a candidate up, in the order a reader of the skill would: beside the
313
+ * SKILL.md, then the repo root through a DECLARED shared dir (resolved — the
314
+ * repo said this tree is shared), then the repo root on its own (`repo-root-only`
315
+ * — it works from here, but nothing declared it, so it is reported).
316
+ */
317
+ function lookup(rel, skillDir, opts) {
318
+ const exists = opts.existsSync;
319
+ if (exists((0, posix_path_js_1.resolve)(skillDir, rel)))
320
+ return "found";
321
+ if (opts.repoRoot === undefined)
322
+ return "missing";
323
+ if (!exists((0, posix_path_js_1.resolve)(opts.repoRoot, rel)))
324
+ return "missing";
325
+ const sharedDirs = opts.sharedDirs ?? [];
326
+ return sharedDirs.includes(rel.split("/")[0]) ? "found" : "repo-root-only";
327
+ }
328
+ /**
329
+ * Reads a SKILL.md body, finds every file it mentions (`scripts/x.sh`,
330
+ * `[guide](references/guide.md)`), and returns the ones that are NOT in the
331
+ * skill's own folder. Files that are there are not returned at all.
332
+ *
333
+ * ```ts
334
+ * // skillDir = .claude/skills/deploy, repoRoot = the repo
335
+ * skillResourceIssues("Run `scripts/deploy.sh`.\nSee `scripts/smoke.sh`.", skillDir, {
336
+ * existsSync, repoRoot,
337
+ * });
338
+ * // → [{ ref: "scripts/deploy.sh", resolution: "repo-root-only", … },
339
+ * // { ref: "scripts/smoke.sh", resolution: "missing", … }]
340
+ * ```
314
341
  *
315
- * The shared detector behind both `vigiles lint` (the `skill-resource-resolves`
316
- * rule) and `vigiles audit` (the read-only report) — one detector, no drift.
342
+ * Despite the name, the result holds both kinds: `missing` (a real break) and
343
+ * `repo-root-only` (works here, breaks when installed elsewhere — a note). The
344
+ * split into two lists happens once, in `collectSurfaceFindings`. It only reads
345
+ * the file system through the injected `existsSync`, so it runs on disk and in
346
+ * the browser, and `lint` and `audit` both call it.
317
347
  */
318
348
  function skillResourceIssues(skillBody, skillDir, opts) {
319
349
  if (DISABLE_RE.test(skillBody))
320
350
  return [];
321
- const exists = opts.existsSync;
322
351
  const lineOffset = opts.lineOffset ?? 0;
323
- const sharedDirs = new Set(opts.sharedDirs ?? []);
324
- // A ref resolves if it exists under the skill's own dir. If (and only if) its
325
- // first segment is a DECLARED shared dir, it may also resolve against the repo
326
- // root — the opt-in shared-tree case. No shared dirs → skill-dir-only (unchanged).
327
- const resolvesAnywhere = (rel) => {
328
- if (exists((0, posix_path_js_1.resolve)(skillDir, rel)))
329
- return true;
330
- const firstSeg = rel.split("/")[0];
331
- return (opts.repoRoot !== undefined &&
332
- sharedDirs.has(firstSeg) &&
333
- exists((0, posix_path_js_1.resolve)(opts.repoRoot, rel)));
334
- };
335
- const findings = [];
336
- const seen = new Set();
337
352
  const lines = skillBody.split("\n");
338
- for (const ref of (0, markdown_js_1.markdownRefs)(skillBody)) {
353
+ const reported = (0, markdown_js_1.markdownRefs)(skillBody).flatMap((ref) => {
339
354
  const c = candidateFor(ref, lines[ref.line - 1] ?? "");
340
355
  if (c === null)
341
- continue;
342
- if (resolvesAnywhere(c.resolved))
343
- continue;
344
- // De-dupe the same missing file referenced several times in the body.
345
- const key = `${c.kind}:${c.resolved}`;
346
- if (seen.has(key))
347
- continue;
348
- seen.add(key);
349
- findings.push({
350
- ref: c.ref,
351
- resolved: c.resolved,
352
- kind: c.kind,
353
- line: c.line + lineOffset,
354
- });
355
- }
356
- return findings;
356
+ return [];
357
+ const resolution = lookup(c.resolved, skillDir, opts);
358
+ return resolution === "found"
359
+ ? []
360
+ : [{ ...c, line: c.line + lineOffset, resolution }];
361
+ });
362
+ // De-dupe the same file referenced several times in the body: the first
363
+ // mention is the one reported.
364
+ return reported.filter((f, i) => reported.findIndex((g) => g.kind === f.kind && g.resolved === f.resolved) === i);
365
+ }
366
+ /**
367
+ * What a `repo-root-only` finding means and what to do about it — ONE sentence
368
+ * shared by every surface that prints the note (`audit`'s text and HTML report,
369
+ * `lint`'s line and its CI annotation), so they cannot drift apart.
370
+ *
371
+ * The cure depends on the path's shape: `sharedDirs` declares a top-level
372
+ * DIRECTORY, so a ref under one (`scripts/check.sh`) can be declared shared,
373
+ * while a bare file at the root (`guide.md`) has no directory to declare and the
374
+ * only cure is to ship it beside the SKILL.md.
375
+ */
376
+ function repoRootOnlyAdvice(f) {
377
+ const slash = f.resolved.indexOf("/");
378
+ const cure = slash > 0
379
+ ? `If repo-root resolution is intended, add "${f.resolved.slice(0, slash)}" to sharedDirs in .vigilesrc.json.`
380
+ : "Ship it beside the SKILL.md if the skill is meant to be installed elsewhere.";
381
+ return ("resolves only from the repo root, not from the skill directory — " +
382
+ `it breaks once the skill is installed outside this repository. ${cure}`);
357
383
  }
358
384
  //# sourceMappingURL=skill-resources.js.map
@@ -495,6 +495,23 @@ export interface SkillSpec {
495
495
  * for the default inline execution.
496
496
  */
497
497
  readonly context?: "fork";
498
+ /**
499
+ * The subagent type a forked skill starts (`agent` frontmatter): a built-in
500
+ * type (`Explore`, `Plan`, `general-purpose`) or a custom one from the
501
+ * harness's agents directory. Requires `context: "fork"` — without a fork
502
+ * there is no subagent to pick (compile error `agent-without-fork`). Omitted,
503
+ * the harness uses `general-purpose`.
504
+ */
505
+ readonly agent?: string;
506
+ /**
507
+ * The model the skill runs on (`model` frontmatter): an alias (`sonnet`,
508
+ * `opus`, `haiku`, `fable`), a full model id, or `inherit`. With
509
+ * `context: "fork"` it sets the forked subagent's model; inline, it overrides
510
+ * the model for the rest of the current turn. Omitted on a forked skill, the
511
+ * subagent resolves to the main conversation's model — which is the costly
512
+ * default this field exists to override.
513
+ */
514
+ readonly model?: string;
498
515
  /**
499
516
  * The allowed-tools contract for this skill. Each entry must be a known
500
517
  * built-in tool or an MCP tool (`mcp__server__tool`). Omit to inherit all
@@ -1,5 +1,6 @@
1
1
  import type { HarnessDialect } from "./dialect.js";
2
- import type { HarnessDeclarationShape, VigilesConfigShape } from "./config-schema.js";
2
+ import type { HarnessDeclarationShape, RulesConfig, VigilesConfigOf } from "./config-schema.js";
3
+ export type { RuleEntry, RulesConfig } from "./config-schema.js";
3
4
  /** A parsed rule from a markdown instruction file. */
4
5
  export interface ParsedRule {
5
6
  title: string;
@@ -123,310 +124,6 @@ export interface CompileBudgetConfig {
123
124
  /** The whole rendered Rules section. Default 20,000 (at "error"). */
124
125
  maxRulesChars?: number;
125
126
  }
126
- export interface RulesConfig {
127
- /**
128
- * Opt-in: a doc in a configured dir (default `docs/`) that no other `.md`
129
- * references. The `orphans` block turns the SCAN on; this turns the FINDING
130
- * into a warning or an error.
131
- *
132
- * It lived outside this interface until 2026-09 and therefore could not be
133
- * set at all: `"warn"` and `"off"` were both ignored and the check always
134
- * exited 1, so a repo's only choice was an always-blocking check or deleting
135
- * the `orphans` block (#181). Default: "error", matching the old behaviour.
136
- */
137
- "orphan-docs"?: RuleSeverity;
138
- /**
139
- * Re-derive a compiled instruction file's references from its `.spec.ts` and
140
- * report the dead ones.
141
- *
142
- * The integrity hash answers "is this file still what the spec compiled to";
143
- * it says nothing about whether the paths and scripts it NAMES still exist. So
144
- * an artifact committed while its refs were live stayed green forever after
145
- * the target was deleted — `compile` errored, `lint` said "hash valid" and
146
- * exited 0 (#173). Default: "error", matching `compile`.
147
- */
148
- "spec-refs"?: RuleSeverity;
149
- /**
150
- * The always-loaded instruction weight may not move away from the committed
151
- * baseline in `.vigiles/instruction-weight.json` — a ratchet against the
152
- * repo's own past, not a fixed budget. No baseline file → a one-line note,
153
- * never a finding, so turning this on fails no repository on day one.
154
- * `vigiles lint --update-baseline` records it. Default: "error".
155
- *
156
- * `["error", { max: 40000 }]` adds an opt-in absolute ceiling on top of the
157
- * ratchet: a total above `max` is a finding whatever the baseline says, and
158
- * the baseline cannot be re-recorded above it.
159
- */
160
- "instruction-weight"?: RuleWithOptions<InstructionWeightConfig>;
161
- /**
162
- * An instruction spec still uses the deprecated `keyFiles` field — a flat
163
- * path → description list compiled into the file loaded on every request.
164
- * Reports the entry count and compiled size with the migration (a `file()`
165
- * ref in the rule that needs the pointer). The spec is parsed, never run.
166
- * Default "warn": a deprecation must not turn a consumer's CI red on upgrade.
167
- */
168
- "deprecated-key-files"?: RuleSeverity;
169
- /**
170
- * Near-duplicate rules WITHIN one spec, by NCD similarity — spec bloat, two
171
- * rules saying the same thing in different words.
172
- *
173
- * Also previously untierable, and worse: it had no rule id at all, so there
174
- * was no name a config could even mention (#181). Default: "error".
175
- */
176
- "duplicate-rules"?: RuleSeverity;
177
- /**
178
- * Require a `.spec.ts` behind each instruction file (CLAUDE.md / AGENTS.md) —
179
- * the file must be compiled from a typed spec, not hand-written. NARROW: only a
180
- * `.spec.ts` sibling (or an explicit `<!-- vigiles-disable
181
- * require-instructions-spec -->` marker) satisfies it; inline
182
- * `<!-- vigiles:enforce -->` comments do NOT (the rule name says "spec"). Default:
183
- * "warn". `vigiles init` auto-adopts every instruction file into a spec, so this
184
- * is GREEN by construction after setup — a safety net for a NEW hand-added file,
185
- * not a nag. The workflow-tier opt-in (gated under `--strict`).
186
- */
187
- "require-instructions-spec"?: RuleSeverity;
188
- /**
189
- * Require a `.spec.ts` behind each SKILL.md — the consistent
190
- * `require-<surface>-spec` parallel to `require-instructions-spec`. Default:
191
- * false (OFF): skills are legitimately hand-written, and the coverage that
192
- * matters ("every skill ships with a test/eval") is the `untested-skill` rule.
193
- * Set it explicitly if your team wants every skill spec-managed.
194
- */
195
- "require-skill-spec"?: RuleSeverity;
196
- /** Detect hand-edits to compiled markdown via SHA-256 hash. Default: "warn". */
197
- integrity?: RuleSeverity;
198
- /** Enforce minimum spec coverage thresholds. Default: false. ESLint-style: ["warn", { scripts: 50 }]. */
199
- coverage?: RuleWithOptions<CoverageThresholds>;
200
- /** Flag a skill (SKILL.md) that ships with no test or eval. Default: "warn". */
201
- "untested-skill"?: RuleWithOptions<TestCoverageConfig>;
202
- /** Flag a subagent (agents/*.md) that ships with no test or eval. Default: "warn". */
203
- "untested-subagent"?: RuleWithOptions<TestCoverageConfig>;
204
- /** Flag a hook script that ships with no test or eval. Default: "warn". */
205
- "untested-hook"?: RuleWithOptions<TestCoverageConfig>;
206
- /** Flag an output style that ships with no test or eval. Default: "warn". */
207
- "untested-output-style"?: RuleWithOptions<TestCoverageConfig>;
208
- /**
209
- * Nudge (or block) when an instruction file has code-shaped references that
210
- * aren't expressed as vigiles marks (so the lint can't verify them), or a
211
- * `vigiles:symbol` mark that points at a missing symbol. Drives the
212
- * PostToolUse refs-hook: "warn" (default) → a non-blocking nudge, "error" →
213
- * block the edit, false → off.
214
- */
215
- "unmarked-refs"?: RuleSeverity;
216
- /**
217
- * Cross-reference each subagent's `tools:` rail against the harness tool
218
- * catalog — flag a never-available tool or a close typo (the moat). Only
219
- * high-confidence issues are reported (a bare unrecognized tool is likely
220
- * plugin/MCP-provided, never flagged). Off unless set; "warn" surfaces,
221
- * "error" gates CI. Same detector as `scan` + `compileAgent`.
222
- */
223
- "subagent-tool-contract"?: RuleSeverity;
224
- /**
225
- * Flag a hook registered under an event name the harness doesn't define (a
226
- * typo → the hook never fires). High-precision: close typos only, never a
227
- * framework/custom event. Default "warn"; "error" gates CI. Same detector as
228
- * `scan`.
229
- */
230
- "hook-events"?: RuleSeverity;
231
- /**
232
- * Flag a skill/agent missing a required frontmatter field — a skill needs
233
- * `name` (to load), an agent needs `name` + `description`. A broken surface
234
- * that won't register. Default "warn"; "error" gates CI. Same detector as `scan`.
235
- */
236
- "subagent-frontmatter"?: RuleSeverity;
237
- /**
238
- * Flag a declared MCP server that can't start — neither a `command` (stdio)
239
- * nor a `url` (http/sse). Default "warn"; "error" gates CI. Same detector as
240
- * `scan`. (JSON `.mcp.json`/manifest `mcpServers`; Codex TOML not yet parsed.)
241
- */
242
- "mcp-config"?: RuleSeverity;
243
- /**
244
- * RECOMMEND (not require) that a SKILL.md declares an explicit `name` +
245
- * `description` rather than relying on the dir-name / first-paragraph
246
- * fallbacks — a more reliable trigger surface. The skill still loads without
247
- * them, so this is a best-practice nudge: default "warn"; set "error" to
248
- * enforce on your own skills. Same detector as `scan` (skillMetaIssues).
249
- */
250
- "skill-frontmatter"?: RuleSeverity;
251
- /**
252
- * Cross-reference an `mcp__server__tool` in a subagent's contract against the
253
- * plugin's declared `mcpServers` — flag a server the plugin doesn't declare
254
- * (the MCP half of the tool moat; `subagent-tool-contract` checks the built-in
255
- * half). High-precision: only flags when the plugin SHIPS a declared set,
256
- * allowlists harness built-ins (`ide`), and skips the plugin-namespaced
257
- * `mcp__plugin_…` form. Default "warn"; "error" gates CI. Same detector as
258
- * `scan` (mcpToolIssues).
259
- */
260
- "mcp-tool-resolves"?: RuleSeverity;
261
- /**
262
- * A file a COMPILED hook line needs is missing — the runtime, the program or
263
- * its stamp — so the hook cannot run. Read from the hook-line plan, never
264
- * from parsing a line. Default "warn"; `vigiles:recommended` raises it to
265
- * "error". See docs/rules/hook-script-exists.md.
266
- */
267
- "hook-script-exists"?: RuleSeverity;
268
- /**
269
- * One finding per hook line vigiles did not write: it cannot say what such a
270
- * line runs or whether it swallows its own failure, so it names the hook and
271
- * points at compiled hooks (`vigiles/hook`). Default OFF, also under
272
- * `vigiles:recommended`: the cure is an experimental API, so it is opt-in
273
- * until compiled hooks leave experimental. See docs/rules/hand-written-hook.md.
274
- */
275
- "hand-written-hook"?: RuleSeverity;
276
- /**
277
- * Cross-reference a subagent's `disallowedTools:` block-list against the
278
- * catalog — the deny-side mirror of `subagent-tool-contract`. A close typo there
279
- * blocks NOTHING (you meant to deny `Bash`, wrote `Bsh`), leaving the tool
280
- * available. High-precision: close-typo only (a never-available tool is
281
- * harmless to list, a bare unknown is likely a plugin tool). Default "warn";
282
- * "error" gates CI. Same detector as `scan` (disallowedToolIssues).
283
- */
284
- "disallowed-tools-contract"?: RuleSeverity;
285
- /**
286
- * Flag two model-invocable skills whose descriptions are near-identical — the
287
- * selector can't tell them apart, so the wrong one fires (a precision
288
- * collision). A DETERMINISTIC NCD proxy for a `--trigger`-class behavioral bug;
289
- * calibrated FP-safe (only basically-identical text, below the sweep's
290
- * most-similar distinct pair). Default "warn"; "error" gates CI. Same detector
291
- * as `scan` (descriptionOverlaps).
292
- */
293
- "description-overlap"?: RuleSeverity;
294
- /**
295
- * Flag a model-invocable skill whose `description` is so long the trigger
296
- * signal is buried — the selector weighs the opening most, so a bloated
297
- * description hurts recall + precision. A DETERMINISTIC heuristic proxy for a
298
- * `--trigger`-class behavioral bug; calibrated FP-safe (generous default
299
- * budget, 500 chars). Default "warn" — a proxy, never gates. Same detector as
300
- * `scan` (descriptionBudgetIssues).
301
- */
302
- "skill-description-budget"?: RuleSeverity;
303
- /**
304
- * Size budgets on a COMPILED instruction file (`compile` from a `.spec.ts`):
305
- * one `commands` entry, one prose section, and the whole Rules section. The
306
- * whole always-loaded size is `instruction-weight`'s; `keyFiles` is
307
- * deprecated, so neither is measured here.
308
- *
309
- * Default "warn", which is exactly the behaviour before this rule had a name:
310
- * the per-entry and per-section budgets print as warnings and never stop a
311
- * compile; the Rules total is not evaluated unless a threshold is configured.
312
- * "error" (set by `vigiles:recommended`) makes every budget fail `compile` and
313
- * `lint`. Options are thresholds — see {@link CompileBudgetConfig}. See
314
- * docs/rules/compile-budget.md.
315
- */
316
- "compile-budget"?: RuleWithOptions<CompileBudgetConfig>;
317
- /**
318
- * Flag a skill/agent whose `---` frontmatter block EXISTS but isn't valid YAML
319
- * — fields may not parse as intended. CAVEAT: a real YAML parser (js-yaml) is
320
- * stricter than some loaders, so a one-line `description:` containing a `: `
321
- * colon or an `<example>` block is flagged even though it may still load.
322
- * Hence default "warn" (a nudge), not "error" — verify before enforcing. Same
323
- * detector as `scan` (malformedFrontmatter).
324
- */
325
- "frontmatter-valid"?: RuleSeverity;
326
- /**
327
- * Flag a `type: "mcp_tool"` hook action that's incomplete (missing `server` /
328
- * `tool`) or targets a server the plugin doesn't declare in `mcpServers` — the
329
- * hook silently never dispatches. High-precision: the undeclared-server half is
330
- * gated on the plugin shipping a declared set and allowlists built-ins (`ide`),
331
- * mirroring `mcp-tool-resolves`. Default "warn"; "error" gates CI. Same detector
332
- * as `scan` (mcpHookIssues).
333
- */
334
- "mcp-hook-target-resolves"?: RuleSeverity;
335
- /**
336
- * Flag a unit (subagent / model-invocable skill) whose declared tools hold all
337
- * THREE legs of Simon Willison's "lethal trifecta" — read private data, ingest
338
- * untrusted content, AND exfiltrate — a prompt-injection exfil path with no
339
- * exploit code (Meta's Rule of Two: allow at most two). A capability SET-
340
- * intersection over the declared contract, NOT a text scan; high-precision (only
341
- * well-known tools map to a leg). An EXPLICIT all-three contract is a "hard"
342
- * finding; an inherits-all unit (no contract → every leg) is "advisory". Default
343
- * "warn" (don't-cry-wolf rollout); raise to "error" to gate CI. Same detector as
344
- * `scan` (lethalTrifectaIssues). See docs/rules/lethal-trifecta.md.
345
- */
346
- "lethal-trifecta"?: RuleSeverity;
347
- /**
348
- * Flag a SKILL.md body referencing a bundled file (`scripts/`/`references/`/
349
- * `assets/`, or a relative markdown link with an extension) that doesn't exist
350
- * on disk under the skill dir — the agent reads the instruction, gets nothing,
351
- * and silently continues. The cross-reference moat applied to the SKILL.md body.
352
- * High-precision / FP-safe (skips URLs, `$VAR` tokens, `../` escapes, extension-
353
- * less mentions). Default "warn"; raise to "error" to gate CI. Same detector as
354
- * `scan` (skillResourceIssues). See docs/rules/skill-resource-resolves.md.
355
- */
356
- "skill-resource-resolves"?: RuleSeverity;
357
- /**
358
- * Flag a SKILL.md that opens with frontmatter-looking keys (`name:`,
359
- * `description:`, …) but has NO opening `---` fence — the harness loads the
360
- * whole file as body, so the skill has no name/description/trigger and is
361
- * invisible (never fires). High-precision (a fixed key whitelist; markdown /
362
- * prose lines never match). Default "warn"; raise to "error" to gate CI. Same
363
- * detector as `scan` (skillFenceIssues). See docs/rules/skill-missing-fence.md.
364
- */
365
- "skill-missing-fence"?: RuleSeverity;
366
- /**
367
- * Flag a functional surface directory (skills/agents/commands) nested INSIDE
368
- * the `.claude-plugin/` manifest dir, where only `plugin.json` belongs — the
369
- * harness can't see it, so the surface is invisible (the #1 plugin-author
370
- * mistake). Pure filesystem check, FP-safe. Default "warn"; raise to "error"
371
- * to gate CI. Same detector as `scan` (pluginLayoutIssues). See
372
- * docs/rules/plugin-dir-layout.md.
373
- */
374
- "plugin-dir-layout"?: RuleSeverity;
375
- /**
376
- * Flag a lethal trifecta that EMERGES across a delegation edge — a subagent
377
- * whose effective (own ∪ delegated-to) capability holds all three legs though
378
- * no single unit does (the combined blast radius). The capability-diff across
379
- * the delegation tree; skips units the per-unit `lethal-trifecta` already
380
- * flags (no double-report), FP-safe (explicit edges, wildcard-guarded). Default
381
- * "warn"; raise to "error" to gate CI. Same detector as `scan`
382
- * (delegationTrifecta). See docs/rules/delegation-trifecta.md.
383
- */
384
- "delegation-trifecta"?: RuleSeverity;
385
- /**
386
- * Flag a hook that LOOKS like it blocks but silently doesn't — a block decision
387
- * (`exit 2` / `decision` / `permissionDecision`) on an event that can't veto, or
388
- * the legacy top-level `decision` field on a permission-gated event where only
389
- * `hookSpecificOutput.permissionDecision` works (#19009, the #1 verified hook
390
- * pain). FP-safe (conservative literal patterns; the blocking-event sets are
391
- * read from the dialect, so it runs only where they're declared). Default "warn";
392
- * raise to "error" to gate CI. Same detector as `scan` (hookBlockFindings). See
393
- * docs/rules/hook-block-ineffective.md.
394
- */
395
- "hook-block-ineffective"?: RuleSeverity;
396
- /**
397
- * Flag a hook `matcher` string that doesn't fire the way it reads — a close
398
- * typo of a built-in tool (`bash`→`Bash`), a matcher that doesn't COMPILE, an
399
- * MCP pattern that can match no tool name at all (`mcp_memory_*` instead of
400
- * `mcp__memory__.*`), an MCP pattern too narrow for real server naming
401
- * (`mcp__[^_]+__[^_]+` can't cross the `_` in `mcp__Google_Calendar__…`), or a
402
- * server the plugin doesn't declare. A matcher is a PATTERN, so patterns are
403
- * validated by compiling and probing, never by literal shape. High-precision
404
- * (close-typo only; MCP gated on a declared set, built-ins allowlisted;
405
- * match-all and alternation skipped). Default "warn"; raise to "error" to gate
406
- * CI. Same detector as `scan` (hookMatcherFindings). See
407
- * docs/rules/hook-matcher.md.
408
- */
409
- "hook-matcher"?: RuleSeverity;
410
- /**
411
- * Validate vigiles-builder calls quoted inside ```ts fences in markdown —
412
- * `enforce()` / `file()` / `cmd()` / `ref()` — against the real linter catalog,
413
- * filesystem and package scripts.
414
- *
415
- * DEFAULT OFF, and the default is the finding. Measured on two repositories
416
- * 2026-08-19 (2 582 markdown files, 52 refs): **zero true positives, and every
417
- * error it has ever raised was a false one** — a design sketch writing
418
- * `cmd("npm test")` for a package that doesn't exist yet, or a third-party
419
- * `CLAUDE.md` captured verbatim as benchmark data. The reason is structural,
420
- * not calibration: a fenced block in prose is a DRAWING of config, and this
421
- * rule reads it as config. The consumer repo could only reach a clean `lint`
422
- * by excluding a third of itself, after which the pass scanned 604 files and
423
- * found 0 refs — inert, and still paying for the walk.
424
- *
425
- * Turn it on where markdown really is the source (a docs site whose fences are
426
- * copy-pasted into live specs). See docs/rules/doc-refs.md.
427
- */
428
- "doc-refs"?: RuleSeverity;
429
- }
430
127
  /** Extract severity from a rule value (handles both simple and tuple forms). */
431
128
  export declare function ruleSeverity<T>(rule: RuleWithOptions<T> | undefined): RuleSeverity;
432
129
  /** Extract options from a rule value (returns undefined for simple severity). */
@@ -450,22 +147,23 @@ export declare function ruleOptions<T>(rule: RuleWithOptions<T> | undefined): T
450
147
  */
451
148
  export type HarnessDeclaration = HarnessDeclarationShape;
452
149
  /**
453
- * Full vigiles configuration, loaded from `.vigilesrc.json`.
150
+ * Full vigiles configuration, loaded from `.vigilesrc.json`, with `rules` keyed
151
+ * by a string id — the form generic code takes.
454
152
  *
455
153
  * 🔴 DERIVED FROM THE SCHEMA, NOT WRITTEN BESIDE IT. The shape, the defaults and
456
- * the per-key prose all live in `./config-schema.ts`; this is
457
- * `z.infer<typeof vigilesConfigSchema>` with the defaults applied, so the type
458
- * says exactly what a parsed config carries — `rules` non-optional and complete
459
- * because every rule key has a schema default, optional keys optional because
460
- * the schema says so. A hand-written twin is the copy that drifts: `harness` and
461
- * `surfaceRoots` lived in that twin, in `docs/cli.md` and in the loader's
462
- * coercions, and the three disagreed about what was read (#240).
154
+ * the per-key prose all live in `./config-schema.ts`, and the `rules` are built
155
+ * from the rule set the composition root hands in; the root's PRECISE type
156
+ * (each id with its own options) is `VigilesConfig` in `src/rules/index.ts`. A
157
+ * hand-written twin is the copy that drifts: `harness` and `surfaceRoots` lived
158
+ * in that twin, in `docs/cli.md` and in the loader's coercions, and the three
159
+ * disagreed about what was read (#240). The per-rule prose that lived in a
160
+ * hand-written `RulesConfig` here is each rule's `summary` and its doc.
463
161
  *
464
162
  * The re-export is TYPE-ONLY on purpose — `types.ts` is imported by node-free
465
163
  * core modules, and a value import of the schema module would pull Zod into
466
164
  * every one of them.
467
165
  */
468
- export type VigilesConfig = VigilesConfigShape;
166
+ export type VigilesConfig = VigilesConfigOf<RulesConfig>;
469
167
  /** Valid marker types for rule detection. */
470
168
  export type MarkerType = "headings" | "checkboxes";
471
169
  /** Options for parseRules. */
@@ -1,17 +1,12 @@
1
+ import { type ConfigSet } from "./config-schema.js";
1
2
  import type { ParsedRule, ValidationError, ValidationResult, ReadResult, FileResult, ValidatePathsResult, RulesConfig, VigilesConfig, HarnessDeclaration, MarkerType, ParseOptions, ValidateOptions, ValidatePathsOptions, ReadOptions } from "./types.js";
2
3
  export type { ParsedRule, ValidationError, ValidationResult, ReadResult, FileResult, ValidatePathsResult, RulesConfig, VigilesConfig, HarnessDeclaration, MarkerType, ParseOptions, ValidateOptions, ValidatePathsOptions, ReadOptions, };
3
4
  /**
4
- * The shipped default severity of every rule — DERIVED from the schema, never
5
- * listed twice.
6
- *
7
- * It used to be the literal beside the type, which is exactly the pair that
8
- * drifts: `rule-meta.test.ts` already cross-checks each rule's documented
9
- * `defaultSeverity` against this object, and it could only ever catch a doc that
10
- * disagreed with the literal, never a literal that disagreed with what parsing
11
- * actually produced. Reading it out of the parser closes that gap: this IS what
12
- * a `{}` config loads as.
5
+ * The defaults with `presets` applied — an empty file extended on the CLI.
6
+ * There is no rule-set-free default here: what every rule defaults to is
7
+ * declared by the rule, and the set arrives as `set` from the root.
13
8
  */
14
- export declare const DEFAULT_RULES: Required<RulesConfig>;
9
+ export declare function configDefaults<C>(set: ConfigSet<C>, presets?: readonly string[]): C;
15
10
  export declare function findInstructionFiles(cwd: string, configFiles?: string[]): string[];
16
11
  /**
17
12
  * Read and VALIDATE `.vigilesrc.json`.
@@ -45,9 +40,15 @@ export declare function findInstructionFiles(cwd: string, configFiles?: string[]
45
40
  * does not execute until the function is called. A rail that never reads a
46
41
  * config never pays for the validator.
47
42
  */
48
- export declare function loadConfig(searchFrom?: string, { onInvalid }?: {
43
+ export declare function loadConfig<C>(
44
+ /** The config for the rule set the root hands in (`configFor`). */
45
+ set: ConfigSet<C>, searchFrom?: string, { onInvalid, presets, }?: Readonly<{
49
46
  onInvalid?: "throw" | "warn";
50
- }): VigilesConfig;
47
+ /** Presets applied on top of the file's own (`--preset=`), see
48
+ * `ConfigSet.parse`. Applied to the defaults too, so they work in a repo
49
+ * with no `.vigilesrc.json` at all. */
50
+ presets?: readonly string[];
51
+ }>): C;
51
52
  export declare function parseRules(content: string, { ruleMarkers }?: ParseOptions): ParsedRule[];
52
53
  export declare function validate(content: string, { ruleMarkers, rules: rulesConfig, filePath, dialect }?: ValidateOptions): ValidationResult;
53
54
  export declare function readInstructionFile(filePath: string, options?: ReadOptions): ReadResult;