@event4u/agent-config 7.4.0 → 7.5.0

package/src/scripts/hooks/design_slop_hook.ts

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse anti-slop nudge — surfaces high-severity aesthetic tells in
+ * proposed UI content BEFORE the write (road-to-anti-slop-detector Phase 3).
+ *
+ * OPTIONAL, host-limited (pre_tool_use fires on ~2–3 hosts). The universal
+ * source of truth is the `lint_design_slop` linter / CI gate; this hook is a
+ * convenience layer that runs the same registry against the about-to-be-written
+ * content. Default-OFF: no-ops unless `hooks.design_slop.enabled: true` in
+ * `.agent-settings.yml`. fail_closed: false (never break a write for a flag).
+ *
+ * FLAGS, NEVER A BLOCK. On a P0/P1 finding it WARNS (exit 2 + reason); it never
+ * returns block (exit 1). Mirrors the injection-scan "warn, don't block" shape.
+ *
+ * Anti-loop degradation (council-required safety valve): a `file::rule`
+ * signature surfaced ≥ DEGRADE_AFTER times is downgraded to silent, so a
+ * deliberate-but-undeclared pattern the agent keeps re-writing never traps it.
+ * State: <root>/agents/runtime/state/design-slop-hook.json.
+ *
+ * Exit codes (dispatcher contract): 0 allow · 2 warn (+ JSON reason on stdout).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { type DesignContext } from "../design_slop_rules.js";
+import { loadDesignContext, scanFile } from "../lint_design_slop.js";
+
+const SETTINGS_FILE = ".agent-settings.yml";
+const EXIT_ALLOW = 0;
+const EXIT_WARN = 2;
+const DEGRADE_AFTER = 3; // surfaces of the same file::rule signature before going silent
+const UI_EXT = /\.(html|htm|css|scss|sass|less|vue|svelte|astro|jsx|tsx)$/i;
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+function isObject(v: unknown): v is JsonObject {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Minimal `.agent-settings.yml` reader for hooks.design_slop.enabled (mirrors injection-scan). */
+function enabled(root: string): boolean {
+  const f = path.join(root, SETTINGS_FILE);
+  let text: string;
+  try {
+    if (!fs.statSync(f).isFile()) return false;
+    text = fs.readFileSync(f, "utf-8");
+  } catch {
+    return false;
+  }
+  let inHooks = false;
+  let inDs = false;
+  for (const raw of text.split(/\r\n|\r|\n/)) {
+    const line = raw.replace(/\s+$/, "");
+    if (!line || line.replace(/^\s+/, "").startsWith("#")) continue;
+    if (!(line.startsWith(" ") || line.startsWith("\t"))) {
+      inHooks = /^hooks\s*:\s*$/.test(line);
+      inDs = false;
+      continue;
+    }
+    if (inHooks) {
+      if (/^\s+design_slop\s*:\s*$/.test(line)) {
+        inDs = true;
+        continue;
+      }
+      if (inDs && /^\s{0,3}\S/.test(line)) inDs = false;
+    }
+    if (inDs && /^\s+enabled\s*:\s*true\b/.test(line)) return true;
+  }
+  return false;
+}
+
+/** Best-effort: pull (toolName, filePath, proposedContent) from the PreToolUse envelope. */
+function extract(envelope: JsonObject): { file: string; content: string } | null {
+  const ti = envelope["tool_input"] ?? envelope["toolInput"] ?? envelope["input"];
+  if (!isObject(ti)) return null;
+  const fileVal = ti["file_path"] ?? ti["path"] ?? ti["filePath"];
+  const file = typeof fileVal === "string" ? fileVal : "";
+  // Edit → new_string/new_str; Write → content; some hosts → text
+  for (const key of ["content", "new_string", "new_str", "text", "newText"]) {
+    const v = ti[key];
+    if (typeof v === "string" && v.length > 0) return { file, content: v };
+  }
+  return null;
+}
+
+function stateFile(root: string): string {
+  return path.join(root, "agents", "runtime", "state", "design-slop-hook.json");
+}
+
+function readState(root: string): Record<string, number> {
+  try {
+    const t = fs.readFileSync(stateFile(root), "utf-8");
+    const parsed = JSON.parse(t);
+    return isObject(parsed) ? (parsed as Record<string, number>) : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeState(root: string, state: Record<string, number>): void {
+  try {
+    const sf = stateFile(root);
+    fs.mkdirSync(path.dirname(sf), { recursive: true });
+    fs.writeFileSync(sf, JSON.stringify(state, null, 2) + "\n");
+  } catch {
+    /* fail-open: never break a write because state could not persist */
+  }
+}
+
+function readStdin(): string {
+  try {
+    return fs.readFileSync(0, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+export function main(): number {
+  let envelope: JsonValue;
+  try {
+    const raw = readStdin();
+    envelope = raw.trim() ? (JSON.parse(raw) as JsonValue) : {};
+  } catch {
+    return EXIT_ALLOW;
+  }
+  if (!isObject(envelope)) return EXIT_ALLOW;
+
+  const rootVal = envelope["cwd"] ?? envelope["project_root"] ?? ".";
+  const root = typeof rootVal === "string" && rootVal ? rootVal : ".";
+  if (!enabled(root)) return EXIT_ALLOW;
+
+  const ex = extract(envelope);
+  if (!ex || !ex.file || !UI_EXT.test(ex.file)) return EXIT_ALLOW;
+
+  let ctx: DesignContext;
+  try {
+    ctx = loadDesignContext(path.dirname(path.resolve(root, ex.file)));
+  } catch {
+    ctx = { raw: "", has: () => false };
+  }
+
+  let findings;
+  try {
+    findings = scanFile(ex.content, ex.file, ctx).filter(
+      (f) => f.severity === "P0" || f.severity === "P1",
+    );
+  } catch {
+    return EXIT_ALLOW;
+  }
+  if (findings.length === 0) return EXIT_ALLOW;
+
+  // Anti-loop degradation: drop any signature already surfaced DEGRADE_AFTER times.
+  const state = readState(root);
+  const surfaced = findings.filter((f) => {
+    const sig = `${ex.file}::${f.rule}`;
+    const seen = state[sig] ?? 0;
+    if (seen >= DEGRADE_AFTER) return false; // gone silent — never trap the agent
+    state[sig] = seen + 1;
+    return true;
+  });
+  writeState(root, state);
+
+  if (surfaced.length === 0) return EXIT_ALLOW;
+
+  const lines = surfaced
+    .map((f) => `${f.catalogId} (${f.rule}) ${f.file}:${f.line} — ${f.message}`)
+    .join("; ");
+  const reason =
+    "⚠️ Anti-slop: high-severity aesthetic tell(s) in the proposed UI — " +
+    lines +
+    ". Rebuttable: declare intent in DESIGN.md, add design-slop-disable-next-line, " +
+    "or proceed if deliberate (this is a flag, not a block).";
+  process.stdout.write(JSON.stringify({ decision: "warn", reason }) + "\n");
+  return EXIT_WARN;
+}
+
+const isCliEntry =
+  process.argv[1] !== undefined &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (isCliEntry) process.exit(main());

package/src/scripts/lint_agent_security.ts

@@ -43,6 +43,7 @@ type Finding = Record<string, unknown>;
 
 const LINTERS: ReadonlyArray<[string, string]> = [
   ["hidden-unicode", "lint_hidden_unicode.ts"],
+  ["mixed-script-confusable", "lint_confusables.ts"],
   ["instruction-smuggling", "lint_instruction_smuggling.ts"],
   ["mcp-config-security", "lint_mcp_config_security.ts"],
   ["dangerous-frontmatter", "lint_skill_frontmatter_safety.ts"],

package/src/scripts/lint_confusables.ts

@@ -0,0 +1,197 @@
+// Visible mixed-script confusable / homoglyph linter
+// (road-to-injection-defense-pressure-corpus.md, Phase 1.2).
+//
+// Sibling of `lint_hidden_unicode.ts`. That linter catches the INVISIBLE
+// smuggling class (zero-width, bidi, tag-block). This one catches the VISIBLE
+// class it misses: a Latin word with one or more letters swapped for
+// visually-identical Cyrillic or Greek lookalikes (mixed-script token) — the
+// homoglyph version of the rules-file-backdoor attack. A reviewer sees
+// "ignore"; the model reads a token whose 'o' is U+043E CYRILLIC SMALL LETTER O.
+//
+// Detection signature (high-precision, low-false-positive):
+//   A whitespace-delimited token is flagged when ALL hold —
+//     1. it contains >= 1 Latin letter AND >= 1 Cyrillic-or-Greek letter that
+//        is in the TR39 confusable set (has a Latin lookalike). Math operators
+//        with NO Latin lookalike (Δ Σ Π Ω Φ Θ Λ Ξ Ψ Γ …) are NOT confusables,
+//        so legit notation like "ΔNWC" / "Σwᵢ" is never flagged,
+//     2. it has >= MIN_LETTERS total letters, and
+//     3. Latin is the MAJORITY script (the attack is a Latin word with foreign
+//        lookalike substitutions, not a foreign word with one Latin letter).
+//   Pure-Cyrillic / pure-Greek / CJK prose is single-script per token and is
+//   never flagged — legit non-Latin text passes.
+//
+// Scope + containment mirror lint_hidden_unicode: scans every .md under
+// src/{skills,rules,agent-src,domains} via sl.iter_corpus(); a
+// ```security-example fence or a `security-lint: allow mixed-script-confusable`
+// pragma exempts a region/file (a doc teaching confusables needs to show one).
+//
+// Exit 0 clean, 1 on any blocking finding.
+//
+// Usage: ./scripts-run src/scripts/lint_confusables [--json]
+
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import * as sl from './_lib/security_lint.js';
+
+export const CHECK = 'mixed-script-confusable';
+
+const MIN_LETTERS = 3;
+
+// Unicode-script classifiers via property escapes (requires the `u` flag).
+const _LATIN = /\p{Script=Latin}/u;
+const _CYRILLIC = /\p{Script=Cyrillic}/u;
+const _GREEK = /\p{Script=Greek}/u;
+const _LETTER = /\p{L}/u;
+// A "token" is a maximal run of letters / combining marks / decimal digits.
+const _TOKEN = /[\p{L}\p{M}\p{Nd}]+/gu;
+
+// Cyrillic + Greek codepoints that have a basic-Latin lookalike (Unicode TR39
+// confusables, common subset). A foreign letter only counts toward the
+// confusable signal when it is in this set — Greek math operators with no Latin
+// twin (Δ Σ Π Ω Φ Θ Λ Ξ Ψ Γ δ π ω …) are deliberately excluded so legit
+// notation does not false-positive.
+const _CONFUSABLE_FOREIGN: ReadonlySet<number> = new Set([
+    // Cyrillic lowercase ↔ Latin
+    0x0430 /*а→a*/, 0x0435 /*е→e*/, 0x043e /*о→o*/, 0x0440 /*р→p*/, 0x0441 /*с→c*/,
+    0x0443 /*у→y*/, 0x0445 /*х→x*/, 0x0455 /*ѕ→s*/, 0x0456 /*і→i*/, 0x0458 /*ј→j*/,
+    0x04bb /*һ→h*/, 0x0501 /*ԁ→d*/, 0x051b /*ԛ→q*/, 0x0577 /*no*/,
+    // Cyrillic uppercase ↔ Latin
+    0x0410 /*А→A*/, 0x0412 /*В→B*/, 0x0415 /*Е→E*/, 0x041a /*К→K*/, 0x041c /*М→M*/,
+    0x041d /*Н→H*/, 0x041e /*О→O*/, 0x0420 /*Р→P*/, 0x0421 /*С→C*/, 0x0422 /*Т→T*/,
+    0x0423 /*У→Y*/, 0x0425 /*Х→X*/, 0x0405 /*Ѕ→S*/, 0x0406 /*І→I*/, 0x0408 /*Ј→J*/,
+    // Greek lowercase ↔ Latin
+    0x03b1 /*α→a*/, 0x03b5 /*ε→e*/, 0x03bf /*ο→o*/, 0x03bd /*ν→v*/, 0x03c1 /*ρ→p*/,
+    0x03c5 /*υ→u*/, 0x03c7 /*χ→x*/, 0x03ba /*κ→k*/,
+    // Greek uppercase ↔ Latin (only those with a real Latin twin)
+    0x0391 /*Α→A*/, 0x0392 /*Β→B*/, 0x0395 /*Ε→E*/, 0x0396 /*Ζ→Z*/, 0x0397 /*Η→H*/,
+    0x0399 /*Ι→I*/, 0x039a /*Κ→K*/, 0x039c /*Μ→M*/, 0x039d /*Ν→N*/, 0x039f /*Ο→O*/,
+    0x03a1 /*Ρ→P*/, 0x03a4 /*Τ→T*/, 0x03a5 /*Υ→Y*/, 0x03a7 /*Χ→X*/, 0x0392 /*Β→B*/,
+]);
+
+type ScriptName = 'latin' | 'cyrillic' | 'greek' | 'other';
+
+function _script_of(ch: string): ScriptName {
+    if (_LATIN.test(ch)) return 'latin';
+    if (_CYRILLIC.test(ch)) return 'cyrillic';
+    if (_GREEK.test(ch)) return 'greek';
+    return 'other';
+}
+
+/**
+ * Classify a single token. Returns the offending mixed-script descriptor when
+ * the token matches the homoglyph signature, else null.
+ */
+export function _classify_token(token: string): string | null {
+    let latin = 0;
+    let cyrillic = 0;
+    let greek = 0;
+    let letters = 0;
+    for (const ch of token) {
+        if (!_LETTER.test(ch)) continue; // skip combining marks / digits for script vote
+        letters += 1;
+        const script = _script_of(ch);
+        if (script === 'latin') {
+            latin += 1;
+        } else if (script === 'cyrillic' || script === 'greek') {
+            // Only confusable foreign letters (TR39) count — math operators with
+            // no Latin twin are ignored, so legit notation never trips.
+            if (_CONFUSABLE_FOREIGN.has(ch.codePointAt(0) as number)) {
+                if (script === 'cyrillic') cyrillic += 1;
+                else greek += 1;
+            }
+        }
+    }
+    if (letters < MIN_LETTERS) return null;
+    const foreign = cyrillic + greek;
+    if (latin === 0 || foreign === 0) return null; // single-script (or no Latin) → legit
+    if (latin <= foreign) return null; // majority must be Latin (foreign word ≠ attack)
+    const which = cyrillic > 0 && greek > 0
+        ? 'cyrillic+greek'
+        : cyrillic > 0
+            ? 'cyrillic'
+            : 'greek';
+    return `latin+${which} (${latin} latin / ${foreign} foreign-confusable)`;
+}
+
+export function _scan(sf: sl.ScannedFile): sl.Finding[] {
+    if (sf.pragma_allows(CHECK)) {
+        return [];
+    }
+    const out: sl.Finding[] = [];
+    for (const [lineno, text] of sf.iter_lines({ skip_example_fence: true })) {
+        const tokens = text.match(_TOKEN);
+        if (tokens === null) continue;
+        for (const tok of tokens) {
+            const desc = _classify_token(tok);
+            if (desc !== null) {
+                out.push(
+                    new sl.Finding(
+                        sf.rel,
+                        lineno,
+                        CHECK,
+                        'HIGH',
+                        `mixed-script confusable token "${tok}" — ${desc}`,
+                        sf.weight,
+                    ),
+                );
+            }
+        }
+    }
+    return out;
+}
+
+interface Args {
+    json: boolean;
+}
+
+function _argError(msg: string): never {
+    process.stderr.write('usage: lint_confusables [-h] [--json]\n');
+    process.stderr.write(`lint_confusables: error: ${msg}\n`);
+    process.exit(2);
+}
+
+function parse_args(argv: readonly string[]): Args {
+    const out: Args = { json: false };
+    const extra: string[] = [];
+    for (const a of argv) {
+        if (a === '-h' || a === '--help') {
+            process.stdout.write('usage: lint_confusables [-h] [--json]\n');
+            process.exit(0);
+        } else if (a === '--json') {
+            out.json = true;
+        } else {
+            extra.push(a);
+        }
+    }
+    if (extra.length > 0) {
+        _argError(`unrecognized arguments: ${extra.join(' ')}`);
+    }
+    return out;
+}
+
+export function main(argv: readonly string[] | null = null): number {
+    const args = parse_args(argv ?? process.argv.slice(2));
+
+    const findings: sl.Finding[] = [];
+    for (const sf of sl.iter_corpus()) {
+        for (const h of _scan(sf)) {
+            findings.push(h);
+        }
+    }
+
+    if (args.json) {
+        const payload = sl.py_json_dumps_indent2(findings.map((f) => f.toDict()));
+        process.stdout.write(payload + '\n');
+        return findings.some((f) => f.is_fail) ? 1 : 0;
+    }
+
+    return sl.report(findings, { check_label: 'mixed-script-confusable' });
+}
+
+const _isCliEntry =
+    process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCliEntry) {
+    process.exitCode = main();
+}

package/src/scripts/lint_design_slop.ts

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+/**
+ * lint_design_slop — deterministic anti-slop DETECTOR for consumer projects.
+ *
+ * The aesthetic-PROVENANCE layer that `lint_design_quality` deliberately omits.
+ * It scans HTML/CSS/JSX/Markdown for the "AI tells" catalogued in
+ * `docs/guidelines/design-antipatterns.md` and emits structured findings
+ * (rule-id + catalog-id + severity P0–P3 + file:line). The rule registry lives
+ * in `design_slop_rules.ts`.
+ *
+ * FLAGS, NEVER A HARD BLOCK. Default exit is 0 regardless of findings — slop
+ * tells are rebuttable presumptions, not failures. CI opts into failing with
+ * `--fail-on <P0|P1|P2|P3>` (fails when any finding at or above that severity
+ * remains). This honours the council 2026-06-28 "flags not blocks" verdict.
+ *
+ * Zero runtime token cost: this runs in Node (CI / pre-commit / optional hook),
+ * never in the model's context. `design-review` cites the structured `--json`
+ * output instead of reloading the 12 KB prose catalog.
+ *
+ * Dependency-free pattern analysis (no postcss/@babel) — see the design note in
+ * design_slop_rules.ts. Same posture as lint_design_quality.
+ *
+ * Usage:
+ *   npx tsx lint_design_slop.ts --dir src/ [--json] [--fail-on P1] [--quiet]
+ *
+ * Context gate: a consumer DESIGN.md (project root or scan dir) that declares a
+ * pattern as intentional suppresses the matching rule (e.g. "warm-neutral" →
+ * C5 cream-palette is not flagged). Inline-ignore (eslint-style):
+ *   design-slop-disable <rule-id>            (file scope, top of file)
+ *   design-slop-disable-next-line <rule-id>
+ *   design-slop-disable-line <rule-id>
+ * Per-project config (.design-quality.json, shared with lint_design_quality):
+ *   { "ignoreRules": ["slop-c5-cream-palette"], "ignoreFiles": ["src/legacy/**"] }
+ *
+ * Exit codes: 0 = clean OR findings-below-threshold, 2 = findings at/above
+ * --fail-on threshold, 1 = internal error.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import {
+  SLOP_RULES,
+  type DesignContext,
+  type Engine,
+  type Severity,
+} from "./design_slop_rules.js";
+
+interface Finding {
+  rule: string;
+  catalogId: string;
+  severity: Severity;
+  file: string;
+  line: number;
+  snippet: string;
+  message: string;
+}
+
+interface ProjectConfig {
+  ignoreRules?: string[];
+  ignoreFiles?: string[];
+}
+
+const SEVERITY_ORDER: Severity[] = ["P3", "P2", "P1", "P0"];
+const sevRank = (s: Severity): number => SEVERITY_ORDER.indexOf(s);
+
+// ext → which engine-classes a file of that type can contain
+function enginesForExt(ext: string): Set<Engine> {
+  if (/\.(css|scss|sass|less)$/i.test(ext)) return new Set<Engine>(["css"]);
+  if (/\.(html|htm|vue|svelte|astro)$/i.test(ext)) return new Set<Engine>(["css", "html", "copy"]);
+  if (/\.(jsx|tsx)$/i.test(ext)) return new Set<Engine>(["css", "jsx", "copy"]);
+  if (/\.(md|mdx)$/i.test(ext)) return new Set<Engine>(["copy"]);
+  return new Set<Engine>();
+}
+
+function* walkDir(dir: string, ext: RegExp): Generator<string> {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+    if (entry.isDirectory()) yield* walkDir(full, ext);
+    else if (ext.test(entry.name)) yield full;
+  }
+}
+
+function loadConfig(dir: string): ProjectConfig {
+  const p = path.join(dir, ".design-quality.json");
+  if (!fs.existsSync(p)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf-8")) as ProjectConfig;
+  } catch {
+    return {};
+  }
+}
+
+/** Read DESIGN.md (scan dir, then project root) as the context-gate source. */
+export function loadDesignContext(scanDir: string): DesignContext {
+  const candidates = [
+    path.join(scanDir, "DESIGN.md"),
+    path.join(process.cwd(), "DESIGN.md"),
+    path.join(scanDir, "..", "DESIGN.md"),
+  ];
+  let raw = "";
+  for (const c of candidates) {
+    if (fs.existsSync(c)) {
+      raw = fs.readFileSync(c, "utf-8").toLowerCase();
+      break;
+    }
+  }
+  return {
+    raw,
+    has: (...keywords: string[]) => keywords.some((k) => raw.includes(k.toLowerCase())),
+  };
+}
+
+function parseIgnores(lines: string[]): Map<string, Set<number>> {
+  const ignores = new Map<string, Set<number>>();
+  const add = (rule: string, line: number) => {
+    const set = ignores.get(rule) ?? new Set<number>();
+    set.add(line);
+    ignores.set(rule, set);
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const file = /design-slop-disable\s+([\w-]+)/i.exec(line);
+    if (file && file[1] && !/-line|-next-line/.test(line)) {
+      ignores.set(file[1].toLowerCase(), new Set([...Array(99999).keys()].map((n) => n + 1)));
+    }
+    const next = /design-slop-disable-next-line\s+([\w-]+)/i.exec(line);
+    if (next && next[1]) add(next[1].toLowerCase(), i + 2);
+    const cur = /design-slop-disable-line\s+([\w-]+)/i.exec(line);
+    if (cur && cur[1]) add(cur[1].toLowerCase(), i + 1);
+  }
+  return ignores;
+}
+
+export function scanFile(
+  content: string,
+  relPath: string,
+  ctx: DesignContext,
+): Finding[] {
+  const lines = content.split("\n");
+  const ext = path.extname(relPath).toLowerCase();
+  const fileEngines = enginesForExt(ext);
+  if (fileEngines.size === 0) return [];
+  const ignores = parseIgnores(lines);
+
+  const out: Finding[] = [];
+  for (const rule of SLOP_RULES) {
+    if (!rule.engines.some((e) => fileEngines.has(e))) continue;
+    if (rule.gated && rule.gated(ctx)) continue; // DESIGN.md declares intent → suppress
+    let hits;
+    try {
+      hits = rule.detect({ content, lines, ext, ctx });
+    } catch {
+      continue; // a single rule throwing never kills the scan
+    }
+    for (const h of hits) {
+      const ruleIgnore = ignores.get(rule.id.toLowerCase());
+      if (ruleIgnore && ruleIgnore.has(h.line)) continue;
+      out.push({
+        rule: rule.id,
+        catalogId: rule.catalogId,
+        severity: rule.severity,
+        file: relPath,
+        line: h.line,
+        snippet: h.snippet,
+        message: rule.message,
+      });
+    }
+  }
+  return out;
+}
+
+function main(): void {
+  const args = process.argv.slice(2);
+  const jsonMode = args.includes("--json");
+  const quiet = args.includes("--quiet");
+  const dirIdx = args.indexOf("--dir");
+  const scanDir = dirIdx >= 0 && args[dirIdx + 1] ? path.resolve(args[dirIdx + 1]!) : path.resolve(process.cwd(), "src");
+  const failIdx = args.indexOf("--fail-on");
+  const failOn = (failIdx >= 0 ? args[failIdx + 1] : undefined) as Severity | undefined;
+
+  if (!fs.existsSync(scanDir)) {
+    if (!quiet) {
+      process.stderr.write(`[lint_design_slop] scan directory not found: ${scanDir}\n`);
+      process.stderr.write("Opt-in for consumer projects. Run with --dir <path> at your UI source.\n");
+    }
+    process.exit(0);
+  }
+
+  const ctx = loadDesignContext(scanDir);
+  const config = loadConfig(process.cwd());
+  const ignoreRules = new Set((config.ignoreRules ?? []).map((r) => r.toLowerCase()));
+  const ignoreGlobs = config.ignoreFiles ?? [];
+
+  const files: string[] = [];
+  for (const f of walkDir(scanDir, /\.(html|htm|css|scss|sass|less|vue|svelte|astro|jsx|tsx|md|mdx)$/i)) {
+    if (!ignoreGlobs.some((g) => f.includes(g.replace("**", "")))) files.push(f);
+  }
+
+  const findings: Finding[] = [];
+  for (const fp of files) {
+    const rel = path.relative(process.cwd(), fp);
+    try {
+      const fileFindings = scanFile(fs.readFileSync(fp, "utf-8"), rel, ctx).filter(
+        (f) => !ignoreRules.has(f.rule.toLowerCase()),
+      );
+      findings.push(...fileFindings);
+    } catch (err) {
+      if (!quiet) process.stderr.write(`[lint_design_slop] error: ${fp}: ${err}\n`);
+    }
+  }
+
+  findings.sort((a, b) => sevRank(b.severity) - sevRank(a.severity));
+
+  const overThreshold = failOn
+    ? findings.filter((f) => sevRank(f.severity) >= sevRank(failOn))
+    : [];
+
+  if (jsonMode) {
+    process.stdout.write(JSON.stringify({ findings, failOn: failOn ?? null, overThreshold: overThreshold.length }, null, 2) + "\n");
+    process.exit(overThreshold.length > 0 ? 2 : 0);
+  }
+
+  if (findings.length === 0) {
+    if (!quiet) process.stdout.write(`✅  lint_design_slop: no anti-slop tells in ${files.length} file(s).\n`);
+    process.exit(0);
+  }
+
+  for (const f of findings) {
+    const icon = f.severity === "P0" || f.severity === "P1" ? "⚠️ " : "•";
+    process.stdout.write(`${icon} [${f.severity} ${f.catalogId}] ${f.file}:${f.line} (${f.rule}) — ${f.message}\n     ${f.snippet}\n`);
+  }
+  process.stdout.write(
+    `\nlint_design_slop: ${findings.length} tell(s) flagged (rebuttable — declare intent in DESIGN.md, ` +
+      `design-slop-disable-next-line <rule>, or .design-quality.json).` +
+      (failOn ? ` ${overThreshold.length} at/above ${failOn}.` : " Flags only; no CI failure (pass --fail-on to gate).") +
+      "\n",
+  );
+  process.exit(overThreshold.length > 0 ? 2 : 0);
+}
+
+// Run only when invoked directly (not when imported by the test guard).
+const invokedDirectly =
+  process.argv[1] !== undefined && /lint_design_slop\.ts$/.test(process.argv[1]);
+if (invokedDirectly) main();