karajan-code 3.1.0 → 3.3.0

package/packages/hu-board/src/plan-mutations.js

@@ -17,13 +17,13 @@
 import { readFileSync, existsSync, readdirSync, mkdirSync, openSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
-import { writeJsonAtomicSync } from '../../../src/utils/atomic-write.js';
+import { writeJsonAtomicSync } from '@karajan/core/atomic-write';
 import { spawn } from 'node:child_process';
 import { trackRun, untrack } from './run-tracker.js';
 import { getHuBoardRunsDir } from './db.js';
 import { fileURLToPath } from 'node:url';
-import { updateHuStatus, certifyAllHus, updateHu } from '../../../src/plan/plan-hu-ops.js';
-import { validateBlockedByChange } from '../../../src/plan/plan-validation.js';
+import { updateHuStatus, certifyAllHus, updateHu } from '@karajan/core/plan-hu-ops';
+import { validateBlockedByChange } from '@karajan/core/plan-validation';
 import { syncPlanFile } from './sync.js';
 import { getDb } from './db.js';
 
@@ -230,7 +230,7 @@ export async function revertHuFromSnapshot({ planId, huId, projectId }) {
   const projectDir = plan.projectDir;
   if (!projectDir) return { ok: false, error: 'plan sin projectDir' };
 
-  const { restoreHuSnapshot } = await import('../../../src/git/hu-snapshot.js');
+  const { restoreHuSnapshot } = await import('@karajan/core/hu-snapshot');
   const restore = await restoreHuSnapshot({ projectDir, huId });
   if (!restore.ok) return { ok: false, error: `restore falló: ${restore.error}` };
 

package/packages/hu-board/src/routes/api.js

@@ -22,6 +22,7 @@ import {
   listPlanIdsForProject,
   updateStoryStatus,
   setProjectIsTest,
+  getProjectCost,
 } from '../db.js';
 import { fullScan } from '../sync.js';
 import { setHuStatus, setHuFields, markPlanReady, runPlan, renameProject, revertHuFromSnapshot } from '../plan-mutations.js';
@@ -285,6 +286,20 @@ router.get('/stories/:id', (req, res) => {
   }
 });
 
+/**
+ * GET /api/projects/:id/cost - Aggregated $ cost for a project (KJC-TSK-0516).
+ * Sums stories.cost_usd, groups by plan_id, returns 404 if project missing.
+ */
+router.get('/projects/:id/cost', (req, res) => {
+  try {
+    const cost = getProjectCost(req.params.id);
+    if (!cost) return res.status(404).json({ error: 'Project not found' });
+    res.json(cost);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
 /**
  * GET /api/projects/:id/sessions - Sessions for a project.
  */
@@ -1325,7 +1340,7 @@ router.post('/rag/query', async (req, res) => {
     return res.status(400).json({ error: "'text' is required (non-empty string)" });
   }
   try {
-    const { openVecStore, countChunks } = await import('../../../../src/rag/vec-store.js');
+    const { openVecStore, countChunks } = await import('@karajan/core/vec-store');
     const { makeEmbedder } = await import('../../../../src/rag/embedders/factory.js');
     const { query } = await import('../../../../src/rag/retriever.js');
     const db = openVecStore({ dim: 768 });

package/packages/hu-board/src/routes/rag.js

@@ -5,7 +5,7 @@
 import { Router } from "express";
 import { existsSync, statSync } from "node:fs";
 import Database from "better-sqlite3";
-import { dbPath } from "../../../../src/rag/vec-store.js";
+import { dbPath } from "@karajan/core/vec-store";
 import { readConfig } from "../config-yaml.js";
 
 const router = Router();

package/packages/hu-board/src/routes/wiki.js

@@ -0,0 +1,43 @@
+// KJC-TSK-0508 — HU Board Wiki panel route.
+// POST /api/wiki/query → spawns `qmd query --format json` against the local
+// per-project QMD wiki (registered by `kj init` via KJC-TSK-0506). Returns
+// 503 with installable:true so the front renders an "Install QMD" CTA
+// instead of a generic error when the binary is missing.
+import { Router } from "express";
+import { runCommand } from "@karajan/core/process";
+
+const router = Router();
+const QMD_NOT_INSTALLED = /command not found|ENOENT|not recognized as/i;
+
+router.post("/query", async (req, res) => {
+  const raw = req.body?.query;
+  const query = typeof raw === "string" ? raw.trim() : "";
+  if (!query) return res.status(400).json({ ok: false, error: "query is required" });
+  const limit = Math.min(Math.max(parseInt(req.body?.limit, 10) || 10, 1), 50);
+  const collection = req.body?.collection ? String(req.body.collection).trim() : null;
+  const fast = req.body?.fast === true;
+
+  const args = ["query", query, "--format", "json", "-n", String(limit)];
+  if (collection) args.push("-c", collection);
+  if (fast) args.push("--no-rerank");
+
+  try {
+    const out = await runCommand("qmd", args, { timeout: 120_000 });
+    if (out.exitCode === 127 || QMD_NOT_INSTALLED.test(out.stderr || "")) {
+      return res.status(503).json({ ok: false, error: "qmd not installed", installable: true });
+    }
+    if (out.exitCode !== 0) {
+      const msg = (out.stderr || out.stdout || `qmd exit ${out.exitCode}`).trim();
+      return res.status(500).json({ ok: false, error: msg });
+    }
+    let results;
+    try { results = JSON.parse(out.stdout || "[]"); }
+    catch { return res.status(500).json({ ok: false, error: "qmd output is not valid JSON" }); }
+    res.json({ ok: true, results, count: Array.isArray(results) ? results.length : 0 });
+  } catch (err) {
+    if (err?.code === "ENOENT") return res.status(503).json({ ok: false, error: "qmd not installed", installable: true });
+    res.status(500).json({ ok: false, error: err?.message || String(err) });
+  }
+});
+
+export default router;

package/packages/hu-board/src/run-tracker.js

@@ -16,7 +16,7 @@
  * se borran como cleanup (responsabilidad de run-registry).
  */
 
-import { listActiveRuns as fsList } from "../../../src/utils/run-registry.js";
+import { listActiveRuns as fsList } from "@karajan/core/run-registry";
 
 const runs = new Map();
 let reaperTimer = null;

package/packages/hu-board/src/server.js

@@ -10,13 +10,14 @@ import { fullScan, startWatcher } from './sync.js';
 import apiRoutes from './routes/api.js';
 import pipelineRoutes from './routes/pipeline.js';
 import ragRoutes from './routes/rag.js';
+import wikiRoutes from './routes/wiki.js';
 import { authMiddleware } from './auth.js';
 import { getOrCreateToken, getTokenPath } from './token-store.js';
 import { reapZombieSessions } from './zombie-reaper.js';
 import { reapZombieHus } from './hu-zombie-reaper.js';
 import { setHuStatus as setHuStatusPlanMutation, setHuFailResult as setHuFailResultPlanMutation } from './plan-mutations.js';
 import { cleanupEphemeralProjects } from './ephemeral-cleaner.js';
-import { findAvailablePort as findAvailablePortBase } from '../../../src/utils/port-check.js';
+import { findAvailablePort as findAvailablePortBase } from '@karajan/core/port-check';
 
 /**
  * Path to the PID file the CLI's `kj board start` / `kj board stop`
@@ -237,7 +238,7 @@ async function main() {
   //   - cooldownUntil > now  → re-programa setTimeout que dispara en cooldown
   // Idempotente (lockfile per session). Cero polling.
   try {
-    const { reconcileAll } = await import('../../../src/brain/standby-scheduler.js');
+    const { reconcileAll } = await import('@karajan/core/standby-scheduler');
     const { spawn } = await import('node:child_process');
     const { join, dirname } = await import('node:path');
     const { fileURLToPath } = await import('node:url');
@@ -300,6 +301,7 @@ async function main() {
   app.use('/api', buildRateLimiter(), authMiddleware(), apiRoutes);
   app.use('/api/pipeline', authMiddleware(), pipelineRoutes);
   app.use('/api/rag', authMiddleware(), ragRoutes);
+  app.use('/api/wiki', authMiddleware(), wikiRoutes);
 
   // SPA fallback: serve index.html for non-API, non-static routes
   app.get('/{*splat}', (_req, res) => {

package/packages/hu-board/src/sync.js

@@ -14,7 +14,7 @@ import {
   removeTombstone,
 } from './db.js';
 import { publish as publishEvent } from './event-bus.js';
-import { getSharedPlansDir, SHARED_DIR_NAME, isSharedPath } from '../../../src/utils/shared-paths.js';
+import { getSharedPlansDir, SHARED_DIR_NAME, isSharedPath } from '@karajan/core/shared-paths';
 import { readConfig } from './config-yaml.js';
 
 /**

package/scripts/git-hooks/post-merge

@@ -3,5 +3,16 @@
 # never serves stale code. Installed by `kj rag install-hooks`. The marker
 # in this comment is how the installer tells kj-managed hooks from user hooks.
 set -euo pipefail
-if ! command -v kj >/dev/null 2>&1; then exit 0; fi
-kj rag index --since auto >/dev/null 2>&1 || true
+if command -v kj >/dev/null 2>&1; then
+  kj rag index --since auto >/dev/null 2>&1 || true
+fi
+
+# KJC-TSK-0507 — Refresh the per-project QMD semantic wiki when the merge
+# touched indexable folders (docs/, .reviews/, .karajan/plans/). Background
+# so it never blocks the user's `git pull` / `git merge`.
+if command -v qmd >/dev/null 2>&1; then
+  if git diff-tree -r --name-only ORIG_HEAD HEAD 2>/dev/null \
+      | grep -qE '^(docs/|\.reviews/|\.karajan/plans/)'; then
+    (qmd update >/dev/null 2>&1 || true) &
+  fi
+fi

package/src/agents/aider-agent.js

@@ -1,6 +1,46 @@
 import { BaseAgent } from "./base-agent.js";
 import { resolveBin } from "./resolve-bin.js";
 
+/**
+ * Extract token usage from Aider's stdout. Two shapes are supported:
+ *
+ *   1. LiteLLM passthrough — an OpenAI-style JSON `usage` block surfaces
+ *      `prompt_tokens_details.cached_tokens` for prompt-cache hits.
+ *   2. Aider's native footer "Tokens: <sent> sent, <received> received
+ *      [, <cached> cache hit]." (supports comma-separated and `k` suffix).
+ *
+ * Returns `{tokens_in, tokens_out, cached_tokens}` or null when no usage
+ * is found (= unmeasured; callers leave the fields undefined).
+ */
+export function extractAiderUsage(text) {
+  if (!text) return null;
+  for (const line of text.split("\n")) {
+    const t = line.trim();
+    if (!t.startsWith("{")) continue;
+    let obj;
+    try { obj = JSON.parse(t); } catch { continue; }
+    const u = obj?.usage ?? (typeof obj?.prompt_tokens === "number" ? obj : null);
+    if (!u || typeof u.prompt_tokens !== "number") continue;
+    return {
+      tokens_in: u.prompt_tokens,
+      tokens_out: u.completion_tokens ?? 0,
+      cached_tokens: u.prompt_tokens_details?.cached_tokens ?? 0
+    };
+  }
+  const m = text.match(/Tokens:\s*([\d.,]+k?)\s*sent,\s*([\d.,]+k?)\s*received(?:,\s*([\d.,]+k?)\s*cache\s*hit)?/i);
+  if (!m) return null;
+  const parse = (s) => {
+    const c = s.replaceAll(",", "");
+    return c.toLowerCase().endsWith("k")
+      ? Math.round(parseFloat(c.slice(0, -1)) * 1000)
+      : Number(c);
+  };
+  const sent = parse(m[1]);
+  const recv = parse(m[2]);
+  if (!Number.isFinite(sent) || !Number.isFinite(recv)) return null;
+  return { tokens_in: sent, tokens_out: recv, cached_tokens: m[3] ? parse(m[3]) : 0 };
+}
+
 export class AiderAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
@@ -32,6 +72,7 @@ export class AiderAgent extends BaseAgent {
       silenceTimeoutMs: task.silenceTimeoutMs,
       timeout: task.timeoutMs
     });
-    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+    const usage = extractAiderUsage(res.stdout) ?? extractAiderUsage(res.stderr);
+    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode, ...usage };
   }
 }

package/src/agents/claude-agent.js

@@ -68,8 +68,16 @@ function collectAssistantText(obj) {
 /**
  * Extract usage metrics from stream-json/json NDJSON output.
  * Looks for the "result" line which contains total_cost_usd,
- * usage.input_tokens/output_tokens, and modelUsage.
- * Returns an object with tokens_in, tokens_out, cost_usd, model or null if not found.
+ * usage.input_tokens/output_tokens, cache_read_input_tokens,
+ * cache_creation_input_tokens, and modelUsage.
+ *
+ * `cached_tokens` aggregates both cache_read_input_tokens (tokens served
+ * from Anthropic's automatic prompt cache) and cache_creation_input_tokens
+ * (tokens just written to the cache during this call). The sum represents
+ * the total volume of input that benefited from prompt-caching machinery.
+ *
+ * Returns an object with tokens_in, tokens_out, cached_tokens, cost_usd,
+ * model or null if not found.
  */
 function extractUsageFromStreamJson(raw) {
   const events = parseClaudeEvents(raw);
@@ -79,11 +87,14 @@ function extractUsageFromStreamJson(raw) {
 
     const tokens_in = obj.usage?.input_tokens ?? 0;
     const tokens_out = obj.usage?.output_tokens ?? 0;
+    const cache_read = obj.usage?.cache_read_input_tokens ?? 0;
+    const cache_creation = obj.usage?.cache_creation_input_tokens ?? 0;
+    const cached_tokens = cache_read + cache_creation;
     const cost_usd = obj.total_cost_usd ?? undefined;
     const modelUsage = obj.modelUsage;
     const model = modelUsage ? Object.keys(modelUsage)[0] || null : null;
 
-    return { tokens_in, tokens_out, cost_usd, model };
+    return { tokens_in, tokens_out, cached_tokens, cost_usd, model };
   }
   return null;
 }

package/src/agents/codex-agent.js

@@ -2,18 +2,55 @@ import { BaseAgent } from "./base-agent.js";
 import { resolveBin } from "./resolve-bin.js";
 
 /**
- * Extract token usage from Codex CLI stdout.
- * Codex prints "tokens used\n<number>" at the end, where number may have comma separators.
- * Returns { tokens_out } with the total token count, or null if not found.
- * Since Codex doesn't split input/output, we assign the total to tokens_out
- * as a conservative estimate for cost calculation.
+ * Try to extract an OpenAI-style `usage` JSON block from codex stdout.
+ *
+ * OpenAI's Chat Completions API exposes prompt-cache hits via
+ * `usage.prompt_tokens_details.cached_tokens` (since Aug 2024). Codex
+ * CLI doesn't surface this in its default footer, but newer flags or a
+ * wrapper may emit a JSON `usage` line. We scan stdout line-by-line and
+ * accept the first parseable object that carries `prompt_tokens`.
+ *
+ * Returns `{tokens_in, tokens_out, cached_tokens}` or null when absent.
+ */
+function extractJsonUsage(stdout) {
+  for (const line of stdout.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("{")) continue;
+    let obj;
+    try { obj = JSON.parse(trimmed); } catch { continue; }
+    const usage = obj?.usage ?? (typeof obj?.prompt_tokens === "number" ? obj : null);
+    if (!usage || typeof usage.prompt_tokens !== "number") continue;
+    return {
+      tokens_in: usage.prompt_tokens,
+      tokens_out: usage.completion_tokens ?? 0,
+      cached_tokens: usage.prompt_tokens_details?.cached_tokens ?? 0
+    };
+  }
+  return null;
+}
+
+/**
+ * Extract token usage from Codex CLI stdout. Two shapes are supported:
+ *
+ *   1. OpenAI-style JSON `usage` block (preferred):
+ *      `{"usage":{"prompt_tokens":N,"completion_tokens":M,
+ *                 "prompt_tokens_details":{"cached_tokens":C}}}`
+ *      → `{tokens_in:N, tokens_out:M, cached_tokens:C}`.
+ *
+ *   2. Legacy "tokens used\n<number>" footer (codex's default total,
+ *      no cache visibility) → `{tokens_in:0, tokens_out, cached_tokens:0}`.
+ *
+ * Returns null when neither shape is found.
  */
 function extractCodexTokens(stdout) {
-  const match = (stdout || "").match(/tokens?\s+used\s*\n\s*([\d,]+)/i);
+  if (!stdout) return null;
+  const json = extractJsonUsage(stdout);
+  if (json) return json;
+  const match = stdout.match(/tokens?\s+used\s*\n\s*([\d,]+)/i);
   if (!match) return null;
   const total = Number(match[1].replaceAll(/,/g, ""));
   if (!Number.isFinite(total) || total <= 0) return null;
-  return { tokens_in: 0, tokens_out: total };
+  return { tokens_in: 0, tokens_out: total, cached_tokens: 0 };
 }
 
 export class CodexAgent extends BaseAgent {

package/src/agents/gemini-agent.js

@@ -1,6 +1,41 @@
 import { BaseAgent } from "./base-agent.js";
 import { resolveBin } from "./resolve-bin.js";
 
+/**
+ * Extract Gemini's `usageMetadata` from stdout, including
+ * `cachedContentTokenCount` (Gemini's context-caching API metric,
+ * https://ai.google.dev/api/caching).
+ *
+ * The gemini CLI emits `usageMetadata` as part of its JSON response
+ * shape (today: only `--output-format json`, used in reviewTask; in
+ * plain runTask mode no usage is surfaced). When absent, returns null
+ * so the caller leaves `cached_tokens` undefined (= unmeasured,
+ * distinct from a measured 0).
+ */
+export function extractGeminiUsage(text) {
+  if (!text) return null;
+  const candidates = [];
+  for (const line of text.split("\n")) {
+    const t = line.trim();
+    if (t.startsWith("{") || t.startsWith("[")) candidates.push(t);
+  }
+  candidates.push(text.trim());
+  for (const candidate of candidates) {
+    let obj;
+    try { obj = JSON.parse(candidate); } catch { continue; }
+    const meta = obj?.usageMetadata
+      ?? obj?.usage_metadata
+      ?? obj?.response?.usageMetadata;
+    if (!meta || typeof meta.promptTokenCount !== "number") continue;
+    return {
+      tokens_in: meta.promptTokenCount,
+      tokens_out: meta.candidatesTokenCount ?? 0,
+      cached_tokens: meta.cachedContentTokenCount ?? 0
+    };
+  }
+  return null;
+}
+
 export class GeminiAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
@@ -33,6 +68,7 @@ export class GeminiAgent extends BaseAgent {
       silenceTimeoutMs: task.silenceTimeoutMs,
       timeout: task.timeoutMs
     });
-    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+    const usage = extractGeminiUsage(res.stdout) ?? extractGeminiUsage(res.stderr);
+    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode, ...usage };
   }
 }

package/src/agents/opencode-agent.js

@@ -1,6 +1,38 @@
 import { BaseAgent } from "./base-agent.js";
 import { resolveBin } from "./resolve-bin.js";
 
+/**
+ * Extract OpenAI-style `usage` from OpenCode stdout. With `--format json`
+ * (used in reviewTask) the CLI emits a JSON document; with LiteLLM-backed
+ * runs that document carries `usage.prompt_tokens_details.cached_tokens`.
+ *
+ * Accepts the whole payload, individual lines, or array elements with a
+ * nested `usage` object. Returns `{tokens_in, tokens_out, cached_tokens}`
+ * or null (= unmeasured).
+ */
+export function extractOpenCodeUsage(text) {
+  if (!text) return null;
+  const candidates = [text.trim()];
+  for (const line of text.split("\n")) {
+    const t = line.trim();
+    if (t.startsWith("{") || t.startsWith("[")) candidates.push(t);
+  }
+  for (const candidate of candidates) {
+    let obj;
+    try { obj = JSON.parse(candidate); } catch { continue; }
+    const usage = obj?.usage
+      ?? obj?.result?.usage
+      ?? (Array.isArray(obj) ? obj.find((e) => e?.usage)?.usage : null);
+    if (!usage || typeof usage.prompt_tokens !== "number") continue;
+    return {
+      tokens_in: usage.prompt_tokens,
+      tokens_out: usage.completion_tokens ?? 0,
+      cached_tokens: usage.prompt_tokens_details?.cached_tokens ?? 0
+    };
+  }
+  return null;
+}
+
 export class OpenCodeAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
@@ -34,6 +66,7 @@ export class OpenCodeAgent extends BaseAgent {
       silenceTimeoutMs: task.silenceTimeoutMs,
       timeout: task.timeoutMs
     });
-    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+    const usage = extractOpenCodeUsage(res.stdout) ?? extractOpenCodeUsage(res.stderr);
+    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode, ...usage };
   }
 }

package/src/audit/ai-slop-findings.js

@@ -0,0 +1,102 @@
+// AI-slop tells detector — KJC-TSK-0503. Deterministic, offline,
+// regex-based scanner over JS/TS source. Five categories:
+// tautologic-comments, banner-separators, boilerplate-docstrings,
+// magic-fallbacks, redundant-jsdoc. Score 100 = clean.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const FILE_EXTS = new Set([".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx"]);
+const IGNORE_DIRS = new Set([
+  "node_modules", "dist", "build", "coverage",
+  ".git", ".karajan", "public", ".next", ".nuxt", ".vercel", ".cache",
+]);
+const VERB = "(?:returns?|gets?|sets?|fetches?|loads?|saves?|creates?|builds?|makes?|computes?|handles?|checks?|validates?)";
+const LINE_PATTERNS = {
+  "banner-separators": /\/[/*]\s*[=*\-_#~]{5,}/,
+  "magic-fallbacks": /(\?\?|\|\|)\s*(?:""|''|null|undefined)\s*(?:\)|;|,|$)/,
+  "redundant-jsdoc": new RegExp(`@param\\s+\\{[^}]+\\}\\s+(\\w+)\\s+(?:-\\s*)?(?:the\\s+)?\\1\\s+(?:parameter|argument|value)`, "i"),
+};
+const TAUT_RE = new RegExp(`^\\s*//\\s*${VERB}\\s+(?:the\\s+|a\\s+|an\\s+)?(\\w+)\\s*\\.?\\s*$`, "i");
+const DOC_RE = new RegExp(`^\\s*/\\*\\*\\s*${VERB}\\s+(?:the\\s+|a\\s+|an\\s+)?(\\w+)\\s*\\.?\\s*\\*/\\s*$`, "i");
+const DECL_RE = /^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function|const|let|var|class)\s+(\w+)/;
+
+export const CATEGORIES = Object.freeze([
+  "tautologic-comments", "banner-separators", "boilerplate-docstrings",
+  "magic-fallbacks", "redundant-jsdoc",
+]);
+
+function nextDecl(lines, from) {
+  for (let j = from; j < Math.min(from + 3, lines.length); j++) {
+    const m = lines[j]?.match(DECL_RE);
+    if (m) return m[1];
+  }
+  return null;
+}
+const stem = (a, b) => { const al = a.toLowerCase(), bl = b.toLowerCase(); return al === bl || al.includes(bl) || bl.includes(al); };
+
+export function scanText(relPath, text) {
+  const out = [];
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNo = i + 1;
+    for (const [category, re] of Object.entries(LINE_PATTERNS)) {
+      if (re.test(line)) out.push({ path: relPath, line: lineNo, category, snippet: line.trim().slice(0, 100) });
+    }
+    const t = line.match(TAUT_RE);
+    if (t) {
+      const decl = nextDecl(lines, i + 1);
+      if (decl && stem(decl, t[1])) out.push({ path: relPath, line: lineNo, category: "tautologic-comments", snippet: line.trim().slice(0, 100) });
+    }
+    const d = line.match(DOC_RE);
+    if (d) {
+      const decl = nextDecl(lines, i + 1);
+      if (decl && stem(decl, d[1])) out.push({ path: relPath, line: lineNo, category: "boilerplate-docstrings", snippet: line.trim().slice(0, 100) });
+    }
+  }
+  return out;
+}
+
+function listSourceFiles(root) {
+  const out = [];
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (IGNORE_DIRS.has(e.name) || e.name.startsWith(".")) continue;
+        stack.push(full);
+      } else if (FILE_EXTS.has(path.extname(e.name))) out.push(full);
+    }
+  }
+  return out;
+}
+
+export async function collectAiSlop(rootDir, opts = {}) {
+  const maxLOC = Number.isFinite(opts.maxLOC) ? opts.maxLOC : 200_000;
+  const maxWorst = Number.isFinite(opts.maxWorst) ? opts.maxWorst : 10;
+  try {
+    const findings = [];
+    let totalLOC = 0, filesScanned = 0;
+    for (const file of listSourceFiles(rootDir)) {
+      if (totalLOC >= maxLOC) break;
+      let content;
+      try { content = fs.readFileSync(file, "utf-8"); } catch { continue; }
+      findings.push(...scanText(path.relative(rootDir, file) || file, content));
+      totalLOC += content.split(/\r?\n/).length;
+      filesScanned++;
+    }
+    const byCategory = Object.fromEntries(CATEGORIES.map((c) => [c, 0]));
+    for (const f of findings) byCategory[f.category]++;
+    const density = totalLOC > 0 ? (findings.length / totalLOC) * 100 : 0;
+    const score = Math.max(0, Math.min(100, Math.round(100 - density * 100)));
+    const worst = findings.slice().sort((a, b) => (a.path === b.path ? a.line - b.line : a.path.localeCompare(b.path))).slice(0, maxWorst);
+    return { available: true, filesScanned, totalLOC, total: findings.length, score, byCategory, worst };
+  } catch (err) {
+    return { available: false, reason: err?.message || String(err) };
+  }
+}

package/src/audit/deterministic-summary.js

@@ -41,11 +41,28 @@ export function formatDeterministicSummary(ctx) {
   if (ctx.circularDeps) lines.push(...formatCircularDepsBlock(ctx.circularDeps));
   if (ctx.deadExports) lines.push(...formatDeadExportsBlock(ctx.deadExports));
   if (ctx.injectionFindings) lines.push(...formatInjectionBlock(ctx.injectionFindings));
+  if (ctx.aiSlop) lines.push(...formatAiSlopBlock(ctx.aiSlop));
   if (ctx.webperf) lines.push(...formatWebperfBlock(ctx.webperf));
 
   return lines.join("\n");
 }
 
+function formatAiSlopBlock(slop) {
+  if (!slop.available) return ["### AI-slop tells (deterministic)", `- Status: not available — ${slop.reason || "scan failed"}`, ""];
+  const lines = ["### AI-slop tells (deterministic)", `- Files scanned: ${slop.filesScanned ?? 0}`, `- Score: ${slop.score}/100 (100 = clean)`, `- Findings: ${slop.total ?? 0}`];
+  if ((slop.total ?? 0) > 0) {
+    for (const [cat, n] of Object.entries(slop.byCategory || {})) {
+      if (n > 0) lines.push(`  - ${cat}: ${n}`);
+    }
+    if (Array.isArray(slop.worst) && slop.worst.length > 0) {
+      lines.push("  - Worst offenders:");
+      for (const f of slop.worst) lines.push(`    - ${f.path}:${f.line} [${f.category}] ${f.snippet}`);
+    }
+  }
+  lines.push("");
+  return lines;
+}
+
 function formatInjectionBlock(inj) {
   if (!inj.available) return ["### Prompt-injection scan", `- Status: not available — ${inj.reason || "scan failed"}`, ""];
   const lines = ["### Prompt-injection scan (specs / domain / onboarding)", `- Files scanned: ${inj.scanned ?? 0}`, `- Findings: ${inj.total ?? 0}`];
@@ -278,5 +295,6 @@ export function deterministicContextHasFindings(ctx) {
   if (ctx.circularDeps?.available && (ctx.circularDeps.total ?? 0) > 0) return true;
   if (ctx.deadExports?.available && (ctx.deadExports.total ?? 0) > 0) return true;
   if (ctx.growthDelta && (Math.abs(ctx.growthDelta.lines || 0) > 100 || Math.abs(ctx.growthDelta.deps || 0) > 0)) return true;
+  if (ctx.aiSlop?.available && (ctx.aiSlop.total ?? 0) > 0) return true;
   return false;
 }