contextdevkit 1.8.0

package/templates/contextkit/tools/scripts/deep-analysis.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * Deep analysis — the deterministic aggregator behind `/deep-analysis`.
+ *
+ * Runs every deterministic scanner the project ships and merges their findings
+ * into ONE report, shaped for `pipeline.mjs ingest`. The slash command adds the
+ * judgment layer (security/architecture/bugs) on top. Defensive: a scanner that
+ * errors or isn't applicable contributes nothing rather than failing the run.
+ *
+ *   node .../deep-analysis.mjs            # console summary
+ *   node .../deep-analysis.mjs --json     # merged { findings: [...] }
+ *   node .../deep-analysis.mjs --write    # → contextkit/memory/deep-analysis-findings.json
+ */
+import { execFileSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+
+const ROOT = process.cwd();
+const P = pathsFor(ROOT);
+const SCANS = [
+  { name: 'tech-debt', script: 'tech-debt-scan.mjs' },
+  { name: 'deps', script: 'deps-audit.mjs' },
+  { name: 'contract', script: 'contract-scan.mjs' },
+];
+
+function runScan(script) {
+  try {
+    const out = execFileSync('node', [`contextkit/tools/scripts/${script}`, '--json'], { cwd: ROOT, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 120000 });
+    const parsed = JSON.parse(out.replace(/^/, ''));
+    return Array.isArray(parsed) ? parsed : parsed.findings || [];
+  } catch {
+    return [];
+  }
+}
+
+function main() {
+  const findings = [];
+  const byScan = {};
+  for (const s of SCANS) {
+    const f = runScan(s.script).map((x) => ({ ...x, scan: s.name }));
+    byScan[s.name] = f.length;
+    findings.push(...f);
+  }
+  const report = { findings, byScan, total: findings.length, at: new Date().toISOString() };
+
+  if (process.argv.includes('--write')) {
+    writeFileSync(resolve(P.memory, 'deep-analysis-findings.json'), JSON.stringify(report, null, 2), 'utf-8');
+    console.log(`🔬 deep-analysis: ${findings.length} finding(s) → contextkit/memory/deep-analysis-findings.json`);
+    console.log('   → ingest:  node contextkit/tools/scripts/pipeline.mjs ingest contextkit/memory/deep-analysis-findings.json --type chore');
+    return;
+  }
+  if (process.argv.includes('--json')) {
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    return;
+  }
+  console.log(`🔬 deep-analysis: ${findings.length} deterministic finding(s) across ${SCANS.length} scanners.`);
+  for (const [k, n] of Object.entries(byScan)) console.log(`   ${k}: ${n}`);
+  console.log('   (run /deep-analysis for the full sweep: + judgment, report, ADRs, backlog.)');
+}
+
+main();

package/templates/contextkit/tools/scripts/deps-audit.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/**
+ * Dependency / supply-chain audit — the security-team's deterministic check.
+ *
+ * Zero-dep checks on the manifest + lockfile + installed metadata, plus an
+ * OPTIONAL native audit (`npm`/`pnpm`/`yarn audit`) when the toolchain is
+ * present and online. Findings are shaped to feed `pipeline.mjs ingest`
+ * (kind/severity/path/message/source), so supply-chain issues flow into the
+ * DevPipeline backlog like any other finding.
+ *
+ * Policy lives in `contextkit/config.json` → `deps` (requireLockfile, license
+ * allow/deny); see runtime/config/defaults.mjs.
+ *
+ *   node .../deps-audit.mjs            # console summary
+ *   node .../deps-audit.mjs --json     # machine-readable { findings: [...] }
+ *   node .../deps-audit.mjs --write    # → contextkit/memory/deps-findings.json (for ingest)
+ *   node .../deps-audit.mjs --sbom     # → contextkit/memory/sbom.json (CycloneDX)
+ *
+ * Defensive: never throws; degrades to "nothing to report" when it can't tell.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfigSync } from '../../runtime/config/load.mjs';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+import { readJsonSafe } from '../../runtime/hooks/safe-io.mjs';
+
+const ROOT = process.cwd();
+const P = pathsFor(ROOT);
+const SEV = { critical: 5, high: 4, moderate: 3, low: 2, info: 1 };
+const findings = [];
+
+function add(severity, kind, message, path = 'package.json') {
+  findings.push({ kind, severity, path, message, source: `deps:${kind}:${path}` });
+}
+
+const readJson = (p) => readJsonSafe(p);
+
+function depPolicy() {
+  try {
+    return loadConfigSync(ROOT).deps || {};
+  } catch {
+    return { requireLockfile: true, licenses: { allow: [], deny: [] } };
+  }
+}
+
+/** All declared dependency names (prod + dev). */
+function depNames(pkg) {
+  return Object.keys({ ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) });
+}
+
+/** Best-effort SPDX id from an installed package's metadata. null if unknown. */
+function licenseOf(name) {
+  const meta = readJson(resolve(ROOT, 'node_modules', name, 'package.json'));
+  if (!meta) return null;
+  if (typeof meta.license === 'string') return meta.license;
+  if (meta.license && typeof meta.license.type === 'string') return meta.license.type;
+  if (Array.isArray(meta.licenses) && meta.licenses[0]?.type) return meta.licenses[0].type;
+  return null;
+}
+
+function auditLicenses(pkg, policy) {
+  const allow = (policy.licenses?.allow || []).map((s) => s.toLowerCase());
+  const deny = (policy.licenses?.deny || []).map((s) => s.toLowerCase());
+  if (!allow.length && !deny.length) return;
+  for (const name of depNames(pkg)) {
+    const lic = licenseOf(name);
+    if (!lic) continue; // not installed / unknown — degrade silently
+    const l = lic.toLowerCase();
+    if (deny.includes(l)) add(4, 'license-deny', `\`${name}\`: license ${lic} is denied by policy (deps.licenses.deny).`);
+    else if (allow.length && !allow.includes(l)) add(2, 'license-unlisted', `\`${name}\`: license ${lic} is not in the allow-list (deps.licenses.allow).`);
+  }
+}
+
+/** Heuristic: a declared dep that does not appear in the lockfile text. */
+function auditDrift(pkg, lockText) {
+  for (const name of depNames(pkg)) {
+    const present = lockText.includes(`node_modules/${name}`) || lockText.includes(`"${name}"`) || lockText.includes(`${name}@`) || lockText.includes(`/${name}/`);
+    if (!present) add(2, 'lockfile-drift', `\`${name}\` is declared but not found in the lockfile — run install to sync it.`);
+  }
+}
+
+function buildSbom(pkg) {
+  const all = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const components = Object.entries(all).map(([name, range]) => {
+    const meta = readJson(resolve(ROOT, 'node_modules', name, 'package.json'));
+    const version = meta?.version || String(range).replace(/^[^0-9]*/, '') || '0.0.0';
+    const lic = licenseOf(name);
+    return { type: 'library', name, version, purl: `pkg:npm/${name}@${version}`, ...(lic ? { licenses: [{ license: { id: lic } }] } : {}) };
+  });
+  return {
+    bomFormat: 'CycloneDX',
+    specVersion: '1.5',
+    metadata: {
+      timestamp: new Date().toISOString(),
+      tools: [{ vendor: 'ContextDevKit', name: 'deps-audit' }],
+      component: { type: 'application', name: pkg.name || 'app', version: pkg.version || '0.0.0' },
+    },
+    components,
+  };
+}
+
+function findLock() {
+  const locks = ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'npm-shrinkwrap.json'];
+  return locks.find((l) => existsSync(resolve(ROOT, l)));
+}
+
+function auditNode(policy) {
+  if (!existsSync(resolve(ROOT, 'package.json'))) return false;
+  const pkg = readJson(resolve(ROOT, 'package.json')) || {};
+  const all = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const hasDeps = Object.keys(all).length > 0;
+
+  const lock = findLock();
+  if (hasDeps && !lock && policy.requireLockfile !== false) add(4, 'no-lockfile', 'No lockfile committed — installs are not reproducible. Commit one.');
+
+  for (const [name, range] of Object.entries(all)) {
+    if (typeof range !== 'string') continue;
+    if (range === '*' || range === 'latest' || /^[><]/.test(range)) {
+      add(3, 'loose-range', `\`${name}\`: "${range}" is unbounded — pin a version (or a caret range with a lockfile).`);
+    }
+  }
+
+  auditLicenses(pkg, policy);
+  if (lock) {
+    auditDrift(pkg, readFileSync(resolve(ROOT, lock), 'utf-8'));
+    runNativeAudit(lock);
+  }
+  return true;
+}
+
+function runNativeAudit(lock) {
+  const pm = lock.startsWith('pnpm') ? 'pnpm' : lock.startsWith('yarn') ? 'yarn' : 'npm';
+  try {
+    parseNpmAudit(execFileSync(pm, ['audit', '--json'], { cwd: ROOT, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 60000 }));
+  } catch (err) {
+    // `npm audit` exits non-zero when vulnerabilities exist — the JSON is still on stdout.
+    if (err?.stdout) {
+      try { parseNpmAudit(err.stdout); return; } catch { /* fall through */ }
+    }
+    add(1, 'audit-skipped', `Could not run \`${pm} audit\` (offline or unavailable) — run it before release.`);
+  }
+}
+
+function parseNpmAudit(out) {
+  const parsed = JSON.parse(out);
+  for (const [name, v] of Object.entries(parsed.vulnerabilities || {})) { // npm v7+
+    add(SEV[v.severity] || 2, 'cve', `\`${name}\`: ${v.severity} advisory — see \`npm audit\`.`);
+  }
+  for (const a of Object.values(data.advisories || {})) { // npm v6
+    add(SEV[a.severity] || 2, 'cve', `\`${a.module_name}\`: ${a.severity} — ${a.title}.`);
+  }
+}
+
+function pythonHint() {
+  if (existsSync(resolve(ROOT, 'requirements.txt')) || existsSync(resolve(ROOT, 'pyproject.toml'))) {
+    add(1, 'py-audit', 'Python deps detected — run `pip-audit` / `safety check` for CVEs (not automated here yet).');
+  }
+}
+
+function writeSbom() {
+  const pkg = readJson(resolve(ROOT, 'package.json'));
+  if (!pkg) {
+    console.log('🔐 deps-audit --sbom: no package.json found.');
+    return;
+  }
+  const out = resolve(P.memory, 'sbom.json');
+  writeFileSync(out, JSON.stringify(buildSbom(pkg), null, 2), 'utf-8');
+  console.log('🔐 deps-audit: SBOM written → contextkit/memory/sbom.json (CycloneDX 1.5).');
+}
+
+function main() {
+  if (process.argv.includes('--sbom')) {
+    writeSbom();
+    return;
+  }
+  auditNode(depPolicy());
+  pythonHint();
+  const report = { findings };
+
+  if (process.argv.includes('--write')) {
+    writeFileSync(resolve(P.memory, 'deps-findings.json'), JSON.stringify(report, null, 2), 'utf-8');
+    console.log(`🔐 deps-audit: ${findings.length} finding(s) → contextkit/memory/deps-findings.json`);
+    console.log('   → feed the backlog:  node contextkit/tools/scripts/pipeline.mjs ingest contextkit/memory/deps-findings.json --type chore');
+    return;
+  }
+  if (process.argv.includes('--json')) {
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    return;
+  }
+  if (findings.length === 0) {
+    console.log('🔐 deps-audit: no issues found.');
+    return;
+  }
+  console.log(`🔐 deps-audit: ${findings.length} finding(s).`);
+  for (const f of [...findings].sort((a, b) => b.severity - a.severity)) {
+    console.log(`   ${'●'.repeat(f.severity)} ${f.kind} — ${f.message}`);
+  }
+}
+
+main();

package/templates/contextkit/tools/scripts/detect-stack.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * Read-only project analyzer for `/setupcontextdevkit`.
+ *
+ * Inspects the project root and prints a JSON report: languages, package
+ * manager, frameworks, monorepo flag, likely source dirs, README summary, and
+ * SUGGESTED `ledger` path lists + `l5.highRiskPaths` tuned to the detected
+ * stack. It writes nothing — the slash command decides what to apply.
+ *
+ * Usage:  node contextkit/tools/scripts/detect-stack.mjs   (prints JSON)
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const ROOT = process.cwd();
+
+const read = (rel) => {
+  try {
+    return readFileSync(resolve(ROOT, rel), 'utf-8').replace(/^/, '');
+  } catch {
+    return null;
+  }
+};
+const has = (rel) => existsSync(resolve(ROOT, rel));
+const isDir = (rel) => {
+  try {
+    return statSync(resolve(ROOT, rel)).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+function detectPackageManager() {
+  if (has('pnpm-lock.yaml')) return 'pnpm';
+  if (has('yarn.lock')) return 'yarn';
+  if (has('bun.lockb')) return 'bun';
+  if (has('package-lock.json')) return 'npm';
+  const pkg = readJson('package.json');
+  if (pkg?.packageManager) return String(pkg.packageManager).split('@')[0];
+  return has('package.json') ? 'npm' : null;
+}
+
+function readJson(rel) {
+  const raw = read(rel);
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function detectLanguages() {
+  const langs = new Set();
+  if (has('package.json')) langs.add('javascript');
+  if (has('tsconfig.json') || has('tsconfig.base.json')) langs.add('typescript');
+  if (has('pyproject.toml') || has('requirements.txt') || has('setup.py')) langs.add('python');
+  if (has('go.mod')) langs.add('go');
+  if (has('Cargo.toml')) langs.add('rust');
+  if (has('pom.xml') || has('build.gradle') || has('build.gradle.kts')) langs.add('java/kotlin');
+  if (has('Gemfile')) langs.add('ruby');
+  if (has('composer.json')) langs.add('php');
+  return [...langs];
+}
+
+function detectFrameworks() {
+  const pkg = readJson('package.json');
+  const deps = pkg ? Object.keys({ ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) }) : [];
+  const known = ['next', 'react', 'react-native', 'expo', 'vue', 'nuxt', 'svelte', '@sveltejs/kit', 'astro', 'solid-js', 'angular', 'hono', 'express', 'fastify', '@nestjs/core', 'koa', 'drizzle-orm', 'prisma', '@prisma/client', 'typeorm', 'mongoose', 'vite', 'webpack', 'electron', 'tauri', '@tanstack/start', '@tanstack/react-router', '@tanstack/react-query', '@tanstack/react-table', '@tanstack/react-form', '@tanstack/react-virtual', '@tanstack/solid-query', '@tanstack/vue-query'];
+  const found = known.filter((k) => deps.includes(k));
+  if (has('manage.py')) found.push('django');
+  if (read('requirements.txt')?.match(/flask/i) || read('pyproject.toml')?.match(/flask/i)) found.push('flask');
+  if (read('pyproject.toml')?.match(/fastapi/i) || read('requirements.txt')?.match(/fastapi/i)) found.push('fastapi');
+  return found;
+}
+
+function detectTestRunner() {
+  const pkg = readJson('package.json');
+  const deps = pkg ? Object.keys({ ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) }) : [];
+  for (const t of ['vitest', 'jest', 'mocha', 'ava', 'playwright', '@playwright/test', 'cypress']) if (deps.includes(t)) return t;
+  if (has('pytest.ini') || read('pyproject.toml')?.match(/pytest/i)) return 'pytest';
+  return null;
+}
+
+const CODE_DIR_CANDIDATES = ['src', 'app', 'apps', 'packages', 'lib', 'components', 'pages', 'server', 'client', 'cmd', 'internal', 'pkg', 'tests', 'test', 'spec', 'api', 'core', 'modules'];
+
+function detectSourceDirs() {
+  return CODE_DIR_CANDIDATES.filter((d) => isDir(d)).map((d) => `${d}/`);
+}
+
+function detectMonorepo() {
+  if (has('pnpm-workspace.yaml') || has('lerna.json') || has('turbo.json') || has('nx.json')) return true;
+  const pkg = readJson('package.json');
+  return Boolean(pkg?.workspaces);
+}
+
+function suggestHighRiskPaths() {
+  const out = new Set();
+  const candidates = [
+    'prisma/schema.prisma', 'db/schema.ts', 'src/db/schema.ts', 'packages/db/src/schema.ts', 'drizzle/', 'migrations/', 'db/migrations/',
+    'src/auth/', 'auth/', 'src/middleware/auth.ts', 'src/lib/auth/',
+    'openapi.yaml', 'openapi.json', 'schema.graphql', 'src/schema.graphql',
+    'packages/shared-types/', 'packages/shared/', 'src/contracts/', 'src/types/',
+    'wrangler.toml', 'serverless.yml', 'Dockerfile', '.github/workflows/',
+  ];
+  for (const c of candidates) if (has(c)) out.add(c.endsWith('/') ? c : c);
+  // any *.proto at root-ish
+  return [...out];
+}
+
+function suggestLedger(sourceDirs, languages) {
+  const important = new Set([...sourceDirs, 'contextkit/', '.claude/', '.github/', 'CLAUDE.md']);
+  for (const m of ['package.json', 'tsconfig.json', 'pyproject.toml', 'go.mod', 'Cargo.toml', 'pom.xml', 'Gemfile', 'composer.json', 'pnpm-workspace.yaml', 'turbo.json', 'wrangler.toml']) {
+    if (has(m)) important.add(m);
+  }
+  const irrelevant = new Set(['node_modules/', '.git/', '.context-snapshot.md', '.claude/.sessions/', '.claude/.workspace/']);
+  for (const d of ['dist/', 'build/', 'out/', '.next/', '.turbo/', '.expo/', '.svelte-kit/', 'coverage/', '__pycache__/', '.pytest_cache/', 'target/', 'vendor/', '.venv/', 'venv/', 'bin/', 'obj/']) {
+    if (isDir(d.replace(/\/$/, '')) || ['node_modules/', 'dist/', 'build/'].includes(d)) irrelevant.add(d);
+  }
+  return { important: [...important], irrelevant: [...irrelevant] };
+}
+
+function readmeSummary() {
+  for (const name of ['README.md', 'readme.md', 'README.MD', 'Readme.md']) {
+    const raw = read(name);
+    if (raw) {
+      const lines = raw.split('\n').map((l) => l.trim()).filter(Boolean).slice(0, 8);
+      return lines.join(' ').slice(0, 600);
+    }
+  }
+  return null;
+}
+
+function rootEntries() {
+  try {
+    return readdirSync(ROOT).filter((e) => !e.startsWith('.tmp')).slice(0, 60);
+  } catch {
+    return [];
+  }
+}
+
+const sourceDirs = detectSourceDirs();
+const languages = detectLanguages();
+const report = {
+  root: ROOT,
+  languages,
+  packageManager: detectPackageManager(),
+  frameworks: detectFrameworks(),
+  testRunner: detectTestRunner(),
+  monorepo: detectMonorepo(),
+  sourceDirs,
+  hasReadme: Boolean(readmeSummary()),
+  readmeSummary: readmeSummary(),
+  rootEntries: rootEntries(),
+  greenfield: sourceDirs.length === 0 && languages.length === 0,
+  suggested: {
+    ledger: suggestLedger(sourceDirs, languages),
+    highRiskPaths: suggestHighRiskPaths(),
+    qaCriticalPaths: suggestHighRiskPaths(),
+    recommendedLevel: sourceDirs.length === 0 ? 1 : 2,
+  },
+};
+
+process.stdout.write(JSON.stringify(report, null, 2) + '\n');

package/templates/contextkit/tools/scripts/distill-detect.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * `/log-session` companion — scans the just-written session narrative for
+ * **rule-like phrases** that look constitutional ("we decided X", "from now on
+ * Y", "we should always Z") and surfaces them as **proposal-only** candidates
+ * for `/distill-sessions`. Ticket 043 (Compozy follow-through).
+ *
+ * Posture: **propose, never apply**. This script does not edit `CLAUDE.md`. It
+ * prints one nudge line at the end of `/log-session` and exits 0 either way —
+ * a session with no candidates is not an error, just quiet.
+ *
+ * Optimised for *low false-negatives*. Per the ticket: the cost of a wrong
+ * nudge is one ignored line; the cost of a missed nudge is silent drift.
+ *
+ * Usage:
+ *   distill-detect.mjs <path-to-session-file.md>     # nudge mode
+ *   distill-detect.mjs <path> --json                 # machine-readable
+ *
+ * Zero-dep, pure ESM over `node:*`.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Regex set, ordered roughly by signal strength. Each pattern has a `kind` so
+ * `--json` output can be triaged downstream (e.g. by `/distill-sessions`).
+ *
+ * Keep this list tight — Tier-1 phrases only. Tier-2 phrases ("maybe we
+ * should…", "consider…") produce false positives that train the user to
+ * ignore the nudge.
+ */
+const PATTERNS = [
+  { kind: 'decision', re: /\b(we|i)\s+decided\s+(that\s+|to\s+)/i },
+  { kind: 'decision', re: /\bdecision:\s*\S/i },
+  { kind: 'rule', re: /\bfrom now on\b/i },
+  { kind: 'rule', re: /\bwe\s+(should|must|will)\s+always\b/i },
+  { kind: 'rule', re: /\bwe\s+(should|must|will)\s+never\b/i },
+  { kind: 'rule', re: /\balways\s+(use|prefer|require|enforce)\b/i },
+  { kind: 'rule', re: /\bnever\s+(use|allow|skip|bypass)\b/i },
+  { kind: 'convention', re: /\bconvention:\s*\S/i },
+  { kind: 'invariant', re: /\binvariant:\s*\S/i },
+  { kind: 'lesson', re: /\blesson\s+learn(ed|t)\b/i },
+];
+
+/**
+ * Scans `text` (typically the body of a session log) and returns every
+ * matched candidate sentence. Sentence boundaries are heuristic — `. `, `! `,
+ * `? `, and newline blocks — which is fine: the user only reads the count
+ * + first match.
+ *
+ * @param {string} text
+ * @returns {Array<{ kind: string, line: number, snippet: string }>}
+ */
+export function detect(text) {
+  if (typeof text !== 'string' || text.length === 0) return [];
+  const lines = text.split('\n');
+  const hits = [];
+  const seenLines = new Set();
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (line.trim().startsWith('#')) continue; // skip headings
+    if (line.trim().startsWith('>')) continue; // skip block quotes (often quoting prior decisions, not new ones)
+    for (const { kind, re } of PATTERNS) {
+      if (!re.test(line)) continue;
+      const key = `${i}:${kind}`;
+      if (seenLines.has(key)) continue;
+      seenLines.add(key);
+      const snippet = line.trim().slice(0, 120);
+      hits.push({ kind, line: i + 1, snippet });
+    }
+  }
+  return hits;
+}
+
+function main() {
+  const file = process.argv[2];
+  if (!file) { console.error('Usage: distill-detect.mjs <session-file.md> [--json]'); process.exit(1); }
+  if (!existsSync(file)) { console.error(`distill-detect: file not found — ${file}`); process.exit(1); }
+  const text = readFileSync(file, 'utf-8');
+  const hits = detect(text);
+  if (process.argv.includes('--json')) { console.log(JSON.stringify({ candidates: hits.length, hits }, null, 2)); return; }
+  if (hits.length === 0) return; // quiet success
+  const kinds = [...new Set(hits.map((h) => h.kind))].join(', ');
+  console.log('');
+  console.log(`💡 ${hits.length} rule-like phrase(s) detected (${kinds}). Consider /distill-sessions to propose them for CLAUDE.md.`);
+  console.log(`   First match: ${hits[0].snippet}`);
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) main();