@eltonssouza/development-utility-kit 0.10.0

package/bin/lib/lint.js

@@ -0,0 +1,798 @@
+'use strict';
+
+/**
+ * `duk lint` — structural validation of the harness `.claude/` directory.
+ *
+ * Mechanical, deterministic, no LLM. Per ADR-034:
+ *   "Mecânico, determinístico, scriptável → CLI duk."
+ *
+ * Consolidates and expands scripts/lint-harness.mjs (deprecated by this command).
+ *
+ * Categories:
+ *   1. skills        — SKILL.md frontmatter (name, description, tools, model)
+ *   2. agents        — agent frontmatter (name, description, model)
+ *   3. refs          — agents referenced by skills must exist in .claude/agents/
+ *   4. adrs          — ADR cross-refs (ADR-XYZ mentions must point to existing files)
+ *   5. stacks        — pack files have required sections
+ *   6. d1-contract   — skill body forbids "checklist|golden rule|inviolable rules";
+ *                      agent body forbids "PT triggers:" (from scripts/lint-harness.mjs)
+ *
+ * Output: violations grouped by category + summary.
+ * Exit code: 0 if no FAIL, 1 if any FAIL.
+ *
+ * Flags:
+ *   --json                  machine-readable output
+ *   --category <name>       run only one category (comma-separated for many)
+ *   --help                  show help
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ── Severities ──────────────────────────────────────────────────────────────
+
+const ERROR = 'ERROR';
+const WARN = 'WARN';
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function packageRoot() {
+  return path.resolve(__dirname, '..', '..');
+}
+
+function readSafe(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function isDir(p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function listDir(p) {
+  try {
+    return fs.readdirSync(p, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Extract a YAML-ish frontmatter block as a key→value object. Best-effort:
+ * supports `key: value`, multi-line values get the first line only, lists are
+ * captured as raw string. Returns { frontmatter, body, bodyStartLine }.
+ */
+function extractFrontmatter(content) {
+  const lines = content.split('\n');
+  if (lines[0].trim() !== '---') {
+    return { frontmatter: {}, body: content, bodyStartLine: 1 };
+  }
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') { end = i; break; }
+  }
+  if (end === -1) {
+    return { frontmatter: {}, body: content, bodyStartLine: 1 };
+  }
+  const fmBlock = lines.slice(1, end);
+  const fm = {};
+  for (const rawLine of fmBlock) {
+    // Strip trailing \r so the regex anchor `$` works on CRLF files.
+    // Without this, `(.*)$` is unsatisfiable on lines ending in \r:
+    //   - `.` does not match \r (no /s flag)
+    //   - `$` matches end-of-string or before final \n, never before \r
+    const line = rawLine.replace(/\r$/, '');
+    const m = line.match(/^([A-Za-z0-9_-]+)\s*:\s*(.*)$/);
+    if (m) fm[m[1]] = m[2].trim();
+  }
+  return {
+    frontmatter: fm,
+    body: lines.slice(end + 1).join('\n'),
+    bodyStartLine: end + 2,
+  };
+}
+
+// ── Walkers ─────────────────────────────────────────────────────────────────
+
+function findSkills() {
+  const dir = path.join(packageRoot(), '.claude', 'skills');
+  const out = [];
+  for (const entry of listDir(dir)) {
+    if (entry.isDirectory()) {
+      const skillPath = path.join(dir, entry.name, 'SKILL.md');
+      if (fs.existsSync(skillPath)) {
+        out.push({ name: entry.name, path: skillPath });
+      }
+    }
+  }
+  return out;
+}
+
+function findAgents() {
+  const dir = path.join(packageRoot(), '.claude', 'agents');
+  const out = [];
+  for (const entry of listDir(dir)) {
+    // Skip README.md (directory index, not an agent definition) — per tech-debt Item 22.
+    if (
+      entry.isFile() &&
+      entry.name.endsWith('.md') &&
+      !entry.name.startsWith('_') &&
+      entry.name !== 'README.md'
+    ) {
+      out.push({
+        name: entry.name.replace(/\.md$/, ''),
+        path: path.join(dir, entry.name),
+      });
+    }
+  }
+  return out;
+}
+
+function findADRs() {
+  const dir = path.join(packageRoot(), 'docs', 'brain', 'decisions');
+  const out = [];
+  for (const entry of listDir(dir)) {
+    if (entry.isFile() && /^ADR-\d{3}.*\.md$/.test(entry.name)) {
+      const m = entry.name.match(/^ADR-(\d{3})/);
+      out.push({
+        id: m ? m[1] : null,
+        filename: entry.name,
+        path: path.join(dir, entry.name),
+      });
+    }
+  }
+  return out;
+}
+
+function findStackPacks() {
+  const dir = path.join(packageRoot(), '.claude', 'stacks');
+  const out = [];
+  for (const langEntry of listDir(dir)) {
+    if (langEntry.isDirectory()) {
+      const langDir = path.join(dir, langEntry.name);
+      for (const file of listDir(langDir)) {
+        if (file.isFile() && file.name.endsWith('.md') && file.name !== 'README.md' && file.name !== '_template.md') {
+          out.push({
+            lang: langEntry.name,
+            framework: file.name.replace(/\.md$/, ''),
+            path: path.join(langDir, file.name),
+          });
+        }
+      }
+    }
+  }
+  return out;
+}
+
+// ── Category 1: skills.frontmatter ──────────────────────────────────────────
+
+const SKILL_REQUIRED_FIELDS = ['name', 'description', 'tools', 'model'];
+
+function checkSkillsFrontmatter() {
+  const violations = [];
+  for (const skill of findSkills()) {
+    const content = readSafe(skill.path);
+    if (content === null) {
+      violations.push({ category: 'skills', severity: ERROR, file: skill.path, line: 0, msg: 'cannot read file' });
+      continue;
+    }
+    const { frontmatter } = extractFrontmatter(content);
+    for (const f of SKILL_REQUIRED_FIELDS) {
+      if (!frontmatter[f]) {
+        violations.push({
+          category: 'skills', severity: ERROR, file: skill.path, line: 1,
+          msg: `frontmatter missing required field: ${f}`,
+        });
+      }
+    }
+    if (frontmatter.name && frontmatter.name !== skill.name) {
+      violations.push({
+        category: 'skills', severity: ERROR, file: skill.path, line: 1,
+        msg: `frontmatter name "${frontmatter.name}" != directory name "${skill.name}"`,
+      });
+    }
+  }
+  return violations;
+}
+
+// ── Category 2: agents.frontmatter ──────────────────────────────────────────
+
+const AGENT_REQUIRED_FIELDS = ['name', 'description', 'model'];
+
+function checkAgentsFrontmatter() {
+  const violations = [];
+  for (const agent of findAgents()) {
+    const content = readSafe(agent.path);
+    if (content === null) {
+      violations.push({ category: 'agents', severity: ERROR, file: agent.path, line: 0, msg: 'cannot read file' });
+      continue;
+    }
+    const { frontmatter } = extractFrontmatter(content);
+    for (const f of AGENT_REQUIRED_FIELDS) {
+      if (!frontmatter[f]) {
+        violations.push({
+          category: 'agents', severity: ERROR, file: agent.path, line: 1,
+          msg: `frontmatter missing required field: ${f}`,
+        });
+      }
+    }
+    if (frontmatter.name && frontmatter.name !== agent.name) {
+      violations.push({
+        category: 'agents', severity: ERROR, file: agent.path, line: 1,
+        msg: `frontmatter name "${frontmatter.name}" != filename "${agent.name}"`,
+      });
+    }
+  }
+  return violations;
+}
+
+// ── Category 3: refs (skills → agents) ──────────────────────────────────────
+
+/**
+ * Skills reference agents via backticks: `agent-name`. We extract candidates
+ * from SKILL.md bodies and check they exist on disk. Known "agent" word lists
+ * help us narrow down — we only flag references that look like agent names
+ * AND appear in the project-manager routing table (CLAUDE.md) or the skill's
+ * own SKILL.md body.
+ */
+function checkSkillAgentRefs() {
+  const violations = [];
+  const agentNames = new Set(findAgents().map((a) => a.name));
+  // Allow skills as "subagent_type" targets too (e.g., grill-me dispatches to analyst).
+  const skillNames = new Set(findSkills().map((s) => s.name));
+
+  // Common false-positives: code keywords, generic words. We only flag backticks
+  // matching the kebab-case pattern that look like agent names.
+  for (const skill of findSkills()) {
+    const content = readSafe(skill.path);
+    if (content === null) continue;
+    const { body, bodyStartLine } = extractFrontmatter(content);
+    const lines = body.split('\n');
+
+    // Look only at section "## 3. Routing table" or any table-row with explicit
+    // `subagent_type` mentions. Generic prose with backticks would generate
+    // too many false positives.
+    let inRoutingTable = false;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (/^##\s+\d?\.?\s*Routing table/i.test(line)) inRoutingTable = true;
+      else if (/^##\s+/.test(line)) inRoutingTable = false;
+      if (!inRoutingTable) continue;
+
+      // Extract `name` backtick refs in the line
+      const matches = line.match(/`([a-z][a-z0-9-]+)`/g);
+      if (!matches) continue;
+      for (const m of matches) {
+        const candidate = m.replace(/`/g, '');
+        // Skip if it's a skill name (legitimate cross-skill ref like `grill-me`).
+        if (skillNames.has(candidate)) continue;
+        // Heuristic: only flag candidates that look like agent role names
+        // (contain hyphen and end with -er, -ist, -owner, -lead, etc.)
+        if (!/-(er|ist|owner|lead|engineer|reviewer|analyst|architect|developer|specialist|designer|runner|keeper|migrator|resolver|auditor)$/.test(candidate)) {
+          continue;
+        }
+        if (!agentNames.has(candidate)) {
+          violations.push({
+            category: 'refs', severity: ERROR, file: skill.path,
+            line: bodyStartLine + i,
+            msg: `skill references unknown agent: \`${candidate}\``,
+          });
+        }
+      }
+    }
+  }
+  return violations;
+}
+
+// ── Category 4: adr cross-refs ──────────────────────────────────────────────
+
+// Items 19 + 20 — robustness against false positives:
+//   - Item 19: ignore refs inside blockquote (`> ...`) or inside quoted phrases
+//     (e.g. ADR-031 line 51 quotes a hypothetical decision mentioning ADR-040).
+//   - Item 20: ignore documented gaps in `lint-allowlist.json` (e.g. ADR-001..006
+//     and ADR-009 deleted by design — recorded in tech-debt Items 4 and 20).
+function loadAllowlist() {
+  const file = path.join(__dirname, 'lint-allowlist.json');
+  const raw = readSafe(file);
+  if (raw === null) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+function isMatchInsideQuotes(line, matchStr) {
+  const idx = line.indexOf(matchStr);
+  if (idx < 0) return false;
+  const before = line.substring(0, idx);
+  const dq = (before.match(/"/g) || []).length;
+  const sq = (before.match(/'/g) || []).length;
+  const bt = (before.match(/`/g) || []).length;
+  // Odd count of any quote char before the match means the match sits inside
+  // an open quoted span.
+  return dq % 2 === 1 || sq % 2 === 1 || bt % 2 === 1;
+}
+
+function checkADRCrossRefs() {
+  const violations = [];
+  const adrs = findADRs();
+  const known = new Set(adrs.map((a) => a.id).filter(Boolean));
+  const allowlist = loadAllowlist();
+  const knownGaps = new Set(allowlist['adr-gaps-known'] || []);
+
+  for (const adr of adrs) {
+    const content = readSafe(adr.path);
+    if (content === null) continue;
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      // Item 19: skip blockquote lines — citation context, not a real cross-ref.
+      if (/^\s*>/.test(line)) continue;
+      // Match ADR-XYZ (3 digits)
+      const matches = line.match(/\bADR-(\d{3})\b/g);
+      if (!matches) continue;
+      for (const m of matches) {
+        // Item 19: skip matches inside quoted spans (", ', or `).
+        if (isMatchInsideQuotes(line, m)) continue;
+        const id = m.replace(/^ADR-/, '');
+        // Self-reference is fine.
+        if (id === adr.id) continue;
+        if (!known.has(id)) {
+          violations.push({
+            category: 'adrs', severity: WARN, file: adr.path, line: i + 1,
+            msg: `references missing ${m}`,
+          });
+        }
+      }
+    }
+  }
+
+  // Detect gaps in ADR numbering (informational).
+  // Item 20: skip gaps listed in lint-allowlist.json["adr-gaps-known"].
+  const ids = Array.from(known).map((s) => parseInt(s, 10)).sort((a, b) => a - b);
+  for (let i = 1; i < ids.length; i++) {
+    if (ids[i] - ids[i - 1] > 1) {
+      // Gap: ADR-(prev+1)..ADR-(curr-1) missing
+      for (let g = ids[i - 1] + 1; g < ids[i]; g++) {
+        const padded = String(g).padStart(3, '0');
+        if (knownGaps.has(padded)) continue;
+        violations.push({
+          category: 'adrs', severity: WARN,
+          file: path.join(packageRoot(), 'docs/brain/decisions/'),
+          line: 0,
+          msg: `gap in ADR numbering: ADR-${padded} not found`,
+        });
+      }
+    }
+  }
+
+  return violations;
+}
+
+// ── Category 5: stacks (basic structure) ───────────────────────────────────
+
+// Section headings may carry an optional numeric prefix (e.g. "## 6. Build & run commands").
+// Required for every active stack pack (per ADR-027).
+const STACK_REQUIRED_SECTIONS = [
+  /^##\s+(?:\d+\.\s+)?Build\s*&\s*run/i,
+  /^##\s+(?:\d+\.\s+)?Code\s+patterns/i,
+  /^##\s+(?:\d+\.\s+)?Anti-patterns/i,
+  /^##\s+(?:\d+\.\s+)?Security/i,
+  /^##\s+(?:\d+\.\s+)?Testing/i,
+];
+
+function checkStackPacks() {
+  const violations = [];
+  const packs = findStackPacks();
+  if (packs.length === 0) {
+    violations.push({
+      category: 'stacks', severity: WARN,
+      file: path.join(packageRoot(), '.claude/stacks'),
+      line: 0,
+      msg: 'no stack packs found',
+    });
+    return violations;
+  }
+
+  for (const pack of packs) {
+    const content = readSafe(pack.path);
+    if (content === null) continue;
+    const { body } = extractFrontmatter(content);
+    const lines = body.split('\n');
+    for (const required of STACK_REQUIRED_SECTIONS) {
+      if (!lines.some((l) => required.test(l))) {
+        violations.push({
+          category: 'stacks', severity: WARN, file: pack.path, line: 0,
+          msg: `pack missing recommended section matching: ${required}`,
+        });
+      }
+    }
+  }
+
+  return violations;
+}
+
+// ── Category 6: D1 contract (from scripts/lint-harness.mjs) ────────────────
+
+const PATTERN1_PAIRS = [
+  'brain-keeper',
+  'update-template',
+  'scaffold',
+];
+
+const SKILL_FORBIDDEN_SECTION_PATTERNS = [
+  /^#{1,6}\s+.*\bchecklist\b/i,
+  /^#{1,6}\s+.*\bgolden rule\b/i,
+  /^#{1,6}\s+.*\binviolable rules?\b/i,
+];
+
+const AGENT_FORBIDDEN_BODY_PATTERNS = [
+  /^PT triggers:/i,
+  /^##\s+PT triggers/i,
+];
+
+function checkD1Contract() {
+  const violations = [];
+  for (const name of PATTERN1_PAIRS) {
+    // Skill side
+    const skillPath = path.join(packageRoot(), '.claude', 'skills', name, 'SKILL.md');
+    if (!fs.existsSync(skillPath)) {
+      violations.push({
+        category: 'd1-contract', severity: WARN, file: skillPath, line: 0,
+        msg: `SKILL.md missing for Pattern 1 pair '${name}'`,
+      });
+    } else {
+      const content = readSafe(skillPath);
+      const { body, bodyStartLine } = extractFrontmatter(content || '');
+      const lines = body.split('\n');
+      for (let i = 0; i < lines.length; i++) {
+        for (const pattern of SKILL_FORBIDDEN_SECTION_PATTERNS) {
+          if (pattern.test(lines[i])) {
+            violations.push({
+              category: 'd1-contract', severity: WARN, file: skillPath,
+              line: bodyStartLine + i,
+              msg: `skill body contains forbidden section: "${lines[i].trim()}"`,
+            });
+            break;
+          }
+        }
+      }
+    }
+    // Agent side
+    const agentPath = path.join(packageRoot(), '.claude', 'agents', `${name}.md`);
+    if (!fs.existsSync(agentPath)) {
+      violations.push({
+        category: 'd1-contract', severity: WARN, file: agentPath, line: 0,
+        msg: `agent file missing for Pattern 1 pair '${name}'`,
+      });
+    } else {
+      const content = readSafe(agentPath);
+      const { body, bodyStartLine } = extractFrontmatter(content || '');
+      const lines = body.split('\n');
+      for (let i = 0; i < lines.length; i++) {
+        for (const pattern of AGENT_FORBIDDEN_BODY_PATTERNS) {
+          if (pattern.test(lines[i])) {
+            violations.push({
+              category: 'd1-contract', severity: WARN, file: agentPath,
+              line: bodyStartLine + i,
+              msg: `agent body contains PT trigger section: "${lines[i].trim()}"`,
+            });
+            break;
+          }
+        }
+      }
+    }
+  }
+  return violations;
+}
+
+// ── Category 7: hook-registry (T2.4 / Sprint 2) ───────────────────────────
+// Asserts that flow-guard.js is registered as a UserPromptSubmit hook in
+// .claude/settings.json. Fails if the hook file is absent or not wired.
+
+function checkHookRegistry() {
+  const violations = [];
+  const root = packageRoot();
+  const settingsPath = path.join(root, '.claude', 'settings.json');
+  const hookPath = path.join(root, '.claude', 'hooks', 'flow-guard.js');
+
+  // 1. Hook file must exist
+  if (!fs.existsSync(hookPath)) {
+    violations.push({
+      category: 'hook-registry', severity: ERROR, file: hookPath, line: 0,
+      msg: 'flow-guard.js not found at .claude/hooks/flow-guard.js',
+    });
+  }
+
+  // 2. settings.json must exist and contain UserPromptSubmit + flow-guard reference
+  const settingsContent = readSafe(settingsPath);
+  if (!settingsContent) {
+    violations.push({
+      category: 'hook-registry', severity: ERROR, file: settingsPath, line: 0,
+      msg: 'settings.json not found — flow-guard cannot be registered',
+    });
+    return violations;
+  }
+
+  let settings;
+  try {
+    settings = JSON.parse(settingsContent);
+  } catch {
+    violations.push({
+      category: 'hook-registry', severity: ERROR, file: settingsPath, line: 0,
+      msg: 'settings.json is not valid JSON',
+    });
+    return violations;
+  }
+
+  const hooks = settings && settings.hooks;
+  const userPromptHooks = hooks && hooks.UserPromptSubmit;
+  if (!Array.isArray(userPromptHooks) || userPromptHooks.length === 0) {
+    violations.push({
+      category: 'hook-registry', severity: ERROR, file: settingsPath, line: 0,
+      msg: 'settings.json has no UserPromptSubmit hooks — flow-guard must be registered',
+    });
+    return violations;
+  }
+
+  const hasFlowGuard = userPromptHooks.some((entry) => {
+    if (!entry || !Array.isArray(entry.hooks)) return false;
+    return entry.hooks.some((h) => h && h.command && h.command.includes('flow-guard'));
+  });
+
+  if (!hasFlowGuard) {
+    violations.push({
+      category: 'hook-registry', severity: ERROR, file: settingsPath, line: 0,
+      msg: 'flow-guard.js is not referenced in any UserPromptSubmit hook in settings.json',
+    });
+  }
+
+  return violations;
+}
+
+// ── Category 8: legacy-path-ref (T0.1 / WS-7) ─────────────────────────────
+// Fails if any active .md file under .claude/ or dashboard/public/ still
+// references the old repo name `claude-code-agents`.
+
+const LEGACY_PATH_PATTERN = /claude-code-agents/;
+
+function checkLegacyPathRefs() {
+  const violations = [];
+  const root = packageRoot();
+
+  function scanMdFiles(dir) {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+    catch { return; }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory() && entry.name !== 'node_modules') {
+        scanMdFiles(full);
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        const content = readSafe(full);
+        if (!content) continue;
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+          if (LEGACY_PATH_PATTERN.test(lines[i])) {
+            violations.push({
+              category: 'legacy-path-ref', severity: ERROR,
+              file: full, line: i + 1,
+              msg: `legacy name "claude-code-agents" found — replace with "development-utility-kit"`,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  scanMdFiles(path.join(root, '.claude'));
+  scanMdFiles(path.join(root, 'dashboard', 'public'));
+  return violations;
+}
+
+// ── Category 8: pattern1-thin-skill (T0.2 / ADR-042) ──────────────────────
+// run-sprint/SKILL.md must be a thin trigger (≤ 60 lines of body after
+// frontmatter). The full execution contract lives in sprint-runner.md.
+
+const THIN_SKILL_MAX_LINES = 60;
+
+function checkPattern1ThinSkill() {
+  const violations = [];
+  const skillPath = path.join(packageRoot(), '.claude', 'skills', 'run-sprint', 'SKILL.md');
+  const content = readSafe(skillPath);
+  if (!content) {
+    violations.push({
+      category: 'pattern1-thin-skill', severity: ERROR, file: skillPath, line: 0,
+      msg: 'run-sprint/SKILL.md not found',
+    });
+    return violations;
+  }
+  const { body } = extractFrontmatter(content);
+  const bodyLines = body.split('\n').filter((l) => l.trim() !== '').length;
+  if (bodyLines > THIN_SKILL_MAX_LINES) {
+    violations.push({
+      category: 'pattern1-thin-skill', severity: ERROR, file: skillPath, line: 1,
+      msg: `run-sprint/SKILL.md has ${bodyLines} non-empty body lines (max ${THIN_SKILL_MAX_LINES}). Move the execution contract to .claude/agents/sprint-runner.md per ADR-042.`,
+    });
+  }
+  return violations;
+}
+
+// ── Category 9: moc-gap (T0.3 / WS-11) ────────────────────────────────────
+// Every docs/brain/decisions/ADR-*.md must appear in docs/brain/README.md (MOC).
+// Removing an ADR from the MOC = lint failure (ADR-044).
+
+function checkMocGap() {
+  const violations = [];
+  const root = packageRoot();
+  const mocPath = path.join(root, 'docs', 'brain', 'README.md');
+  const mocContent = readSafe(mocPath);
+  if (!mocContent) {
+    violations.push({
+      category: 'moc-gap', severity: WARN, file: mocPath, line: 0,
+      msg: 'docs/brain/README.md (MOC) not found',
+    });
+    return violations;
+  }
+
+  const adrs = findADRs();
+  for (const adr of adrs) {
+    const id = adr.id;
+    if (!id) continue;
+    // Check MOC references this ADR by its full ID (e.g. ADR-041 or ADR-007)
+    if (!mocContent.includes(`ADR-${id}`)) {
+      violations.push({
+        category: 'moc-gap', severity: ERROR, file: mocPath, line: 0,
+        msg: `ADR-${id} (${adr.filename}) exists in decisions/ but is not listed in MOC (README.md)`,
+      });
+    }
+  }
+  return violations;
+}
+
+// ── Category 10: unversioned-referenced-adr (T0.4 / ADR-044) ──────────────
+// Any ADR referenced by its ID in .claude/**/*.md must be tracked by git.
+// Runs only when inside a git repo.
+
+function checkUnversionedReferencedAdr() {
+  const violations = [];
+  const root = packageRoot();
+
+  // Build set of tracked ADR IDs via git ls-files
+  let trackedIds;
+  try {
+    const { execSync } = require('child_process');
+    const out = execSync('git ls-files docs/brain/decisions/', {
+      cwd: root, encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'],
+    });
+    trackedIds = new Set(
+      out.split('\n')
+        .map((l) => { const m = l.match(/ADR-(\d{3})/); return m ? m[1] : null; })
+        .filter(Boolean)
+    );
+  } catch {
+    // Not in a git repo or git not available — skip silently.
+    return violations;
+  }
+
+  // Scan all .md files under .claude/ for ADR-XYZ references
+  function scanForRefs(dir) {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+    catch { return; }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory() && entry.name !== 'node_modules') {
+        scanForRefs(full);
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        const content = readSafe(full);
+        if (!content) continue;
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+          const refs = lines[i].match(/\bADR-(\d{3})\b/g);
+          if (!refs) continue;
+          for (const ref of refs) {
+            const id = ref.replace('ADR-', '');
+            if (!trackedIds.has(id)) {
+              violations.push({
+                category: 'unversioned-referenced-adr', severity: ERROR,
+                file: full, line: i + 1,
+                msg: `references ${ref} which is not tracked in git (run git add docs/brain/decisions/ADR-${id}-*.md)`,
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+
+  scanForRefs(path.join(root, '.claude'));
+  return violations;
+}
+
+// ── Entry point ─────────────────────────────────────────────────────────────
+
+const CATEGORIES = {
+  skills:                       { fn: checkSkillsFrontmatter,       label: 'skills.frontmatter' },
+  agents:                       { fn: checkAgentsFrontmatter,       label: 'agents.frontmatter' },
+  refs:                         { fn: checkSkillAgentRefs,          label: 'skill → agent refs' },
+  adrs:                         { fn: checkADRCrossRefs,            label: 'ADR cross-refs' },
+  stacks:                       { fn: checkStackPacks,              label: 'stack pack structure' },
+  'd1-contract':                { fn: checkD1Contract,              label: 'D1 contract (skill/agent body)' },
+  'hook-registry':              { fn: checkHookRegistry,            label: 'hook registry (flow-guard wired)' },
+  'legacy-path-ref':            { fn: checkLegacyPathRefs,          label: 'legacy path refs (claude-code-agents)' },
+  'pattern1-thin-skill':        { fn: checkPattern1ThinSkill,       label: 'run-sprint thin trigger (ADR-042)' },
+  'moc-gap':                    { fn: checkMocGap,                  label: 'MOC ↔ decisions gap (ADR-044)' },
+  'unversioned-referenced-adr': { fn: checkUnversionedReferencedAdr, label: 'unversioned referenced ADR (ADR-044)' },
+};
+
+function summarize(violations) {
+  const counts = { ERROR: 0, WARN: 0 };
+  for (const v of violations) counts[v.severity] = (counts[v.severity] || 0) + 1;
+  return counts;
+}
+
+/**
+ * @param {{ json?: boolean, categories?: string[] }} [options]
+ * @returns {number} exit code
+ */
+function runLint(options) {
+  const opts = options || {};
+  const selected = opts.categories && opts.categories.length > 0
+    ? opts.categories.filter((c) => CATEGORIES[c])
+    : Object.keys(CATEGORIES);
+
+  if (opts.categories && selected.length === 0) {
+    process.stderr.write(`Error: unknown category. Valid: ${Object.keys(CATEGORIES).join(', ')}\n`);
+    return 1;
+  }
+
+  let allViolations = [];
+  for (const cat of selected) {
+    allViolations = allViolations.concat(CATEGORIES[cat].fn());
+  }
+
+  const counts = summarize(allViolations);
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({
+      summary: counts,
+      categories: selected,
+      violations: allViolations,
+    }, null, 2) + '\n');
+  } else {
+    process.stdout.write(`duk lint — harness structure validation\n`);
+    process.stdout.write(`Categories: ${selected.map((c) => CATEGORIES[c].label).join(', ')}\n\n`);
+    if (allViolations.length === 0) {
+      process.stdout.write('No violations.\n');
+    } else {
+      // Group by category for readable output
+      const grouped = {};
+      for (const v of allViolations) {
+        if (!grouped[v.category]) grouped[v.category] = [];
+        grouped[v.category].push(v);
+      }
+      for (const cat of Object.keys(grouped)) {
+        process.stdout.write(`── ${CATEGORIES[cat].label} (${grouped[cat].length}) ──\n`);
+        for (const v of grouped[cat]) {
+          const rel = path.relative(packageRoot(), v.file) || v.file;
+          process.stdout.write(`  [${v.severity}] ${rel}:${v.line} — ${v.msg}\n`);
+        }
+        process.stdout.write('\n');
+      }
+      process.stdout.write(`Summary: ${counts.ERROR} ERROR, ${counts.WARN} WARN\n`);
+    }
+  }
+
+  return counts.ERROR > 0 ? 1 : 0;
+}
+
+module.exports = { runLint };