vigiles 39.2.0 → 40.1.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 (53) hide show
  1. package/README.md +9 -8
  2. package/dist/adapter.d.ts +3 -2
  3. package/dist/adapters/claude-code/dialect.js +4 -0
  4. package/dist/adapters/claude-code/output-style.js +15 -0
  5. package/dist/adapters/claude-code/skill-listing.d.ts +48 -0
  6. package/dist/adapters/claude-code/skill-listing.js +54 -0
  7. package/dist/adapters/codex/dialect.js +4 -0
  8. package/dist/adapters/codex/layout.js +5 -0
  9. package/dist/adapters/codex/mock-model.d.ts +7 -0
  10. package/dist/adapters/codex/mock-model.js +1 -0
  11. package/dist/adapters/codex/skill-listing.d.ts +42 -0
  12. package/dist/adapters/codex/skill-listing.js +40 -0
  13. package/dist/audit-html.js +7 -2
  14. package/dist/audit-report.d.ts +51 -0
  15. package/dist/audit-report.js +54 -8
  16. package/dist/audit-report.template.html +33 -38
  17. package/dist/cli-main.d.ts +9 -3
  18. package/dist/cli-main.js +32 -17
  19. package/dist/{instruction-weight-ratchet.d.ts → context-creep-ratchet.d.ts} +34 -12
  20. package/dist/context-creep-ratchet.js +270 -0
  21. package/dist/core/always-loaded.d.ts +128 -0
  22. package/dist/core/always-loaded.js +134 -0
  23. package/dist/core/compile.js +1 -1
  24. package/dist/core/dialect.d.ts +9 -0
  25. package/dist/core/harness-unit.d.ts +20 -0
  26. package/dist/core/harness-unit.js +24 -0
  27. package/dist/core/instruction-baseline.d.ts +179 -11
  28. package/dist/core/instruction-baseline.js +349 -47
  29. package/dist/core/instruction-weight.d.ts +2 -11
  30. package/dist/core/instruction-weight.js +6 -16
  31. package/dist/core/layout.d.ts +40 -0
  32. package/dist/core/layout.js +25 -1
  33. package/dist/core/output-style.d.ts +20 -0
  34. package/dist/core/skill-listing.d.ts +49 -0
  35. package/dist/core/skill-listing.js +23 -0
  36. package/dist/core/types.d.ts +2 -2
  37. package/dist/deprecated-key-files.d.ts +1 -1
  38. package/dist/deprecated-key-files.js +1 -1
  39. package/dist/fs-walk.d.ts +31 -0
  40. package/dist/fs-walk.js +49 -0
  41. package/dist/local-files.js +2 -1
  42. package/dist/plugin-loader.js +40 -19
  43. package/dist/rules/index.d.ts +4 -4
  44. package/dist/rules/index.js +7 -7
  45. package/dist/scan-files.js +24 -3
  46. package/dist/scan.d.ts +30 -1
  47. package/dist/scan.js +69 -3
  48. package/dist/surface-discovery-fs.d.ts +15 -0
  49. package/dist/surface-discovery-fs.js +55 -0
  50. package/dist/vigilesrc.schema.json +2 -2
  51. package/hooks/session-start.sh +3 -1
  52. package/package.json +1 -1
  53. package/dist/instruction-weight-ratchet.js +0 -181
@@ -1,18 +1,24 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.INSTRUCTION_WEIGHT_MEASURE = exports.INSTRUCTION_BASELINE_VERSION = exports.UPDATE_BASELINE_COMMAND = exports.INSTRUCTION_BASELINE_FILE = void 0;
3
+ exports.INSTRUCTION_WEIGHT_MEASURE = exports.LOADED_PART_NAMES = exports.LOADED_PART_MEASURE = exports.INSTRUCTION_BASELINE_VERSION = exports.UPDATE_BASELINE_COMMAND = exports.REMOVE_LEGACY_BASELINE_COMMAND = exports.RENAME_BASELINE_COMMAND = exports.LEGACY_INSTRUCTION_BASELINE_FILE = exports.INSTRUCTION_BASELINE_FILE = void 0;
4
+ exports.legacyBaselineNote = legacyBaselineNote;
4
5
  exports.parseInstructionBaseline = parseInstructionBaseline;
5
6
  exports.entryFor = entryFor;
6
7
  exports.compareToBaseline = compareToBaseline;
8
+ exports.carryUnmeasured = carryUnmeasured;
9
+ exports.compareAlwaysLoadedToBaseline = compareAlwaysLoadedToBaseline;
7
10
  exports.checkCeiling = checkCeiling;
8
11
  exports.recordEntries = recordEntries;
9
12
  exports.serializeBaseline = serializeBaseline;
10
13
  exports.formatVerdict = formatVerdict;
14
+ exports.formatBaselineVerdict = formatBaselineVerdict;
15
+ exports.describeUnmeasured = describeUnmeasured;
16
+ exports.formatUnrecordedParts = formatUnrecordedParts;
11
17
  exports.formatCeiling = formatCeiling;
12
18
  exports.formatRefusal = formatRefusal;
13
19
  exports.formatWeightLine = formatWeightLine;
14
20
  /**
15
- * The instruction-weight RATCHET: the always-loaded weight may not grow past
21
+ * The context-creep RATCHET: the always-loaded weight may not grow past
16
22
  * what the repository itself last recorded.
17
23
  *
18
24
  * WHY A RATCHET AND NOT THE BUDGET. `./instruction-weight.ts` explains why the
@@ -45,17 +51,85 @@ exports.formatWeightLine = formatWeightLine;
45
51
  * baseline is allowed and is the point: growth is not forbidden, it is made
46
52
  * visible as a reviewed diff of a committed file.
47
53
  *
54
+ * VERSION 2 — THE ALWAYS-LOADED CONTEXT. The output style the committed settings select
55
+ * and the skill listing load at session start exactly as the instructions do
56
+ * (`./always-loaded.ts`), so a section moved from `CLAUDE.md` into either is
57
+ * the same relocation the sum above exists to see. A version-2 entry carries
58
+ * them as `parts`, each with its own `measure`, and the verdict is decided on
59
+ * the SUM of the instructions and every recorded part. Per part, so a change
60
+ * to how one part is measured asks to re-record that part by name.
61
+ *
62
+ * ⚠️ THE TRADE-OFF OF A STRICT FILE, stated rather than hidden. Version 1 was
63
+ * read with `.strict()` and `z.literal(1)`, so there is no extension of it an
64
+ * OLDER vigiles accepts: it reads a version-2 file as "cannot be read", which
65
+ * is a finding at the rule's severity — red CI wherever lint still runs the old
66
+ * release, the moment one teammate re-records. Loud, never silent, but red. The
67
+ * alternative, a sibling file old readers ignore, would split one gated sum
68
+ * across two files, so that a move from one to the other read as a shrink in
69
+ * each. What keeps the cost small:
70
+ *
71
+ * - a repo still on version 1 is read as before — the instructions gate as
72
+ * they did, and each new part that is not zero is a NOTE, never a finding,
73
+ * so upgrading vigiles never turns CI red;
74
+ * - `--update-baseline` writes version 2 only when some part is not zero, so
75
+ * a repo with no output style and no listed skill keeps a version-1 file
76
+ * every release reads — and, once a file is version 2, keeps it there even
77
+ * when every part drops to zero, so re-adding a part is growth, not a note;
78
+ * - the note and the rule doc say to upgrade vigiles wherever lint runs
79
+ * BEFORE re-recording.
80
+ *
48
81
  * Pure: parsing, comparison and formatting only. Reading and writing the file
49
- * is the caller's (`src/instruction-weight-ratchet.ts`).
82
+ * is the caller's (`src/context-creep-ratchet.ts`).
50
83
  */
51
84
  const zod_1 = require("zod");
52
85
  const instruction_remedies_js_1 = require("./instruction-remedies.js");
53
86
  /** Where the baseline lives, relative to the directory `.vigilesrc.json` is read from. */
54
- exports.INSTRUCTION_BASELINE_FILE = ".vigiles/instruction-weight.json";
87
+ exports.INSTRUCTION_BASELINE_FILE = ".vigiles/context-creep.json";
88
+ /**
89
+ * The name this baseline had before the rule became `context-creep`. Still
90
+ * READ when the new file is absent (a repo upgrading keeps its ratchet), never
91
+ * written; {@link legacyBaselineNote} tells the author how to move it.
92
+ */
93
+ exports.LEGACY_INSTRUCTION_BASELINE_FILE = ".vigiles/instruction-weight.json";
94
+ /** The command that renames the old baseline — quoted verbatim by the note. */
95
+ exports.RENAME_BASELINE_COMMAND = `git mv ${exports.LEGACY_INSTRUCTION_BASELINE_FILE} ${exports.INSTRUCTION_BASELINE_FILE}`;
96
+ /** The command that drops a stale old baseline once the new one exists. */
97
+ exports.REMOVE_LEGACY_BASELINE_COMMAND = `git rm ${exports.LEGACY_INSTRUCTION_BASELINE_FILE}`;
98
+ /**
99
+ * The one-sentence NOTE (never a finding) for a repo that still has the old
100
+ * file, or `undefined` when it has not. The exact command is in the text: the
101
+ * session-start hook injects `lint --summary` into the agent, and the agent
102
+ * runs the command.
103
+ */
104
+ function legacyBaselineNote(legacy) {
105
+ switch (legacy) {
106
+ case "none":
107
+ return undefined;
108
+ case "only":
109
+ return `${exports.LEGACY_INSTRUCTION_BASELINE_FILE} is the old name of the context-creep baseline (still read) — rename it with \`${exports.RENAME_BASELINE_COMMAND}\``;
110
+ case "both":
111
+ return `${exports.LEGACY_INSTRUCTION_BASELINE_FILE} is stale: ${exports.INSTRUCTION_BASELINE_FILE} is read instead — delete it with \`${exports.REMOVE_LEGACY_BASELINE_COMMAND}\``;
112
+ }
113
+ }
55
114
  /** The command that writes the baseline — named once, quoted by every message. */
56
115
  exports.UPDATE_BASELINE_COMMAND = "vigiles lint --update-baseline";
57
- /** Bumped only on an incompatible change to the on-disk shape. */
58
- exports.INSTRUCTION_BASELINE_VERSION = 1;
116
+ /**
117
+ * The newest on-disk shape this release reads and writes. Bumped only on an
118
+ * incompatible change. Version 1 is still read, and still WRITTEN when no
119
+ * always-loaded part has anything in it — see the header for why.
120
+ */
121
+ exports.INSTRUCTION_BASELINE_VERSION = 2;
122
+ /**
123
+ * Which measurement produced a recorded PART — the same job as
124
+ * {@link INSTRUCTION_WEIGHT_MEASURE}, per part, so a change to how the skill
125
+ * listing is rendered re-records the listing and names it.
126
+ */
127
+ exports.LOADED_PART_MEASURE = 1;
128
+ /** The parts a version-2 entry may carry, in the order they are printed. */
129
+ exports.LOADED_PART_NAMES = [
130
+ "output-style",
131
+ "skill-listing",
132
+ ];
59
133
  /**
60
134
  * Which MEASUREMENT produced a recorded number — bumped whenever a release
61
135
  * changes what counts (chain membership in any adapter, how a file is sized),
@@ -68,24 +142,42 @@ exports.INSTRUCTION_BASELINE_VERSION = 1;
68
142
  * describes the file, not the number in it.
69
143
  */
70
144
  exports.INSTRUCTION_WEIGHT_MEASURE = 1;
145
+ const SUM_MESSAGE = "`total` is not the sum of `files` — the file was edited by hand; re-record it";
146
+ const sumsUp = (e) => Object.values(e.files).reduce((a, b) => a + b, 0) === e.total;
147
+ const partSchema = zod_1.z
148
+ .object({
149
+ measure: zod_1.z.number().int().nonnegative(),
150
+ total: zod_1.z.number().int().nonnegative(),
151
+ files: zod_1.z.record(zod_1.z.string(), zod_1.z.number().int().nonnegative()),
152
+ })
153
+ .strict()
154
+ .refine(sumsUp, { message: SUM_MESSAGE });
71
155
  const entrySchema = zod_1.z
72
156
  .object({
73
157
  unit: zod_1.z.enum(["chars", "bytes"]),
74
158
  measure: zod_1.z.number().int().nonnegative(),
75
159
  total: zod_1.z.number().int().nonnegative(),
76
160
  files: zod_1.z.record(zod_1.z.string(), zod_1.z.number().int().nonnegative()),
161
+ /** Version 2 only: the always-loaded parts beside the instructions. */
162
+ parts: zod_1.z
163
+ .object({
164
+ "output-style": partSchema.optional(),
165
+ "skill-listing": partSchema.optional(),
166
+ })
167
+ .strict()
168
+ .optional(),
77
169
  })
78
170
  .strict()
79
- .refine((e) => Object.values(e.files).reduce((a, b) => a + b, 0) === e.total, {
80
- message: "`total` is not the sum of `files` — the file was edited by hand; re-record it",
81
- });
171
+ .refine(sumsUp, { message: SUM_MESSAGE });
82
172
  const baselineSchema = zod_1.z
83
173
  .object({
84
- version: zod_1.z.literal(exports.INSTRUCTION_BASELINE_VERSION),
174
+ version: zod_1.z.union([zod_1.z.literal(1), zod_1.z.literal(exports.INSTRUCTION_BASELINE_VERSION)]),
85
175
  /** Keyed by bundle location from the config root; `.` is the root itself. */
86
176
  bundles: zod_1.z.record(zod_1.z.string(), entrySchema),
87
177
  })
88
- .strict();
178
+ .strict()
179
+ .refine((b) => b.version !== 1 ||
180
+ Object.values(b.bundles).every((e) => e.parts === undefined), { message: "`parts` needs `version: 2` — re-record the file" });
89
181
  function parseInstructionBaseline(text) {
90
182
  const json = (() => {
91
183
  try {
@@ -107,16 +199,43 @@ function parseInstructionBaseline(text) {
107
199
  .join("; "),
108
200
  };
109
201
  }
110
- /** What a measured weight would be recorded as: the SCORED files only. */
111
- function entryFor(weight) {
202
+ const sortedFiles = (files) => Object.fromEntries([...files]
203
+ .sort((a, b) => a.path.localeCompare(b.path))
204
+ .map((f) => [f.path, f.size]));
205
+ /** A part as it would be recorded, or nothing when it adds nothing. */
206
+ function partEntry(part) {
207
+ return part.kind === "counted" && part.total > 0
208
+ ? {
209
+ measure: exports.LOADED_PART_MEASURE,
210
+ total: part.total,
211
+ files: sortedFiles(part.files),
212
+ }
213
+ : undefined;
214
+ }
215
+ /** The parts of an always-loaded that would be recorded, by name. */
216
+ function partEntries(loaded) {
217
+ if (loaded === undefined)
218
+ return undefined;
219
+ const byName = {
220
+ "output-style": partEntry(loaded.outputStyle),
221
+ "skill-listing": partEntry(loaded.skillListing),
222
+ };
223
+ const kept = Object.entries(byName).filter(([, p]) => p !== undefined);
224
+ return kept.length === 0 ? undefined : Object.fromEntries(kept);
225
+ }
226
+ /**
227
+ * What a measured weight would be recorded as: the SCORED files only, plus
228
+ * every always-loaded part that is not zero when one is handed in.
229
+ */
230
+ function entryFor(weight, loaded) {
112
231
  const scored = weight.files.filter((f) => f.scope === "repo");
232
+ const parts = partEntries(loaded);
113
233
  return {
114
234
  unit: weight.unit,
115
235
  measure: exports.INSTRUCTION_WEIGHT_MEASURE,
116
236
  total: weight.committedTotal,
117
- files: Object.fromEntries([...scored]
118
- .sort((a, b) => a.path.localeCompare(b.path))
119
- .map((f) => [f.path, f.size])),
237
+ files: sortedFiles(scored),
238
+ ...(parts === undefined ? {} : { parts }),
120
239
  };
121
240
  }
122
241
  function changesBetween(before, after) {
@@ -129,7 +248,19 @@ function changesBetween(before, after) {
129
248
  Math.abs((a.to ?? 0) - (a.from ?? 0)) || a.path.localeCompare(b.path));
130
249
  }
131
250
  function compareToBaseline(weight, recorded) {
132
- const current = entryFor(weight);
251
+ return compareEntries(entryFor(weight), recorded);
252
+ }
253
+ /** A recorded number some other measurement produced — of a part, when named. */
254
+ function measureChanged(recorded, current, part) {
255
+ return {
256
+ kind: "measure-changed",
257
+ recorded,
258
+ current,
259
+ ...(part === undefined ? {} : { part }),
260
+ };
261
+ }
262
+ /** The verdict between two entries, decided on `total`. */
263
+ function compareEntries(current, recorded) {
133
264
  if (recorded === undefined)
134
265
  return { kind: "unrecorded", current };
135
266
  if (recorded.unit !== current.unit) {
@@ -140,11 +271,7 @@ function compareToBaseline(weight, recorded) {
140
271
  };
141
272
  }
142
273
  if (recorded.measure !== current.measure) {
143
- return {
144
- kind: "measure-changed",
145
- recorded: recorded.measure,
146
- current: current.measure,
147
- };
274
+ return measureChanged(recorded.measure, current.measure);
148
275
  }
149
276
  if (current.total === recorded.total) {
150
277
  return { kind: "held", total: current.total, unit: current.unit };
@@ -157,6 +284,122 @@ function compareToBaseline(weight, recorded) {
157
284
  changes: changesBetween(recorded.files, current.files),
158
285
  };
159
286
  }
287
+ const PART_LABEL = {
288
+ "output-style": "output style",
289
+ "skill-listing": "skill listing",
290
+ };
291
+ /**
292
+ * One entry with its parts folded in: the total is the always-loaded sum, and each
293
+ * part's files are named with the part, so a `grew` message says which part a
294
+ * file moved in. In memory only — never written.
295
+ */
296
+ function folded(entry) {
297
+ const parts = exports.LOADED_PART_NAMES.flatMap((name) => {
298
+ const part = entry.parts?.[name];
299
+ return part === undefined ? [] : [{ name, part }];
300
+ });
301
+ return {
302
+ unit: entry.unit,
303
+ measure: entry.measure,
304
+ total: parts.reduce((sum, p) => sum + p.part.total, entry.total),
305
+ files: Object.fromEntries([
306
+ ...Object.entries(entry.files),
307
+ ...parts.flatMap(({ name, part }) => Object.entries(part.files).map(([path, size]) => [
308
+ `${path} (${PART_LABEL[name]})`,
309
+ size,
310
+ ])),
311
+ ]),
312
+ };
313
+ }
314
+ /** Each part's size on both sides; a part recorded on neither side is left out. */
315
+ function movesBetween(current, recorded) {
316
+ const parts = exports.LOADED_PART_NAMES.flatMap((part) => {
317
+ const from = recorded.parts?.[part]?.total;
318
+ const to = current.parts?.[part]?.total;
319
+ return from === undefined && to === undefined
320
+ ? []
321
+ : [{ part, from: from ?? 0, to: to ?? 0 }];
322
+ });
323
+ return [
324
+ { part: "instructions", from: recorded.total, to: current.total },
325
+ ...parts,
326
+ ];
327
+ }
328
+ /** The first part whose recorded measurement is not this release's. */
329
+ function partMeasureChanged(current, recorded) {
330
+ const changed = exports.LOADED_PART_NAMES.find((name) => {
331
+ const was = recorded.parts?.[name]?.measure;
332
+ const now = current.parts?.[name]?.measure;
333
+ return was !== undefined && now !== undefined && was !== now;
334
+ });
335
+ if (changed === undefined)
336
+ return undefined;
337
+ return measureChanged(recorded.parts?.[changed]?.measure ?? 0, exports.LOADED_PART_MEASURE, changed);
338
+ }
339
+ const partOf = (loaded, name) => name === "output-style" ? loaded.outputStyle : loaded.skillListing;
340
+ /**
341
+ * `current` with every recorded part this run cannot measure carried over from
342
+ * `recorded`, and the list of those parts. `counted` and `none` are measured —
343
+ * `none` is a real zero — so they are never carried.
344
+ */
345
+ function carryUnmeasured(current, loaded, recorded) {
346
+ const carried = exports.LOADED_PART_NAMES.flatMap((name) => {
347
+ const was = recorded?.parts?.[name];
348
+ const now = partOf(loaded, name);
349
+ return was === undefined || now.kind === "counted" || now.kind === "none"
350
+ ? []
351
+ : [{ name, was, kind: now.kind }];
352
+ });
353
+ if (carried.length === 0)
354
+ return { entry: current, unmeasured: [] };
355
+ const parts = Object.fromEntries([
356
+ ...Object.entries(current.parts ?? {}),
357
+ ...carried.map(({ name, was }) => [name, was]),
358
+ ]);
359
+ return {
360
+ entry: { ...current, parts },
361
+ unmeasured: carried.map(({ name, was, kind }) => ({
362
+ part: name,
363
+ kind,
364
+ recorded: was.total,
365
+ })),
366
+ };
367
+ }
368
+ function compareAlwaysLoadedToBaseline(weight, loaded, recorded, file) {
369
+ const measuredNow = entryFor(weight, loaded);
370
+ const sumGated = file === exports.INSTRUCTION_BASELINE_VERSION ||
371
+ (file === "absent" && measuredNow.parts !== undefined);
372
+ if (!sumGated) {
373
+ return {
374
+ kind: "instructions-only",
375
+ verdict: compareToBaseline(weight, recorded),
376
+ unrecordedParts: exports.LOADED_PART_NAMES.flatMap((part) => {
377
+ const total = measuredNow.parts?.[part]?.total;
378
+ return total === undefined ? [] : [{ part, total }];
379
+ }),
380
+ };
381
+ }
382
+ return compareSum(measuredNow, loaded, recorded);
383
+ }
384
+ /** The `always-loaded` verdict: the sum, with unmeasurable recorded parts carried. */
385
+ function compareSum(measuredNow, loaded, recorded) {
386
+ if (recorded === undefined) {
387
+ return {
388
+ kind: "always-loaded",
389
+ verdict: { kind: "unrecorded", current: folded(measuredNow) },
390
+ byPart: [],
391
+ unmeasured: [],
392
+ };
393
+ }
394
+ const { entry: current, unmeasured } = carryUnmeasured(measuredNow, loaded, recorded);
395
+ return {
396
+ kind: "always-loaded",
397
+ verdict: partMeasureChanged(current, recorded) ??
398
+ compareEntries(folded(current), folded(recorded)),
399
+ byPart: movesBetween(current, recorded),
400
+ unmeasured,
401
+ };
402
+ }
160
403
  /** How many of the heaviest files a ceiling message names. */
161
404
  const CEILING_NAMED_FILES = 5;
162
405
  /** `undefined` when the weight is at or under `max`, or when no ceiling is set. */
@@ -181,9 +424,18 @@ function recordEntries(previous, measured) {
181
424
  const removed = new Set(measured.filter(([, e]) => e === null).map(([at]) => at));
182
425
  const kept = Object.entries(previous?.bundles ?? {}).filter(([at]) => !removed.has(at));
183
426
  const fresh = measured.flatMap(([at, e]) => e === null ? [] : [[at, e]]);
427
+ const bundles = Object.fromEntries([...new Map([...kept, ...fresh]).entries()].sort(([a], [b]) => a.localeCompare(b)));
428
+ // Version 2 when some entry carries a part — see the header: a repo with
429
+ // nothing to add keeps a file every release can read — OR when the file was
430
+ // already version 2. A version is a one-way door: writing version 1 after a
431
+ // repo dropped its last skill or its style would turn a re-added part from
432
+ // growth of the gated sum into a note, so a legitimate cut, recorded,
433
+ // would silently switch off the gate the repo opted into.
434
+ const withParts = Object.values(bundles).some((e) => e.parts !== undefined);
435
+ const wasSumGated = previous?.version === exports.INSTRUCTION_BASELINE_VERSION;
184
436
  return {
185
- version: exports.INSTRUCTION_BASELINE_VERSION,
186
- bundles: Object.fromEntries([...new Map([...kept, ...fresh]).entries()].sort(([a], [b]) => a.localeCompare(b))),
437
+ version: withParts || wasSumGated ? exports.INSTRUCTION_BASELINE_VERSION : 1,
438
+ bundles,
187
439
  };
188
440
  }
189
441
  /** Stable text: sorted keys, two-space indent, trailing newline, no timestamp. */
@@ -199,35 +451,85 @@ function describeChange(c) {
199
451
  return `${c.path} -${n(c.from)} (gone)`;
200
452
  return `${c.path} ${signed(c.to - c.from)}`;
201
453
  }
454
+ /** A re-record request: what counts changed in vigiles, not in the files. */
455
+ function measureChangedText(verdict, where) {
456
+ const whose = verdict.part === undefined ? "" : `'s ${PART_LABEL[verdict.part]}`;
457
+ return (`${where}the context-creep baseline${whose} was recorded by measurement ${String(verdict.recorded)}, this vigiles uses ${String(verdict.current)} — ` +
458
+ `what counts changed in vigiles, not in your files. Re-record it with \`${exports.UPDATE_BASELINE_COMMAND}\``);
459
+ }
202
460
  /** The one-paragraph message a verdict prints as, prefixed by its bundle. */
203
- function formatVerdict(verdict, at) {
461
+ function formatVerdict(verdict, at, subject = "always-loaded instructions") {
204
462
  const where = at === "." ? "" : `${at}: `;
205
463
  switch (verdict.kind) {
206
464
  case "unrecorded":
207
- return (`${where}no instruction-weight baseline recorded (${n(verdict.current.total)} ${verdict.current.unit} always loaded) — ` +
465
+ return (`${where}no context-creep baseline recorded (${n(verdict.current.total)} ${verdict.current.unit} always loaded) — ` +
208
466
  `run \`${exports.UPDATE_BASELINE_COMMAND}\` and commit ${exports.INSTRUCTION_BASELINE_FILE} to stop it growing unnoticed`);
209
467
  case "unit-changed":
210
- return (`${where}the instruction-weight baseline is in ${verdict.recorded} but this harness counts ${verdict.current} — ` +
468
+ return (`${where}the context-creep baseline is in ${verdict.recorded} but this harness counts ${verdict.current} — ` +
211
469
  `re-record it with \`${exports.UPDATE_BASELINE_COMMAND}\``);
212
470
  case "measure-changed":
213
- return (`${where}the instruction-weight baseline was recorded by measurement ${String(verdict.recorded)}, this vigiles uses ${String(verdict.current)} — ` +
214
- `what counts changed in vigiles, not in your files. Re-record it with \`${exports.UPDATE_BASELINE_COMMAND}\``);
471
+ return measureChangedText(verdict, where);
215
472
  case "held":
216
- return `${where}always-loaded instructions held at ${n(verdict.total)} ${verdict.unit} (baseline)`;
473
+ return `${where}${subject} held at ${n(verdict.total)} ${verdict.unit} (baseline)`;
217
474
  case "grew":
218
- case "shrank": {
219
- const head = `${n(verdict.from)} → ${n(verdict.to)} ${verdict.unit} (${signed(verdict.to - verdict.from)})`;
220
- const moved = verdict.changes.length > 0
221
- ? ` Changed: ${verdict.changes.map(describeChange).join(", ")}.`
222
- : "";
223
- return verdict.kind === "grew"
224
- ? `${where}always-loaded instructions grew ${head} over the recorded baseline.${moved} ` +
225
- `If the growth is intended, record it with \`${exports.UPDATE_BASELINE_COMMAND}\` — the diff of ${exports.INSTRUCTION_BASELINE_FILE} is the review. If it is not:\n${instruction_remedies_js_1.MOVE_OUT_OF_ALWAYS_LOADED}`
226
- : `${where}always-loaded instructions shrank ${head}; the baseline still allows the old weight.${moved} ` +
227
- `Lock the cut in with \`${exports.UPDATE_BASELINE_COMMAND}\`, or the headroom can be regrown without a finding.`;
228
- }
475
+ case "shrank":
476
+ return movedText(verdict, `${where}${subject}`);
229
477
  }
230
478
  }
479
+ /** A grew/shrank message: the delta, every file that moved, and what to do. */
480
+ function movedText(verdict, who) {
481
+ const head = `${n(verdict.from)} → ${n(verdict.to)} ${verdict.unit} (${signed(verdict.to - verdict.from)})`;
482
+ const moved = verdict.changes.length > 0
483
+ ? ` Changed: ${verdict.changes.map(describeChange).join(", ")}.`
484
+ : "";
485
+ return verdict.kind === "grew"
486
+ ? `${who} grew ${head} over the recorded baseline.${moved} ` +
487
+ `If the growth is intended, record it with \`${exports.UPDATE_BASELINE_COMMAND}\` — the diff of ${exports.INSTRUCTION_BASELINE_FILE} is the review. If it is not:\n${instruction_remedies_js_1.MOVE_OUT_OF_ALWAYS_LOADED}`
488
+ : `${who} shrank ${head}; the baseline still allows the old weight.${moved} ` +
489
+ `Lock the cut in with \`${exports.UPDATE_BASELINE_COMMAND}\`, or the headroom can be regrown without a finding.`;
490
+ }
491
+ /** "instructions 24,665 · output style 8,616 (+200) · skill listing 31,210". */
492
+ function describeMoves(moves) {
493
+ return moves
494
+ .map((m) => {
495
+ const label = m.part === "instructions" ? "instructions" : PART_LABEL[m.part];
496
+ const delta = m.to === m.from ? "" : ` (${signed(m.to - m.from)})`;
497
+ return `${label} ${n(m.to)}${delta}`;
498
+ })
499
+ .join(" · ");
500
+ }
501
+ /** The message for one bundle's {@link BaselineVerdict}, prefixed by its bundle. */
502
+ function formatBaselineVerdict(verdict, at) {
503
+ if (verdict.kind === "instructions-only") {
504
+ return formatVerdict(verdict.verdict, at);
505
+ }
506
+ const text = formatVerdict(verdict.verdict, at, "always-loaded context");
507
+ const lines = [
508
+ text,
509
+ ...(verdict.byPart.length === 0 ? [] : [describeMoves(verdict.byPart)]),
510
+ ...verdict.unmeasured.map(describeUnmeasured),
511
+ ];
512
+ return lines.join("\n ");
513
+ }
514
+ /** Why a recorded part was carried: the run could not measure it, not a cut. */
515
+ function describeUnmeasured(u) {
516
+ return (`${PART_LABEL[u.part]}: recorded ${n(u.recorded)}, not measured in this run (${u.kind}) — ` +
517
+ `carried at its recorded size, not compared and not dropped by \`${exports.UPDATE_BASELINE_COMMAND}\``);
518
+ }
519
+ /**
520
+ * The NOTE a version-1 file gets for each part that is not zero: always
521
+ * loaded, not yet in the baseline, and what recording it does — including the
522
+ * one cost of recording, an older vigiles reading the new file as unreadable.
523
+ */
524
+ function formatUnrecordedParts(parts, unit, at) {
525
+ const where = at === "." ? "" : `${at}: `;
526
+ const what = parts
527
+ .map((p) => `${PART_LABEL[p.part]} (${n(p.total)} ${unit})`)
528
+ .join(" and ");
529
+ return (`${where}${what} load at session start but are not in the baseline — ` +
530
+ `\`${exports.UPDATE_BASELINE_COMMAND}\` adds them (the file becomes version 2) and the gate becomes their sum with the instructions. ` +
531
+ `Upgrade vigiles wherever lint runs first: an older release cannot read version 2 and reports the file as unreadable.`);
532
+ }
231
533
  /** The message for a total over the ceiling, prefixed by its bundle. */
232
534
  function formatCeiling(verdict, at) {
233
535
  const where = at === "." ? "" : `${at}: `;
@@ -250,19 +552,19 @@ function formatRefusal(verdict, at) {
250
552
  `get under it first, then run \`${exports.UPDATE_BASELINE_COMMAND}\` again.\n${instruction_remedies_js_1.MOVE_OUT_OF_ALWAYS_LOADED}`);
251
553
  }
252
554
  /** The compile-time one-liner: weight now, against the baseline when there is one. */
253
- function formatWeightLine(verdict) {
555
+ function formatWeightLine(verdict, label = "always-loaded") {
254
556
  switch (verdict.kind) {
255
557
  case "unrecorded":
256
- return `always-loaded: ${n(verdict.current.total)} ${verdict.current.unit} (no baseline — \`${exports.UPDATE_BASELINE_COMMAND}\`)`;
558
+ return `${label}: ${n(verdict.current.total)} ${verdict.current.unit} (no baseline — \`${exports.UPDATE_BASELINE_COMMAND}\`)`;
257
559
  case "unit-changed":
258
- return `always-loaded: baseline is in ${verdict.recorded}, this harness counts ${verdict.current}`;
560
+ return `${label}: baseline is in ${verdict.recorded}, this harness counts ${verdict.current}`;
259
561
  case "measure-changed":
260
- return `always-loaded: baseline recorded by measurement ${String(verdict.recorded)}, this vigiles uses ${String(verdict.current)} — re-record`;
562
+ return `${label}: baseline recorded by measurement ${String(verdict.recorded)}, this vigiles uses ${String(verdict.current)} — re-record`;
261
563
  case "held":
262
- return `always-loaded: ${n(verdict.total)} ${verdict.unit} (baseline ${n(verdict.total)}, ±0)`;
564
+ return `${label}: ${n(verdict.total)} ${verdict.unit} (baseline ${n(verdict.total)}, ±0)`;
263
565
  case "grew":
264
566
  case "shrank":
265
- return `always-loaded: ${n(verdict.to)} ${verdict.unit} (baseline ${n(verdict.from)}, ${signed(verdict.to - verdict.from)})`;
567
+ return `${label}: ${n(verdict.to)} ${verdict.unit} (baseline ${n(verdict.from)}, ${signed(verdict.to - verdict.from)})`;
266
568
  }
267
569
  }
268
570
  //# sourceMappingURL=instruction-baseline.js.map
@@ -153,17 +153,8 @@ export interface InstructionWeight {
153
153
  readonly to: readonly string[];
154
154
  }[];
155
155
  }
156
- /**
157
- * Size in the harness's own unit. Bytes and chars differ on any non-ASCII text.
158
- *
159
- * Line endings are counted as `\n`. A checkout with `core.autocrlf` holds the
160
- * same commit with one more character per line, and a number that differs
161
- * between two clones of one commit cannot be committed and compared — a
162
- * 1 000-line file read +1 000 on Windows with no content change. The harness
163
- * may count the CR itself; reproducibility is worth more here than that
164
- * fidelity.
165
- */
166
- export declare function sizeIn(text: string, unit: "chars" | "bytes"): number;
156
+ /** Re-exported from its neutral home, where every always-loaded part is sized. */
157
+ export { sizeIn } from "./harness-unit.js";
167
158
  /**
168
159
  * Weigh a harness's LOADED chain against its own budget.
169
160
  *
@@ -38,22 +38,12 @@
38
38
  * on day one at any size, red the day it grows.
39
39
  */
40
40
  Object.defineProperty(exports, "__esModule", { value: true });
41
- exports.sizeIn = sizeIn;
41
+ exports.sizeIn = void 0;
42
42
  exports.weighInstructions = weighInstructions;
43
- /**
44
- * Size in the harness's own unit. Bytes and chars differ on any non-ASCII text.
45
- *
46
- * Line endings are counted as `\n`. A checkout with `core.autocrlf` holds the
47
- * same commit with one more character per line, and a number that differs
48
- * between two clones of one commit cannot be committed and compared — a
49
- * 1 000-line file read +1 000 on Windows with no content change. The harness
50
- * may count the CR itself; reproducibility is worth more here than that
51
- * fidelity.
52
- */
53
- function sizeIn(text, unit) {
54
- const lf = text.replaceAll("\r\n", "\n");
55
- return unit === "chars" ? lf.length : Buffer.byteLength(lf, "utf8");
56
- }
43
+ const harness_unit_js_1 = require("./harness-unit.js");
44
+ /** Re-exported from its neutral home, where every always-loaded part is sized. */
45
+ var harness_unit_js_2 = require("./harness-unit.js");
46
+ Object.defineProperty(exports, "sizeIn", { enumerable: true, get: function () { return harness_unit_js_2.sizeIn; } });
57
47
  /**
58
48
  * Weigh a harness's LOADED chain against its own budget.
59
49
  *
@@ -89,7 +79,7 @@ function weighInstructions(chain, files, budget) {
89
79
  : [
90
80
  {
91
81
  path: entry.path,
92
- size: sizeIn(text, budget.unit),
82
+ size: (0, harness_unit_js_1.sizeIn)(text, budget.unit),
93
83
  role: entry.role,
94
84
  scope: entry.scope,
95
85
  ...(entry.via === undefined ? {} : { via: entry.via }),
@@ -134,6 +134,11 @@ export interface PluginLayout {
134
134
  * style is read into the session, not invoked. See `output-style.ts`.
135
135
  */
136
136
  readonly outputStyles?: OutputStyleRules;
137
+ /**
138
+ * How deep a session finds a `SKILL.md` under {@link skillsHome} (absent =
139
+ * {@link ONE_FOLDER_PER_SKILL}). See {@link SkillDiscovery}.
140
+ */
141
+ readonly skillDiscovery?: SkillDiscovery;
137
142
  /**
138
143
  * The WORD a per-machine settings sibling inserts before the extension, e.g.
139
144
  * `local` → `.claude/settings.local.json` (absent = this harness has no
@@ -251,6 +256,41 @@ export declare function materializePrefix(layout: PluginLayout): string;
251
256
  * fields that already say so keeps a third spelling from appearing.
252
257
  */
253
258
  export declare function skillsHome(layout: Pick<PluginLayout, "surfaces" | "userSurfaceRoot">): string | null;
259
+ /**
260
+ * Where under the session's skills folder a harness finds a `SKILL.md`: the
261
+ * number of directories between the folder and the file, and whether a
262
+ * directory whose name starts with `.` is entered.
263
+ *
264
+ * WHY A LAYOUT FACT AND NOT A CORE CONSTANT. The always-loaded skill listing
265
+ * read exactly `<skillsHome>/<dir>/SKILL.md`, which is Claude Code's shape and
266
+ * not Codex's: Codex walks a repository skill root recursively (`max_depth` 6
267
+ * in `codex-rs/ext/skills/src/loader/discovery.rs`, hidden directories
268
+ * pruned), so a skill grouped under `.agents/skills/<group>/<name>/` loaded in
269
+ * every session and was left out of the gated sum. Measured on codex-cli
270
+ * 0.153.0: a `SKILL.md` directly in the folder, and one six directories down,
271
+ * are both listed; seven down, or under a `.`-directory, are not.
272
+ *
273
+ * The two readers — the pure filter in `core/always-loaded.ts` and the disk
274
+ * walk in `surface-discovery-fs.ts` — both ask {@link sessionSkillDirs}, so
275
+ * they cannot disagree about which files exist.
276
+ */
277
+ export interface SkillDiscovery {
278
+ /** Fewest directories between the skills folder and a `SKILL.md`. */
279
+ readonly minDepth: number;
280
+ /** Most directories between the skills folder and a `SKILL.md`. */
281
+ readonly maxDepth: number;
282
+ /** Whether a directory whose name starts with `.` is skipped. */
283
+ readonly skipHidden: boolean;
284
+ }
285
+ /** One directory per skill, `<skillsHome>/<name>/SKILL.md` — Claude Code's shape. */
286
+ export declare const ONE_FOLDER_PER_SKILL: SkillDiscovery;
287
+ /** The layout's skill discovery, defaulted. */
288
+ export declare const skillDiscoveryOf: (layout: Pick<PluginLayout, "skillDiscovery">) => SkillDiscovery;
289
+ /**
290
+ * The directories between the skills folder and a `SKILL.md`, for a path
291
+ * RELATIVE to that folder — or `null` when the harness would not read it.
292
+ */
293
+ export declare function sessionSkillDirs(rel: string, discovery: SkillDiscovery): readonly string[] | null;
254
294
  /**
255
295
  * How DEEP a harness reads its {@link PluginLayout.agentDir} — the one statement
256
296
  * of that rule, as a RegExp source fragment matching the part of a path AFTER