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
@@ -39,6 +39,7 @@
39
39
  */
40
40
  import { type PluginScore } from "./score-core.js";
41
41
  import type { ScanReport } from "./scan.js";
42
+ import type { GradedView } from "./core/apply-rules.js";
42
43
  export type CategoryKey = "Truthfulness" | "Triggering" | "Structure" | "Safety" | "Tested" | "Evaluated";
43
44
  export interface CategoryScore {
44
45
  readonly key: CategoryKey;
@@ -106,7 +107,9 @@ export interface AuditScoreOptions {
106
107
  * any n/a ring are shown but excluded from the headline — the grade weighting is
107
108
  * UNCHANGED by the Tested/Evaluated split.
108
109
  */
109
- export declare function auditScore(report: ScanReport, opts?: AuditScoreOptions): AuditScore;
110
+ export declare function auditScore(
111
+ /** The graded view: an ungraded group's findings never reach a ring. */
112
+ report: GradedView<ScanReport>, opts?: AuditScoreOptions): AuditScore;
110
113
  /**
111
114
  * The ring's number as the reader sees it — THREE distinct labels, never two.
112
115
  * A measured `0` and an unasked question are different facts and must not render
@@ -497,7 +497,9 @@ function isEmptyAudit(r) {
497
497
  * any n/a ring are shown but excluded from the headline — the grade weighting is
498
498
  * UNCHANGED by the Tested/Evaluated split.
499
499
  */
500
- function auditScore(report, opts = {}) {
500
+ function auditScore(
501
+ /** The graded view: an ungraded group's findings never reach a ring. */
502
+ report, opts = {}) {
501
503
  if (isEmptyAudit(report)) {
502
504
  const categories = [
503
505
  "Truthfulness",
@@ -42,6 +42,7 @@ import { type AuditScore } from "./audit-score.js";
42
42
  import type { Recommendation } from "./optimize.js";
43
43
  import { type PluginScore } from "./score-core.js";
44
44
  import type { ScanReport } from "./scan.js";
45
+ import type { GradedView } from "./core/apply-rules.js";
45
46
  /**
46
47
  * The inputs the verdict needs — exactly the pieces {@link buildAuditReport}
47
48
  * already holds. `score` is the authoritative base (`overall` + `grade`) the
@@ -49,7 +50,8 @@ import type { ScanReport } from "./scan.js";
49
50
  * it; `recommendations` is the array whose indices `perRecommendation` aligns to.
50
51
  */
51
52
  export interface VerdictInput {
52
- readonly report: ScanReport;
53
+ /** The graded view: an ungraded group's findings never reach the verdict. */
54
+ readonly report: GradedView<ScanReport>;
53
55
  readonly score: AuditScore;
54
56
  readonly recommendations: readonly Recommendation[];
55
57
  }
@@ -16,7 +16,7 @@
16
16
  * That is not cosmetic, because audit's flags govern what LEAVES THE MACHINE:
17
17
  * `--no-html`, `--no-json`, `--out=<dir>`, `--serve`. `--no-htlm` writes the HTML
18
18
  * report while the author believes they suppressed it. For a tool whose thesis is
19
- * "prose isn't policy", accepting an argument it did not understand and carrying
19
+ * that a stated rule is not an enforced one, accepting an argument it did not understand and carrying
20
20
  * on is the same class of error it names elsewhere: the argument is PRESENT, so
21
21
  * the property is assumed enforced.
22
22
  *
@@ -17,7 +17,7 @@
17
17
  * That is not cosmetic, because audit's flags govern what LEAVES THE MACHINE:
18
18
  * `--no-html`, `--no-json`, `--out=<dir>`, `--serve`. `--no-htlm` writes the HTML
19
19
  * report while the author believes they suppressed it. For a tool whose thesis is
20
- * "prose isn't policy", accepting an argument it did not understand and carrying
20
+ * that a stated rule is not an enforced one, accepting an argument it did not understand and carrying
21
21
  * on is the same class of error it names elsewhere: the argument is PRESENT, so
22
22
  * the property is assumed enforced.
23
23
  *
@@ -82,6 +82,9 @@ exports.COMMAND_FLAGS = {
82
82
  compile: [],
83
83
  eject: ["--keep-spec"],
84
84
  lint: [
85
+ // A preset applied on top of the repo's own config for this run (the same
86
+ // names `extends` takes) — see parsePresetFlags.
87
+ "--preset=",
85
88
  "--bundles=",
86
89
  "--summary",
87
90
  "--json",
@@ -102,6 +105,7 @@ exports.COMMAND_FLAGS = {
102
105
  "--update",
103
106
  ],
104
107
  audit: [
108
+ "--preset=",
105
109
  "--json",
106
110
  "--md",
107
111
  "--single",
@@ -18,5 +18,5 @@ import type { VigilesConfig } from "./core/types.js";
18
18
  * Unknown flags are left untouched (each command parses its own besides
19
19
  * these). Returns a new object; the input is not mutated.
20
20
  */
21
- export declare function applyConfigFlags(config: VigilesConfig, args: readonly string[]): VigilesConfig;
21
+ export declare function applyConfigFlags<C extends VigilesConfig>(config: C, args: readonly string[]): C;
22
22
  //# sourceMappingURL=cli-flags.d.ts.map
package/dist/cli-main.js CHANGED
@@ -33,10 +33,16 @@ const generate_harness_js_1 = require("./core/generate-harness.js");
33
33
  const capability_diff_js_1 = require("./core/capability-diff.js");
34
34
  const validate_js_1 = require("./core/validate.js");
35
35
  const overrides_js_1 = require("./overrides.js");
36
+ const config_schema_js_1 = require("./core/config-schema.js");
37
+ const rule_js_1 = require("./core/rule.js");
38
+ const apply_rules_js_1 = require("./core/apply-rules.js");
39
+ const index_js_1 = require("./rules/index.js");
36
40
  const eval_lock_js_1 = require("./eval-lock.js");
37
41
  const eval_entry_js_1 = require("./eval-entry.js");
38
42
  const zod_1 = require("zod");
39
43
  const cli_flags_js_1 = require("./cli-flags.js");
44
+ const config_schema_js_2 = require("./core/config-schema.js");
45
+ const presets_js_1 = require("./core/presets.js");
40
46
  const cli_commands_js_1 = require("./cli-commands.js");
41
47
  const cli_flag_check_js_1 = require("./cli-flag-check.js");
42
48
  const setup_plan_js_1 = require("./setup-plan.js");
@@ -99,6 +105,22 @@ const skill_runtime_js_1 = require("./adapters/claude-code/skill-runtime.js");
99
105
  const linters_js_1 = require("./core/linters.js");
100
106
  const harness_test_js_1 = require("./harness-test.js");
101
107
  const run_scripts_js_1 = require("./adapters/claude-code/run-scripts.js");
108
+ /**
109
+ * THE RULE SET, WIRED IN — the composition root's one job for rules. Core
110
+ * declares the port and takes the set as a parameter; this file (and the
111
+ * browser demo's entry) is the only place `src/rules/` is imported. `CONFIG`
112
+ * is `.vigilesrc.json` built for this set, `loadConfig` the loader bound to it
113
+ * (so every verb reads the same schema), and `INIT_POLICY` what `init` writes,
114
+ * derived from the groups.
115
+ */
116
+ const CONFIG = (0, config_schema_js_1.configFor)(index_js_1.RULES, index_js_1.RULE_GROUPS);
117
+ const INIT_POLICY = (0, rule_js_1.initPolicyOf)(index_js_1.RULES, index_js_1.RULE_GROUPS);
118
+ /** Every rule at its shipped default — what a missing `.vigilesrc.json` loads as. */
119
+ const DEFAULT_CONFIG = (0, validate_js_1.configDefaults)(CONFIG);
120
+ /** `.vigilesrc.json` for this rule set; see `core/validate.ts` `loadConfig`. */
121
+ function loadConfig(searchFrom, opts) {
122
+ return (0, validate_js_1.loadConfig)(CONFIG, searchFrom, opts);
123
+ }
102
124
  const coverage_artifact_js_1 = require("./coverage-artifact.js");
103
125
  const integrity_js_1 = require("./core/integrity.js");
104
126
  const instruction_remedies_js_1 = require("./core/instruction-remedies.js");
@@ -797,9 +819,12 @@ function validateSpecs(root, filePaths, rulesConfig, rules, silent = false) {
797
819
  }
798
820
  return allValid;
799
821
  }
800
- function check(root, frame, filePaths, silent = false) {
822
+ function check(root, frame, filePaths, silent = false,
823
+ // The run's config when the caller has it — so a `--preset=` the run was
824
+ // given reaches the spec checks too, rather than a second read of the file.
825
+ config) {
801
826
  const hashes = verifyHashes(root, frame, filePaths, silent);
802
- const vConfig = (0, validate_js_1.loadConfig)(root);
827
+ const vConfig = config ?? loadConfig(root);
803
828
  const specsValid = validateSpecs(root, filePaths, vConfig.rules, (0, overrides_js_1.ruleResolver)(vConfig.rules, vConfig.overrides), silent);
804
829
  return {
805
830
  valid: hashes.valid && specsValid,
@@ -1584,7 +1609,7 @@ function compileBudgetOptions(config, target) {
1584
1609
  if (rule === undefined)
1585
1610
  return { budgetSeverity: "warn" };
1586
1611
  return {
1587
- budgetSeverity: (0, overrides_js_1.ruleResolver)(config?.rules ?? validate_js_1.DEFAULT_RULES, config?.overrides).severityAt("compile-budget", target),
1612
+ budgetSeverity: (0, overrides_js_1.ruleResolver)(config?.rules ?? DEFAULT_CONFIG.rules, config?.overrides).severityAt("compile-budget", target),
1588
1613
  ...(0, types_js_1.ruleOptions)(rule),
1589
1614
  };
1590
1615
  }
@@ -1654,7 +1679,7 @@ async function runLint(restArgs, flags, excludes, config) {
1654
1679
  // relative to it, and config globs resolve from it — whichever bundle is being
1655
1680
  // scored. Built here, once, instead of each option re-deriving its own root.
1656
1681
  const frame = (0, frame_js_1.frameFor)(root, scanRoot);
1657
- const rules = (0, overrides_js_1.ruleResolver)(config?.rules ?? validate_js_1.DEFAULT_RULES, config?.overrides);
1682
+ const rules = (0, overrides_js_1.ruleResolver)(config?.rules ?? DEFAULT_CONFIG.rules, config?.overrides);
1658
1683
  const run = { config, rules, silent, adapter, excludes, frame };
1659
1684
  if (!silent && nestedBundles.length > 0) {
1660
1685
  const rel = nestedBundles.map((b) => (0, node_path_1.relative)(scanRoot, b) || b);
@@ -1681,7 +1706,7 @@ async function runLint(restArgs, flags, excludes, config) {
1681
1706
  }
1682
1707
  }
1683
1708
  const hashResult = files.length > 0
1684
- ? check(root, frame, files, silent)
1709
+ ? check(root, frame, files, silent, config)
1685
1710
  : { valid: true, hashErrors: 0, validationErrors: 0 };
1686
1711
  // 1b. Verify inline + frontmatter rules in instruction files not managed
1687
1712
  // by a spec. See verifyMarkdownModeRules / docs/markdown-mode.md.
@@ -1717,7 +1742,7 @@ async function runLint(restArgs, flags, excludes, config) {
1717
1742
  // opted into explicitly). `enforce("vigiles/orphan-docs")` in a spec only
1718
1743
  // validates the rule NAME — the block is what drives the scan.
1719
1744
  // 🔴 SEVERITY IS READ, not just the block's presence (#181). `orphan-docs` had
1720
- // a RULE_META entry and a documented severity, and nothing ever read it: both
1745
+ // a declared meta and a documented severity, and nothing ever read it: both
1721
1746
  // `"warn"` and `"off"` still exited 1, so a repo could only choose between an
1722
1747
  // always-blocking check and deleting the `orphans` block. `warn` now reports
1723
1748
  // without touching the exit code and `false`/`"off"` skips the scan, exactly
@@ -1809,9 +1834,14 @@ async function runLint(restArgs, flags, excludes, config) {
1809
1834
  // hold all three legs (read-private + ingest-untrusted + exfiltrate) is a
1810
1835
  // prompt-injection exfil path (Rule of Two). Capability SET-intersection.
1811
1836
  const lethalTrifecta = overBundles(checkLethalTrifecta, run, lintRoots);
1812
- // 7p. Skill-resource — a SKILL.md body referencing a bundled file that doesn't
1813
- // exist on disk under the skill dir (the agent gets nothing). FP-safe.
1814
- const skillResources = overBundles(checkSkillResourceResolves, run, lintRoots);
1837
+ // 7p. The rules that are modules (src/rules/<id>.ts), each through the one
1838
+ // generic check. The LintReport keeps its per-rule wire keys until #390:
1839
+ // today the one module rule (the bundled-resource check) fills the
1840
+ // `skillResource*` pair below.
1841
+ const ruleModules = RULE_MODULES.map((rule) => overBundles((ctx) => checkRuleModule(ctx, rule), run, lintRoots)).reduce((acc, t) => ({
1842
+ issues: acc.issues + t.issues,
1843
+ errors: acc.errors + t.errors,
1844
+ }), { issues: 0, errors: 0 });
1815
1845
  // 7q. Skill-missing-fence — a SKILL.md opening with `name:`/`description:` but no
1816
1846
  // `---` fence loads as plain body (invisible — no name/description/trigger).
1817
1847
  const skillFence = overBundles(checkSkillMissingFence, run, lintRoots);
@@ -1991,8 +2021,8 @@ async function runLint(restArgs, flags, excludes, config) {
1991
2021
  mcpHookErrors: mcpHookTargets.errors,
1992
2022
  lethalTrifectaIssues: lethalTrifecta.issues,
1993
2023
  lethalTrifectaErrors: lethalTrifecta.errors,
1994
- skillResourceIssues: skillResources.issues,
1995
- skillResourceErrors: skillResources.errors,
2024
+ skillResourceIssues: ruleModules.issues,
2025
+ skillResourceErrors: ruleModules.errors,
1996
2026
  skillFenceIssues: skillFence.issues,
1997
2027
  skillFenceErrors: skillFence.errors,
1998
2028
  pluginLayoutIssues: pluginLayout.issues,
@@ -2273,7 +2303,7 @@ function handWrittenInstructionFiles(root, instructionFile, excludes, rules) {
2273
2303
  * repo it sets up passes `require-instructions-spec` (in `vigiles:recommended`)
2274
2304
  * on its first `lint`. Read with the repo's own `exclude`. */
2275
2305
  function nestedHandWrittenInstructionFiles(cwd) {
2276
- const config = (0, validate_js_1.loadConfig)();
2306
+ const config = loadConfig();
2277
2307
  return handWrittenInstructionFiles(cwd, adapter_registry_js_1.defaultAdapter.layout.instructionFile, (0, exclude_js_1.excludeSet)(cwd, config.exclude), (0, overrides_js_1.ruleResolver)(config.rules, config.overrides)).filter((p) => p.includes("/"));
2278
2308
  }
2279
2309
  /** The full adoptable-surface list `audit` reports: every hand-written
@@ -2496,7 +2526,7 @@ function computeRuleRouting(root, instructionFile, excludes) {
2496
2526
  // routing. Enumerating EXECUTES the linter (plugin code loads), hence own-repo
2497
2527
  // + consent — same posture for both.
2498
2528
  const ownRepo = (0, node_path_1.resolve)(root) === (0, node_path_1.resolve)(process.cwd());
2499
- const consented = (0, validate_js_1.loadConfig)().audit?.measure === true;
2529
+ const consented = loadConfig().audit?.measure === true;
2500
2530
  const availableRules = ownRepo && consented
2501
2531
  ? (0, rule_catalog_js_1.mergeCatalogs)((0, rule_catalog_js_1.enumerateEslintCatalog)(root),
2502
2532
  // Only spawn pylint when the repo actually has a Python surface —
@@ -3321,7 +3351,7 @@ async function setupPillar1(detected, targetValue, harnesses) {
3321
3351
  written.push(GENERATED_TYPES);
3322
3352
  const schemaResult = (0, generate_schema_js_1.generateSchema)({
3323
3353
  basePath: cwd,
3324
- linters: (0, validate_js_1.loadConfig)().linters,
3354
+ linters: loadConfig().linters,
3325
3355
  });
3326
3356
  (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(cwd, GENERATED_SCHEMA), schemaResult.json);
3327
3357
  console.log("✓ Generated .vigiles/schema.json (YAML-LSP frontmatter schema)");
@@ -3338,7 +3368,7 @@ async function setupPillar1(detected, targetValue, harnesses) {
3338
3368
  // resolve hook in src/self-resolve.mts), so compiling needs no
3339
3369
  // `node_modules/vigiles` in the user's repo — and a repo with no
3340
3370
  // `package.json` at all (Python, Rust, Go) has no install to run.
3341
- const initConfig = (0, validate_js_1.loadConfig)();
3371
+ const initConfig = loadConfig();
3342
3372
  const excludes = (0, exclude_js_1.excludeSet)(cwd, initConfig.exclude);
3343
3373
  const specs = findSpecs(excludes).filter((s) => {
3344
3374
  const tf = (0, node_path_1.resolve)(cwd, s.replace(/\.spec\.ts$/, ""));
@@ -3873,7 +3903,7 @@ async function setup(args) {
3873
3903
  // Detect project. An existing `.vigilesrc.json` `harness` (from a prior init /
3874
3904
  // a hand-authored config) wins over auto-detection (dogfood I3).
3875
3905
  const detected = detectProject();
3876
- const harnesses = resolveHarnesses(parsed, detected, (0, adapter_registry_js_1.declaredHarnessNames)((0, validate_js_1.loadConfig)().harnesses));
3906
+ const harnesses = resolveHarnesses(parsed, detected, (0, adapter_registry_js_1.declaredHarnessNames)(loadConfig().harnesses));
3877
3907
  printDetection(detected, harnesses);
3878
3908
  // Files actually written, accumulated for an honest commit hint.
3879
3909
  const written = [];
@@ -3964,7 +3994,7 @@ async function setup(args) {
3964
3994
  function minimalRerun(parsed, state) {
3965
3995
  const plan = (0, setup_plan_js_1.resolvePlan)(parsed);
3966
3996
  const detected = detectProject();
3967
- const harnesses = resolveHarnesses(parsed, detected, (0, adapter_registry_js_1.declaredHarnessNames)((0, validate_js_1.loadConfig)().harnesses));
3997
+ const harnesses = resolveHarnesses(parsed, detected, (0, adapter_registry_js_1.declaredHarnessNames)(loadConfig().harnesses));
3968
3998
  console.log(`vigiles is already set up here (found ${state.evidence}) — adding only what is missing.\n`);
3969
3999
  printDetection(detected, harnesses);
3970
4000
  const links = plan.plugin ? linkSkillsOnly(harnesses) : [];
@@ -3972,7 +4002,7 @@ function minimalRerun(parsed, state) {
3972
4002
  const written = [...links, ...devDep];
3973
4003
  if (written.length === 0)
3974
4004
  console.log("\nNothing was missing.");
3975
- const followUps = (0, setup_plan_js_1.fullSetupFollowUps)(fullSetupGap(plan, detected, harnesses));
4005
+ const followUps = (0, setup_plan_js_1.fullSetupFollowUps)(fullSetupGap(plan, detected, harnesses), INIT_POLICY.preset);
3976
4006
  if (followUps.length > 0)
3977
4007
  console.log(`\n${followUps.join("\n")}`);
3978
4008
  if (written.length > 0)
@@ -4071,7 +4101,12 @@ function fullSetupGap(plan, detected, harnesses) {
4071
4101
  function configGap(config, lint) {
4072
4102
  if (config === null)
4073
4103
  return "missing";
4074
- return config.extends === undefined && lint ? "no-preset" : "has-preset";
4104
+ // "Has the preset" means extends RECOMMENDED: `vigiles:experimental` alone
4105
+ // gates nothing. A value that is not a preset list is not ours to judge here.
4106
+ const listed = (0, presets_js_1.extendedPresets)(CONFIG.presetNames, config.extends);
4107
+ return listed !== null && !listed.includes(INIT_POLICY.preset) && lint
4108
+ ? "no-preset"
4109
+ : "has-preset";
4075
4110
  }
4076
4111
  /** `.vigilesrc.json` as a plain object, or null when absent or unreadable. */
4077
4112
  function readProjectConfig(path) {
@@ -4123,6 +4158,7 @@ function writeProjectConfig(opts) {
4123
4158
  }
4124
4159
  }
4125
4160
  const merged = (0, setup_plan_js_1.mergeProjectConfig)(existing, {
4161
+ policy: INIT_POLICY,
4126
4162
  harnesses: harnessConfigKeys(opts.harnesses),
4127
4163
  strict: opts.strict,
4128
4164
  reportOnly: opts.reportOnly,
@@ -4245,7 +4281,7 @@ function untestedRules(config, rules) {
4245
4281
  include: opts.include,
4246
4282
  // Without this the `testExtension` documented on TestCoverageOptions was a
4247
4283
  // config key nothing read: a TypeScript-shaped repo got `.ts` suggestions
4248
- // however the author configured it. Prose isn't policy, in our own CLI.
4284
+ // however the author configured it. A documented key must be a read key, in our own CLI too.
4249
4285
  testExtension: opts.testExtension,
4250
4286
  },
4251
4287
  };
@@ -4633,44 +4669,46 @@ function checkLethalTrifecta(ctx) {
4633
4669
  }
4634
4670
  return tally(found);
4635
4671
  }
4672
+ /** The rules of the set that are modules — each runs through {@link checkRuleModule}. */
4673
+ const RULE_MODULES = index_js_1.RULES.filter((r) => "findings" in r);
4636
4674
  /**
4637
- * Apply the `skill-resource-resolves` rule: a SKILL.md body referencing a bundled
4638
- * file (`scripts/`/`references/`/`assets/` or a relative markdown link with an
4639
- * extension) that doesn't exist on disk — the agent reads the instruction and gets
4640
- * nothing. Reuses `scanPlugin`'s `skillResourceIssues` (high-precision / FP-safe,
4641
- * one detector, no drift). Warning by default; "error" gates CI.
4675
+ * Apply one rule MODULE: what its `findings` reports, each at the severity its
4676
+ * own path gets (`overrides` applied). A `finding` counts and prints at that
4677
+ * severity; a `note` (informational — e.g. a resource that resolves only from
4678
+ * the repository root, #382) prints with `ℹ` and a `::notice` annotation and
4679
+ * never counts, so it can never fail CI. The scan is the same one every other
4680
+ * check reads (`ctx.scan`), with the repo's `sharedDirs` at the frame root.
4681
+ *
4682
+ * The first piece of the one loop the per-rule `check*` functions become
4683
+ * (vigiles#390): nothing here names a rule.
4642
4684
  */
4643
- function checkSkillResourceResolves(ctx) {
4644
- const { config, silent } = ctx;
4645
- if (!ctx.rules.mayFire("skill-resource-resolves"))
4685
+ function checkRuleModule(ctx, rule) {
4686
+ if (!ctx.rules.mayFire(rule.id))
4646
4687
  return { issues: 0, errors: 0 };
4647
- let raw;
4688
+ let found;
4648
4689
  try {
4649
- raw = ctx.scan({
4650
- sharedDirs: config?.sharedDirs,
4651
- // sharedDirs live at the frame root — the repo that OWNS the scan target:
4652
- // cwd for a scoped subdir or a nested bundle, the target for a foreign lint.
4690
+ found = rule.findings(ctx.scan({
4691
+ sharedDirs: ctx.config?.sharedDirs,
4653
4692
  sharedDirsRoot: ctx.frame.root,
4654
- }).skillResourceIssues;
4693
+ }));
4655
4694
  }
4656
4695
  catch {
4657
4696
  return { issues: 0, errors: 0 };
4658
4697
  }
4659
- const found = graded(ctx.rules, "skill-resource-resolves", raw, (f) => ctx.bundle.scanned(f.path));
4660
- if (found.length > 0 && !silent) {
4661
- console.log("\nSkill-resource check:\n");
4662
- for (const s of found) {
4663
- const msg = `${s.name}: bundled resource "${s.finding.ref}" (line ${String(s.finding.line)}) is referenced but missing — the agent reads the instruction and gets nothing.` +
4664
- // The main false-positive source in a skills monorepo, where a SKILL.md
4665
- // legitimately names a repo-root path. The fix already exists and works;
4666
- // it was documented only in docs/skills-monorepo.md, so a CI log gave no
4667
- // hint and the rule read as broken rather than misconfigured.
4668
- ` If it resolves from the repo root instead, add its directory to \`sharedDirs\` in .vigilesrc.json.`;
4669
- console.log(` ${markOf(s.sev).mark} ${ctx.bundle.scanned(s.path)}: ${msg}`);
4670
- ctx.annotate(markOf(s.sev).level, msg, ctx.bundle.scanned(s.path));
4698
+ const pathOf = (f) => ctx.bundle.scanned(f.path);
4699
+ const shown = graded(ctx.rules, rule.id, found, pathOf);
4700
+ if (shown.length > 0 && !ctx.silent) {
4701
+ console.log(`\n${rule.id}:\n`);
4702
+ for (const f of shown) {
4703
+ const { mark, level } = f.kind === "note"
4704
+ ? { mark: "ℹ", level: "notice" }
4705
+ : markOf(f.sev);
4706
+ const msg = `${f.subject}: ${f.message}`;
4707
+ console.log(` ${mark} ${pathOf(f)}: ${msg}`);
4708
+ ctx.annotate(level, msg, pathOf(f));
4671
4709
  }
4672
4710
  }
4673
- return tally(found);
4711
+ return tally(shown.filter((f) => f.kind === "finding"));
4674
4712
  }
4675
4713
  /**
4676
4714
  * Apply the `skill-missing-fence` rule: a SKILL.md that opens with
@@ -5108,7 +5146,7 @@ function resolveCommandHarness(dir, harnessFlag) {
5108
5146
  return (0, adapter_registry_js_1.resolveHarnessSelection)({
5109
5147
  root: dir,
5110
5148
  flag: harnessFlag,
5111
- configHarness: (0, adapter_registry_js_1.declaredHarnessNames)((0, validate_js_1.loadConfig)().harnesses),
5149
+ configHarness: (0, adapter_registry_js_1.declaredHarnessNames)(loadConfig().harnesses),
5112
5150
  });
5113
5151
  }
5114
5152
  async function handleMeasure(restArgs, args) {
@@ -5252,7 +5290,7 @@ function handleGenerateSchema(args, restArgs) {
5252
5290
  console.log("Scanning linters...\n");
5253
5291
  const result = (0, generate_schema_js_1.generateSchema)({
5254
5292
  basePath: process.cwd(),
5255
- linters: (0, validate_js_1.loadConfig)().linters,
5293
+ linters: loadConfig().linters,
5256
5294
  });
5257
5295
  for (const l of result.linters) {
5258
5296
  console.log(` ${l.linter}: ${String(l.count)} rules`);
@@ -5435,7 +5473,7 @@ function resolveEvalLockEnv(args) {
5435
5473
  if (wantUpdate)
5436
5474
  env.VIGILES_EVAL_LOCK = "update";
5437
5475
  if (wantCheck || wantUpdate) {
5438
- const apiVersion = (0, validate_js_1.loadConfig)().eval?.apiVersion;
5476
+ const apiVersion = loadConfig().eval?.apiVersion;
5439
5477
  if (apiVersion !== undefined)
5440
5478
  env.VIGILES_EVAL_API_VERSION = String(apiVersion);
5441
5479
  }
@@ -5531,7 +5569,7 @@ function resolveRecords(cwd, runs, tier, harnessFlag) {
5531
5569
  }
5532
5570
  return [...names];
5533
5571
  }
5534
- const recordsConfig = (0, validate_js_1.loadConfig)();
5572
+ const recordsConfig = loadConfig();
5535
5573
  const layout = harnessLayoutFor(cwd, recordsConfig, harnessFlag);
5536
5574
  // The repo-wide `exclude` only — the per-rule severities/include stay out
5537
5575
  // of record resolution on purpose (a run's probes must map to a surface
@@ -5865,6 +5903,13 @@ function capabilitiesOfReport(report, dialect) {
5865
5903
  }));
5866
5904
  return (0, generate_harness_js_1.computeHarnessCapabilities)(agents, dialect);
5867
5905
  }
5906
+ /**
5907
+ * The `--preset=` line `audit` and `lint` share. The names are the ones
5908
+ * `.vigilesrc.json#extends` takes; `experimental` is the group of checks not yet
5909
+ * measured reliable enough to grade on — on at `warn`, never scored.
5910
+ */
5911
+ const PRESET_HELP = " --preset=<name> add a preset for this run, on top of your config: experimental · recommended\n" +
5912
+ " (experimental = checks not yet measured reliable enough to grade you on: warn, never scored)";
5868
5913
  const COMMAND_HELP = {
5869
5914
  init: {
5870
5915
  usage: " vigiles init [flags] Set up this repo — specs, plugin, and CI.",
@@ -5879,6 +5924,7 @@ const COMMAND_HELP = {
5879
5924
  },
5880
5925
  lint: {
5881
5926
  usage: " vigiles lint [files...] Gate it in CI. The same checks — but a finding fails the build.",
5927
+ detail: [PRESET_HELP],
5882
5928
  },
5883
5929
  audit: {
5884
5930
  // "Reports everything, fails nothing" states always-exit-0 as the FEATURE it is. The line
@@ -5889,6 +5935,7 @@ const COMMAND_HELP = {
5889
5935
  detail: [
5890
5936
  " 2+ dirs → a leaderboard. Writes vigiles-report.html + .json (auto-gitignored).",
5891
5937
  " --single audit this dir as ONE harness, even if it holds many bundles",
5938
+ PRESET_HELP,
5892
5939
  " The executing checks (run your hooks · live MCP · do skills fire?) run only",
5893
5940
  " interactively — audit asks once and remembers; automation uses the testing API.",
5894
5941
  ],
@@ -6495,7 +6542,7 @@ function evalLockNudgeHookCommand() {
6495
6542
  // editing session, and a malformed `.vigilesrc.json` must not turn a JSON typo
6496
6543
  // into a failed edit: the nudge not firing is the cheaper failure. The verbs
6497
6544
  // throw on the same config; what is CHECKED is identical.
6498
- const config = (0, validate_js_1.loadConfig)(cwd, { onInvalid: "warn" });
6545
+ const config = loadConfig(cwd, { onInvalid: "warn" });
6499
6546
  const nudgeRules = (0, overrides_js_1.ruleResolver)(config.rules, config.overrides);
6500
6547
  const { options } = untestedRules(config, nudgeRules);
6501
6548
  // 🔴 THE SAME LAYOUT `vigiles lint` RESOLVES, for the same reason as the config
@@ -6583,7 +6630,7 @@ async function refsHookCommand() {
6583
6630
  // A hook rail — see `evalLockNudgeHookCommand` for why it warns, not throws.
6584
6631
  // Resolved at the edited file's own path, so an `overrides` entry that turns
6585
6632
  // `unmarked-refs` off for a folder is honoured at edit time too.
6586
- const refsConfig = (0, validate_js_1.loadConfig)(cwd, { onInvalid: "warn" });
6633
+ const refsConfig = loadConfig(cwd, { onInvalid: "warn" });
6587
6634
  const severity = (0, overrides_js_1.ruleResolver)(refsConfig.rules, refsConfig.overrides).severityAt("unmarked-refs", (0, node_path_1.relative)(cwd, (0, node_path_1.resolve)(cwd, file)));
6588
6635
  if (severity === false)
6589
6636
  return;
@@ -7287,6 +7334,47 @@ function rememberAuditMeasure(value) {
7287
7334
  /* non-fatal — the run already happened; only the remembered choice is lost */
7288
7335
  }
7289
7336
  }
7337
+ /**
7338
+ * The config this run uses: `.vigilesrc.json`, with any `--preset=<name>`
7339
+ * (audit, lint) applied ON TOP of what the file extends — through the one
7340
+ * validator `extends` uses, so an unknown name is "could not do what you
7341
+ * asked": exit 2, before anything runs. Then the shared flags (--max-rules,
7342
+ * --catalog-only) override it, so every GitHub Action input maps to a real CLI
7343
+ * flag (src/cli-flags.ts).
7344
+ */
7345
+ function loadRunConfig(projectRoot, args) {
7346
+ const presetFlag = (0, config_schema_js_2.parsePresetFlags)(CONFIG.presetNames, args
7347
+ .filter((a) => a.startsWith("--preset="))
7348
+ .map((a) => a.slice("--preset=".length)));
7349
+ if (!presetFlag.ok) {
7350
+ console.error(`✗ ${presetFlag.message}`);
7351
+ process.exit(2);
7352
+ }
7353
+ return (0, cli_flags_js_1.applyConfigFlags)(loadConfig(projectRoot, { presets: presetFlag.presets }), args);
7354
+ }
7355
+ /**
7356
+ * The scan `audit` reports on, with this run's config applied (`applyRules`):
7357
+ * an off rule's findings are gone before anything renders.
7358
+ */
7359
+ function auditScan(target, adapter, config, at) {
7360
+ const scan = (0, scan_js_1.scanPlugin)(target, adapter.layout, adapter.dialect, {
7361
+ deprecatedKeyFiles: specsUsingKeyFiles(at.root, at.excludes.globIgnore),
7362
+ sharedDirs: config.sharedDirs,
7363
+ sharedDirsRoot: at.frameRoot,
7364
+ // `.vigilesrc.json#exclude` reaches surface DISCOVERY, not just the
7365
+ // instruction file. Measured 2026-09-21 before this line existed: a repo
7366
+ // with `{"exclude": [".claude"]}` and one skill at `.claude/skills/demo`
7367
+ // still printed `Skills (1): ✓ demo` and docked Safety to 90 for it — the
7368
+ // grade was computed over a tree the user had told the tool to ignore.
7369
+ excludes: at.excludes,
7370
+ // The repo owner's answer to "N skills no harness reads": these are
7371
+ // mine, grade them — each root under the harness whose layout reads
7372
+ // it, so no array order decides which half of the repo is seen.
7373
+ // `exclude` still wins over it; the walk drops an excluded path first.
7374
+ harnesses: at.harnesses,
7375
+ });
7376
+ return (0, apply_rules_js_1.applyRules)(index_js_1.RULES, index_js_1.RULE_GROUPS, (0, overrides_js_1.ruleResolver)(config.rules, config.overrides), scan);
7377
+ }
7290
7378
  async function main() {
7291
7379
  const { command, projectRoot, args } = enterProjectRoot();
7292
7380
  // `--version` / `-v` / `version` prints the version number, not the help
@@ -7321,9 +7409,7 @@ async function main() {
7321
7409
  }
7322
7410
  }
7323
7411
  const restArgs = args.slice(1).filter((a) => !a.startsWith("--"));
7324
- // Shared flags (--max-rules, --catalog-only) override the loaded config so
7325
- // every GitHub Action input maps to a real CLI flag. See src/cli-flags.ts.
7326
- const config = (0, cli_flags_js_1.applyConfigFlags)((0, validate_js_1.loadConfig)(projectRoot), args);
7412
+ const config = loadRunConfig(projectRoot, args);
7327
7413
  // `.vigilesrc.json#exclude`, parsed ONCE here and threaded to every walk that
7328
7414
  // polices the repo (src/exclude.ts). Built where the config is loaded so a
7329
7415
  // command cannot re-derive it differently — the drift #192 measured.
@@ -7600,20 +7686,14 @@ async function main() {
7600
7686
  // The same single owner of "relative to which directory" `lint` uses
7601
7687
  // (#281): cwd, unless the audited dir is somebody else's repository.
7602
7688
  const frame = (0, frame_js_1.frameFor)(projectRoot, root);
7603
- const report = (0, scan_js_1.scanPlugin)(targets[0], adapter.layout, adapter.dialect, {
7604
- deprecatedKeyFiles: specsUsingKeyFiles(root, excludes.globIgnore),
7605
- sharedDirs: config.sharedDirs,
7606
- sharedDirsRoot: frame.root,
7607
- // `.vigilesrc.json#exclude` reaches surface DISCOVERY, not just the
7608
- // instruction file. Measured 2026-09-21 before this line existed: a repo
7609
- // with `{"exclude": [".claude"]}` and one skill at `.claude/skills/demo`
7610
- // still printed `Skills (1): ✓ demo` and docked Safety to 90 for it — the
7611
- // grade was computed over a tree the user had told the tool to ignore.
7689
+ // The resolved config, applied once at the source: what an off rule
7690
+ // found is gone from everything below (terminal, JSON, HTML).
7691
+ // The resolved config is applied once, at the source: what an off
7692
+ // rule found is gone from everything below (terminal, JSON, HTML).
7693
+ const report = auditScan(targets[0], adapter, config, {
7694
+ root,
7695
+ frameRoot: frame.root,
7612
7696
  excludes,
7613
- // The repo owner's answer to "N skills no harness reads": these are
7614
- // mine, grade them — each root under the harness whose layout reads
7615
- // it, so no array order decides which half of the repo is seen.
7616
- // `exclude` still wins over it; the walk drops an excluded path first.
7617
7697
  harnesses: scanHarnesses,
7618
7698
  });
7619
7699
  if (!json) {
@@ -7743,7 +7823,7 @@ async function main() {
7743
7823
  console.error(formatNothingToAudit(root, adapter.name, market));
7744
7824
  process.exit(2);
7745
7825
  }
7746
- const plan = (0, optimize_js_1.optimize)(report);
7826
+ const plan = (0, optimize_js_1.optimize)((0, apply_rules_js_1.gradedView)(report));
7747
7827
  // The deterministic READ leads: rings + report + fixes + nudges print
7748
7828
  // BEFORE the consent prompt, so a plain `audit` shows its findings first.
7749
7829
  // (JSON stays silent until the single blob below, after consent.)
@@ -7752,6 +7832,8 @@ async function main() {
7752
7832
  // shown before the detailed report so the headline signal leads.
7753
7833
  console.log((0, audit_score_js_1.formatAuditScore)(sc));
7754
7834
  console.log("");
7835
+ // The ungraded blocks come off the filtered scan — the same data
7836
+ // the JSON and HTML render — so the three cannot drift.
7755
7837
  console.log((0, scan_js_1.formatScanReport)(report));
7756
7838
  // Fold each finding's fix inline (replaces the former --fix-plan/--explain
7757
7839
  // flags): the deterministic, free recommendation list under the report.
@@ -7770,8 +7852,7 @@ async function main() {
7770
7852
  console.log("\n" + adoptNudge);
7771
7853
  // A small behavioral nudge — the deterministic read can't tell whether
7772
7854
  // skills actually FIRE; point at the interactive measure + the API.
7773
- const fireNudge = formatTriggerNudge(report.skills.filter((s) => s.hasDescription && !s.userInvoked)
7774
- .length);
7855
+ const fireNudge = formatTriggerNudge(surfaces.triggerableSkills);
7775
7856
  if (fireNudge)
7776
7857
  console.log("\n" + fireNudge);
7777
7858
  }
@@ -13,10 +13,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
13
13
  const spec_js_1 = require("./spec.js");
14
14
  exports.default = (0, spec_js_1.instructionFile)({
15
15
  sections: {
16
- scope: `Working in \`src/core/\`? This is the harness-AGNOSTIC domain (spec, compile, linters, the lint/audit detectors). The root \`CLAUDE.md\` holds the full positioning + rule set — read it first. Two invariants live closest to this code: the core must not import an adapter (\`core ⊄ adapter\`, eslint-enforced) and must not hard-code a Claude Code literal (read it from the injected layout/dialect). This file adds the rule for ADDING or CHANGING a detector.`,
16
+ scope: `Working in \`src/core/\`? This is the harness-AGNOSTIC domain (spec, compile, linters, the lint/audit detectors). The root \`CLAUDE.md\` holds the full positioning + rule set — read it first. Two invariants live closest to this code: the core must not import an adapter (\`core ⊄ adapter\`, eslint-enforced) and must not hard-code a Claude Code literal (read it from the injected layout/dialect). This file adds the rule for ADDING or CHANGING a detector, and where the rule around it lives.`,
17
17
  },
18
18
  rules: {
19
- "detector-meta": (0, spec_js_1.guidance)("A deterministic DETECTOR here is one half of a RULE — and a rule is not done until it is DECLARED. Three things move together (sibling of one-detector-no-drift + rules-docs-in-sync): (1) the pure detector function (shared by `lint` AND `audit`, never reimplemented per surface; read the layout/dialect, never a CC literal); (2) its entry in `src/core/rule-meta.ts` — the `Record<RuleName, RuleMeta>` won't typecheck without it — declaring its DECIDABILITY BUCKET (structural-closed = a type could prevent it / external-decidable = needs the world, error-capable / heuristic-behavioral = warn-or-measure-only), surface, defaultSeverity, the detector name, and any upstreamPrevention; (3) its `docs/rules/<name>.md` (the coverage test binds the registry to the docs by an EXACT set match, so a missing meta or doc fails CI). The bucket is the CEILING, not a preference — a heuristic proxy may NEVER default to `error` (it cries wolf); a structural/external fact MAY, once proven FP-safe. Before writing a new detector, CLASSIFY the defect into a bucket — that decides whether it can ever gate. The full model + the prose behind the buckets is the root `lint-rule-calibration` rule and `research/enforcement-model.md`."),
19
+ "detector-meta": (0, spec_js_1.guidance)("A deterministic DETECTOR here is a domain capability — a pure function shared by `lint` AND `audit`, never reimplemented per surface, reading the injected layout/dialect and never a Claude Code literal. The RULE around it — id, group, default, decidability bucket, cure, how a finding reads — is POLICY and lives in the outer rule layer: a module `src/rules/<id>.ts` (or, until it migrates in #390, its row in `src/rules/index.ts`), plus its `docs/rules/<id>.md`; `src/rules/index.test.ts` binds the set to the docs by an exact set match. Core declares the port (`./rule.ts`) and receives the set as a parameter (`configFor`, `applyRules`): never import `../rules`, never spell a rule id, never name a group — `boundaries`, `local/no-rule-ids` and `local/no-group-names` refuse each. The bucket is the CEILING, not a preference — a heuristic proxy (heuristic-behavioral) may NEVER default to `error` (it cries wolf); a structural-closed or external-decidable fact MAY, once proven FP-safe. Before writing a new detector, CLASSIFY the defect into a bucket — that decides whether it can ever gate. The model behind the buckets is the root `lint-rule-calibration` rule."),
20
20
  },
21
21
  });
22
22
  //# sourceMappingURL=CLAUDE.md.spec.js.map