vigiles 39.1.0 → 40.0.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 (61) hide show
  1. package/dist/adapter.d.ts +3 -2
  2. package/dist/adapters/claude-code/dialect.js +9 -0
  3. package/dist/adapters/claude-code/output-style.js +15 -0
  4. package/dist/adapters/claude-code/skill-listing.d.ts +48 -0
  5. package/dist/adapters/claude-code/skill-listing.js +54 -0
  6. package/dist/adapters/codex/dialect.js +4 -0
  7. package/dist/adapters/codex/layout.js +5 -0
  8. package/dist/adapters/codex/mock-model.d.ts +7 -0
  9. package/dist/adapters/codex/mock-model.js +1 -0
  10. package/dist/adapters/codex/skill-listing.d.ts +42 -0
  11. package/dist/adapters/codex/skill-listing.js +40 -0
  12. package/dist/audit-html.js +7 -2
  13. package/dist/audit-report.d.ts +51 -0
  14. package/dist/audit-report.js +54 -8
  15. package/dist/audit-report.template.html +38 -33
  16. package/dist/cli-flag-check.d.ts +1 -1
  17. package/dist/cli-flag-check.js +1 -1
  18. package/dist/cli-main.d.ts +9 -3
  19. package/dist/cli-main.js +33 -18
  20. package/dist/{instruction-weight-ratchet.d.ts → context-creep-ratchet.d.ts} +34 -12
  21. package/dist/context-creep-ratchet.js +270 -0
  22. package/dist/core/adopt.js +32 -8
  23. package/dist/core/always-loaded.d.ts +128 -0
  24. package/dist/core/always-loaded.js +134 -0
  25. package/dist/core/compile.d.ts +1 -1
  26. package/dist/core/compile.js +48 -15
  27. package/dist/core/dialect.d.ts +10 -1
  28. package/dist/core/dialect.js +2 -0
  29. package/dist/core/harness-unit.d.ts +20 -0
  30. package/dist/core/harness-unit.js +24 -0
  31. package/dist/core/instruction-baseline.d.ts +179 -11
  32. package/dist/core/instruction-baseline.js +349 -47
  33. package/dist/core/instruction-weight.d.ts +2 -11
  34. package/dist/core/instruction-weight.js +6 -16
  35. package/dist/core/layout.d.ts +40 -0
  36. package/dist/core/layout.js +25 -1
  37. package/dist/core/output-style.d.ts +20 -0
  38. package/dist/core/skill-listing.d.ts +49 -0
  39. package/dist/core/skill-listing.js +23 -0
  40. package/dist/core/spec.d.ts +17 -0
  41. package/dist/core/types.d.ts +2 -2
  42. package/dist/deprecated-key-files.d.ts +1 -1
  43. package/dist/deprecated-key-files.js +1 -1
  44. package/dist/doc-commands.d.ts +2 -2
  45. package/dist/fs-walk.d.ts +31 -0
  46. package/dist/fs-walk.js +49 -0
  47. package/dist/local-files.js +2 -1
  48. package/dist/plugin-loader.js +40 -19
  49. package/dist/rules/index.d.ts +4 -4
  50. package/dist/rules/index.js +7 -7
  51. package/dist/scan-files.js +24 -3
  52. package/dist/scan.d.ts +30 -1
  53. package/dist/scan.js +69 -3
  54. package/dist/skill-harness.d.ts +3 -1
  55. package/dist/skill-harness.js +5 -2
  56. package/dist/surface-discovery-fs.d.ts +15 -0
  57. package/dist/surface-discovery-fs.js +55 -0
  58. package/dist/vigilesrc.schema.json +2 -2
  59. package/hooks/session-start.sh +3 -1
  60. package/package.json +1 -1
  61. package/dist/instruction-weight-ratchet.js +0 -181
@@ -1,10 +1,11 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.RULE_FILE_LEAF_RE = exports.AGENT_FILE_LEAF_RE = exports.SURFACE_KINDS = void 0;
3
+ exports.RULE_FILE_LEAF_RE = exports.AGENT_FILE_LEAF_RE = exports.skillDiscoveryOf = exports.ONE_FOLDER_PER_SKILL = exports.SURFACE_KINDS = void 0;
4
4
  exports.surfaceDirs = surfaceDirs;
5
5
  exports.executableSourceDirs = executableSourceDirs;
6
6
  exports.materializePrefix = materializePrefix;
7
7
  exports.skillsHome = skillsHome;
8
+ exports.sessionSkillDirs = sessionSkillDirs;
8
9
  exports.rulesHome = rulesHome;
9
10
  exports.ruleFileRe = ruleFileRe;
10
11
  exports.agentSurfaceName = agentSurfaceName;
@@ -63,6 +64,29 @@ function skillsHome(layout) {
63
64
  const root = layout.userSurfaceRoot;
64
65
  return root === undefined || root === "" ? skill : `${root}/${skill}`;
65
66
  }
67
+ /** One directory per skill, `<skillsHome>/<name>/SKILL.md` — Claude Code's shape. */
68
+ exports.ONE_FOLDER_PER_SKILL = {
69
+ minDepth: 1,
70
+ maxDepth: 1,
71
+ skipHidden: false,
72
+ };
73
+ /** The layout's skill discovery, defaulted. */
74
+ const skillDiscoveryOf = (layout) => layout.skillDiscovery ?? exports.ONE_FOLDER_PER_SKILL;
75
+ exports.skillDiscoveryOf = skillDiscoveryOf;
76
+ /**
77
+ * The directories between the skills folder and a `SKILL.md`, for a path
78
+ * RELATIVE to that folder — or `null` when the harness would not read it.
79
+ */
80
+ function sessionSkillDirs(rel, discovery) {
81
+ const segments = rel.split("/");
82
+ if (segments.at(-1) !== "SKILL.md")
83
+ return null;
84
+ const dirs = segments.slice(0, -1);
85
+ const fits = dirs.length >= discovery.minDepth &&
86
+ dirs.length <= discovery.maxDepth &&
87
+ dirs.every((d) => d !== "" && !(discovery.skipHidden && d.startsWith(".")));
88
+ return fits ? dirs : null;
89
+ }
66
90
  /**
67
91
  * How DEEP a harness reads its {@link PluginLayout.agentDir} — the one statement
68
92
  * of that rule, as a RegExp source fragment matching the part of a path AFTER
@@ -41,7 +41,27 @@ export interface OutputStyleRules {
41
41
  readonly selectNone: Readonly<Record<string, unknown>>;
42
42
  /** Whether one model request carries the style. */
43
43
  readonly reached: (style: OutputStyle, request: ModelRequest) => boolean;
44
+ /**
45
+ * Which style ONE settings object switches on — the inverse of
46
+ * {@link select}. Pure: the caller parses the file. Optional: absent ⇒ the
47
+ * always-loaded report says the selection is not modelled for this harness,
48
+ * rather than guessing that nothing is selected.
49
+ */
50
+ readonly selected?: (settings: Readonly<Record<string, unknown>>) => StyleSelection;
44
51
  }
52
+ /**
53
+ * What a settings object says about the output style. Three different facts:
54
+ * the key is absent, it names the harness's own default (no extra text), or
55
+ * it names a style — which may or may not be a file the repository holds.
56
+ */
57
+ export type StyleSelection = {
58
+ readonly kind: "unset";
59
+ } | {
60
+ readonly kind: "default";
61
+ } | {
62
+ readonly kind: "named";
63
+ readonly name: string;
64
+ };
45
65
  /** What a repository holds, or that its harness has no such thing. */
46
66
  export type OutputStyleScan = {
47
67
  readonly kind: "not-supported";
@@ -0,0 +1,49 @@
1
+ /**
2
+ * The skill listing: the block of one-line skill entries a harness puts into
3
+ * every session before the model has made a single decision, so the model can
4
+ * pick a skill by its description.
5
+ *
6
+ * WHY IT IS PART OF THE ALWAYS-LOADED CONTEXT. Each listed skill costs its entry on
7
+ * every request of every session, whether or not it is ever invoked — the same
8
+ * property that makes the instruction file a cost. A description moved out of
9
+ * `CLAUDE.md` into a skill's frontmatter still loads at session start, so a
10
+ * weight that counts the instruction file and not the listing rewards a move
11
+ * that changes nothing (`./instruction-weight.ts` explains the same evasion for
12
+ * split instruction files).
13
+ *
14
+ * The core knows only that idea. How one entry is rendered — which keys it
15
+ * reads, the per-entry cap, which settings hide a skill — is each harness's own
16
+ * format, given by its dialect as {@link SkillListingRules}. A dialect without
17
+ * it is a harness whose listing vigiles does not model; that is a different
18
+ * fact from "this harness lists nothing", and the always-loaded report keeps
19
+ * the two apart.
20
+ */
21
+ /** One skill as the harness would list it, read once by the core. */
22
+ export interface ListedSkill {
23
+ /** The SKILL.md path, relative to the scanned directory, `/`-separated. */
24
+ readonly path: string;
25
+ /** The skill's directory name — the fallback name when frontmatter has none. */
26
+ readonly dirName: string;
27
+ /**
28
+ * The parsed frontmatter mapping (`{}` when the file has no block). `null`
29
+ * when a block exists and is not valid YAML: the harness decides what such a
30
+ * file does, so the core does not guess a salvaged value for it.
31
+ */
32
+ readonly frontmatter: Readonly<Record<string, unknown>> | null;
33
+ /** The markdown body, frontmatter removed. */
34
+ readonly body: string;
35
+ }
36
+ /** How one harness renders a skill into its session-start listing. */
37
+ export interface SkillListingRules {
38
+ /**
39
+ * The entry exactly as the harness renders it, its own per-entry cap
40
+ * applied — or `null` when the harness does not list this skill at all.
41
+ * `settings` is the COMMITTED settings object (parsed by the layout's codec,
42
+ * `{}` when there is none), because a listing setting there changes what
43
+ * every teammate's session loads.
44
+ */
45
+ readonly entry: (skill: ListedSkill, settings: Readonly<Record<string, unknown>>) => string | null;
46
+ /** The vendor artifact this was read from, version included. */
47
+ readonly capturedFrom: string;
48
+ }
49
+ //# sourceMappingURL=skill-listing.d.ts.map
@@ -0,0 +1,23 @@
1
+ "use strict";
2
+ /**
3
+ * The skill listing: the block of one-line skill entries a harness puts into
4
+ * every session before the model has made a single decision, so the model can
5
+ * pick a skill by its description.
6
+ *
7
+ * WHY IT IS PART OF THE ALWAYS-LOADED CONTEXT. Each listed skill costs its entry on
8
+ * every request of every session, whether or not it is ever invoked — the same
9
+ * property that makes the instruction file a cost. A description moved out of
10
+ * `CLAUDE.md` into a skill's frontmatter still loads at session start, so a
11
+ * weight that counts the instruction file and not the listing rewards a move
12
+ * that changes nothing (`./instruction-weight.ts` explains the same evasion for
13
+ * split instruction files).
14
+ *
15
+ * The core knows only that idea. How one entry is rendered — which keys it
16
+ * reads, the per-entry cap, which settings hide a skill — is each harness's own
17
+ * format, given by its dialect as {@link SkillListingRules}. A dialect without
18
+ * it is a harness whose listing vigiles does not model; that is a different
19
+ * fact from "this harness lists nothing", and the always-loaded report keeps
20
+ * the two apart.
21
+ */
22
+ Object.defineProperty(exports, "__esModule", { value: true });
23
+ //# sourceMappingURL=skill-listing.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
@@ -63,9 +63,9 @@ export interface CoverageThresholds {
63
63
  scripts?: number;
64
64
  }
65
65
  /**
66
- * Options for the `instruction-weight` rule: `["error", { max: 40000 }]`.
66
+ * Options for the `context-creep` rule: `["error", { max: 40000 }]`.
67
67
  */
68
- export interface InstructionWeightConfig {
68
+ export interface ContextCreepConfig {
69
69
  /**
70
70
  * An opt-in ABSOLUTE ceiling on the always-loaded instruction weight, in the
71
71
  * harness's own unit (characters for Claude Code, bytes for Codex). A total
@@ -16,7 +16,7 @@ export declare function findDeprecatedKeyFiles(io: {
16
16
  }): readonly DeprecatedKeyFilesFinding[];
17
17
  /**
18
18
  * `lint`'s side of the rule. Runs ONCE over the repository, like the
19
- * instruction-weight ratchet: a nested bundle's spec would otherwise be
19
+ * context-creep ratchet: a nested bundle's spec would otherwise be
20
20
  * reported again by every bundle that encloses it. Warning by default — a
21
21
  * deprecation that gated would turn a consumer's CI red on upgrade, which the
22
22
  * one-major window exists to prevent.
@@ -32,7 +32,7 @@ function findDeprecatedKeyFiles(io) {
32
32
  const messageFor = (f) => (0, keyfiles_js_1.keyFilesDeprecationMessage)(f, (0, keyfiles_js_1.instructionFileOfSpec)(f.path));
33
33
  /**
34
34
  * `lint`'s side of the rule. Runs ONCE over the repository, like the
35
- * instruction-weight ratchet: a nested bundle's spec would otherwise be
35
+ * context-creep ratchet: a nested bundle's spec would otherwise be
36
36
  * reported again by every bundle that encloses it. Warning by default — a
37
37
  * deprecation that gated would turn a consumer's CI red on upgrade, which the
38
38
  * one-major window exists to prevent.
@@ -7,8 +7,8 @@
7
7
  * that must obey it — "always pass `curl -g`, or bracketed params glob and the
8
8
  * request fails SILENTLY"; "every `psql` needs `--single-transaction`". The rule
9
9
  * and its violation live **in the same file**, three paragraphs apart, and
10
- * nothing compares them. It is `prose isn't policy` turned on the author's own
11
- * document, and it is the smallest possible instance of it.
10
+ * nothing compares them. It is a rule nobody checks, turned on the author's own
11
+ * document, and it is the smallest possible instance of one.
12
12
  *
13
13
  * vigiles cannot INFER such a rule — no tool reads "always use -g" and derives
14
14
  * which flag is mandatory. What was missing is not cleverness but a cheap way to
package/dist/fs-walk.d.ts CHANGED
@@ -77,4 +77,35 @@ export declare function entryOf(path: string): Entry;
77
77
  * check that quietly disagrees with the first.
78
78
  */
79
79
  export declare function walkableRoot(dir: string, scanRoot: string): boolean;
80
+ /** A classified entry, plus whether entries BELOW it may still cross a directory link. */
81
+ export interface LinkedEntry extends Entry {
82
+ readonly mayFollowBelow: boolean;
83
+ }
84
+ /**
85
+ * {@link entryOf} for a walk over a SKILLS folder, where ONE symlinked directory
86
+ * per path may be entered.
87
+ *
88
+ * 🔴 WHY SKILLS GET THIS AND OTHER SURFACES DO NOT. `vigiles init` installs a
89
+ * shipped skill by linking its folder into the skills folder, and both Claude
90
+ * Code and Codex list a linked skill folder like a real one. Under
91
+ * {@link entryOf} alone the loader refused every such link, so on a real
92
+ * repository `vigiles audit` printed `Skills (58)` while the skill listing it
93
+ * weighs — and the harness — carried 83: 27 skill folders were links. The
94
+ * listing reader and the loader now both classify through this function, so the
95
+ * count and the listing cannot disagree about which folders exist.
96
+ *
97
+ * THE POLICY IS {@link walkableRoot}'s, ONE LEVEL DOWN. A linked skill folder is
98
+ * an entry the layout names, like a surface root, so it is followed — with two
99
+ * refusals, both the cycle case: a target that CONTAINS the scanned root
100
+ * (`skills/x -> <repo>`), and a target that contains the link itself
101
+ * (`skills/a/self -> skills`), which re-enters the tree being walked.
102
+ *
103
+ * Termination is by CONSTRUCTION, as everywhere in this module: below a
104
+ * followed link `mayFollowBelow` is `false`, so every path crosses at most one
105
+ * directory link (plus its root's own), and a walk over finite real
106
+ * directories ends. A chain of links that never points back at an ancestor
107
+ * (`A/b -> B`, `B/c -> A`) is cut at the second hop by the same rule. There is
108
+ * no visited-set to get wrong.
109
+ */
110
+ export declare function skillTreeEntryOf(path: string, scanRoot: string, mayFollow: boolean): LinkedEntry;
80
111
  //# sourceMappingURL=fs-walk.d.ts.map
package/dist/fs-walk.js CHANGED
@@ -2,6 +2,7 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.entryOf = entryOf;
4
4
  exports.walkableRoot = walkableRoot;
5
+ exports.skillTreeEntryOf = skillTreeEntryOf;
5
6
  /**
6
7
  * The ONE symlink policy for every recursive directory walk in vigiles.
7
8
  *
@@ -131,6 +132,54 @@ function walkableRoot(dir, scanRoot) {
131
132
  return false; // dangling link — nothing to walk
132
133
  }
133
134
  }
135
+ /**
136
+ * {@link entryOf} for a walk over a SKILLS folder, where ONE symlinked directory
137
+ * per path may be entered.
138
+ *
139
+ * 🔴 WHY SKILLS GET THIS AND OTHER SURFACES DO NOT. `vigiles init` installs a
140
+ * shipped skill by linking its folder into the skills folder, and both Claude
141
+ * Code and Codex list a linked skill folder like a real one. Under
142
+ * {@link entryOf} alone the loader refused every such link, so on a real
143
+ * repository `vigiles audit` printed `Skills (58)` while the skill listing it
144
+ * weighs — and the harness — carried 83: 27 skill folders were links. The
145
+ * listing reader and the loader now both classify through this function, so the
146
+ * count and the listing cannot disagree about which folders exist.
147
+ *
148
+ * THE POLICY IS {@link walkableRoot}'s, ONE LEVEL DOWN. A linked skill folder is
149
+ * an entry the layout names, like a surface root, so it is followed — with two
150
+ * refusals, both the cycle case: a target that CONTAINS the scanned root
151
+ * (`skills/x -> <repo>`), and a target that contains the link itself
152
+ * (`skills/a/self -> skills`), which re-enters the tree being walked.
153
+ *
154
+ * Termination is by CONSTRUCTION, as everywhere in this module: below a
155
+ * followed link `mayFollowBelow` is `false`, so every path crosses at most one
156
+ * directory link (plus its root's own), and a walk over finite real
157
+ * directories ends. A chain of links that never points back at an ancestor
158
+ * (`A/b -> B`, `B/c -> A`) is cut at the second hop by the same rule. There is
159
+ * no visited-set to get wrong.
160
+ */
161
+ function skillTreeEntryOf(path, scanRoot, mayFollow) {
162
+ const entry = entryOf(path);
163
+ if (entry.kind === "skip" && mayFollow && followableDirLink(path, scanRoot))
164
+ return { kind: "dir", size: 0, mayFollowBelow: false };
165
+ return { ...entry, mayFollowBelow: mayFollow };
166
+ }
167
+ /**
168
+ * Whether an entry {@link entryOf} skipped is a directory link a skills walk may
169
+ * enter. Only skipped entries are asked, so a plain directory never reaches
170
+ * here; a dangling link throws from `realpathSync` and is refused.
171
+ */
172
+ function followableDirLink(path, scanRoot) {
173
+ try {
174
+ const target = (0, node_fs_1.realpathSync)(path);
175
+ return (!contains(target, realpath(scanRoot)) &&
176
+ !contains(target, (0, node_fs_1.realpathSync)((0, node_path_1.dirname)(path))) &&
177
+ (0, node_fs_1.statSync)(target).isDirectory());
178
+ }
179
+ catch {
180
+ return false;
181
+ }
182
+ }
134
183
  /** `realpathSync`, falling back to a plain resolve for a root that is not there. */
135
184
  function realpath(p) {
136
185
  try {
@@ -108,7 +108,8 @@ exports.COMMITTED_PATHS = [
108
108
  "schema.json", // YAML-LSP frontmatter schema (`vigiles init`)
109
109
  "guards.json", // the declared guard set (`core/guards.ts`)
110
110
  "action-gates.json", // declared action gates (`action-gate.ts`)
111
- "instruction-weight.json", // the instruction-weight ratchet's baseline (`core/instruction-baseline.ts`)
111
+ "context-creep.json", // the context-creep ratchet's baseline (`core/instruction-baseline.ts`)
112
+ "instruction-weight.json", // that baseline's name before the rename, still read (`core/instruction-baseline.ts`)
112
113
  ];
113
114
  /** The header comment on a `.vigiles/.gitignore` vigiles creates. */
114
115
  /** The ignore file vigiles keeps inside `.vigiles/`. One spelling for every reader. */
@@ -125,6 +125,7 @@ function readPluginHooks(root, layout) {
125
125
  }
126
126
  return { declared: false, hooks: undefined };
127
127
  }
128
+ const NO_DIR_LINKS = { scanRoot: "", mayFollow: false };
128
129
  /**
129
130
  * Recursively collect text files under `dir` as `relativePath → contents`.
130
131
  *
@@ -137,7 +138,10 @@ function readPluginHooks(root, layout) {
137
138
  * quieter half of the same bug: the loader reads a foreign tree into the file map
138
139
  * that the entire report is computed from.
139
140
  *
140
- * The decision is {@link entryOf}, which lives in `fs-walk.ts` rather than here.
141
+ * The decision is `entryOf`, which lives in `fs-walk.ts` rather than here — asked
142
+ * through `skillTreeEntryOf`, which answers exactly as `entryOf` does unless the
143
+ * walk is over a skills folder and may still cross one directory link (a skill
144
+ * folder `vigiles init` linked in).
141
145
  * It was shared with `harnessSurfaceFilesOnDisk` in `scan.ts` — the other walk
142
146
  * over the same trees, and exactly the kind of pair this repo has been bitten by
143
147
  * fixing on only one side — until that walk was deleted with the foreign-runner
@@ -151,7 +155,7 @@ function readPluginHooks(root, layout) {
151
155
  * `entryOf` has already cleared would cost a syscall per directory to answer a
152
156
  * question that cannot come out differently.
153
157
  */
154
- function readTree(dir, base, excluded = exclude_js_1.excludesNothing) {
158
+ function readTree(dir, base, excluded = exclude_js_1.excludesNothing, links = NO_DIR_LINKS) {
155
159
  const out = {};
156
160
  for (const entry of (0, node_fs_1.readdirSync)(dir)) {
157
161
  const full = (0, node_path_1.join)(dir, entry);
@@ -160,11 +164,13 @@ function readTree(dir, base, excluded = exclude_js_1.excludesNothing) {
160
164
  // excluded at its own root (`bench`, `vendor/corpus`), which is a descendant
161
165
  // of a surface dir, so a check that only guarded the walk's start would let
162
166
  // every one of its files into the file map the whole report is computed from.
167
+ // It is asked of the LINK's path, before anything follows it, so an excluded
168
+ // linked skill folder is not read either.
163
169
  if (excluded(full))
164
170
  continue;
165
- const { kind, size } = (0, fs_walk_js_1.entryOf)(full);
171
+ const { kind, size, mayFollowBelow } = (0, fs_walk_js_1.skillTreeEntryOf)(full, links.scanRoot, links.mayFollow);
166
172
  if (kind === "dir")
167
- Object.assign(out, readTree(full, base, excluded));
173
+ Object.assign(out, readTree(full, base, excluded, { ...links, mayFollow: mayFollowBelow }));
168
174
  // The cap keeps a stray binary out of the in-memory file map, and the size
169
175
  // comes from the SAME stat that classified the entry. Asking a second time
170
176
  // needed its own `catch` — reachable only if the file vanished between the two
@@ -329,27 +335,42 @@ function surfaceHasLoadable(layout, surface, tree) {
329
335
  ? keys.some((k) => (0, node_path_1.basename)(k) === "SKILL.md")
330
336
  : keys.some((k) => k.endsWith(".md"));
331
337
  }
338
+ /**
339
+ * One surface dir's tree, or `{}` when there is nothing to read.
340
+ *
341
+ * `walkableRoot` classifies the walk's ENTRY POINT — `statSync` follows a symlink,
342
+ * so a `skills -> ..` link handed the whole repo (node_modules included) to the
343
+ * file map the entire report is computed from. It is a DIFFERENT rule from the
344
+ * per-entry one and that function says why; a shared skills dir linked in from
345
+ * outside is still read.
346
+ */
347
+ function surfaceTreeAt(root, dir, excluded, links = NO_DIR_LINKS) {
348
+ const isDir = (0, node_fs_1.existsSync)(dir) && (0, node_fs_1.statSync)(dir).isDirectory();
349
+ return isDir && (0, fs_walk_js_1.walkableRoot)(dir, root) && !excluded(dir)
350
+ ? readTree(dir, dir, excluded, links)
351
+ : {};
352
+ }
353
+ /**
354
+ * The link policy a surface's walk gets: the SKILLS surface may cross one
355
+ * directory link per path — a linked skill folder is how `vigiles init`
356
+ * installs a skill, and the harness lists it — every other surface none.
357
+ */
358
+ function linksFor(layout, surface, root) {
359
+ return surface === layout.surfaces.skill
360
+ ? { scanRoot: root, mayFollow: true }
361
+ : NO_DIR_LINKS;
362
+ }
332
363
  function materializeSurfaces(root, layout, files, sources, excluded = exclude_js_1.excludesNothing, surfaceRoots) {
333
364
  const counts = {};
334
365
  const harnessCounts = {};
335
- const isDir = (p) => (0, node_fs_1.existsSync)(p) && (0, node_fs_1.statSync)(p).isDirectory();
336
- /**
337
- * One surface dir's tree, or `{}` when there is nothing to read.
338
- *
339
- * `walkableRoot` classifies the walk's ENTRY POINT — `isDir` follows a symlink,
340
- * so a `skills -> ..` link handed the whole repo (node_modules included) to the
341
- * file map the entire report is computed from. It is a DIFFERENT rule from the
342
- * per-entry one and that function says why; a shared skills dir linked in from
343
- * outside is still read.
344
- */
345
- const surfaceTree = (dir) => isDir(dir) && (0, fs_walk_js_1.walkableRoot)(dir, root) && !excluded(dir)
346
- ? readTree(dir, dir, excluded)
347
- : {};
366
+ const surfaceTree = (dir, links) => surfaceTreeAt(root, dir, excluded, links);
348
367
  /** Every surface tree of one scope, read once, keyed by surface dir. */
349
368
  const scopeTrees = (base) => {
350
369
  const trees = new Map();
351
- for (const surface of (0, layout_js_1.surfaceDirs)(layout))
352
- trees.set(surface, surfaceTree((0, node_path_1.join)(root, base, surface)));
370
+ for (const surface of (0, layout_js_1.surfaceDirs)(layout)) {
371
+ const dir = (0, node_path_1.join)(root, base, surface);
372
+ trees.set(surface, surfaceTree(dir, linksFor(layout, surface, root)));
373
+ }
353
374
  return trees;
354
375
  };
355
376
  const hasLoadable = (trees) => (0, layout_js_1.surfaceDirs)(layout).some((s) => surfaceHasLoadable(layout, s, trees.get(s) ?? {}));
@@ -381,14 +381,14 @@ export declare const RULES: readonly [{
381
381
  readonly summary: "Builder calls quoted in markdown ```ts fences resolve for real (opt-in: a fence is usually a drawing of config, not config).";
382
382
  readonly detector: "findDocRefs";
383
383
  }, {
384
- readonly id: "instruction-weight";
384
+ readonly id: "context-creep";
385
385
  readonly group: "structural";
386
386
  readonly bucket: "external-decidable";
387
- readonly surface: readonly ["instruction"];
387
+ readonly surface: readonly ["instruction", "skill", "output-style"];
388
388
  readonly defaultSeverity: "error";
389
389
  readonly cure: "edit";
390
- readonly summary: "The always-loaded instruction weight did not move off its committed baseline.";
391
- readonly detector: "compareToBaseline";
390
+ readonly summary: "What the harness loads at session start (instructions, the selected output style, the skill listing) did not move off its committed baseline.";
391
+ readonly detector: "compareAlwaysLoadedToBaseline";
392
392
  readonly options: z.ZodObject<{
393
393
  max: z.ZodOptional<z.ZodNumber>;
394
394
  }, z.core.$strict>;
@@ -47,12 +47,12 @@ const testCoverageConfig = zod_1.z
47
47
  })
48
48
  .strict();
49
49
  /**
50
- * Options for `instruction-weight`. `max` is an opt-in ABSOLUTE ceiling on the
50
+ * Options for `context-creep`. `max` is an opt-in ABSOLUTE ceiling on the
51
51
  * always-loaded total, in the harness's own unit — independent of the ratchet's
52
52
  * baseline. A positive integer: `0` would fail every repo that has an
53
53
  * instruction file, and `"40000"` is a string the author meant as a number.
54
54
  */
55
- const instructionWeightConfig = zod_1.z
55
+ const contextCreepConfig = zod_1.z
56
56
  .object({
57
57
  max: zod_1.z.number().int().positive().optional(),
58
58
  })
@@ -437,15 +437,15 @@ exports.RULES = [
437
437
  detector: "findDocRefs",
438
438
  }),
439
439
  (0, rule_js_1.defineRule)({
440
- id: "instruction-weight",
440
+ id: "context-creep",
441
441
  group: "structural",
442
442
  bucket: "external-decidable",
443
- surface: ["instruction"],
443
+ surface: ["instruction", "skill", "output-style"],
444
444
  defaultSeverity: "error",
445
445
  cure: "edit",
446
- summary: "The always-loaded instruction weight did not move off its committed baseline.",
447
- detector: "compareToBaseline",
448
- options: instructionWeightConfig,
446
+ summary: "What the harness loads at session start (instructions, the selected output style, the skill listing) did not move off its committed baseline.",
447
+ detector: "compareAlwaysLoadedToBaseline",
448
+ options: contextCreepConfig,
449
449
  }),
450
450
  (0, rule_js_1.defineRule)({
451
451
  id: "deprecated-key-files",
@@ -43,6 +43,7 @@ const layout_js_1 = require("./adapters/claude-code/layout.js");
43
43
  const dialect_js_1 = require("./adapters/claude-code/dialect.js");
44
44
  const layout_js_2 = require("./core/layout.js");
45
45
  const instruction_weight_js_1 = require("./core/instruction-weight.js");
46
+ const always_loaded_js_1 = require("./core/always-loaded.js");
46
47
  const integrity_header_js_1 = require("./core/integrity-header.js");
47
48
  const instruction_chain_js_1 = require("./core/instruction-chain.js");
48
49
  const hook_normalize_js_1 = require("./core/hook-normalize.js");
@@ -655,9 +656,7 @@ function scanFiles(files, layout = layout_js_1.claudeCodeLayout, dialect = diale
655
656
  // depth-1 dot-directories and nothing else, so handing the whole fetched map
656
657
  // over would make the browser weigh files the CLI never opens. Same filter,
657
658
  // same import pass, same chain; only the storage differs.
658
- instructionWeight: dialect.instructionBudget
659
- ? (0, instruction_weight_js_1.weighInstructions)(lay.instructionChain(instructionFiles), instructionFiles, dialect.instructionBudget)
660
- : null,
659
+ ...alwaysLoadedInMap(lay, dialect, instructionFiles, files),
661
660
  untested: coverage.untested.length,
662
661
  untestedHarness: coverage.harness.untested.length,
663
662
  unevaluated: coverage.evals.untested.length,
@@ -666,4 +665,26 @@ function scanFiles(files, layout = layout_js_1.claudeCodeLayout, dialect = diale
666
665
  puritySummary,
667
666
  };
668
667
  }
668
+ /**
669
+ * The browser twin of `scan.ts`'s `alwaysLoadedOf`: the same weight over the
670
+ * same bounded instruction files, and the always-loaded context over the WHOLE fetched
671
+ * tree — `weighAlwaysLoaded` keeps only the paths the disk reader reads (the
672
+ * session's style folder and one `SKILL.md` per skill directory), so the two
673
+ * engines see the same files.
674
+ */
675
+ function alwaysLoadedInMap(lay, dialect, instructionFiles, files) {
676
+ const budget = dialect.instructionBudget;
677
+ if (budget === undefined)
678
+ return { instructionWeight: null };
679
+ const instructionWeight = (0, instruction_weight_js_1.weighInstructions)(lay.instructionChain(instructionFiles), instructionFiles, budget);
680
+ return {
681
+ instructionWeight,
682
+ alwaysLoaded: (0, always_loaded_js_1.weighAlwaysLoaded)({
683
+ weight: instructionWeight,
684
+ files: { ...files, ...instructionFiles },
685
+ layout: lay,
686
+ dialect,
687
+ }),
688
+ };
689
+ }
669
690
  //# sourceMappingURL=scan-files.js.map
package/dist/scan.d.ts CHANGED
@@ -35,6 +35,7 @@ import { type EvidenceCounts } from "./coverage-evidence.js";
35
35
  import type { PurityLevel, EffectSurface } from "./core/effects.js";
36
36
  import { type HandWrittenHook, type StaleHook } from "./scan-core.js";
37
37
  import { type InstructionWeight } from "./core/instruction-weight.js";
38
+ import { type AlwaysLoadedContext } from "./core/always-loaded.js";
38
39
  import type { FilteredScan } from "./core/apply-rules.js";
39
40
  export * from "./scan-core.js";
40
41
  export interface ScanSkill {
@@ -319,6 +320,16 @@ export interface ScanReport {
319
320
  * on day one is switched off on day one.
320
321
  */
321
322
  readonly instructionWeight: InstructionWeight | null;
323
+ /**
324
+ * The ALWAYS-LOADED CONTEXT around that weight — the instructions plus the output
325
+ * style the committed settings select and the skill listing, each in the
326
+ * same unit (`core/always-loaded.ts`). Present exactly when
327
+ * `instructionWeight` is: both engines build the pair as one
328
+ * {@link AlwaysLoaded}. Kept as two fields here because the report is
329
+ * filtered through `Omit`-based views, which do not distribute over a
330
+ * union; the gate reads the pair through `MeasuredBundle`, which is one.
331
+ */
332
+ readonly alwaysLoaded?: AlwaysLoadedContext;
322
333
  /**
323
334
  * Instruction specs still using the deprecated `keyFiles` — the
324
335
  * `deprecated-key-files` rule's own detector (`findDeprecatedKeyFiles`),
@@ -424,12 +435,30 @@ export interface ScanHarness {
424
435
  * The always-loaded instruction weight of ONE directory under ONE harness —
425
436
  * the bounded read, the harness's chain, and the sum, in one place.
426
437
  *
427
- * `scanPlugin` reports it, `lint`'s instruction-weight ratchet gates on it and
438
+ * `scanPlugin` reports it, `lint`'s context-creep ratchet gates on it and
428
439
  * `compile` prints it, so all three must arrive at the same number by the same
429
440
  * route; this function is that route. `null` when the harness publishes no
430
441
  * budget (there is no unit to count in).
431
442
  */
432
443
  export declare function measureInstructionWeight(dir: string, harness: Pick<ScanHarness, "layout" | "dialect">): InstructionWeight | null;
444
+ /**
445
+ * The always-loaded weight of one directory and the always-loaded context around it —
446
+ * both or neither, as one union, so no reader can hold a weight without the
447
+ * parts that go with it (and read a recorded part as 0).
448
+ */
449
+ export type AlwaysLoaded = {
450
+ readonly instructionWeight: null;
451
+ readonly alwaysLoaded?: undefined;
452
+ } | {
453
+ readonly instructionWeight: InstructionWeight;
454
+ readonly alwaysLoaded: AlwaysLoadedContext;
455
+ };
456
+ /**
457
+ * The always-loaded context of ONE directory under ONE harness — the same route as
458
+ * {@link measureInstructionWeight}, plus the style and skill files. `lint`'s
459
+ * ratchet gates on it, `compile` prints it and `scanPlugin` reports it.
460
+ */
461
+ export declare function measureAlwaysLoaded(dir: string, harness: Pick<ScanHarness, "layout" | "dialect">): AlwaysLoaded;
433
462
  /** Scan a plugin/repo directory and report its surfaces + structural issues. */
434
463
  export declare function scanPlugin(dir: string, layout: PluginLayout, dialect: HarnessDialect, opts?: {
435
464
  sharedDirs?: readonly string[];