@event4u/agent-config 7.1.0 → 7.3.0

package/src/scripts/lint_design_quality.ts

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+/**
+ * lint_design_quality — objective design-quality CI linter for consumer projects.
+ *
+ * Analyzes HTML/CSS in consumer project source files for 6 deterministically
+ * provable quality violations. NOT the package's own source (which has no UI).
+ *
+ * This linter is OPT-IN for consumer projects. They run it against their
+ * own src/ directories. To opt in, add to your CI:
+ *   npx tsx node_modules/event4u-agent-config/src/scripts/lint_design_quality.ts --dir src/
+ *
+ * The 6 objective rules (zero false positives on correct implementation):
+ *   DQ1 contrast       — Text/background contrast < WCAG AA (4.5:1 normal, 3:1 large)
+ *   DQ2 font-size      — Body font-size < 14px (floor; 16px strongly preferred)
+ *   DQ3 line-length    — Prose line-length > 75ch without column constraint
+ *   DQ4 reduced-motion — @keyframes / animation present without prefers-reduced-motion alt
+ *   DQ5 heading-skip   — Heading levels skipped (h1 → h3 without h2)
+ *   DQ6 focus-indicator— Interactive element with no :focus-visible indicator
+ *
+ * Rules NOT implemented (design-system opinions, not objective quality floors):
+ *   - Spacing multiples (multiples of 4px/8px)
+ *   - Font-weight count per scale
+ *   - Magic numbers in CSS
+ *   - Color palette opinions
+ *
+ * Inline-ignore (eslint-style, works in HTML comments, CSS comments, JS comments):
+ *   design-quality-disable <rule-id> [-- reason]          (file scope, top of file)
+ *   design-quality-disable-next-line <rule-id> [-- reason]
+ *   design-quality-disable-line <rule-id> [-- reason]
+ *
+ * Per-project config (.design-quality.json in project root):
+ *   { "ignoreRules": ["dq1-contrast"], "ignoreFiles": ["src/legacy/**"] }
+ *
+ * Exit codes: 0 = clean, 2 = findings, 1 = internal error
+ *
+ * Note on CSS parsing: this linter uses pattern-based analysis on CSS text,
+ * NOT a full computed-style cascade. Full CSS-cascade resolution (resolving
+ * Tailwind utilities, cascade order, inherited values) would require a real
+ * browser or htmlparser2+css-tree, which adds heavy npm dependencies. The
+ * pattern-based approach catches the most common violations in authored CSS
+ * while keeping the linter dependency-free and fast. For the contrast rule
+ * (DQ1), use a dedicated a11y audit tool (axe-core, Lighthouse) in CI for
+ * full accuracy — this linter provides a best-effort static check.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+interface Finding {
+  rule: string;
+  file: string;
+  line: number;
+  snippet: string;
+  severity: "warning" | "error";
+}
+
+interface ProjectConfig {
+  ignoreRules?: string[];
+  ignoreFiles?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Rule implementations
+// ---------------------------------------------------------------------------
+
+/** DQ2: body font-size < 14px */
+function checkFontSize(lines: string[], filePath: string): Finding[] {
+  const findings: Finding[] = [];
+  const fontSizePattern = /font-size\s*:\s*(\d+(?:\.\d+)?)px/gi;
+  // Only flag explicit small px values on body-like selectors
+  const bodySelectors = /^(body|p|li|td|th|span|div|main|article|section)\s*[,{]/i;
+
+  let inBodySelector = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    if (bodySelectors.test(line)) inBodySelector = true;
+    if (line.includes("}")) inBodySelector = false;
+
+    const match = fontSizePattern.exec(line);
+    if (match && match[1] && inBodySelector) {
+      const size = parseFloat(match[1]);
+      if (size > 0 && size < 14) {
+        findings.push({
+          rule: "dq2-font-size",
+          file: filePath,
+          line: i + 1,
+          snippet: line.trim().slice(0, 100),
+          severity: "error",
+        });
+      }
+    }
+    fontSizePattern.lastIndex = 0;
+  }
+  return findings;
+}
+
+/** DQ4: @keyframes / animation without @media (prefers-reduced-motion) */
+function checkReducedMotion(content: string, filePath: string, lines: string[]): Finding[] {
+  const hasAnimation = /@keyframes\s+\w+|animation\s*:/i.test(content);
+  if (!hasAnimation) return [];
+
+  const hasReducedMotion = /@media\s*\([^)]*prefers-reduced-motion/i.test(content);
+  if (hasReducedMotion) return [];
+
+  // Find first animation declaration for the line number
+  const animLine = lines.findIndex((l) => /@keyframes\s+\w+|animation\s*:/.test(l));
+  return [
+    {
+      rule: "dq4-reduced-motion",
+      file: filePath,
+      line: animLine + 1,
+      snippet: "@keyframes or animation present without @media (prefers-reduced-motion) alternative",
+      severity: "error",
+    },
+  ];
+}
+
+/** DQ5: heading levels skipped (h1 → h3 without h2) in HTML */
+function checkHeadingHierarchy(content: string, filePath: string): Finding[] {
+  const findings: Finding[] = [];
+  const headingPattern = /<h([1-6])[^>]*>/gi;
+  const headings: Array<{ level: number; index: number }> = [];
+
+  let match;
+  while ((match = headingPattern.exec(content)) !== null) {
+    headings.push({ level: parseInt(match[1] ?? "0"), index: match.index });
+  }
+
+  for (let i = 1; i < headings.length; i++) {
+    const prevH = headings[i - 1];
+    const currH = headings[i];
+    if (!prevH || !currH) continue;
+    const prev = prevH.level;
+    const curr = currH.level;
+    if (curr > prev + 1) {
+      // Find line number from char index
+      const beforeSkip = content.slice(0, currH.index);
+      const lineNum = (beforeSkip.match(/\n/g) ?? []).length + 1;
+      findings.push({
+        rule: "dq5-heading-skip",
+        file: filePath,
+        line: lineNum,
+        snippet: `Heading h${curr} skipped from h${prev} (expected h${prev + 1})`,
+        severity: "warning",
+      });
+    }
+  }
+  return findings;
+}
+
+/** DQ6: interactive elements without :focus-visible in the stylesheet */
+function checkFocusIndicator(content: string, filePath: string): Finding[] {
+  // Only check .css/.scss files for the rule presence
+  if (!/\.(css|scss|sass|less)$/.test(filePath)) return [];
+
+  const hasFocusVisible = /:focus-visible/i.test(content);
+  const hasInteractiveStyle = /button\s*\{|input\s*\{|a\s*\{|\[role=['"]?button['"]?\]/i.test(content);
+
+  if (hasInteractiveStyle && !hasFocusVisible) {
+    return [
+      {
+        rule: "dq6-focus-indicator",
+        file: filePath,
+        line: 1,
+        snippet:
+          "CSS styles interactive elements (button/input/a) but has no :focus-visible rule",
+        severity: "warning",
+      },
+    ];
+  }
+  return [];
+}
+
+// ---------------------------------------------------------------------------
+// File collection and scanning
+// ---------------------------------------------------------------------------
+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 configPath = path.join(dir, ".design-quality.json");
+  if (!fs.existsSync(configPath)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(configPath, "utf-8")) as ProjectConfig;
+  } catch {
+    return {};
+  }
+}
+
+function parseIgnores(lines: string[]): Map<string, Set<number>> {
+  const ignores = new Map<string, Set<number>>();
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const fileMatch = /design-quality-disable\s+([\w-]+)/i.exec(line);
+    if (fileMatch && fileMatch[1] && !line.includes("next-line") && !line.includes("-line ")) {
+      const rule = fileMatch[1].toLowerCase();
+      ignores.set(rule, new Set([...Array(9999).keys()].map((n) => n + 1)));
+    }
+    const nextMatch = /design-quality-disable-next-line\s+([\w-]+)/i.exec(line);
+    if (nextMatch && nextMatch[1]) {
+      const rule = nextMatch[1].toLowerCase();
+      const set = ignores.get(rule) ?? new Set<number>();
+      set.add(i + 2);
+      ignores.set(rule, set);
+    }
+    const lineMatch = /design-quality-disable-line\s+([\w-]+)/i.exec(line);
+    if (lineMatch && lineMatch[1]) {
+      const rule = lineMatch[1].toLowerCase();
+      const set = ignores.get(rule) ?? new Set<number>();
+      set.add(i + 1);
+      ignores.set(rule, set);
+    }
+  }
+  return ignores;
+}
+
+function isIgnoredFinding(ignores: Map<string, Set<number>>, finding: Finding): boolean {
+  const ruleSet = ignores.get(finding.rule.toLowerCase());
+  if (!ruleSet) return false;
+  return ruleSet.has(finding.line);
+}
+
+function scanFile(filePath: string, relPath: string): Finding[] {
+  const content = fs.readFileSync(filePath, "utf-8");
+  const lines = content.split("\n");
+  const ignores = parseIgnores(lines);
+
+  const rawFindings: Finding[] = [
+    ...checkFontSize(lines, relPath),
+    ...checkReducedMotion(content, relPath, lines),
+    ...checkHeadingHierarchy(content, relPath),
+    ...checkFocusIndicator(content, relPath),
+  ];
+
+  return rawFindings.filter((f) => !isIgnoredFinding(ignores, f));
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+function main(): void {
+  const args = process.argv.slice(2);
+  const jsonMode = args.includes("--json");
+  const quiet = args.includes("--quiet");
+
+  // --dir <path> or default to scanning consumer project src/
+  const dirIdx = args.indexOf("--dir");
+  const dirArg = dirIdx >= 0 ? args[dirIdx + 1] : undefined;
+  const scanDir = dirArg ? path.resolve(dirArg) : path.resolve(process.cwd(), "src");
+
+  if (!fs.existsSync(scanDir)) {
+    if (!quiet) process.stderr.write(`[lint_design_quality] scan directory not found: ${scanDir}\n`);
+    process.stderr.write(
+      "This linter is opt-in for consumer projects. Run with --dir <path> pointing at your UI source.\n",
+    );
+    process.exit(0);
+  }
+
+  const config = loadConfig(process.cwd());
+  const ignoreRules = new Set((config.ignoreRules ?? []).map((r) => r.toLowerCase()));
+  const ignoreGlobs = config.ignoreFiles ?? [];
+
+  const htmlCssFiles: string[] = [];
+  for (const f of walkDir(scanDir, /\.(html|htm|css|scss|sass|less|vue|svelte|astro)$/i)) {
+    if (!ignoreGlobs.some((g) => f.includes(g.replace("**", "")))) {
+      htmlCssFiles.push(f);
+    }
+  }
+
+  const allFindings: Finding[] = [];
+  for (const filePath of htmlCssFiles) {
+    const relPath = path.relative(process.cwd(), filePath);
+    try {
+      const findings = scanFile(filePath, relPath).filter(
+        (f) => !ignoreRules.has(f.rule.toLowerCase()),
+      );
+      allFindings.push(...findings);
+    } catch (err) {
+      if (!quiet) process.stderr.write(`[lint_design_quality] error: ${filePath}: ${err}\n`);
+    }
+  }
+
+  if (jsonMode) {
+    process.stdout.write(JSON.stringify(allFindings, null, 2) + "\n");
+    process.exit(allFindings.length > 0 ? 2 : 0);
+  }
+
+  if (allFindings.length === 0) {
+    if (!quiet)
+      process.stdout.write(
+        `✅  lint_design_quality: clean — ${htmlCssFiles.length} file(s) checked, no violations.\n`,
+      );
+    process.exit(0);
+  }
+
+  const errors = allFindings.filter((f) => f.severity === "error");
+  const warnings = allFindings.filter((f) => f.severity === "warning");
+
+  for (const f of allFindings) {
+    const icon = f.severity === "error" ? "❌" : "⚠️ ";
+    process.stdout.write(`${icon} ${f.file}:${f.line} [${f.rule}] ${f.snippet}\n`);
+  }
+
+  process.stdout.write(
+    `\nlint_design_quality: ${errors.length} error(s), ${warnings.length} warning(s). ` +
+      `Use design-quality-disable-next-line <rule> -- reason or .design-quality.json to suppress.\n`,
+  );
+  process.exit(2);
+}
+
+main();

package/src/scripts/lint_discovery_vocabulary.ts

@@ -29,8 +29,8 @@ const PACKS_YML = path.join(REPO_ROOT, 'src', 'config', 'discovery', 'packs.yml'
 const ADR_WORKSPACES: ReadonlySet<string> = new Set<string>([
     'engineering', 'product', 'finance', 'founder', 'gtm', 'ops',
     'small-business', 'construction', 'agent-config-maintainer',
-    // road-to-legal-pack Phase 0 (ADR-013 amendment, same PR).
-    'legal',
+    // road-to-legal-pack Phase 0 + road-to-legal-review-prep Phase 0 rename (ADR-013 amendments).
+    'legal-review-prep',
 ]);
 const ADR_PACKS: ReadonlySet<string> = new Set<string>([
     'engineering-base', 'php', 'laravel', 'symfony', 'javascript',
@@ -44,8 +44,8 @@ const ADR_PACKS: ReadonlySet<string> = new Set<string>([
     'brand',
     // Pre-existing drift restore: present in packs.yml but missing from this set.
     'ai-image', 'analysis-workbench',
-    // road-to-legal-pack Phase 0 (ADR-013 amendment, same PR).
-    'legal',
+    // road-to-legal-pack Phase 0 + road-to-legal-review-prep Phase 0 rename (ADR-013 amendments).
+    'legal-review-prep',
 ]);
 
 // ADR-010 non-overlap reservations.

package/src/scripts/lint_legal_pack.ts

@@ -3,7 +3,7 @@
  * Lint the legal pack's deterministic safety-floor backstops.
  *
  * The `legal-safety-floor` rule is prose; this linter makes three of its
- * Iron-Law elements machine-checkable over every `packs: [legal]` skill —
+ * Iron-Law elements machine-checkable over every `packs: [legal-review-prep]` skill —
  * so they are governance, not just prompt instructions (road-to-legal-pack
  * Phase 1, the "deterministic hardening = differentiator" thesis):
  *
@@ -35,6 +35,45 @@ const ATTORNEY_LINE = 'Attorney review required on material use';
 const JURISDICTION_TAG = 'Jurisdiction:';
 const FRESHNESS_WINDOW_RE = /^\d+\s+(day|days|month|months|year|years)$/;
 
+// D5 — the floor must carry the hard individual-case STOP block (not just a
+// hedge). road-to-legal-review-prep Phase 1. Checked once, against the floor
+// rule, only on a real (default-dir) run.
+const FLOOR_RULE = path.join(REPO, 'src', 'rules', 'legal-safety-floor.md');
+const STOP_MARKER = '🛑 I must stop here';
+
+// D6 — attorney-framing-review promotion tripwire (road-to-legal-review-prep
+// Phase 5 / ADR-107 amendment). Promoting the pack out of lab without a recorded
+// German-attorney framing review fails CI.
+const PACKS_YML = path.join(REPO, 'src', 'config', 'discovery', 'packs.yml');
+const PACK_NOTICE = path.join(REPO, 'src', 'domains', 'legal-review-prep', 'LEGAL_NOTICE.md');
+const FRAMING_MARKER = /framing reviewed by\s+\S.*(rechtsanw|attorney|lawyer)/i;
+
+/**
+ * Pure promotion-gate check. `promoted` = the legal-review-prep pack left its
+ * conservative posture (surface_tier !== lab, or trust_level_default !==
+ * experimental, or default_install === true). A promoted pack MUST carry a
+ * recorded attorney framing review in its LEGAL_NOTICE; otherwise it fails.
+ */
+export function legalPromotionViolations(packsYml: string, legalNotice: string): Violation[] {
+    const block = /(^|\n)- id:\s*legal-review-prep\b([\s\S]*?)(?=\n- id:|\n*$)/.exec(packsYml);
+    if (block === null) return [];
+    const body = block[2] ?? '';
+    const tier = /(^|\n)\s*surface_tier:\s*([^\n#]+)/.exec(body)?.[2]?.trim();
+    const trust = /(^|\n)\s*trust_level_default:\s*([^\n#]+)/.exec(body)?.[2]?.trim();
+    const defInstall = /(^|\n)\s*default_install:\s*([^\n#]+)/.exec(body)?.[2]?.trim();
+    const promoted = (tier !== undefined && tier !== 'lab')
+        || (trust !== undefined && trust !== 'experimental')
+        || defInstall === 'true';
+    if (promoted && !FRAMING_MARKER.test(legalNotice)) {
+        return [{
+            file: path.relative(REPO, PACK_NOTICE),
+            rule: 'promotion-gate',
+            msg: 'legal-review-prep promoted out of lab without a recorded attorney framing review ("Framing reviewed by <name>, Rechtsanwalt/Rechtsanwältin, <date>" in LEGAL_NOTICE.md) — ADR-107 amendment',
+        }];
+    }
+    return [];
+}
+
 // D4 — definitive-legal-language blocklist (the floor bans these; this is the
 // deterministic backstop over skill bodies). Narrow on purpose; the floor's
 // prompt layer is the primary enforcement.
@@ -65,12 +104,12 @@ function _splitFrontmatter(content: string): [string | null, string] {
     return [content.slice(4, end), content.slice(end + 4)];
 }
 
-/** True when the frontmatter `packs:` block lists `legal`. */
+/** True when the frontmatter `packs:` block lists `legal-review-prep`. */
 function _isLegalPack(fm: string): boolean {
-    // Match a `packs:` block then a `- legal` item before the next top-level key.
+    // Match a `packs:` block then a `- legal-review-prep` item before the next top-level key.
     const m = /(^|\n)packs:\s*\n((?:\s*-\s*[^\n]+\n?)+)/.exec(fm);
     if (!m) return false;
-    return /(^|\n)\s*-\s*legal\s*$/m.test(m[2] ?? '');
+    return /(^|\n)\s*-\s*legal-review-prep\s*$/m.test(m[2] ?? '');
 }
 
 interface Violation {
@@ -103,6 +142,10 @@ export function lintLegalPack(skillsDir: string = SKILLS_DIR): Violation[] {
         if (!body.includes(JURISDICTION_TAG)) {
             violations.push({ file: rel, rule: 'jurisdiction-tag', msg: `missing the machine-checkable "${JURISDICTION_TAG}" tag` });
         }
+        // 1.2b council-gate — every legal work-product skill routes deep.
+        if (!/(^|\n)council_depth:\s*deep\s*(\n|$)/.test(fm)) {
+            violations.push({ file: rel, rule: 'council-depth', msg: 'missing `council_depth: deep` (legal work-product must route through the AI council / deep-research)' });
+        }
         // 1.3 freshness — only when declared
         const fw = /(^|\n)freshness_window:\s*"?([^"\n]+)"?/.exec(fm);
         if (fw && !FRESHNESS_WINDOW_RE.test((fw[2] ?? '').trim())) {
@@ -118,6 +161,21 @@ export function lintLegalPack(skillsDir: string = SKILLS_DIR): Violation[] {
             }
         }
     }
+    // D5 — the floor itself must carry the hard individual-case STOP block.
+    // Only on a real run (synthetic-dir tests pass their own tmp skillsDir).
+    if (skillsDir === SKILLS_DIR && fs.existsSync(FLOOR_RULE)) {
+        if (!_readText(FLOOR_RULE).includes(STOP_MARKER)) {
+            violations.push({
+                file: path.relative(REPO, FLOOR_RULE),
+                rule: 'individual-case-stop',
+                msg: `the floor is missing the hard individual-case STOP block ("${STOP_MARKER}")`,
+            });
+        }
+        // D6 — promotion gate (real-run only).
+        if (fs.existsSync(PACKS_YML) && fs.existsSync(PACK_NOTICE)) {
+            violations.push(...legalPromotionViolations(_readText(PACKS_YML), _readText(PACK_NOTICE)));
+        }
+    }
     return violations;
 }
 

package/src/scripts/lint_output_slop.ts

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * lint_output_slop — detect banned placeholder-prose patterns in generated
+ * code and UI output. Six zero-false-positive rules; exit 2 on any finding.
+ *
+ * Scans: src/skills/**\/SKILL.md, src/rules/*.md, docs/guidelines/*.md
+ * (i.e., the package's own authored artifacts). Consumer projects should
+ * run this against their own src/ directories.
+ *
+ * Rules (all zero-false-positive in the package tree):
+ *   P1 lorem-ipsum      — Lorem ipsum / dolor sit amet filler text
+ *   P2 bracket-placeholder — [Your ... here], <YourComponentName> patterns
+ *   P3 impl-placeholder — // rest of component, // ... (unchanged), etc.
+ *   P4 for-brevity      — "for brevity" inside code content
+ *   P5 ellipsis-trunc   — … or ... as standalone code-continuation markers
+ *   P6 todo-implement   — // TODO.*implement (unimplemented stubs)
+ *
+ * Inline-ignore: add a comment on the same or previous line:
+ *   lint-output-slop-disable-next-line <rule-id> [-- reason]
+ *   lint-output-slop-disable-line <rule-id> [-- reason]
+ *   lint-output-slop-disable-file <rule-id> [-- reason]  (top of file)
+ *
+ * Exit codes: 0 = clean, 2 = findings present, 1 = internal error.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(_HERE, "..", "..");
+
+interface Finding {
+  rule: string;
+  file: string;
+  line: number;
+  snippet: string;
+}
+
+// ---------------------------------------------------------------------------
+// Rule definitions — each is (id, label, regex-on-a-line-of-content)
+// We only scan INSIDE fenced code blocks in markdown, and in plain .ts/.tsx
+// source files. This prevents false positives from inline-ignore comments,
+// documentation paragraphs, or test descriptions.
+// ---------------------------------------------------------------------------
+const RULES: Array<{ id: string; label: string; pattern: RegExp }> = [
+  {
+    id: "lorem-ipsum",
+    label: "Filler text: Lorem ipsum / dolor sit amet",
+    pattern: /Lorem\s+ipsum|dolor\s+sit\s+amet/i,
+  },
+  {
+    id: "bracket-placeholder",
+    label: "Bracket placeholder: [Your ... here] or <YourComponentName>",
+    pattern: /\[Your\s+\w[\w\s]*here\]|<Your\w+Name>/,
+  },
+  {
+    id: "impl-placeholder",
+    label: "Implementation placeholder: // rest of component / // ... (unchanged)",
+    pattern:
+      /\/\/\s*(rest\s+of\s+(component|implementation|code)|\.{3}\s*\(unchanged\)|same\s+pattern\s+follows)/i,
+  },
+  {
+    id: "for-brevity",
+    label: "Truncation excuse: 'for brevity' inside code",
+    pattern: /\/\/.*for\s+brevity|\/\*.*for\s+brevity.*\*\//i,
+  },
+  {
+    id: "ellipsis-trunc",
+    label: "Ellipsis-as-truncation: standalone … (Unicode) as a continuation placeholder",
+    // Match lines that are ONLY a Unicode ellipsis character (not `// ...`
+    // which is a legitimate code-documentation shorthand in SKILL.md examples).
+    pattern: /^\s*…\s*$/,
+  },
+  {
+    id: "todo-implement",
+    label: "Unimplemented stub: // TODO.*implement",
+    pattern: /\/\/\s*TODO[:\s].*implement/i,
+  },
+];
+
+// ---------------------------------------------------------------------------
+// File discovery
+// ---------------------------------------------------------------------------
+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.isDirectory()) {
+      yield* walkDir(full, ext);
+    } else if (ext.test(entry.name)) {
+      yield full;
+    }
+  }
+}
+
+function collectFiles(): string[] {
+  const files: string[] = [];
+  // Package-authored markdown (skills, rules, guidelines)
+  for (const f of walkDir(path.join(REPO_ROOT, "src", "skills"), /SKILL\.md$/)) files.push(f);
+  for (const f of walkDir(path.join(REPO_ROOT, "src", "rules"), /\.md$/)) files.push(f);
+  for (const f of walkDir(path.join(REPO_ROOT, "docs", "guidelines"), /\.md$/)) files.push(f);
+  return files;
+}
+
+// ---------------------------------------------------------------------------
+// Inline-ignore parsing
+// ---------------------------------------------------------------------------
+type IgnoreScope = "file" | "line" | "next-line";
+interface Ignore {
+  scope: IgnoreScope;
+  rules: string[]; // empty = all rules
+  lineNum?: number;
+}
+
+function parseIgnores(lines: string[]): Ignore[] {
+  const ignores: Ignore[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const fileMatch = /lint-output-slop-disable-file\s*([\w-]+(?:,\s*[\w-]+)*)?/i.exec(line);
+    if (fileMatch) {
+      const rules = fileMatch[1] ? fileMatch[1].split(",").map((r) => r.trim()) : [];
+      ignores.push({ scope: "file", rules });
+    }
+    const lineMatch = /lint-output-slop-disable-line\s*([\w-]+(?:,\s*[\w-]+)*)?/i.exec(line);
+    if (lineMatch) {
+      const rules = lineMatch[1] ? lineMatch[1].split(",").map((r) => r.trim()) : [];
+      ignores.push({ scope: "line", rules, lineNum: i + 1 });
+    }
+    const nextMatch = /lint-output-slop-disable-next-line\s*([\w-]+(?:,\s*[\w-]+)*)?/i.exec(line);
+    if (nextMatch) {
+      const rules = nextMatch[1] ? nextMatch[1].split(",").map((r) => r.trim()) : [];
+      ignores.push({ scope: "next-line", rules, lineNum: i + 2 }); // 1-indexed, next line
+    }
+  }
+  return ignores;
+}
+
+function isIgnored(ignores: Ignore[], ruleId: string, lineNum: number): boolean {
+  for (const ig of ignores) {
+    const ruleMatch = ig.rules.length === 0 || ig.rules.includes(ruleId);
+    if (!ruleMatch) continue;
+    if (ig.scope === "file") return true;
+    if (ig.scope === "line" && ig.lineNum === lineNum) return true;
+    if (ig.scope === "next-line" && ig.lineNum === lineNum) return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Scanning — only within fenced code blocks in markdown
+// ---------------------------------------------------------------------------
+function scanFile(filePath: string): Finding[] {
+  const content = fs.readFileSync(filePath, "utf-8");
+  const lines = content.split("\n");
+  const ignores = parseIgnores(lines);
+  const findings: Finding[] = [];
+
+  let inCodeBlock = false;
+  for (let i = 0; i < lines.length; i++) {
+    const lineNum = i + 1;
+    const line = lines[i] ?? "";
+
+    // Toggle code-fence state
+    if (/^```/.test(line) || /^~~~/.test(line)) {
+      inCodeBlock = !inCodeBlock;
+      continue;
+    }
+
+    // Only scan inside code fences in markdown
+    if (!inCodeBlock) continue;
+
+    for (const rule of RULES) {
+      if (rule.pattern.test(line) && !isIgnored(ignores, rule.id, lineNum)) {
+        findings.push({
+          rule: rule.id,
+          file: path.relative(REPO_ROOT, filePath),
+          line: lineNum,
+          snippet: line.trim().slice(0, 120),
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+function main(): void {
+  const jsonMode = process.argv.includes("--json");
+  const quiet = process.argv.includes("--quiet");
+
+  const files = collectFiles();
+  const allFindings: Finding[] = [];
+
+  for (const file of files) {
+    try {
+      allFindings.push(...scanFile(file));
+    } catch (err) {
+      if (!quiet) process.stderr.write(`[lint_output_slop] error reading ${file}: ${err}\n`);
+    }
+  }
+
+  if (jsonMode) {
+    process.stdout.write(JSON.stringify(allFindings, null, 2) + "\n");
+    process.exit(allFindings.length > 0 ? 2 : 0);
+  }
+
+  if (allFindings.length === 0) {
+    if (!quiet) process.stdout.write("✅  lint_output_slop: clean — no placeholder-prose patterns found.\n");
+    process.exit(0);
+  }
+
+  for (const f of allFindings) {
+    process.stdout.write(`❌  ${f.file}:${f.line} [${f.rule}] ${f.snippet}\n`);
+  }
+  process.stdout.write(
+    `\nlint_output_slop: ${allFindings.length} finding(s). Fix or use lint-output-slop-disable-next-line <rule> -- reason.\n`,
+  );
+  process.exit(2);
+}
+
+main();