@yawlabs/ctxlint 0.23.0 → 0.24.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.23.0 --strict
+  entry: npx @yawlabs/ctxlint@0.24.0 --strict
   language: node
   always_run: true
   pass_filenames: false

package/dist/index.js

@@ -24050,150 +24050,7 @@ var init_cli_subcommands = __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 fs6 from "node:fs";
-import * as os2 from "node:os";
-import * as path7 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);
-}
+// src/utils/markdown.ts
 function inlineCodeSpans(line) {
   const spans = [];
   const re2 = /`([^`]+)`/g;
@@ -24210,200 +24067,66 @@ function maskCodeSpans(line, spans) {
   }
   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 nonProseLineMask(lines) {
+  return classifyLines(lines).map((c3) => c3.fence || c3.comment);
 }
-function fingerprintFiles(paths) {
-  return paths.map((p2) => {
-    try {
-      const st2 = fs6.statSync(p2);
-      return `${st2.mtimeMs}:${st2.size}`;
-    } catch {
-      return "absent";
-    }
-  }).join("|");
+function htmlCommentLineMask(lines) {
+  return classifyLines(lines).map((c3) => c3.comment);
 }
-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(p2, "utf-8"));
-    } catch {
+function classifyLines(lines) {
+  const out = lines.map(() => ({ fence: false, comment: false }));
+  let inFence = false;
+  let inHtmlComment = false;
+  for (let i2 = 0; i2 < lines.length; i2++) {
+    const raw = lines[i2];
+    const trimmed2 = raw.trimStart();
+    if (trimmed2.startsWith("```")) {
+      out[i2].fence = true;
+      inFence = !inFence;
       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}`
-      );
+    if (inFence) {
+      out[i2].fence = true;
       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;
+    const probe = maskCodeSpans(trimmed2, inlineCodeSpans(trimmed2));
+    if (inHtmlComment) {
+      out[i2].comment = true;
+      if (probe.includes("-->")) inHtmlComment = false;
+      continue;
     }
-    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;
-      }
+    if (HTML_COMMENT.test(probe.replace(HTML_COMMENT_PAIR, ""))) {
+      out[i2].comment = true;
+      inHtmlComment = true;
     }
   }
-  return false;
+  return out;
 }
-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;
+function stripInlineHtmlComments(line) {
+  return line.replace(HTML_COMMENT_PAIR, (m) => "#".repeat(m.length));
 }
-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.`
-      });
-    }
+function htmlCommentSpans(line) {
+  const re2 = /<!--[\s\S]*?-->/g;
+  const spans = [];
+  let m;
+  while ((m = re2.exec(line)) !== null) {
+    spans.push({ start: m.index, end: m.index + m[0].length });
   }
-  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)."
-  };
+  return spans;
 }
-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"() {
+var HTML_COMMENT_PAIR, HTML_COMMENT;
+var init_markdown = __esm({
+  "src/utils/markdown.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;
+    HTML_COMMENT_PAIR = /<!--[\s\S]*?-->/g;
+    HTML_COMMENT = /<!--/;
   }
 });
 
 // src/core/checks/commands.ts
-import * as fs7 from "node:fs";
-import * as path8 from "node:path";
+import * as fs6 from "node:fs";
+import * as path7 from "node:path";
 function isManagerBuiltin(manager, sub) {
   return PM_MANAGER_BUILTINS[manager]?.has(sub) ?? false;
 }
@@ -24444,7 +24167,7 @@ function loadDeniedCommandPrefixes(projectRoot) {
   for (const rel of ["settings.json", "settings.local.json"]) {
     let content;
     try {
-      content = stripBom(fs7.readFileSync(path8.join(projectRoot, ".claude", rel), "utf-8"));
+      content = stripBom(fs6.readFileSync(path7.join(projectRoot, ".claude", rel), "utf-8"));
     } catch {
       continue;
     }
@@ -24463,21 +24186,48 @@ function loadDeniedCommandPrefixes(projectRoot) {
 function isDeniedCommand(cmd, deniedPrefixes) {
   return deniedPrefixes.some((p2) => cmd === p2 || cmd.startsWith(`${p2} `));
 }
-function isProhibitedMention(lines, ref) {
-  const line = lines[ref.line - 1] ?? "";
+function narrowAtContrastComma(clause) {
+  const idx = clause.lastIndexOf(",");
+  if (idx === -1) return clause;
+  const tail = clause.slice(idx + 1);
+  return RECOMMENDATION_VERB.test(tail) ? tail : clause;
+}
+function isProhibitedAt(rawLine, offset) {
+  const line = stripInlineHtmlComments(rawLine);
   const masked = maskCodeSpans(line, inlineCodeSpans(line));
-  const prefix = masked.slice(0, Math.max(0, ref.column - 1));
-  const clause = prefix.split(CLAUSE_TERMINATOR).pop() ?? "";
+  const prefix = masked.slice(0, Math.max(0, offset));
+  const clause = narrowAtContrastComma(prefix.split(CLAUSE_TERMINATOR).pop() ?? "");
   return PROHIBITION_TOKEN.test(clause);
 }
+function isProhibitedRef(lines, ref) {
+  return isProhibitedAt(lines[ref.line - 1] ?? "", ref.column - 1);
+}
+function isProhibitedInvocation(lines, inv) {
+  const line = lines[inv.line - 1] ?? "";
+  for (const span of inlineCodeSpans(line)) {
+    if (span.content.trim() === inv.cmd) return isProhibitedAt(line, span.start);
+  }
+  const idx = line.indexOf(inv.cmd);
+  return idx < 0 ? false : isProhibitedAt(line, idx);
+}
 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");
+  const commentLines = htmlCommentLineMask(contentLines);
+  const inHtmlComment = (line, column) => {
+    if (commentLines[line - 1] === true) return true;
+    const offset = column - 1;
+    return htmlCommentSpans(contentLines[line - 1] ?? "").some(
+      (s) => offset >= s.start && offset < s.end
+    );
+  };
   if (!pkgJson) {
-    const skipped = file2.references.commands.find((ref) => wouldNeedPackageJson(ref.value));
+    const skipped = file2.references.commands.find(
+      (ref) => wouldNeedPackageJson(ref.value) && !inHtmlComment(ref.line, ref.column) && !isDeniedCommand(ref.value, deniedPrefixes) && !isProhibitedRef(contentLines, ref)
+    );
     if (skipped) {
       issues.push({
         severity: "info",
@@ -24489,8 +24239,11 @@ async function checkCommands(file2, projectRoot) {
       });
     }
   }
-  issues.push(...checkUnknownSubcommand(file2, projectRoot, pkgJson));
+  issues.push(
+    ...checkUnknownSubcommand(file2, projectRoot, pkgJson, deniedPrefixes, contentLines)
+  );
   for (const ref of file2.references.commands) {
+    if (inHtmlComment(ref.line, ref.column)) continue;
     const cmd = ref.value;
     const masked = analyzeMaskedExitStatus(cmd, pkgJson?.scripts);
     if (masked && !pipefailInScope(file2.content, ref.line)) {
@@ -24504,6 +24257,7 @@ async function checkCommands(file2, projectRoot) {
         suggestion: "Add `set -o pipefail` before the pipeline, drop the filter, or read `${PIPESTATUS[0]}` instead of `$?`."
       });
     }
+    if (isDeniedCommand(cmd, deniedPrefixes) || isProhibitedRef(contentLines, ref)) continue;
     const scriptMatch = cmd.match(NPM_SCRIPT_PATTERN);
     if (scriptMatch && pkgJson) {
       const scriptName = scriptNameFromMatch(scriptMatch);
@@ -24546,11 +24300,9 @@ async function checkCommands(file2, projectRoot) {
         ...pkgJson.optionalDependencies
       };
       if (!(pkgName in allDeps)) {
-        if (isDeniedCommand(cmd, deniedPrefixes)) continue;
-        if (isProhibitedMention(contentLines, ref)) continue;
-        const binPath = path8.join(projectRoot, "node_modules", ".bin", pkgName);
+        const binPath = path7.join(projectRoot, "node_modules", ".bin", pkgName);
         try {
-          fs7.accessSync(binPath);
+          fs6.accessSync(binPath);
         } catch {
           issues.push({
             severity: "warning",
@@ -24598,9 +24350,9 @@ async function checkCommands(file2, projectRoot) {
         ...pkgJson.optionalDependencies
       };
       if (!(pkgName in allDeps)) {
-        const binPath = path8.join(projectRoot, "node_modules", ".bin", tool);
+        const binPath = path7.join(projectRoot, "node_modules", ".bin", tool);
         try {
-          fs7.accessSync(binPath);
+          fs6.accessSync(binPath);
         } catch {
           issues.push({
             severity: "warning",
@@ -24615,7 +24367,7 @@ async function checkCommands(file2, projectRoot) {
   }
   return issues;
 }
-function checkUnknownSubcommand(file2, projectRoot, pkgJson) {
+function checkUnknownSubcommand(file2, projectRoot, pkgJson, deniedPrefixes, contentLines) {
   const bins = ownedBins(pkgJson);
   if (bins.length === 0) return [];
   const invocations = findBinInvocations(file2.content, new Set(bins.map((b2) => b2.name)));
@@ -24623,6 +24375,8 @@ function checkUnknownSubcommand(file2, projectRoot, pkgJson) {
   const resolved = /* @__PURE__ */ new Map();
   const issues = [];
   for (const inv of invocations) {
+    if (isDeniedCommand(inv.cmd, deniedPrefixes)) continue;
+    if (isProhibitedInvocation(contentLines, inv)) continue;
     if (!resolved.has(inv.bin)) {
       const bin = bins.find((b2) => b2.name === inv.bin);
       resolved.set(inv.bin, bin ? knownSubcommands(projectRoot, bin.entry) : null);
@@ -24644,7 +24398,7 @@ function checkUnknownSubcommand(file2, projectRoot, pkgJson) {
 }
 function loadMakefile(projectRoot) {
   try {
-    return stripBom(fs7.readFileSync(path8.join(projectRoot, "Makefile"), "utf-8"));
+    return stripBom(fs6.readFileSync(path7.join(projectRoot, "Makefile"), "utf-8"));
   } catch {
     return null;
   }
@@ -24662,7 +24416,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, PROHIBITION_TOKEN, CLAUSE_TERMINATOR;
+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, RECOMMENDATION_VERB;
 var init_commands = __esm({
   "src/core/checks/commands.ts"() {
     "use strict";
@@ -24671,7 +24425,7 @@ var init_commands = __esm({
     init_fs();
     init_exit_status();
     init_cli_subcommands();
-    init_tier_tokens();
+    init_markdown();
     NPM_SCRIPT_PATTERN = /^(?:npm\s+run|(pnpm|yarn|bun)(?:\s+(run))?)\s+(\S+)/;
     MAKE_PATTERN = /^make\s+\S/;
     PM_BUILTIN_SUBCOMMANDS = /* @__PURE__ */ new Set([
@@ -24743,17 +24497,18 @@ var init_commands = __esm({
     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|$)/;
+    RECOMMENDATION_VERB = /\b(?:run|use|call|invoke|execute|prefer|deploy|install)\b/i;
   }
 });
 
 // src/core/checks/staleness.ts
-import * as path9 from "node:path";
+import * as path8 from "node:path";
 async function checkStaleness(file2, projectRoot) {
   const issues = [];
   if (!await isGitRepo(projectRoot)) {
     return issues;
   }
-  const relativePath = path9.relative(projectRoot, file2.filePath).replace(/\\/g, "/");
+  const relativePath = path8.relative(projectRoot, file2.filePath).replace(/\\/g, "/");
   const lastModified = await getFileLastModified(projectRoot, relativePath);
   if (!lastModified || isNaN(lastModified.getTime())) {
     return issues;
@@ -24869,6 +24624,344 @@ 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 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 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");
+  const nonProse = nonProseLineMask(lines);
+  for (let i2 = 0; i2 < lines.length; i2++) {
+    if (nonProse[i2]) continue;
+    const line = stripInlineHtmlComments(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_markdown();
+    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/utils/similarity.ts
 function jaccardSimilarityFromSets(a, b2, opts = {}) {
   const bothEmptyIsIdentical = opts.bothEmptyIsIdentical ?? false;
@@ -29015,7 +29108,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.23.0";
+  if (true) return "0.24.0";
   try {
     const __dir = dirname7(fileURLToPath2(import.meta.url));
     const pkgPath = resolve15(__dir, "../package.json");
@@ -70107,6 +70200,13 @@ __export(cli_exports, {
 });
 import * as fs15 from "node:fs";
 import * as path20 from "node:path";
+function existsAsDirectory(p2) {
+  try {
+    return fs15.statSync(p2).isDirectory();
+  } catch {
+    return false;
+  }
+}
 function validateCheckNames(names, source) {
   const invalid = names.filter((n7) => n7 && !VALID_CHECKS.has(n7));
   if (invalid.length > 0) {
@@ -70130,6 +70230,12 @@ async function runCli() {
     false
   ).option("--no-ignore-file", "Disable .ctxlintignore suppression (see all findings)").option("--watch", "Re-lint on context file changes", false).action(async (projectPath, opts) => {
     const resolvedPath = path20.resolve(projectPath);
+    if (!existsAsDirectory(resolvedPath)) {
+      console.error(
+        `Error: ${resolvedPath} is not an existing directory. Check the path argument.`
+      );
+      process.exit(2);
+    }
     const { config: config2, options, activeChecks } = resolveSession(resolvedPath, opts);
     const spinner = options.format === "text" && !options.quiet ? ora("Scanning for context files...").start() : void 0;
     try {
@@ -70448,7 +70554,7 @@ function resolveDepth(raw) {
 }
 function resolveSession(resolvedPath, opts, throwOnConfigError = false) {
   const configPath = opts.config ? path20.resolve(opts.config) : void 0;
-  const config2 = configPath ? loadConfigFromPath(configPath, throwOnConfigError) : loadConfig(resolvedPath);
+  const config2 = configPath ? loadConfigFromPath(configPath, throwOnConfigError) : loadDiscoveredConfig(resolvedPath, throwOnConfigError);
   const mcpGlobal = opts.mcpGlobal || config2?.mcpGlobal || false;
   const mcpOnly = opts.mcpOnly || config2?.mcpOnly || false;
   const mcpFlag = opts.mcp || mcpGlobal || mcpOnly || config2?.mcp || false;
@@ -70516,6 +70622,16 @@ function resolveSession(resolvedPath, opts, throwOnConfigError = false) {
   const activeChecks = options.checks.filter((c3) => !options.ignore.includes(c3));
   return { config: config2, options, activeChecks };
 }
+function loadDiscoveredConfig(resolvedPath, throwOnError = false) {
+  try {
+    return loadConfig(resolvedPath);
+  } catch (err) {
+    if (throwOnError) throw err;
+    const detail = err instanceof Error ? err.message : String(err);
+    console.error(`Error: ${detail}`);
+    process.exit(2);
+  }
+}
 function loadConfigFromPath(configPath, throwOnError = false) {
   try {
     return loadConfigFromExplicitPath(configPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/ctxlint",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "mcpName": "io.github.YawLabs/ctxlint",
   "description": "Lint your AI agent context files, MCP server configs, and session data against your actual codebase",
   "bin": {