vigiles 39.2.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 (52) hide show
  1. package/dist/adapter.d.ts +3 -2
  2. package/dist/adapters/claude-code/dialect.js +4 -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-main.d.ts +9 -3
  17. package/dist/cli-main.js +32 -17
  18. package/dist/{instruction-weight-ratchet.d.ts → context-creep-ratchet.d.ts} +34 -12
  19. package/dist/context-creep-ratchet.js +270 -0
  20. package/dist/core/always-loaded.d.ts +128 -0
  21. package/dist/core/always-loaded.js +134 -0
  22. package/dist/core/compile.js +1 -1
  23. package/dist/core/dialect.d.ts +9 -0
  24. package/dist/core/harness-unit.d.ts +20 -0
  25. package/dist/core/harness-unit.js +24 -0
  26. package/dist/core/instruction-baseline.d.ts +179 -11
  27. package/dist/core/instruction-baseline.js +349 -47
  28. package/dist/core/instruction-weight.d.ts +2 -11
  29. package/dist/core/instruction-weight.js +6 -16
  30. package/dist/core/layout.d.ts +40 -0
  31. package/dist/core/layout.js +25 -1
  32. package/dist/core/output-style.d.ts +20 -0
  33. package/dist/core/skill-listing.d.ts +49 -0
  34. package/dist/core/skill-listing.js +23 -0
  35. package/dist/core/types.d.ts +2 -2
  36. package/dist/deprecated-key-files.d.ts +1 -1
  37. package/dist/deprecated-key-files.js +1 -1
  38. package/dist/fs-walk.d.ts +31 -0
  39. package/dist/fs-walk.js +49 -0
  40. package/dist/local-files.js +2 -1
  41. package/dist/plugin-loader.js +40 -19
  42. package/dist/rules/index.d.ts +4 -4
  43. package/dist/rules/index.js +7 -7
  44. package/dist/scan-files.js +24 -3
  45. package/dist/scan.d.ts +30 -1
  46. package/dist/scan.js +69 -3
  47. package/dist/surface-discovery-fs.d.ts +15 -0
  48. package/dist/surface-discovery-fs.js +55 -0
  49. package/dist/vigilesrc.schema.json +2 -2
  50. package/hooks/session-start.sh +3 -1
  51. package/package.json +1 -1
  52. package/dist/instruction-weight-ratchet.js +0 -181
@@ -84,8 +84,14 @@ interface LintReport {
84
84
  hookBlockErrors: number;
85
85
  hookMatcherIssues: number;
86
86
  hookMatcherErrors: number;
87
- instructionWeightIssues: number;
88
- instructionWeightErrors: number;
87
+ contextCreepIssues: number;
88
+ contextCreepErrors: number;
89
+ /**
90
+ * Notes the context-creep ratchet raises that never count: today the one
91
+ * naming the old baseline file and the command that moves it. `--summary`
92
+ * prints them, because the session-start hook injects that output.
93
+ */
94
+ contextCreepNotes: readonly string[];
89
95
  deprecatedKeyFilesIssues: number;
90
96
  deprecatedKeyFilesErrors: number;
91
97
  docRefErrors: number;
@@ -129,7 +135,7 @@ export declare function lintTotals(report: LintReport): {
129
135
  * suggest improvements.
130
136
  *
131
137
  * Flags:
132
- * --summary Print a single-line summary (for SessionStart hooks)
138
+ * --summary Print a single-line summary (for SessionStart hooks), plus one note line while the old baseline file exists
133
139
  * --json Print structured JSON report (for CI integration)
134
140
  */
135
141
  /**
package/dist/cli-main.js CHANGED
@@ -49,7 +49,7 @@ const setup_plan_js_1 = require("./setup-plan.js");
49
49
  const types_js_1 = require("./core/types.js");
50
50
  const test_coverage_js_1 = require("./test-coverage.js");
51
51
  const scan_js_1 = require("./scan.js");
52
- const instruction_weight_ratchet_js_1 = require("./instruction-weight-ratchet.js");
52
+ const context_creep_ratchet_js_1 = require("./context-creep-ratchet.js");
53
53
  const frame_js_1 = require("./core/frame.js");
54
54
  const surface_discovery_js_1 = require("./core/surface-discovery.js");
55
55
  const scan_trigger_suggest_js_1 = require("./scan-trigger-suggest.js");
@@ -538,7 +538,7 @@ function writeInstructionMirrors(primaryOutput, harnesses) {
538
538
  *
539
539
  * `estimateTokens` is `length / 4`, calibrated for ASCII English; it undercounts
540
540
  * Cyrillic and CJK substantially. It is labelled `est.` for that reason and must
541
- * never become the number a rule gates on — see the instruction-weight rule.
541
+ * never become the number a rule gates on — see the context-creep rule.
542
542
  */
543
543
  function formatArtifactSize(markdown) {
544
544
  const chars = markdown.length;
@@ -711,6 +711,17 @@ async function compile(specPaths, config, excludes, opts = {}) {
711
711
  function isGitHubActions() {
712
712
  return process.env.GITHUB_ACTIONS === "true";
713
713
  }
714
+ /**
715
+ * One bundle's always-loaded weight and always-loaded context, measured by the one
716
+ * route `scan` reports and `lint`'s ratchet gates — so `lint` and `compile`
717
+ * cannot arrive at a different number from the audit.
718
+ */
719
+ function measuredBundle(at, abs, harness) {
720
+ const m = (0, scan_js_1.measureAlwaysLoaded)(abs, harness);
721
+ return m.instructionWeight === null
722
+ ? [at, null]
723
+ : [at, m.instructionWeight, m.alwaysLoaded];
724
+ }
714
725
  /**
715
726
  * Emit a GitHub Actions annotation for the inline PR experience.
716
727
  * No-op outside GitHub Actions.
@@ -1080,7 +1091,7 @@ function lintExitCode(report) {
1080
1091
  report.delegationTrifectaErrors > 0 ||
1081
1092
  report.hookBlockErrors > 0 ||
1082
1093
  report.hookMatcherErrors > 0 ||
1083
- report.instructionWeightErrors > 0 ||
1094
+ report.contextCreepErrors > 0 ||
1084
1095
  report.deprecatedKeyFilesErrors > 0 ||
1085
1096
  report.symbolRefErrors > 0 ||
1086
1097
  report.mcpRefErrors > 0 ||
@@ -1327,7 +1338,7 @@ function verifyMarkdownModeRules(frame, files, silent, config) {
1327
1338
  * suggest improvements.
1328
1339
  *
1329
1340
  * Flags:
1330
- * --summary Print a single-line summary (for SessionStart hooks)
1341
+ * --summary Print a single-line summary (for SessionStart hooks), plus one note line while the old baseline file exists
1331
1342
  * --json Print structured JSON report (for CI integration)
1332
1343
  */
1333
1344
  /**
@@ -1859,19 +1870,16 @@ async function runLint(restArgs, flags, excludes, config) {
1859
1870
  // typo, an uncompilable or unreachable MCP pattern, one too narrow for real
1860
1871
  // server naming, or an undeclared MCP server).
1861
1872
  const hookMatcher = overBundles(checkHookMatcher, run, lintRoots);
1862
- // 7v. Instruction-weight ratchet — the always-loaded instruction weight may
1873
+ // 7v. Context-creep ratchet — the always-loaded instruction weight may
1863
1874
  // not move off the committed baseline. One file for the whole run (bundles
1864
1875
  // are keys inside it), so it runs ONCE over `lintRoots`, not per bundle.
1865
- const instructionWeight = (0, instruction_weight_ratchet_js_1.checkInstructionWeightRatchet)({
1876
+ const contextCreep = (0, context_creep_ratchet_js_1.checkContextCreepRatchet)({
1866
1877
  root: frame.root,
1867
- severity: (0, types_js_1.ruleSeverity)(config?.rules?.["instruction-weight"]),
1868
- max: (0, types_js_1.ruleOptions)(config?.rules?.["instruction-weight"])?.max,
1878
+ severity: (0, types_js_1.ruleSeverity)(config?.rules?.["context-creep"]),
1879
+ max: (0, types_js_1.ruleOptions)(config?.rules?.["context-creep"])?.max,
1869
1880
  update: flags.includes("--update-baseline"),
1870
1881
  silent,
1871
- measure: () => lintRoots.map((abs) => [
1872
- frame.bundle(abs).at,
1873
- (0, scan_js_1.measureInstructionWeight)(abs, adapter),
1874
- ]),
1882
+ measure: () => lintRoots.map((abs) => measuredBundle(frame.bundle(abs).at, abs, adapter)),
1875
1883
  annotate: (level, message) => {
1876
1884
  ghAnnotate(level, message);
1877
1885
  },
@@ -2033,8 +2041,9 @@ async function runLint(restArgs, flags, excludes, config) {
2033
2041
  hookBlockErrors: hookBlock.errors,
2034
2042
  hookMatcherIssues: hookMatcher.issues,
2035
2043
  hookMatcherErrors: hookMatcher.errors,
2036
- instructionWeightIssues: instructionWeight.issues,
2037
- instructionWeightErrors: instructionWeight.errors,
2044
+ contextCreepIssues: contextCreep.issues,
2045
+ contextCreepErrors: contextCreep.errors,
2046
+ contextCreepNotes: contextCreep.notes,
2038
2047
  deprecatedKeyFilesIssues: deprecatedKeyFiles.issues,
2039
2048
  deprecatedKeyFilesErrors: deprecatedKeyFiles.errors,
2040
2049
  // Only the "error" tier gates. At "warn" the findings are printed and
@@ -2117,6 +2126,11 @@ function printLintSummary(report) {
2117
2126
  else {
2118
2127
  console.log(`vigiles: ${parts.join(" / ")}`);
2119
2128
  }
2129
+ // One extra line per note, only when there is one: the old baseline file's
2130
+ // rename command reaches the agent through the session-start hook.
2131
+ report.contextCreepNotes.forEach((note) => {
2132
+ console.log(`vigiles: note — ${note}`);
2133
+ });
2120
2134
  }
2121
2135
  function collectDocumentedRules(excludes) {
2122
2136
  const documented = new Set();
@@ -7479,13 +7493,14 @@ async function main() {
7479
7493
  (await compile(specs, config, excludes, { harnessFlag })) && valid;
7480
7494
  // The always-loaded weight the author just produced, against the
7481
7495
  // committed baseline — shown at the moment of change. Report-only:
7482
- // `lint` is the gate (rule `instruction-weight`).
7496
+ // `lint` is the gate (rule `context-creep`).
7483
7497
  if (specs.length > 0) {
7484
- const weightLine = (0, instruction_weight_ratchet_js_1.compileWeightLine)(projectRoot, (0, scan_js_1.measureInstructionWeight)(projectRoot, (0, adapter_registry_js_1.resolveHarnessSelection)({
7498
+ const measured = measuredBundle(".", projectRoot, (0, adapter_registry_js_1.resolveHarnessSelection)({
7485
7499
  root: projectRoot,
7486
7500
  flag: harnessFlag,
7487
7501
  configHarness: (0, adapter_registry_js_1.declaredHarnessNames)(config.harnesses),
7488
- }).adapter));
7502
+ }).adapter);
7503
+ const weightLine = (0, context_creep_ratchet_js_1.compileWeightLine)(projectRoot, measured);
7489
7504
  if (weightLine !== null)
7490
7505
  console.log(`\n${weightLine}`);
7491
7506
  }
@@ -1,15 +1,33 @@
1
- import { type InstructionBaseline, type ParsedBaseline } from "./core/instruction-baseline.js";
1
+ import { type InstructionBaseline, type LegacyBaseline, type ParsedBaseline } from "./core/instruction-baseline.js";
2
+ import type { AlwaysLoadedContext } from "./core/always-loaded.js";
2
3
  import type { InstructionWeight } from "./core/instruction-weight.js";
3
4
  import type { RuleSeverity } from "./core/types.js";
4
5
  /** The file on disk, read once: absent, parsed, or refused. */
5
6
  export type BaselineOnDisk = {
6
7
  readonly kind: "absent";
7
8
  } | ParsedBaseline;
9
+ /**
10
+ * Where the baseline is read from, and whether the pre-rename file is still
11
+ * around. The new file wins; the old one is read only when the new one is
12
+ * absent, so a repo that upgrades keeps its ratchet until it renames the file.
13
+ */
14
+ export interface BaselineSource {
15
+ /** The path read (repo-relative): the new file, else the old one, else the new path. */
16
+ readonly file: string;
17
+ readonly legacy: LegacyBaseline;
18
+ }
19
+ export declare function baselineSource(root: string): BaselineSource;
8
20
  export declare function readInstructionBaseline(root: string): BaselineOnDisk;
9
- /** One bundle's measurement: where it is, and its weight (`null` = nothing to weigh). */
10
- export type MeasuredBundle = readonly [
21
+ /**
22
+ * One bundle's measurement: where it is, and either nothing to weigh or its
23
+ * weight WITH the always-loaded context around it. One union, not an optional third
24
+ * element: a weight without its always-loaded context used to read as "no parts", so a
25
+ * recorded part was compared as 0 — a shrink nobody made.
26
+ */
27
+ export type MeasuredBundle = readonly [at: string, weight: null] | readonly [
11
28
  at: string,
12
- weight: InstructionWeight | null
29
+ weight: InstructionWeight,
30
+ loaded: AlwaysLoadedContext
13
31
  ];
14
32
  /** Write the baseline for every measured bundle; returns what was written. */
15
33
  export declare function writeInstructionBaseline(root: string, onDisk: BaselineOnDisk, measured: readonly MeasuredBundle[]): InstructionBaseline;
@@ -33,13 +51,13 @@ export interface RatchetLine {
33
51
  * the file exists: a bundle that appeared after the baseline was recorded is
34
52
  * weight nobody signed off on.
35
53
  */
36
- export declare function ratchetLines(onDisk: BaselineOnDisk, measured: readonly MeasuredBundle[], max?: number): readonly RatchetLine[];
54
+ export declare function ratchetLines(onDisk: BaselineOnDisk, measured: readonly MeasuredBundle[], max?: number, source?: BaselineSource): readonly RatchetLine[];
37
55
  /**
38
56
  * The bundles `--update-baseline` must not record: each one over the ceiling,
39
57
  * as the refusal text. Empty when there is no ceiling or nothing exceeds it.
40
58
  */
41
59
  export declare function updateRefusals(measured: readonly MeasuredBundle[], max: number | undefined): readonly string[];
42
- /** The options {@link checkInstructionWeightRatchet} takes. */
60
+ /** The options {@link checkContextCreepRatchet} takes. */
43
61
  interface RatchetOptions {
44
62
  readonly root: string;
45
63
  readonly severity: RuleSeverity;
@@ -51,16 +69,20 @@ interface RatchetOptions {
51
69
  readonly measure: () => readonly MeasuredBundle[];
52
70
  readonly annotate: (level: "error" | "warning", message: string) => void;
53
71
  }
72
+ /** What {@link checkContextCreepRatchet} hands back to `lint`. */
73
+ interface RatchetResult {
74
+ readonly issues: number;
75
+ readonly errors: number;
76
+ /** Notes to show even when `lint` is silent (`--summary`): the old-file rename command. */
77
+ readonly notes: readonly string[];
78
+ }
54
79
  /** Run the ratchet for `lint`: print, annotate, count. */
55
- export declare function checkInstructionWeightRatchet(opts: RatchetOptions): {
56
- issues: number;
57
- errors: number;
58
- };
80
+ export declare function checkContextCreepRatchet(opts: RatchetOptions): RatchetResult;
59
81
  /**
60
82
  * The line `compile` prints after writing instruction files: the weight NOW,
61
83
  * against the baseline, at the moment the author changed it. Report-only —
62
84
  * `lint` stays the single gate. `null` when there is nothing to weigh.
63
85
  */
64
- export declare function compileWeightLine(root: string, weight: InstructionWeight | null): string | null;
86
+ export declare function compileWeightLine(root: string, measured: MeasuredBundle): string | null;
65
87
  export {};
66
- //# sourceMappingURL=instruction-weight-ratchet.d.ts.map
88
+ //# sourceMappingURL=context-creep-ratchet.d.ts.map
@@ -0,0 +1,270 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.baselineSource = baselineSource;
4
+ exports.readInstructionBaseline = readInstructionBaseline;
5
+ exports.writeInstructionBaseline = writeInstructionBaseline;
6
+ exports.ratchetLines = ratchetLines;
7
+ exports.updateRefusals = updateRefusals;
8
+ exports.checkContextCreepRatchet = checkContextCreepRatchet;
9
+ exports.compileWeightLine = compileWeightLine;
10
+ /**
11
+ * `lint`'s side of the context-creep ratchet: measure each scored bundle,
12
+ * compare it with `.vigiles/context-creep.json`, and — only under the
13
+ * explicit `--update-baseline` — write that file.
14
+ *
15
+ * The decisions (what a verdict is, what it says) live in
16
+ * `core/instruction-baseline.ts`; this module owns the two effects the core
17
+ * must not have, reading and writing the committed file, plus turning verdicts
18
+ * into lint counters.
19
+ *
20
+ * WHY THE FILE IS COMMITTED, unlike `.vigiles/coverage.json`. Coverage records
21
+ * what tests ran on THIS machine, so a committed copy would credit a checkout
22
+ * where nothing ran. The baseline records a property of the COMMIT: it is built
23
+ * from `committedTotal`, which already leaves out every per-machine file
24
+ * (`CLAUDE.local.md`, a gitignored settings sibling), so two clones of one
25
+ * commit compute byte-identical files. That is what lets CI compare against it.
26
+ */
27
+ const node_fs_1 = require("node:fs");
28
+ const node_path_1 = require("node:path");
29
+ const instruction_baseline_js_1 = require("./core/instruction-baseline.js");
30
+ function baselineSource(root) {
31
+ const hasNew = (0, node_fs_1.existsSync)((0, node_path_1.join)(root, instruction_baseline_js_1.INSTRUCTION_BASELINE_FILE));
32
+ const hasOld = (0, node_fs_1.existsSync)((0, node_path_1.join)(root, instruction_baseline_js_1.LEGACY_INSTRUCTION_BASELINE_FILE));
33
+ if (hasNew) {
34
+ return {
35
+ file: instruction_baseline_js_1.INSTRUCTION_BASELINE_FILE,
36
+ legacy: hasOld ? "both" : "none",
37
+ };
38
+ }
39
+ return hasOld
40
+ ? { file: instruction_baseline_js_1.LEGACY_INSTRUCTION_BASELINE_FILE, legacy: "only" }
41
+ : { file: instruction_baseline_js_1.INSTRUCTION_BASELINE_FILE, legacy: "none" };
42
+ }
43
+ function readInstructionBaseline(root) {
44
+ const path = (0, node_path_1.join)(root, baselineSource(root).file);
45
+ return (0, node_fs_1.existsSync)(path)
46
+ ? (0, instruction_baseline_js_1.parseInstructionBaseline)((0, node_fs_1.readFileSync)(path, "utf-8"))
47
+ : { kind: "absent" };
48
+ }
49
+ /** Write the baseline for every measured bundle; returns what was written. */
50
+ function writeInstructionBaseline(root, onDisk, measured) {
51
+ const previous = onDisk.kind === "ok" ? onDisk.baseline : undefined;
52
+ const next = (0, instruction_baseline_js_1.recordEntries)(previous, measured.map((m) => [m[0], recordedEntry(m, previous)]));
53
+ const path = (0, node_path_1.join)(root, instruction_baseline_js_1.INSTRUCTION_BASELINE_FILE);
54
+ (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
55
+ (0, node_fs_1.writeFileSync)(path, (0, instruction_baseline_js_1.serializeBaseline)(next));
56
+ return next;
57
+ }
58
+ /**
59
+ * What `--update-baseline` writes for one bundle: the measured entry, with
60
+ * every part the old entry records and this run cannot measure carried over —
61
+ * re-recording must not drop a part only because the adapter stopped modelling
62
+ * it (`carryUnmeasured`).
63
+ */
64
+ function recordedEntry(m, previous) {
65
+ if (m[1] === null)
66
+ return null;
67
+ const [at, weight, loaded] = m;
68
+ const old = entryAt(previous?.bundles ?? {}, at);
69
+ return (0, instruction_baseline_js_1.carryUnmeasured)((0, instruction_baseline_js_1.entryFor)(weight, loaded), loaded, old).entry;
70
+ }
71
+ /** One bundle's recorded entry, or `undefined` when the file has none. */
72
+ const entryAt = (bundles, at) => Object.hasOwn(bundles, at) ? bundles[at] : undefined;
73
+ /**
74
+ * Pure: the lines a run prints, given what was measured and what is on disk.
75
+ * `max` is the opt-in absolute ceiling; a bundle over it adds a finding of its
76
+ * own, whatever the baseline says (including when there is none, or it is
77
+ * unreadable).
78
+ *
79
+ * A bundle with no entry is a nudge while the repo has NO baseline file (it has
80
+ * not opted in, and a fresh repo must not fail on day one) — but a FINDING once
81
+ * the file exists: a bundle that appeared after the baseline was recorded is
82
+ * weight nobody signed off on.
83
+ */
84
+ function ratchetLines(onDisk, measured, max, source = { file: instruction_baseline_js_1.INSTRUCTION_BASELINE_FILE, legacy: "none" }) {
85
+ return [
86
+ ...baselineLines(onDisk, measured, source.file),
87
+ ...legacyLines(source.legacy),
88
+ ...measured.flatMap(([at, weight]) => ceilingLine(at, weight, max)),
89
+ ];
90
+ }
91
+ /** One bundle's ceiling finding, or nothing when it is at or under `max`. */
92
+ function ceilingLine(at, weight, max) {
93
+ const over = weight === null ? undefined : (0, instruction_baseline_js_1.checkCeiling)(weight, max);
94
+ return over === undefined
95
+ ? []
96
+ : [{ at, status: "finding", text: (0, instruction_baseline_js_1.formatCeiling)(over, at) }];
97
+ }
98
+ /** The one finding an unreadable baseline file gets. */
99
+ const unreadableLine = (message, file) => ({
100
+ at: ".",
101
+ status: "finding",
102
+ text: `${file} cannot be read (${message}) — ` +
103
+ `re-record it with \`${instruction_baseline_js_1.UPDATE_BASELINE_COMMAND}\``,
104
+ });
105
+ /** The rename/remove NOTE for a repo that still has the old baseline file. */
106
+ function legacyLines(legacy) {
107
+ const text = (0, instruction_baseline_js_1.legacyBaselineNote)(legacy);
108
+ return text === undefined ? [] : [{ at: ".", status: "note", text }];
109
+ }
110
+ function baselineLines(onDisk, measured, path) {
111
+ if (onDisk.kind === "invalid")
112
+ return [unreadableLine(onDisk.message, path)];
113
+ const recorded = onDisk.kind === "ok" ? onDisk.baseline.bundles : {};
114
+ const file = onDisk.kind === "ok" ? onDisk.baseline.version : "absent";
115
+ return measured.flatMap((m) => {
116
+ if (m[1] === null)
117
+ return [];
118
+ const [at, weight, loaded] = m;
119
+ const verdict = (0, instruction_baseline_js_1.compareAlwaysLoadedToBaseline)(weight, loaded, entryAt(recorded, at), file);
120
+ const text = `${(0, instruction_baseline_js_1.formatBaselineVerdict)(verdict, at)}${unfollowedNote(weight)}`;
121
+ return [
122
+ { at, status: lineStatus(verdict, onDisk), text },
123
+ ...partNotes(verdict, weight.unit, at),
124
+ ];
125
+ });
126
+ }
127
+ /**
128
+ * `held` is ok; a bundle with no entry is a nudge while the repo has no
129
+ * baseline file — every other verdict is a finding.
130
+ */
131
+ function lineStatus(verdict, onDisk) {
132
+ if (verdict.verdict.kind === "held")
133
+ return "ok";
134
+ return verdict.verdict.kind === "unrecorded" && onDisk.kind !== "ok"
135
+ ? "note"
136
+ : "finding";
137
+ }
138
+ /**
139
+ * An import named and not read is weight this number lacks — a second hop, or
140
+ * a path that does not resolve. Said on the line itself, because the gate
141
+ * holding is only as true as the sum it holds.
142
+ */
143
+ function unfollowedNote(weight) {
144
+ return weight.unreadImports.length > 0
145
+ ? ` (${String(weight.unreadImports.length)} import(s) not followed: ${weight.unreadImports.join(", ")} — their size is not in this number)`
146
+ : "";
147
+ }
148
+ /**
149
+ * A version-1 file's NOTE for parts that are not in it. Never a finding: a
150
+ * repo whose file predates the always-loaded context must not go red on upgrade — it
151
+ * records the parts when it chooses to, and they gate from then on.
152
+ */
153
+ function partNotes(verdict, unit, at) {
154
+ return verdict.kind === "instructions-only" &&
155
+ verdict.unrecordedParts.length > 0
156
+ ? [
157
+ {
158
+ at,
159
+ status: "note",
160
+ text: (0, instruction_baseline_js_1.formatUnrecordedParts)(verdict.unrecordedParts, unit, at),
161
+ },
162
+ ]
163
+ : [];
164
+ }
165
+ /**
166
+ * The bundles `--update-baseline` must not record: each one over the ceiling,
167
+ * as the refusal text. Empty when there is no ceiling or nothing exceeds it.
168
+ */
169
+ function updateRefusals(measured, max) {
170
+ return measured.flatMap(([at, weight]) => {
171
+ const over = weight === null ? undefined : (0, instruction_baseline_js_1.checkCeiling)(weight, max);
172
+ return over === undefined ? [] : [(0, instruction_baseline_js_1.formatRefusal)(over, at)];
173
+ });
174
+ }
175
+ /**
176
+ * What `lint` compares against: the file as it is, or — under `--update-baseline`
177
+ * and when nothing is over the ceiling — the file just written. A baseline above
178
+ * the ceiling would bypass it (re-recording is how a ratchet gets loosened), so
179
+ * then nothing is written and the refusals are returned for the caller to fail on.
180
+ */
181
+ function recordOrRead(opts, measured) {
182
+ const before = readInstructionBaseline(opts.root);
183
+ const refusals = opts.update ? updateRefusals(measured, opts.max) : [];
184
+ const record = opts.update && refusals.length === 0;
185
+ return {
186
+ refusals,
187
+ onDisk: record
188
+ ? {
189
+ kind: "ok",
190
+ baseline: writeInstructionBaseline(opts.root, before, measured),
191
+ }
192
+ : before,
193
+ };
194
+ }
195
+ /** The human-readable report: what was recorded, then one line per bundle. */
196
+ function printReport(lines, severity, recorded) {
197
+ console.log("\nContext-creep ratchet:\n");
198
+ if (recorded)
199
+ console.log(` ✓ recorded ${instruction_baseline_js_1.INSTRUCTION_BASELINE_FILE}`);
200
+ const marks = {
201
+ finding: severity === "error" ? "✗" : "⚠",
202
+ ok: "✓",
203
+ note: "ℹ",
204
+ };
205
+ lines.forEach((l) => {
206
+ console.log(` ${marks[l.status]} ${l.text}`);
207
+ });
208
+ }
209
+ /** The notes `--summary` carries: only while the rule is on, and only the old-file one. */
210
+ function noteTexts(severity, source) {
211
+ return severity ? legacyLines(source.legacy).map((l) => l.text) : [];
212
+ }
213
+ /** The refusals, printed and annotated: a baseline above the ceiling is never written. */
214
+ function reportRefusals(opts, refusals) {
215
+ refusals.forEach((message) => {
216
+ console.error(`✗ ${message}`);
217
+ opts.annotate("error", message);
218
+ });
219
+ }
220
+ /** Run the ratchet for `lint`: print, annotate, count. */
221
+ function checkContextCreepRatchet(opts) {
222
+ const { severity, update, silent } = opts;
223
+ if (!severity && !update)
224
+ return { issues: 0, errors: 0, notes: [] };
225
+ const measured = opts.measure();
226
+ const { onDisk, refusals } = recordOrRead(opts, measured);
227
+ reportRefusals(opts, refusals);
228
+ // Read AFTER a possible write: an update leaves the new file beside an old
229
+ // one, and the note must then say the old one is stale.
230
+ const source = baselineSource(opts.root);
231
+ const lines = severity
232
+ ? ratchetLines(onDisk, measured, opts.max, source)
233
+ : [];
234
+ const findings = lines.filter((l) => l.status === "finding");
235
+ if (!silent && (update || lines.length > 0)) {
236
+ printReport(lines, severity, update && refusals.length === 0);
237
+ }
238
+ const level = severity === "error" ? "error" : "warning";
239
+ findings.forEach((l) => {
240
+ opts.annotate(level, l.text);
241
+ });
242
+ return {
243
+ issues: findings.length + refusals.length,
244
+ errors: (severity === "error" ? findings.length : 0) + refusals.length,
245
+ notes: noteTexts(severity, source),
246
+ };
247
+ }
248
+ /**
249
+ * The line `compile` prints after writing instruction files: the weight NOW,
250
+ * against the baseline, at the moment the author changed it. Report-only —
251
+ * `lint` stays the single gate. `null` when there is nothing to weigh.
252
+ */
253
+ function compileWeightLine(root, measured) {
254
+ if (measured[1] === null)
255
+ return null;
256
+ const [, weight, loaded] = measured;
257
+ const onDisk = readInstructionBaseline(root);
258
+ if (onDisk.kind === "invalid") {
259
+ return `always-loaded: ${baselineSource(root).file} cannot be read (${onDisk.message})`;
260
+ }
261
+ const recorded = onDisk.kind === "ok" ? onDisk.baseline.bundles : {};
262
+ const verdict = (0, instruction_baseline_js_1.compareAlwaysLoadedToBaseline)(weight, loaded, entryAt(recorded, "."), onDisk.kind === "ok" ? onDisk.baseline.version : "absent");
263
+ const line = (0, instruction_baseline_js_1.formatWeightLine)(verdict.verdict, verdict.kind === "always-loaded"
264
+ ? "always-loaded context"
265
+ : "always-loaded");
266
+ return verdict.kind === "always-loaded" && verdict.unmeasured.length > 0
267
+ ? [line, ...verdict.unmeasured.map(instruction_baseline_js_1.describeUnmeasured)].join("\n ")
268
+ : line;
269
+ }
270
+ //# sourceMappingURL=context-creep-ratchet.js.map
@@ -0,0 +1,128 @@
1
+ /**
2
+ * The ALWAYS-LOADED CONTEXT: everything the harness loads at session start without a
3
+ * decision — the always-loaded instructions, the output style the committed
4
+ * settings select, and the skill listing — summed in the harness's own unit.
5
+ *
6
+ * WHY THE SUM, AND NOT THE INSTRUCTIONS ALONE. `./instruction-weight.ts`
7
+ * explains why a per-FILE weight invites the evasion it is meant to catch: text
8
+ * moved into an always-loaded sibling is still loaded. The output style and the
9
+ * skill listing are always-loaded siblings of the same kind. A section cut
10
+ * from `CLAUDE.md` into the selected style, or into a skill's description,
11
+ * still reaches the model on every request; a weight that counts only the
12
+ * instruction file reads that move as a shrink. The parts are reported one by
13
+ * one so a reader can see WHERE the weight is, and summed so a move between
14
+ * them nets out.
15
+ *
16
+ * WHAT IT IS NOT. It is the part of every request THE REPOSITORY decides, not
17
+ * the size of a request: the harness's own system prompt and tool definitions,
18
+ * user- and plugin-level skills, and the conversation history are added in a
19
+ * real session and are not repository facts. Units are the harness's own
20
+ * (characters for Claude Code, bytes for Codex) and never tokens, for the
21
+ * reason `InstructionBudget.unit` gives.
22
+ *
23
+ * WHAT IS COUNTED, PER PART.
24
+ *
25
+ * - output style: only a style the COMMITTED settings select and the
26
+ * repository holds as a file in the session's own style folder. A style
27
+ * selected in a per-machine settings file is not a property of the commit;
28
+ * a name no repository file declares (a built-in style, or a typo the
29
+ * harness silently resolves to its default) has no size vigiles can read,
30
+ * and is reported by name rather than counted as zero.
31
+ * - skill listing: every skill in the folder a session at the repository
32
+ * root loads (`skillsHome`), at the depths the harness reads there
33
+ * (`SkillDiscovery`: one folder per skill on Claude Code, a recursive walk
34
+ * on Codex), rendered by the harness's own entry format with its
35
+ * per-entry cap. A plugin's `skills/` folder is what the plugin's
36
+ * USERS load, not a session here.
37
+ *
38
+ * Pure: the caller hands in a file map (repo-relative path → text) holding the
39
+ * committed settings, the style files and the SKILL.md files. The CLI reads
40
+ * them from disk; the browser engine passes the tree it fetched.
41
+ */
42
+ import type { HarnessDialect } from "./dialect.js";
43
+ import { type HarnessUnit } from "./harness-unit.js";
44
+ import { type PluginLayout } from "./layout.js";
45
+ import type { ListedSkill } from "./skill-listing.js";
46
+ /** The parts that join the instructions in the always-loaded context. */
47
+ export type LoadedPartName = "output-style" | "skill-listing";
48
+ /** One file's share of a part, in the harness's unit. */
49
+ export interface LoadedPartFile {
50
+ readonly path: string;
51
+ readonly size: number;
52
+ }
53
+ /**
54
+ * One part of the always-loaded context. Each absence is its own fact, because each
55
+ * calls for a different reading:
56
+ *
57
+ * - `counted` — the part loads, and this is its size;
58
+ * - `none` — the harness has this part and the repository loads nothing of
59
+ * it (no style selected, no listed skill);
60
+ * - `not-supported` — the harness has no such thing (Codex has no output
61
+ * styles);
62
+ * - `not-modelled` — the adapter does not say how the harness does it, so
63
+ * vigiles cannot measure it; NOT the same as zero;
64
+ * - `unresolved` — a style is selected by a name no repository file
65
+ * declares: a built-in style, or a typo that loads the default.
66
+ */
67
+ export type LoadedPart = {
68
+ readonly kind: "counted";
69
+ readonly total: number;
70
+ readonly files: readonly LoadedPartFile[];
71
+ } | {
72
+ readonly kind: "none";
73
+ } | {
74
+ readonly kind: "not-supported";
75
+ } | {
76
+ readonly kind: "not-modelled";
77
+ } | {
78
+ readonly kind: "unresolved";
79
+ readonly name: string;
80
+ };
81
+ export interface AlwaysLoadedContext {
82
+ readonly unit: HarnessUnit;
83
+ /** The instructions' committed total — the same number the weight scores. */
84
+ readonly instructions: number;
85
+ readonly outputStyle: LoadedPart;
86
+ readonly skillListing: LoadedPart;
87
+ /** Instructions plus every `counted` part. */
88
+ readonly total: number;
89
+ }
90
+ type AlwaysLoadedLayout = Pick<PluginLayout, "outputStyles" | "userSurfaceRoot" | "surfaces" | "skillDiscovery" | "settings" | "settingsPath">;
91
+ /** The instructions' weight, as `weighInstructions` measured it. */
92
+ export interface WeighedInstructions {
93
+ readonly unit: HarnessUnit;
94
+ /** The SCORED total — what a teammate on the same commit also loads. */
95
+ readonly committedTotal: number;
96
+ }
97
+ export interface AlwaysLoadedInput {
98
+ readonly weight: WeighedInstructions;
99
+ readonly files: Readonly<Record<string, string>>;
100
+ readonly layout: AlwaysLoadedLayout;
101
+ readonly dialect: Pick<HarnessDialect, "skillListing">;
102
+ }
103
+ /** What one part is measured from: the input, in the weight's unit. */
104
+ export interface LoadedPartInput {
105
+ readonly files: Readonly<Record<string, string>>;
106
+ readonly layout: AlwaysLoadedLayout;
107
+ readonly dialect: Pick<HarnessDialect, "skillListing">;
108
+ readonly unit: HarnessUnit;
109
+ }
110
+ /** The selected output style's part. */
111
+ export declare function outputStylePart(input: LoadedPartInput, settings: Readonly<Record<string, unknown>>): LoadedPart;
112
+ /**
113
+ * Every SKILL.md the session's skills folder holds at a depth the harness
114
+ * reads ({@link skillDiscoveryOf}), read once.
115
+ */
116
+ export declare function sessionSkills(layout: AlwaysLoadedLayout, files: Readonly<Record<string, string>>): readonly ListedSkill[];
117
+ /** The skill listing's part: each listed skill's entry, sized. */
118
+ export declare function skillListingPart(input: LoadedPartInput, settings: Readonly<Record<string, unknown>>): LoadedPart;
119
+ /** The size a part adds to the sum: its total when counted, else nothing. */
120
+ export declare const partTotal: (part: LoadedPart) => number;
121
+ /**
122
+ * Weigh the always-loaded context: the instructions' committed total (already
123
+ * measured by the instruction weight) plus the selected output style and the
124
+ * skill listing, each in the same unit by the same `sizeIn`.
125
+ */
126
+ export declare function weighAlwaysLoaded(input: AlwaysLoadedInput): AlwaysLoadedContext;
127
+ export {};
128
+ //# sourceMappingURL=always-loaded.d.ts.map