@yawlabs/ctxlint 0.21.0 → 0.23.0

package/.pre-commit-hooks.yaml

@@ -4,7 +4,7 @@
   # Version-pinned so a checkout at `rev: vX.Y.Z` runs exactly that release
   # of ctxlint — matches the pinning done by `ctxlint init`. release.sh keeps
   # this in sync with package.json on each bump.
-  entry: npx @yawlabs/ctxlint@0.21.0 --strict
+  entry: npx @yawlabs/ctxlint@0.23.0 --strict
   language: node
   always_run: true
   pass_filenames: false

package/bin/ctxlint.mjs

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+/**
+ * Runtime launcher for @yawlabs/ctxlint.
+ *
+ * Prefers the oam runtime (https://oamjs.org) and falls back to the Node process
+ * already running this file. The CLI itself (`dist/index.js`) is
+ * runtime-agnostic -- a pre-bundled ESM entry using only `node:` builtins that
+ * oam implements -- so neither path changes behavior. This covers both modes the
+ * binary has: the linter (`ctxlint audit ...`) and the MCP server
+ * (`ctxlint serve`), since every argument passes through untouched.
+ *
+ * WHY THE FALLBACK COSTS NOTHING
+ * npm has already started Node to run this launcher, so falling back is a plain
+ * `import()` of the CLI into THIS process: no extra spawn, no extra startup,
+ * byte-identical to invoking dist/index.js directly. Discovery is stat-only --
+ * never a subprocess -- so the miss case stays sub-millisecond.
+ *
+ * WHAT THE OAM PATH COSTS
+ * Reaching oam through an npm `bin` means Node boots first and oam boots second,
+ * so the launcher is slower than either runtime alone. It exists so `npx` users
+ * get oam automatically. To skip it -- and for `serve`, which an MCP host starts
+ * once per session, this is the better config -- point at oam directly:
+ *   { "command": "oam", "args": ["run", "<abs>/dist/index.js", "--", "serve"] }
+ *
+ * NO SANDBOX HERE -- DELIBERATELY
+ * oam 0.9.0's `--permission` is real hardening, but it does not fit a linter.
+ * ctxlint's whole purpose is to read context files the caller names at run time
+ * -- CLAUDE.md, skills, agent transcripts, MCP configs, anywhere on disk -- so a
+ * filesystem-read grant would have to be `*` to keep the tool working. Narrowing
+ * it would turn "this path is not linted" into a silent clean result, which is
+ * the worst failure mode a linter has. What is left to deny (network, child
+ * process) it never uses anyway, so the sandbox would gate nothing real.
+ *
+ * MINIMUM OAM VERSION
+ * 0.9.0. Below it `child_process.execFile` ran its arguments through a SHELL,
+ * `exec` accepted `timeout` and ignored it, `spawnSync` truncated at `maxBuffer`
+ * while reporting success, and `stdio: 'inherit'`/`'ignore'` both behaved as
+ * `'pipe'`. This tool spawns nothing in shipped code, so the floor is enforced
+ * for consistency across @yawlabs/*-mcp rather than because this launcher was
+ * exposed. An older oam is not an error: the launcher falls back to Node and
+ * says so on stderr.
+ *
+ * SELECTION
+ *   CTXLINT_RUNTIME=oam     require oam; fail loudly if it is missing
+ *   CTXLINT_RUNTIME=node    never use oam
+ *   CTXLINT_RUNTIME=auto    prefer oam, silently fall back (default)
+ *   OAM_BIN=/path/to/oam    explicit binary, checked before any discovery
+ */
+
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { constants, homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Oldest oam whose `child_process` matches Node. See MINIMUM OAM VERSION above. */
+const OAM_MIN = [0, 9, 0];
+
+// Two forms, deliberately. `import()` on Windows REJECTS a bare `C:\...` path
+// with ERR_UNSUPPORTED_ESM_URL_SCHEME (it reads `c:` as a protocol), so the
+// in-process fallback must use the file:// URL. spawn() needs a real path.
+const SERVER_URL = new URL("../dist/index.js", import.meta.url);
+const SERVER_ENTRY = fileURLToPath(SERVER_URL);
+const isWin = process.platform === "win32";
+const exe = isWin ? "oam.exe" : "oam";
+
+/** Locate an oam binary, or null. Every branch is a stat, never a subprocess. */
+function findOam() {
+  // 1. Explicit override wins and is never second-guessed.
+  const override = process.env.OAM_BIN;
+  if (override) return existsSync(override) ? override : null;
+
+  // 2. Installed locations, BEFORE PATH. Someone who develops oam itself usually
+  //    has oam/target/release on PATH, and a build directory is the wrong thing
+  //    for a user-facing launcher to bind to: cargo replaces the binary
+  //    underneath running processes, and the dev build is not the release the
+  //    user installed. OAM_BIN remains the way to point at a dev build.
+  const installed = [join(homedir(), ".oam", "bin", exe)];
+  if (isWin) {
+    installed.unshift(join(process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "oam", "bin", exe));
+  }
+  for (const candidate of installed) {
+    if (existsSync(candidate)) return candidate;
+  }
+
+  // 3. PATH, resolved manually rather than by spawning `which`/`where`, which
+  //    would cost a subprocess on every launch just to decide whether to spawn.
+  const pathExt = isWin ? (process.env.PATHEXT ?? ".EXE").split(";").filter(Boolean) : [""];
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    if (!dir) continue;
+    for (const ext of isWin ? pathExt : [""]) {
+      const candidate = join(dir, isWin ? `oam${ext.toLowerCase()}` : "oam");
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * `oam --version` -> [major, minor, patch], or null when it cannot be read.
+ * A pre-release suffix (0.9.0-rc.1) truncates to its base version.
+ */
+function oamVersion(cmd) {
+  try {
+    const out = execFileSync(cmd, ["--version"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const m = /(\d+)\.(\d+)\.(\d+)/.exec(out);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+  } catch {
+    // Not executable, wrong arch, or deleted since the stat. Caller degrades.
+    return null;
+  }
+}
+
+/** True when `v` is at least `min`, comparing major/minor/patch in order. */
+function atLeast(v, min) {
+  if (!v) return false;
+  for (let i = 0; i < min.length; i++) {
+    if (v[i] > min[i]) return true;
+    if (v[i] < min[i]) return false;
+  }
+  return true;
+}
+
+/** Run the CLI in THIS process. The zero-overhead fallback. */
+async function runInProcess() {
+  // Point argv[1] at the CLI first, so the in-process path is indistinguishable
+  // from having executed the file directly -- an entry-point guard
+  // (`import.meta.url === pathToFileURL(process.argv[1]).href`) must read true.
+  process.argv[1] = SERVER_ENTRY;
+  await import(SERVER_URL.href);
+}
+
+const mode = (process.env.CTXLINT_RUNTIME ?? "auto").toLowerCase();
+
+if (mode === "node") {
+  await runInProcess();
+} else {
+  const oam = findOam();
+
+  if (!oam) {
+    if (mode === "oam") {
+      // Explicitly demanded, so this is a real misconfiguration -- do not
+      // silently do something else. writeSync because stderr is async for
+      // TTYs/pipes on Windows and process.exit truncates pending writes.
+      const { writeSync } = await import("node:fs");
+      writeSync(
+        2,
+        "ctxlint: CTXLINT_RUNTIME=oam but no oam binary was found.\n" +
+          "Install from https://oamjs.org, set OAM_BIN=/path/to/oam, or use CTXLINT_RUNTIME=node.\n",
+      );
+      process.exit(1);
+    }
+    await runInProcess();
+  } else if (!atLeast(oamVersion(oam), OAM_MIN)) {
+    // Discovery itself stays stat-only; this is the first subprocess, and it
+    // runs only once we have already decided to spawn oam anyway. Measured 26ms
+    // median (n=12, windows-arm64), paid once per invocation.
+    const min = OAM_MIN.join(".");
+    if (mode === "oam") {
+      const { writeSync } = await import("node:fs");
+      writeSync(
+        2,
+        `ctxlint: CTXLINT_RUNTIME=oam but ${oam} is older than oam ${min}.\n` +
+          `Run \`oam self-update\`, or use CTXLINT_RUNTIME=node.\n`,
+      );
+      process.exit(1);
+    }
+    // auto: an old oam is a reason to prefer Node, not to fail. Say so, because
+    // a silent downgrade is how someone keeps running an oam they meant to
+    // update. stderr is safe -- MCP frames travel on stdout under `serve`.
+    process.stderr.write(`ctxlint: oam at ${oam} is older than ${min}; using Node instead.\n`);
+    await runInProcess();
+  } else {
+    // `--` separates oam's own flags from the script's argv. Everything after it
+    // lands in process.argv for the CLI, so `audit`, `serve` and every flag
+    // survive the hop unchanged.
+    const child = spawn(oam, ["run", SERVER_ENTRY, "--", ...process.argv.slice(2)], {
+      // inherit keeps the SAME fds, so MCP's newline-delimited JSON framing on
+      // stdin/stdout under `serve` is untouched, and the linter's exit-code and
+      // output behavior is identical to running it directly.
+      stdio: "inherit",
+      env: process.env,
+      windowsHide: true,
+    });
+
+    // If oam cannot be executed at all (deleted between the stat and the spawn,
+    // wrong arch, permission), fall back rather than failing outright.
+    // `spawned` guards against falling back AFTER the child has begun running.
+    let spawned = false;
+    child.on("spawn", () => {
+      spawned = true;
+    });
+    child.on("error", (err) => {
+      if (spawned) return;
+      if (mode === "oam") {
+        process.stderr.write(`ctxlint: failed to launch oam (${err.message})\n`);
+        process.exit(1);
+      }
+      void runInProcess();
+    });
+
+    // Forward termination so the CLI's own shutdown path runs in the child
+    // rather than the child being orphaned. Signals are a no-op on Windows but
+    // harmless to register.
+    for (const sig of ["SIGINT", "SIGTERM"]) {
+      process.on(sig, () => {
+        if (!child.killed) child.kill(sig);
+      });
+    }
+
+    child.on("exit", (code, signal) => {
+      // Mirror the child's fate: a signal death becomes 128+n so callers see a
+      // conventional shell exit status rather than a bare 0. ctxlint's exit code
+      // is how CI reads a lint failure, so passing it through is load-bearing.
+      if (signal) {
+        process.exit(128 + (constants.signals[signal] ?? 15));
+      }
+      process.exit(code ?? 0);
+    });
+  }
+}

package/dist/index.js

@@ -24050,84 +24050,443 @@ var init_cli_subcommands = __esm({
   }
 });
 
-// src/core/checks/commands.ts
+// src/core/checks/tokens.ts
+function resolveTokenThresholds(overrides) {
+  if (!overrides) return DEFAULT_TOKEN_THRESHOLDS;
+  const merged = { ...DEFAULT_TOKEN_THRESHOLDS, ...overrides };
+  if (merged.info >= merged.warning || merged.warning >= merged.error) {
+    console.error(
+      `Warning: token thresholds should satisfy info < warning < error (got ${merged.info}, ${merged.warning}, ${merged.error}) \u2014 using defaults`
+    );
+    return DEFAULT_TOKEN_THRESHOLDS;
+  }
+  return merged;
+}
+async function checkTokens(file2, _projectRoot, thresholds = DEFAULT_TOKEN_THRESHOLDS) {
+  const issues = [];
+  const tokens = file2.totalTokens;
+  if (tokens >= thresholds.error) {
+    issues.push({
+      severity: "error",
+      check: "tokens",
+      ruleId: "tokens/excessive",
+      line: 1,
+      message: `${tokens.toLocaleString()} tokens \u2014 consumes significant context window space`,
+      suggestion: "Consider splitting into focused sections or removing redundant content."
+    });
+  } else if (tokens >= thresholds.warning) {
+    issues.push({
+      severity: "warning",
+      check: "tokens",
+      ruleId: "tokens/large",
+      line: 1,
+      message: `${tokens.toLocaleString()} tokens \u2014 large context file`,
+      suggestion: "Consider trimming \u2014 research shows diminishing returns past ~300 lines."
+    });
+  } else if (tokens >= thresholds.info) {
+    issues.push({
+      severity: "info",
+      check: "tokens",
+      ruleId: "tokens/info",
+      line: 1,
+      message: `Uses ~${tokens.toLocaleString()} tokens per session`
+    });
+  }
+  return issues;
+}
+function checkAggregateTokens(files, thresholds = DEFAULT_TOKEN_THRESHOLDS) {
+  const total = files.reduce((sum, f) => sum + f.tokens, 0);
+  if (total >= thresholds.aggregate && files.length > 1) {
+    return {
+      severity: "warning",
+      check: "tokens",
+      ruleId: "tokens/aggregate",
+      line: 0,
+      message: `${files.length} context files consume ${total.toLocaleString()} tokens combined`,
+      suggestion: "Consider consolidating or trimming to reduce per-session context cost."
+    };
+  }
+  return null;
+}
+var DEFAULT_TOKEN_THRESHOLDS;
+var init_tokens2 = __esm({
+  "src/core/checks/tokens.ts"() {
+    "use strict";
+    init_define_WEB_FIRST_SEGMENTS();
+    DEFAULT_TOKEN_THRESHOLDS = {
+      info: 1e3,
+      warning: 3e3,
+      error: 8e3,
+      aggregate: 5e3,
+      tierBreakdown: 1e3,
+      tierAggregate: 4e3
+    };
+  }
+});
+
+// src/core/checks/tier-tokens.ts
 import * as fs6 from "node:fs";
+import * as os2 from "node:os";
 import * as path7 from "node:path";
-function isManagerBuiltin(manager, sub) {
-  return PM_MANAGER_BUILTINS[manager]?.has(sub) ?? false;
+function hasFrontmatterList(content, field) {
+  const lines = content.split("\n");
+  if (lines[0]?.trim() !== "---") return false;
+  const fieldPattern = new RegExp(`^${field}\\s*:\\s*(.*)$`);
+  for (let i2 = 1; i2 < lines.length; i2++) {
+    const line = lines[i2];
+    if (line.trim() === "---") return false;
+    const match = line.match(fieldPattern);
+    if (match) {
+      const val = match[1].trim();
+      if (val && val !== "[]") return true;
+      for (let j3 = i2 + 1; j3 < lines.length; j3++) {
+        const next = lines[j3];
+        if (next.trim() === "---") return false;
+        if (next.trim() === "") continue;
+        if (next.trim().startsWith("- ")) return true;
+        break;
+      }
+    }
+  }
+  return false;
 }
-function scriptNameFromMatch(match) {
-  const [, manager, explicitRun, name] = match;
-  if (name.startsWith("-")) return null;
-  if (manager && !explicitRun && PM_BUILTIN_SUBCOMMANDS.has(name)) return null;
-  if (manager && !explicitRun && isManagerBuiltin(manager, name)) return null;
-  return name;
+function frontmatterScalar(content, field) {
+  const lines = content.split("\n");
+  if (lines[0]?.trim() !== "---") return null;
+  const fieldPattern = new RegExp(`^${field}\\s*:\\s*(.*)$`);
+  for (let i2 = 1; i2 < lines.length; i2++) {
+    if (lines[i2].trim() === "---") return null;
+    const match = lines[i2].match(fieldPattern);
+    if (match) return match[1].trim().replace(/^['"]|['"]$/g, "") || null;
+  }
+  return null;
 }
-function extractNpxPackage(cmd) {
-  if (!/^npx\b/.test(cmd)) return null;
-  const tokens = cmd.split(/\s+/).slice(1);
-  for (let i2 = 0; i2 < tokens.length; i2++) {
-    const t2 = tokens[i2];
-    if (t2 === "-p" || t2 === "--package") {
-      const v2 = tokens[i2 + 1];
-      if (v2 && !v2.startsWith("-")) return v2;
-      continue;
+function isAlwaysLoaded(file2) {
+  const rel = file2.relativePath.replace(/\\/g, "/");
+  if (rel.endsWith(".mdc")) return false;
+  if (rel.startsWith(".github/instructions/")) return false;
+  if (rel.includes("/rules/")) {
+    if (hasFrontmatterList(file2.content, "paths")) return false;
+    if (hasFrontmatterList(file2.content, "globs")) return false;
+    if (rel.includes(".windsurf/rules/")) {
+      const trigger = frontmatterScalar(file2.content, "trigger");
+      if (trigger && trigger.toLowerCase() !== "always_on") return false;
     }
-    if (t2.startsWith("-p=") || t2.startsWith("--package=")) {
-      return t2.slice(t2.indexOf("=") + 1) || null;
+    return true;
+  }
+  const basename4 = rel.split("/").pop() ?? "";
+  for (const name of ALWAYS_LOADED_NAMES) {
+    if (name.includes("/")) {
+      if (rel === name || rel.endsWith("/" + name)) return true;
+    } else if (basename4 === name) {
+      return true;
     }
-    if (t2.startsWith("-")) continue;
-    return t2;
+  }
+  return false;
+}
+function computeSectionCosts(file2) {
+  if (file2.sections.length === 0) return [];
+  const hasH2 = file2.sections.some((s) => s.level === 2);
+  const topLevel = hasH2 ? 2 : 1;
+  const lines = file2.content.split("\n");
+  return file2.sections.filter((s) => s.level === topLevel).map((s) => {
+    const body = lines.slice(s.startLine - 1, s.endLine).join("\n");
+    return { title: s.title, line: s.startLine, tokens: countTokens(body) };
+  }).sort((a, b2) => b2.tokens - a.tokens);
+}
+function inlineCodeSpans(line) {
+  const spans = [];
+  const re2 = /`([^`]+)`/g;
+  let m;
+  while ((m = re2.exec(line)) !== null) {
+    spans.push({ start: m.index, end: m.index + m[0].length, content: m[1] });
+  }
+  return spans;
+}
+function maskCodeSpans(line, spans) {
+  let out = line;
+  for (const s of spans) {
+    out = out.slice(0, s.start) + "#".repeat(s.end - s.start) + out.slice(s.end);
+  }
+  return out;
+}
+function findInviolableCommand(line) {
+  const spans = inlineCodeSpans(line);
+  if (spans.length === 0) return null;
+  const masked = maskCodeSpans(line, spans);
+  FRAMING_TOKEN.lastIndex = 0;
+  let m;
+  while ((m = FRAMING_TOKEN.exec(masked)) !== null) {
+    const token = m[1];
+    if (token === token.toLowerCase()) continue;
+    const afterIdx = m.index + m[0].length;
+    const span = spans.find((s) => s.start >= afterIdx);
+    if (!span) continue;
+    const gap = masked.slice(afterIdx, span.start);
+    if (gap.length > FRAMING_COMMAND_GAP || /[.!?]/.test(gap)) continue;
+    return { framing: token, command: span.content };
   }
   return null;
 }
-function wouldNeedPackageJson(cmd) {
-  const scriptMatch = cmd.match(NPM_SCRIPT_PATTERN);
-  if (scriptMatch && scriptNameFromMatch(scriptMatch) !== null) return true;
-  const shorthandMatch = cmd.match(PKG_SHORTHAND_PATTERN);
-  if (shorthandMatch && !isManagerBuiltin(shorthandMatch[1], shorthandMatch[2])) return true;
-  return /^npx\b/.test(cmd) || PKG_DEPENDENT_TOOL_PATTERN.test(cmd);
+function fingerprintFiles(paths) {
+  return paths.map((p2) => {
+    try {
+      const st2 = fs6.statSync(p2);
+      return `${st2.mtimeMs}:${st2.size}`;
+    } catch {
+      return "absent";
+    }
+  }).join("|");
 }
-function loadDeniedCommandPrefixes(projectRoot) {
-  const prefixes = [];
-  for (const rel of ["settings.json", "settings.local.json"]) {
+function loadSettingsSources(projectRoot, includeGlobal) {
+  const candidates = [
+    path7.join(projectRoot, ".claude", "settings.json"),
+    path7.join(projectRoot, ".claude", "settings.local.json")
+  ];
+  if (includeGlobal) {
+    candidates.push(path7.join(os2.homedir(), ".claude", "settings.json"));
+  }
+  const fingerprint = fingerprintFiles(candidates);
+  if (settingsCache?.root === projectRoot && settingsCache.includeGlobal === includeGlobal && settingsCache.fingerprint === fingerprint) {
+    return settingsCache.data;
+  }
+  const sources = [];
+  for (const p2 of candidates) {
     let content;
     try {
-      content = stripBom(fs6.readFileSync(path7.join(projectRoot, ".claude", rel), "utf-8"));
+      content = stripBom(fs6.readFileSync(p2, "utf-8"));
     } catch {
       continue;
     }
-    const data = parse2(content, [], { allowTrailingComma: true });
-    const deny = data?.permissions?.deny;
-    if (!Array.isArray(deny)) continue;
-    for (const entry of deny) {
-      if (typeof entry !== "string") continue;
-      const inner = entry.replace(/^[A-Za-z]+\((.*)\)$/, "$1");
-      const prefix = inner.replace(/:?\*+$/, "").trim();
-      if (prefix) prefixes.push(prefix);
+    const errors = [];
+    const data = parse2(content, errors, { allowTrailingComma: true });
+    if (errors.length > 0) {
+      console.warn(
+        `ctxlint: could not parse ${p2}: ${printParseErrorCode(errors[0].error)} at offset ${errors[0].offset}`
+      );
+      continue;
     }
+    if (!data || typeof data !== "object") continue;
+    sources.push(data);
   }
-  return prefixes;
+  settingsCache = { root: projectRoot, includeGlobal, fingerprint, data: sources };
+  return sources;
 }
-function isDeniedCommand(cmd, deniedPrefixes) {
-  return deniedPrefixes.some((p2) => cmd === p2 || cmd.startsWith(`${p2} `));
+function canonicalizeCommand(backticked) {
+  const beforeFlags = backticked.trim().split(/\s+--?/, 1)[0];
+  return beforeFlags.replace(/\s+/g, " ");
 }
-async function checkCommands(file2, projectRoot) {
-  const issues = [];
-  const pkgJson = loadPackageJson(projectRoot);
-  const makefile = loadMakefile(projectRoot);
-  const deniedPrefixes = loadDeniedCommandPrefixes(projectRoot);
-  if (!pkgJson) {
-    const skipped = file2.references.commands.find((ref) => wouldNeedPackageJson(ref.value));
-    if (skipped) {
-      issues.push({
-        severity: "info",
-        check: "commands",
-        ruleId: "commands/package-json-missing",
-        line: skipped.line,
-        message: "package.json missing or unparseable \u2014 command checks skipped",
-        suggestion: "Add a parseable package.json at the project root so script, npx, and tool references can be validated."
-      });
+function buildCommandPattern(cmd) {
+  const tokens = cmd.split(/\s+/).filter(Boolean);
+  const escaped = tokens.map((t2) => t2.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+  if (tokens.length === 1) {
+    return new RegExp(`(?<![A-Za-z0-9_\\-])${escaped[0]}(?![A-Za-z0-9_\\-])`, "i");
+  }
+  const body = escaped.join("[\\s\\-_]+");
+  return new RegExp(`(?<![A-Za-z0-9])${body}(?![A-Za-z0-9])`, "i");
+}
+function commandIsEnforced(cmd, settings) {
+  const pattern = buildCommandPattern(cmd);
+  for (const s of settings) {
+    for (const entry of [...s.permissions?.deny ?? [], ...s.permissions?.ask ?? []]) {
+      if (pattern.test(entry)) return true;
+    }
+    for (const h2 of [...s.hooks?.PreToolUse ?? [], ...s.hooks?.Stop ?? []]) {
+      if (pattern.test(h2.matcher || "")) return true;
+      for (const sub of h2.hooks ?? []) {
+        if (pattern.test(sub.command || "")) return true;
+      }
+    }
+  }
+  return false;
+}
+function checkHardEnforcement(file2, settings) {
+  const issues = [];
+  const lines = file2.content.split("\n");
+  for (let i2 = 0; i2 < lines.length; i2++) {
+    const line = lines[i2];
+    const match = findInviolableCommand(line);
+    if (!match) continue;
+    const cmd = canonicalizeCommand(match.command);
+    if (!cmd) continue;
+    if (commandIsEnforced(cmd, settings)) continue;
+    const suggestion = match.framing.toUpperCase() === "ALWAYS" ? `Rules in always-loaded files are advisory. For \`${cmd}\`, add a hook in .claude/settings.json (e.g. a PreToolUse or Stop hook that runs or verifies \`${cmd}\`) so the requirement doesn't depend on the agent remembering.` : `Rules in always-loaded files are advisory. For \`${cmd}\`, add a PreToolUse hook (or permissions.deny entry) in .claude/settings.json so the command is physically blocked.`;
+    issues.push({
+      severity: "info",
+      check: "tier-tokens",
+      ruleId: "tier-tokens/hard-enforcement-missing",
+      line: i2 + 1,
+      message: `Inviolable framing ("${line.trim().slice(0, 80)}") without a hook to back it up`,
+      suggestion
+    });
+  }
+  return issues;
+}
+async function checkTierTokens(file2, projectRoot, thresholds = DEFAULT_TOKEN_THRESHOLDS, includeGlobal = false) {
+  if (!isAlwaysLoaded(file2)) return [];
+  const issues = [];
+  const threshold = thresholds.tierBreakdown;
+  if (file2.totalTokens >= threshold) {
+    const sectionCosts = computeSectionCosts(file2);
+    if (sectionCosts.length > 0) {
+      const top = sectionCosts.slice(0, TOP_SECTIONS_TO_REPORT);
+      const heaviest = top[0];
+      const pct = Math.round(heaviest.tokens / file2.totalTokens * 100);
+      const detail = top.map((s) => `  - "${s.title}" (L${s.line}): ~${s.tokens.toLocaleString()} tokens`).join("\n");
+      issues.push({
+        severity: "info",
+        check: "tier-tokens",
+        ruleId: "tier-tokens/section-breakdown",
+        line: heaviest.line,
+        message: `${file2.totalTokens.toLocaleString()} tokens loaded every session \u2014 heaviest top-level section${top.length === 1 ? "" : "s"}:`,
+        detail,
+        suggestion: `"${heaviest.title}" is ~${heaviest.tokens.toLocaleString()} tokens (${pct}% of file). Consider demoting to an on-demand tier (skill, subagent, or memory) so it loads only when relevant.`
+      });
+    }
+  }
+  const settings = loadSettingsSources(projectRoot, includeGlobal);
+  issues.push(...checkHardEnforcement(file2, settings));
+  return issues;
+}
+function checkAggregateTierTokens(files, thresholds = DEFAULT_TOKEN_THRESHOLDS) {
+  const alwaysLoaded = files.filter(isAlwaysLoaded);
+  if (alwaysLoaded.length < 2) return null;
+  const total = alwaysLoaded.reduce((sum, f) => sum + f.totalTokens, 0);
+  const threshold = thresholds.tierAggregate;
+  if (total < threshold) return null;
+  const breakdown = alwaysLoaded.slice().sort((a, b2) => b2.totalTokens - a.totalTokens).slice(0, 5).map((f) => `  - ${f.relativePath}: ~${f.totalTokens.toLocaleString()} tokens`).join("\n");
+  return {
+    severity: "warning",
+    check: "tier-tokens",
+    ruleId: "tier-tokens/aggregate",
+    line: 0,
+    message: `${alwaysLoaded.length} always-loaded files total ${total.toLocaleString()} tokens \u2014 loaded every session`,
+    detail: breakdown,
+    suggestion: "Consider moving the largest files or their heaviest sections to on-demand tiers (skills, subagents, memory)."
+  };
+}
+var ALWAYS_LOADED_NAMES, TOP_SECTIONS_TO_REPORT, FRAMING_TOKEN, FRAMING_COMMAND_GAP, settingsCache;
+var init_tier_tokens = __esm({
+  "src/core/checks/tier-tokens.ts"() {
+    "use strict";
+    init_define_WEB_FIRST_SEGMENTS();
+    init_main3();
+    init_tokens();
+    init_fs();
+    init_tokens2();
+    ALWAYS_LOADED_NAMES = [
+      "CLAUDE.md",
+      "CLAUDE.local.md",
+      "AGENTS.md",
+      "AGENTS.override.md",
+      "AGENT.md",
+      "GEMINI.md",
+      ".cursorrules",
+      ".windsurfrules",
+      ".clinerules",
+      ".aiderules",
+      ".continuerules",
+      ".rules",
+      ".goosehints",
+      "replit.md",
+      ".github/copilot-instructions.md",
+      ".junie/guidelines.md",
+      ".junie/AGENTS.md",
+      ".goose/instructions.md"
+    ];
+    TOP_SECTIONS_TO_REPORT = 3;
+    FRAMING_TOKEN = /(?<![\w'.-])(never|always|don'?t|do\s+not|must\s+not)(?![\w'.-])/gi;
+    FRAMING_COMMAND_GAP = 80;
+    settingsCache = null;
+  }
+});
+
+// src/core/checks/commands.ts
+import * as fs7 from "node:fs";
+import * as path8 from "node:path";
+function isManagerBuiltin(manager, sub) {
+  return PM_MANAGER_BUILTINS[manager]?.has(sub) ?? false;
+}
+function scriptNameFromMatch(match) {
+  const [, manager, explicitRun, name] = match;
+  if (name.startsWith("-")) return null;
+  if (manager && !explicitRun && PM_BUILTIN_SUBCOMMANDS.has(name)) return null;
+  if (manager && !explicitRun && isManagerBuiltin(manager, name)) return null;
+  return name;
+}
+function extractNpxPackage(cmd) {
+  if (!/^npx\b/.test(cmd)) return null;
+  const tokens = cmd.split(/\s+/).slice(1);
+  for (let i2 = 0; i2 < tokens.length; i2++) {
+    const t2 = tokens[i2];
+    if (t2 === "-p" || t2 === "--package") {
+      const v2 = tokens[i2 + 1];
+      if (v2 && !v2.startsWith("-")) return v2;
+      continue;
+    }
+    if (t2.startsWith("-p=") || t2.startsWith("--package=")) {
+      return t2.slice(t2.indexOf("=") + 1) || null;
+    }
+    if (t2.startsWith("-")) continue;
+    return t2;
+  }
+  return null;
+}
+function wouldNeedPackageJson(cmd) {
+  const scriptMatch = cmd.match(NPM_SCRIPT_PATTERN);
+  if (scriptMatch && scriptNameFromMatch(scriptMatch) !== null) return true;
+  const shorthandMatch = cmd.match(PKG_SHORTHAND_PATTERN);
+  if (shorthandMatch && !isManagerBuiltin(shorthandMatch[1], shorthandMatch[2])) return true;
+  return /^npx\b/.test(cmd) || PKG_DEPENDENT_TOOL_PATTERN.test(cmd);
+}
+function loadDeniedCommandPrefixes(projectRoot) {
+  const prefixes = [];
+  for (const rel of ["settings.json", "settings.local.json"]) {
+    let content;
+    try {
+      content = stripBom(fs7.readFileSync(path8.join(projectRoot, ".claude", rel), "utf-8"));
+    } catch {
+      continue;
+    }
+    const data = parse2(content, [], { allowTrailingComma: true });
+    const deny = data?.permissions?.deny;
+    if (!Array.isArray(deny)) continue;
+    for (const entry of deny) {
+      if (typeof entry !== "string") continue;
+      const inner = entry.replace(/^[A-Za-z]+\((.*)\)$/, "$1");
+      const prefix = inner.replace(/:?\*+$/, "").trim();
+      if (prefix) prefixes.push(prefix);
+    }
+  }
+  return prefixes;
+}
+function isDeniedCommand(cmd, deniedPrefixes) {
+  return deniedPrefixes.some((p2) => cmd === p2 || cmd.startsWith(`${p2} `));
+}
+function isProhibitedMention(lines, ref) {
+  const line = lines[ref.line - 1] ?? "";
+  const masked = maskCodeSpans(line, inlineCodeSpans(line));
+  const prefix = masked.slice(0, Math.max(0, ref.column - 1));
+  const clause = prefix.split(CLAUSE_TERMINATOR).pop() ?? "";
+  return PROHIBITION_TOKEN.test(clause);
+}
+async function checkCommands(file2, projectRoot) {
+  const issues = [];
+  const pkgJson = loadPackageJson(projectRoot);
+  const makefile = loadMakefile(projectRoot);
+  const deniedPrefixes = loadDeniedCommandPrefixes(projectRoot);
+  const contentLines = file2.content.split("\n");
+  if (!pkgJson) {
+    const skipped = file2.references.commands.find((ref) => wouldNeedPackageJson(ref.value));
+    if (skipped) {
+      issues.push({
+        severity: "info",
+        check: "commands",
+        ruleId: "commands/package-json-missing",
+        line: skipped.line,
+        message: "package.json missing or unparseable \u2014 command checks skipped",
+        suggestion: "Add a parseable package.json at the project root so script, npx, and tool references can be validated."
+      });
     }
   }
   issues.push(...checkUnknownSubcommand(file2, projectRoot, pkgJson));
@@ -24188,9 +24547,10 @@ async function checkCommands(file2, projectRoot) {
       };
       if (!(pkgName in allDeps)) {
         if (isDeniedCommand(cmd, deniedPrefixes)) continue;
-        const binPath = path7.join(projectRoot, "node_modules", ".bin", pkgName);
+        if (isProhibitedMention(contentLines, ref)) continue;
+        const binPath = path8.join(projectRoot, "node_modules", ".bin", pkgName);
         try {
-          fs6.accessSync(binPath);
+          fs7.accessSync(binPath);
         } catch {
           issues.push({
             severity: "warning",
@@ -24238,9 +24598,9 @@ async function checkCommands(file2, projectRoot) {
         ...pkgJson.optionalDependencies
       };
       if (!(pkgName in allDeps)) {
-        const binPath = path7.join(projectRoot, "node_modules", ".bin", tool);
+        const binPath = path8.join(projectRoot, "node_modules", ".bin", tool);
         try {
-          fs6.accessSync(binPath);
+          fs7.accessSync(binPath);
         } catch {
           issues.push({
             severity: "warning",
@@ -24284,7 +24644,7 @@ function checkUnknownSubcommand(file2, projectRoot, pkgJson) {
 }
 function loadMakefile(projectRoot) {
   try {
-    return stripBom(fs6.readFileSync(path7.join(projectRoot, "Makefile"), "utf-8"));
+    return stripBom(fs7.readFileSync(path8.join(projectRoot, "Makefile"), "utf-8"));
   } catch {
     return null;
   }
@@ -24302,7 +24662,7 @@ function hasMakeTarget(makefile, target) {
   const pattern = new RegExp(`^${escaped}\\s*:(?!:?=)`, "m");
   return pattern.test(makefile);
 }
-var NPM_SCRIPT_PATTERN, MAKE_PATTERN, PM_BUILTIN_SUBCOMMANDS, PM_MANAGER_BUILTINS, PKG_DEPENDENT_TOOL_PATTERN, BIN_TO_PACKAGE, PKG_SHORTHAND_PATTERN;
+var NPM_SCRIPT_PATTERN, MAKE_PATTERN, PM_BUILTIN_SUBCOMMANDS, PM_MANAGER_BUILTINS, PKG_DEPENDENT_TOOL_PATTERN, BIN_TO_PACKAGE, PKG_SHORTHAND_PATTERN, PROHIBITION_TOKEN, CLAUSE_TERMINATOR;
 var init_commands = __esm({
   "src/core/checks/commands.ts"() {
     "use strict";
@@ -24311,6 +24671,7 @@ var init_commands = __esm({
     init_fs();
     init_exit_status();
     init_cli_subcommands();
+    init_tier_tokens();
     NPM_SCRIPT_PATTERN = /^(?:npm\s+run|(pnpm|yarn|bun)(?:\s+(run))?)\s+(\S+)/;
     MAKE_PATTERN = /^make\s+\S/;
     PM_BUILTIN_SUBCOMMANDS = /* @__PURE__ */ new Set([
@@ -24380,17 +24741,19 @@ var init_commands = __esm({
       tsc: "typescript"
     };
     PKG_SHORTHAND_PATTERN = /^(npm|pnpm|yarn|bun)\s+(test|start|build|dev|lint|format|check|typecheck|clean|serve|preview|e2e)\b/;
+    PROHIBITION_TOKEN = /\b(?:never|don['’]?t|do\s+not|must\s+not|avoid)\b/i;
+    CLAUSE_TERMINATOR = /[.!?;—]|\s--(?=\s|$)/;
   }
 });
 
 // src/core/checks/staleness.ts
-import * as path8 from "node:path";
+import * as path9 from "node:path";
 async function checkStaleness(file2, projectRoot) {
   const issues = [];
   if (!await isGitRepo(projectRoot)) {
     return issues;
   }
-  const relativePath = path8.relative(projectRoot, file2.filePath).replace(/\\/g, "/");
+  const relativePath = path9.relative(projectRoot, file2.filePath).replace(/\\/g, "/");
   const lastModified = await getFileLastModified(projectRoot, relativePath);
   if (!lastModified || isNaN(lastModified.getTime())) {
     return issues;
@@ -24506,322 +24869,6 @@ var init_suppressions = __esm({
   }
 });
 
-// src/core/checks/tokens.ts
-function resolveTokenThresholds(overrides) {
-  if (!overrides) return DEFAULT_TOKEN_THRESHOLDS;
-  const merged = { ...DEFAULT_TOKEN_THRESHOLDS, ...overrides };
-  if (merged.info >= merged.warning || merged.warning >= merged.error) {
-    console.error(
-      `Warning: token thresholds should satisfy info < warning < error (got ${merged.info}, ${merged.warning}, ${merged.error}) \u2014 using defaults`
-    );
-    return DEFAULT_TOKEN_THRESHOLDS;
-  }
-  return merged;
-}
-async function checkTokens(file2, _projectRoot, thresholds = DEFAULT_TOKEN_THRESHOLDS) {
-  const issues = [];
-  const tokens = file2.totalTokens;
-  if (tokens >= thresholds.error) {
-    issues.push({
-      severity: "error",
-      check: "tokens",
-      ruleId: "tokens/excessive",
-      line: 1,
-      message: `${tokens.toLocaleString()} tokens \u2014 consumes significant context window space`,
-      suggestion: "Consider splitting into focused sections or removing redundant content."
-    });
-  } else if (tokens >= thresholds.warning) {
-    issues.push({
-      severity: "warning",
-      check: "tokens",
-      ruleId: "tokens/large",
-      line: 1,
-      message: `${tokens.toLocaleString()} tokens \u2014 large context file`,
-      suggestion: "Consider trimming \u2014 research shows diminishing returns past ~300 lines."
-    });
-  } else if (tokens >= thresholds.info) {
-    issues.push({
-      severity: "info",
-      check: "tokens",
-      ruleId: "tokens/info",
-      line: 1,
-      message: `Uses ~${tokens.toLocaleString()} tokens per session`
-    });
-  }
-  return issues;
-}
-function checkAggregateTokens(files, thresholds = DEFAULT_TOKEN_THRESHOLDS) {
-  const total = files.reduce((sum, f) => sum + f.tokens, 0);
-  if (total >= thresholds.aggregate && files.length > 1) {
-    return {
-      severity: "warning",
-      check: "tokens",
-      ruleId: "tokens/aggregate",
-      line: 0,
-      message: `${files.length} context files consume ${total.toLocaleString()} tokens combined`,
-      suggestion: "Consider consolidating or trimming to reduce per-session context cost."
-    };
-  }
-  return null;
-}
-var DEFAULT_TOKEN_THRESHOLDS;
-var init_tokens2 = __esm({
-  "src/core/checks/tokens.ts"() {
-    "use strict";
-    init_define_WEB_FIRST_SEGMENTS();
-    DEFAULT_TOKEN_THRESHOLDS = {
-      info: 1e3,
-      warning: 3e3,
-      error: 8e3,
-      aggregate: 5e3,
-      tierBreakdown: 1e3,
-      tierAggregate: 4e3
-    };
-  }
-});
-
-// src/core/checks/tier-tokens.ts
-import * as fs7 from "node:fs";
-import * as os2 from "node:os";
-import * as path9 from "node:path";
-function hasFrontmatterList(content, field) {
-  const lines = content.split("\n");
-  if (lines[0]?.trim() !== "---") return false;
-  const fieldPattern = new RegExp(`^${field}\\s*:\\s*(.*)$`);
-  for (let i2 = 1; i2 < lines.length; i2++) {
-    const line = lines[i2];
-    if (line.trim() === "---") return false;
-    const match = line.match(fieldPattern);
-    if (match) {
-      const val = match[1].trim();
-      if (val && val !== "[]") return true;
-      for (let j3 = i2 + 1; j3 < lines.length; j3++) {
-        const next = lines[j3];
-        if (next.trim() === "---") return false;
-        if (next.trim() === "") continue;
-        if (next.trim().startsWith("- ")) return true;
-        break;
-      }
-    }
-  }
-  return false;
-}
-function frontmatterScalar(content, field) {
-  const lines = content.split("\n");
-  if (lines[0]?.trim() !== "---") return null;
-  const fieldPattern = new RegExp(`^${field}\\s*:\\s*(.*)$`);
-  for (let i2 = 1; i2 < lines.length; i2++) {
-    if (lines[i2].trim() === "---") return null;
-    const match = lines[i2].match(fieldPattern);
-    if (match) return match[1].trim().replace(/^['"]|['"]$/g, "") || null;
-  }
-  return null;
-}
-function isAlwaysLoaded(file2) {
-  const rel = file2.relativePath.replace(/\\/g, "/");
-  if (rel.endsWith(".mdc")) return false;
-  if (rel.startsWith(".github/instructions/")) return false;
-  if (rel.includes("/rules/")) {
-    if (hasFrontmatterList(file2.content, "paths")) return false;
-    if (hasFrontmatterList(file2.content, "globs")) return false;
-    if (rel.includes(".windsurf/rules/")) {
-      const trigger = frontmatterScalar(file2.content, "trigger");
-      if (trigger && trigger.toLowerCase() !== "always_on") return false;
-    }
-    return true;
-  }
-  const basename4 = rel.split("/").pop() ?? "";
-  for (const name of ALWAYS_LOADED_NAMES) {
-    if (name.includes("/")) {
-      if (rel === name || rel.endsWith("/" + name)) return true;
-    } else if (basename4 === name) {
-      return true;
-    }
-  }
-  return false;
-}
-function computeSectionCosts(file2) {
-  if (file2.sections.length === 0) return [];
-  const hasH2 = file2.sections.some((s) => s.level === 2);
-  const topLevel = hasH2 ? 2 : 1;
-  const lines = file2.content.split("\n");
-  return file2.sections.filter((s) => s.level === topLevel).map((s) => {
-    const body = lines.slice(s.startLine - 1, s.endLine).join("\n");
-    return { title: s.title, line: s.startLine, tokens: countTokens(body) };
-  }).sort((a, b2) => b2.tokens - a.tokens);
-}
-function fingerprintFiles(paths) {
-  return paths.map((p2) => {
-    try {
-      const st2 = fs7.statSync(p2);
-      return `${st2.mtimeMs}:${st2.size}`;
-    } catch {
-      return "absent";
-    }
-  }).join("|");
-}
-function loadSettingsSources(projectRoot, includeGlobal) {
-  const candidates = [
-    path9.join(projectRoot, ".claude", "settings.json"),
-    path9.join(projectRoot, ".claude", "settings.local.json")
-  ];
-  if (includeGlobal) {
-    candidates.push(path9.join(os2.homedir(), ".claude", "settings.json"));
-  }
-  const fingerprint = fingerprintFiles(candidates);
-  if (settingsCache?.root === projectRoot && settingsCache.includeGlobal === includeGlobal && settingsCache.fingerprint === fingerprint) {
-    return settingsCache.data;
-  }
-  const sources = [];
-  for (const p2 of candidates) {
-    let content;
-    try {
-      content = stripBom(fs7.readFileSync(p2, "utf-8"));
-    } catch {
-      continue;
-    }
-    const errors = [];
-    const data = parse2(content, errors, { allowTrailingComma: true });
-    if (errors.length > 0) {
-      console.warn(
-        `ctxlint: could not parse ${p2}: ${printParseErrorCode(errors[0].error)} at offset ${errors[0].offset}`
-      );
-      continue;
-    }
-    if (!data || typeof data !== "object") continue;
-    sources.push(data);
-  }
-  settingsCache = { root: projectRoot, includeGlobal, fingerprint, data: sources };
-  return sources;
-}
-function canonicalizeCommand(backticked) {
-  const beforeFlags = backticked.trim().split(/\s+--?/, 1)[0];
-  return beforeFlags.replace(/\s+/g, " ");
-}
-function buildCommandPattern(cmd) {
-  const tokens = cmd.split(/\s+/).filter(Boolean);
-  const escaped = tokens.map((t2) => t2.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
-  if (tokens.length === 1) {
-    return new RegExp(`(?<![A-Za-z0-9_\\-])${escaped[0]}(?![A-Za-z0-9_\\-])`, "i");
-  }
-  const body = escaped.join("[\\s\\-_]+");
-  return new RegExp(`(?<![A-Za-z0-9])${body}(?![A-Za-z0-9])`, "i");
-}
-function commandIsEnforced(cmd, settings) {
-  const pattern = buildCommandPattern(cmd);
-  for (const s of settings) {
-    for (const entry of [...s.permissions?.deny ?? [], ...s.permissions?.ask ?? []]) {
-      if (pattern.test(entry)) return true;
-    }
-    for (const h2 of [...s.hooks?.PreToolUse ?? [], ...s.hooks?.Stop ?? []]) {
-      if (pattern.test(h2.matcher || "")) return true;
-      for (const sub of h2.hooks ?? []) {
-        if (pattern.test(sub.command || "")) return true;
-      }
-    }
-  }
-  return false;
-}
-function checkHardEnforcement(file2, settings) {
-  const issues = [];
-  const lines = file2.content.split("\n");
-  for (let i2 = 0; i2 < lines.length; i2++) {
-    const line = lines[i2];
-    const match = line.match(INVIOLABLE_WITH_COMMAND);
-    if (!match) continue;
-    const cmd = canonicalizeCommand(match[2]);
-    if (!cmd) continue;
-    if (commandIsEnforced(cmd, settings)) continue;
-    const suggestion = match[1].toUpperCase() === "ALWAYS" ? `Rules in always-loaded files are advisory. For \`${cmd}\`, add a hook in .claude/settings.json (e.g. a PreToolUse or Stop hook that runs or verifies \`${cmd}\`) so the requirement doesn't depend on the agent remembering.` : `Rules in always-loaded files are advisory. For \`${cmd}\`, add a PreToolUse hook (or permissions.deny entry) in .claude/settings.json so the command is physically blocked.`;
-    issues.push({
-      severity: "info",
-      check: "tier-tokens",
-      ruleId: "tier-tokens/hard-enforcement-missing",
-      line: i2 + 1,
-      message: `Inviolable framing ("${line.trim().slice(0, 80)}") without a hook to back it up`,
-      suggestion
-    });
-  }
-  return issues;
-}
-async function checkTierTokens(file2, projectRoot, thresholds = DEFAULT_TOKEN_THRESHOLDS, includeGlobal = false) {
-  if (!isAlwaysLoaded(file2)) return [];
-  const issues = [];
-  const threshold = thresholds.tierBreakdown;
-  if (file2.totalTokens >= threshold) {
-    const sectionCosts = computeSectionCosts(file2);
-    if (sectionCosts.length > 0) {
-      const top = sectionCosts.slice(0, TOP_SECTIONS_TO_REPORT);
-      const heaviest = top[0];
-      const pct = Math.round(heaviest.tokens / file2.totalTokens * 100);
-      const detail = top.map((s) => `  - "${s.title}" (L${s.line}): ~${s.tokens.toLocaleString()} tokens`).join("\n");
-      issues.push({
-        severity: "info",
-        check: "tier-tokens",
-        ruleId: "tier-tokens/section-breakdown",
-        line: heaviest.line,
-        message: `${file2.totalTokens.toLocaleString()} tokens loaded every session \u2014 heaviest top-level section${top.length === 1 ? "" : "s"}:`,
-        detail,
-        suggestion: `"${heaviest.title}" is ~${heaviest.tokens.toLocaleString()} tokens (${pct}% of file). Consider demoting to an on-demand tier (skill, subagent, or memory) so it loads only when relevant.`
-      });
-    }
-  }
-  const settings = loadSettingsSources(projectRoot, includeGlobal);
-  issues.push(...checkHardEnforcement(file2, settings));
-  return issues;
-}
-function checkAggregateTierTokens(files, thresholds = DEFAULT_TOKEN_THRESHOLDS) {
-  const alwaysLoaded = files.filter(isAlwaysLoaded);
-  if (alwaysLoaded.length < 2) return null;
-  const total = alwaysLoaded.reduce((sum, f) => sum + f.totalTokens, 0);
-  const threshold = thresholds.tierAggregate;
-  if (total < threshold) return null;
-  const breakdown = alwaysLoaded.slice().sort((a, b2) => b2.totalTokens - a.totalTokens).slice(0, 5).map((f) => `  - ${f.relativePath}: ~${f.totalTokens.toLocaleString()} tokens`).join("\n");
-  return {
-    severity: "warning",
-    check: "tier-tokens",
-    ruleId: "tier-tokens/aggregate",
-    line: 0,
-    message: `${alwaysLoaded.length} always-loaded files total ${total.toLocaleString()} tokens \u2014 loaded every session`,
-    detail: breakdown,
-    suggestion: "Consider moving the largest files or their heaviest sections to on-demand tiers (skills, subagents, memory)."
-  };
-}
-var ALWAYS_LOADED_NAMES, TOP_SECTIONS_TO_REPORT, INVIOLABLE_WITH_COMMAND, settingsCache;
-var init_tier_tokens = __esm({
-  "src/core/checks/tier-tokens.ts"() {
-    "use strict";
-    init_define_WEB_FIRST_SEGMENTS();
-    init_main3();
-    init_tokens();
-    init_fs();
-    init_tokens2();
-    ALWAYS_LOADED_NAMES = [
-      "CLAUDE.md",
-      "CLAUDE.local.md",
-      "AGENTS.md",
-      "AGENTS.override.md",
-      "AGENT.md",
-      "GEMINI.md",
-      ".cursorrules",
-      ".windsurfrules",
-      ".clinerules",
-      ".aiderules",
-      ".continuerules",
-      ".rules",
-      ".goosehints",
-      "replit.md",
-      ".github/copilot-instructions.md",
-      ".junie/guidelines.md",
-      ".junie/AGENTS.md",
-      ".goose/instructions.md"
-    ];
-    TOP_SECTIONS_TO_REPORT = 3;
-    INVIOLABLE_WITH_COMMAND = /\b(NEVER|ALWAYS|DON'?T|DO NOT|MUST NOT)\b[^.!?`]{0,80}`([^`]+)`/i;
-    settingsCache = null;
-  }
-});
-
 // src/utils/similarity.ts
 function jaccardSimilarityFromSets(a, b2, opts = {}) {
   const bothEmptyIsIdentical = opts.bothEmptyIsIdentical ?? false;
@@ -28968,7 +29015,7 @@ import { readFileSync as readFileSync8 } from "node:fs";
 import { resolve as resolve15, dirname as dirname7 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 function loadVersion() {
-  if (true) return "0.20.0";
+  if (true) return "0.23.0";
   try {
     const __dir = dirname7(fileURLToPath2(import.meta.url));
     const pkgPath = resolve15(__dir, "../package.json");

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@yawlabs/ctxlint",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "mcpName": "io.github.YawLabs/ctxlint",
   "description": "Lint your AI agent context files, MCP server configs, and session data against your actual codebase",
   "bin": {
-    "ctxlint": "dist/index.js"
+    "ctxlint": "bin/ctxlint.mjs"
   },
   "type": "module",
   "exports": {
@@ -13,6 +13,7 @@
   "scripts": {
     "build": "node build.mjs",
     "dev": "node build.mjs",
+    "prepublishOnly": "node build.mjs",
     "generate": "node scripts/generate-catalog-prose.mjs",
     "generate:check": "node scripts/generate-catalog-prose.mjs --check",
     "pretest": "node build.mjs",
@@ -59,6 +60,7 @@
   ],
   "files": [
     "dist/index.js",
+    "bin/ctxlint.mjs",
     ".pre-commit-hooks.yaml",
     "action.yml",
     "CONTEXT_LINT_SPEC.md",