karajan-code 3.0.0 → 3.2.0

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.
  */
@@ -545,15 +560,27 @@ router.post('/tombstones/:type/:id/restore', (req, res) => {
  * rewritten before we ack, then re-synced into SQLite, so a reload
  * renders the committed state.
  */
-// Status que el USUARIO puede setear manualmente vía el dropdown del
-// modal. NO incluimos coding/reviewing/running — esos son lifecycle
-// del orquestador (settearlos a mano genera zombies). Tampoco
-// incluimos los canonicales (`running`) por la misma razón. `failed`
-// y `blocked` son útiles para que el usuario marque manualmente HUs
-// que no quiere correr ahora.
-// KJC-TSK-0403: 'failed' eliminado — el orquestador estampa result=fail
-// dejando status=pending. Setearlo a mano vía PATCH ya no tiene sentido.
-const ALLOWED_STORY_STATUSES = new Set(['pending', 'certified', 'done', 'blocked', 'needs_context']);
+// KJC-TSK-0394 PR6 (AC 6): el PATCH endpoint sólo acepta el modelo
+// canónico {pending, running, done}. Status legacy (`certified`,
+// `coding`, `reviewing`, `failed`, `blocked`, `needs_context`) siguen
+// vivos en plans existentes y los traduce la UI con canonicalStatus(),
+// pero NO pueden ser seteados por escrituras nuevas — devolvemos 400
+// con `suggestion` apuntando al mapping correcto. `running` queda fuera
+// del dropdown del modal (lifecycle del orquestador), pero el endpoint
+// lo acepta por si un programa externo lo necesita.
+const ALLOWED_STORY_STATUSES = new Set(['pending', 'running', 'done']);
+// Mapping canónico para la sugerencia del 400 cuando el caller manda
+// un valor legacy. Mantenemos la regla viva en src/plan/plan-schema.js
+// (mapLegacyStatusToResult) — esta tabla es sólo el subset accionable
+// desde el endpoint (status + result).
+const LEGACY_STATUS_SUGGESTION = {
+  certified: { status: 'done', result: 'pass' },
+  failed: { status: 'pending', result: 'fail' },
+  coding: { status: 'running', result: null },
+  reviewing: { status: 'running', result: null },
+  blocked: { status: 'pending', result: null },
+  needs_context: { status: 'pending', result: null },
+};
 // KJC-TSK-0406: coder_model y reviewer_model son editables desde el
 // modal del board. Independientes — el usuario puede subir el reviewer
 // y bajar el coder sin afectar al resto del plan.
@@ -579,8 +606,14 @@ router.patch('/stories/:id', (req, res) => {
       });
     }
     if (hasStatus && !ALLOWED_STORY_STATUSES.has(body.status)) {
+      // KJC-TSK-0394 PR6 (AC 6): si el caller manda un status legacy,
+      // devolvemos un 400 con `suggestion` apuntando al mapping canónico.
+      // Una herramienta externa puede leer el body, aplicar el mapeo y
+      // re-intentar — sin tener que descubrir la tabla por ensayo y error.
+      const suggestion = LEGACY_STATUS_SUGGESTION[body.status] || null;
       return res.status(400).json({
         error: `status must be one of: ${[...ALLOWED_STORY_STATUSES].join(', ')}`,
+        suggestion,
       });
     }
 
@@ -1307,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/audit-test-diet.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * scripts/audit-test-diet.mjs — semantic loss-of-meaning auditor (KJC-TSK-0345).
+ * Categories: empty-no-expect, skipped-pending, imports-orphan, deprecated-export,
+ * subsumed-candidate. Each finding carries confidence (high|low). Complements
+ * tests/_diet/audit.mjs (which classifies by LOC bucket only).
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_ROOT = resolve(HERE, "..");
+const SKIP_DIRS = new Set(["_diet", "fixtures", "node_modules"]);
+
+export function walkTests(rootDir, testsSubdir = "tests") {
+  const out = [];
+  const base = join(rootDir, testsSubdir);
+  if (!existsSync(base)) return out;
+  const stack = [base];
+  while (stack.length) {
+    for (const e of readdirSync(stack.pop(), { withFileTypes: true })) {
+      const p = join(e.parentPath ?? base, e.name);
+      if (e.isDirectory() && !SKIP_DIRS.has(e.name)) stack.push(p);
+      else if (e.isFile() && /\.test\.(m?js|ts)$/.test(e.name)) out.push(p);
+    }
+  }
+  return out;
+}
+
+export function parseImports(source) {
+  const imports = [];
+  const re = /^[ \t]*import\s+(?:([\w*\s{},]+?)\s+from\s+)?['"]([^'"]+)['"]/gm;
+  let m;
+  while ((m = re.exec(source)) !== null) {
+    const named = [];
+    const braced = (m[1] || "").match(/\{([^}]+)\}/);
+    if (braced) for (const part of braced[1].split(",")) {
+      const name = part.trim().split(/\s+as\s+/)[0].trim();
+      if (name) named.push(name);
+    }
+    imports.push({ specifier: m[2], named });
+  }
+  return imports;
+}
+
+export function resolveSrcImport(testFile, specifier, rootDir) {
+  if (!specifier.startsWith(".") && !specifier.startsWith("#")) return null;
+  const base = specifier.startsWith("#") ? resolve(rootDir, specifier.replace(/^#/, "src/")) : resolve(dirname(testFile), specifier);
+  for (const c of [base, `${base}.js`, `${base}.mjs`, join(base, "index.js")]) {
+    if (existsSync(c) && statSync(c).isFile()) return c;
+  }
+  return null;
+}
+
+export function extractItNames(source) {
+  const names = new Set();
+  for (const m of source.matchAll(/\b(?:it|test)(?:\.(?:only|skip|todo))?\s*\(\s*['"`]([^'"`]+)['"`]/g)) names.add(m[1]);
+  return names;
+}
+
+export function extractExports(source) {
+  const names = new Set();
+  for (const m of source.matchAll(/export\s+(?:async\s+)?(?:function|class|const|let|var)\s+([A-Za-z_$][\w$]*)/g)) names.add(m[1]);
+  for (const m of source.matchAll(/export\s*\{([^}]+)\}/g)) for (const part of m[1].split(",")) {
+    const name = part.trim().split(/\s+as\s+/).pop().trim();
+    if (name) names.add(name);
+  }
+  if (/export\s+default\b/.test(source)) names.add("default");
+  return names;
+}
+
+export function auditFile(testFile, rootDir) {
+  const source = readFileSync(testFile, "utf-8");
+  const rel = relative(rootDir, testFile);
+  const findings = [];
+  const hasIt = /\b(?:it|test)\s*\(/.test(source);
+  if (hasIt && !/\bexpect\s*\(/.test(source)) findings.push({ category: "empty-no-expect", confidence: "high", detail: "it()/test() blocks with no expect()" });
+  if (/\b(?:it|test|describe)\.skip\s*\(|\bxit\s*\(|\bxtest\s*\(|\b(?:it|test)\.todo\s*\(/.test(source)) {
+    findings.push({ category: "skipped-pending", confidence: "high", detail: "uses .skip / xit / xtest / .todo" });
+  }
+  const srcImports = [];
+  for (const imp of parseImports(source)) {
+    if (!imp.specifier.startsWith(".") && !imp.specifier.startsWith("#")) continue;
+    const resolved = resolveSrcImport(testFile, imp.specifier, rootDir);
+    if (!resolved) { findings.push({ category: "imports-orphan", confidence: "high", detail: `cannot resolve '${imp.specifier}'` }); continue; }
+    if (imp.named.length) {
+      const missing = imp.named.filter((n) => !extractExports(readFileSync(resolved, "utf-8")).has(n));
+      if (missing.length) findings.push({ category: "deprecated-export", confidence: "low", detail: `${imp.specifier} no longer exports: ${missing.join(", ")}` });
+    }
+    srcImports.push({ resolved: relative(rootDir, resolved), named: imp.named });
+  }
+  return { path: rel, srcImports, findings, itNames: extractItNames(source) };
+}
+
+export function findSubsumed(perFile) {
+  const bySrc = new Map();
+  for (const f of perFile) for (const imp of f.srcImports) {
+    if (!bySrc.has(imp.resolved)) bySrc.set(imp.resolved, []);
+    bySrc.get(imp.resolved).push({ path: f.path, named: new Set(imp.named), itNames: f.itNames });
+  }
+  const out = [];
+  for (const [src, consumers] of bySrc) {
+    if (consumers.length < 2) continue;
+    const sorted = [...consumers].sort((a, b) => a.named.size - b.named.size);
+    const narrow = sorted[0]; const broad = sorted[sorted.length - 1];
+    if (narrow.path === broad.path || narrow.named.size === 0 || broad.named.size === 0) continue;
+    if (!(narrow.named.size < broad.named.size && [...narrow.named].every((n) => broad.named.has(n)))) continue;
+    // Require ≥50% of narrow's it() names to also appear in broad's. Imports
+    // alone are a false-positive trap: two tests can share helpers and assert
+    // on disjoint behavior (e.g. tests/budget.test.js vs tests/utils/budget.test.js).
+    if (narrow.itNames.size === 0) continue;
+    const overlap = [...narrow.itNames].filter((n) => broad.itNames.has(n)).length;
+    if (overlap / narrow.itNames.size < 0.5) continue;
+    out.push({ category: "subsumed-candidate", confidence: "low", path: narrow.path, detail: `${overlap}/${narrow.itNames.size} it() names also in ${broad.path}; subset of imports from ${src}` });
+  }
+  return out;
+}
+
+export function auditTestDiet(rootDir = DEFAULT_ROOT) {
+  const files = walkTests(rootDir);
+  const perFile = files.map((f) => auditFile(f, rootDir));
+  const findings = [];
+  for (const f of perFile) for (const x of f.findings) findings.push({ path: f.path, ...x });
+  for (const s of findSubsumed(perFile)) findings.push(s);
+  return { generatedAt: new Date().toISOString(), rootDir, totals: { filesAudited: files.length, findings: findings.length }, findings };
+}
+
+export function renderMarkdown(report) {
+  const byCat = new Map();
+  for (const f of report.findings) {
+    if (!byCat.has(f.category)) byCat.set(f.category, []);
+    byCat.get(f.category).push(f);
+  }
+  const lines = [`# Semantic test-diet audit`, ``, `Generated: ${report.generatedAt}`, `Files audited: ${report.totals.filesAudited}`, `Findings: ${report.totals.findings}`, ``];
+  for (const [cat, items] of byCat) {
+    lines.push(`## ${cat} (${items.length})`, ``);
+    for (const it of items) lines.push(`- \`${it.path}\` — ${it.detail} (confidence: ${it.confidence})`);
+    lines.push(``);
+  }
+  return lines.join("\n");
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const report = auditTestDiet(DEFAULT_ROOT);
+  const outDir = join(DEFAULT_ROOT, "audit");
+  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+  writeFileSync(join(outDir, "test-diet-semantic.json"), JSON.stringify(report, null, 2));
+  writeFileSync(join(outDir, "test-diet-semantic.md"), renderMarkdown(report));
+  console.log(`audit: ${report.totals.filesAudited} files, ${report.totals.findings} findings -> audit/test-diet-semantic.{json,md}`);
+}

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/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;
 }

package/src/audit/harness-scorecard.js

@@ -2,11 +2,44 @@
 // One-shot container: detect Docker, auto-pull on first run (cache hit
 // thereafter), execute `assess <repo>` with the project mounted read-only.
 // No compose, no port discovery — assess is a single process that exits.
+//
+// KJC-BUG-0077 — classify failures (docker_missing / image_inaccessible /
+// auth_required / network_error / unknown) and emit an actionable hint
+// alongside the raw stderr so `kj audit` surfaces something better than
+// the opaque "pull access denied" line the registry returns.
 import { runCommand } from "../utils/process.js";
 
 const D = { image: "markmishaev76/ai-harness-scorecard:latest", pullTimeoutMs: 300000, assessTimeoutMs: 180000 };
 const pos = (v, d) => (Number(v) > 0 ? Number(v) : d);
 
+const DOCKER_FAILURE_PATTERNS = [
+  { reason: "image_inaccessible", re: /pull access denied|repository does not exist|manifest unknown|not found: manifest|denied: requested access/i },
+  { reason: "auth_required",      re: /unauthorized|authentication required|login required|requires authentication/i },
+  { reason: "network_error",      re: /no such host|connection refused|dial tcp|i\/o timeout|TLS handshake|net\/http|temporary failure in name resolution/i },
+];
+
+export function classifyDockerFailure(stderr = "") {
+  const s = String(stderr);
+  for (const { reason, re } of DOCKER_FAILURE_PATTERNS) {
+    if (re.test(s)) return reason;
+  }
+  return "unknown";
+}
+
+export function hintForReason(reason, image) {
+  switch (reason) {
+    case "image_inaccessible":
+      return `Image \`${image}\` is not accessible from the public registry (it may have been removed, renamed, or made private). Either run \`kj audit --no-harness\` to skip this step, or override \`audit.harness.image\` with a mirror you control.`;
+    case "auth_required":
+      return `Pulling \`${image}\` requires registry authentication. Run \`docker login <registry>\` first, or override \`audit.harness.image\` with a public mirror.`;
+    case "network_error":
+      return `Network error reaching the registry while pulling \`${image}\`. Retry once connectivity is back; \`kj audit --no-harness\` skips this step in the meantime.`;
+    case "docker_missing":
+      return `Docker is not available on this machine. Install Docker (or run \`kj audit --no-harness\` to silence this).`;
+    default: return null;
+  }
+}
+
 export function normalizeHarnessConfig(h = {}) {
   return {
     enabled: h.enabled !== false,
@@ -32,20 +65,36 @@ export async function ensureHarnessImage(harness = null) {
   const cfg = normalizeHarnessConfig(harness || {});
   if (await isHarnessImagePresent(cfg.image)) return { pulled: false, reused: true, image: cfg.image };
   const r = await runCommand("docker", ["pull", cfg.image], { timeout: cfg.pullTimeoutMs });
-  if (r.exitCode !== 0) return { pulled: false, reused: false, image: cfg.image, error: r.stderr?.trim() || `exit ${r.exitCode}` };
+  if (r.exitCode !== 0) {
+    const stderr = r.stderr?.trim() || `exit ${r.exitCode}`;
+    const reason = classifyDockerFailure(stderr);
+    return { pulled: false, reused: false, image: cfg.image, error: stderr, reason };
+  }
   return { pulled: true, reused: false, image: cfg.image };
 }
 
 export async function runHarnessAssess(repoPath, harness = null) {
   const cfg = normalizeHarnessConfig(harness || {});
+  if (!(await isDockerAvailable())) {
+    return { ok: false, reason: "docker_missing", image: cfg.image, error: "Docker daemon is not available", hint: hintForReason("docker_missing", cfg.image) };
+  }
+  const pull = await ensureHarnessImage(cfg);
+  if (pull.error) {
+    const reason = pull.reason || "pull_failed";
+    return { ok: false, reason, image: cfg.image, error: pull.error, hint: hintForReason(reason, cfg.image) };
+  }
   const r = await runCommand(
     "docker",
     ["run", "--rm", "-v", `${repoPath}:/repo:ro`, cfg.image, "assess", "/repo", "--format", "json"],
     { timeout: cfg.assessTimeoutMs },
   );
-  if (r.exitCode !== 0) return { ok: false, error: r.stderr?.trim() || r.stdout?.trim() || `exit ${r.exitCode}` };
+  if (r.exitCode !== 0) {
+    const stderr = r.stderr?.trim() || r.stdout?.trim() || `exit ${r.exitCode}`;
+    const reason = classifyDockerFailure(stderr);
+    return { ok: false, reason, image: cfg.image, error: stderr, hint: hintForReason(reason, cfg.image) };
+  }
   try {
     const parsed = JSON.parse(r.stdout);
     return { ok: true, score: parsed.overall_score, grade: parsed.grade, raw: parsed };
-  } catch (e) { return { ok: false, error: `Invalid JSON from harness: ${e.message}` }; }
+  } catch (e) { return { ok: false, reason: "invalid_json", error: `Invalid JSON from harness: ${e.message}` }; }
 }

package/src/audit/harness-section.js

@@ -22,7 +22,7 @@ export async function runHarnessSection({ projectDir, harnessConfig = null, runA
   const cfg = normalizeHarnessConfig(harnessConfig || {});
   if (!cfg.enabled) return { ok: true, skipped: true, reason: "disabled" };
   const res = await runAssess(projectDir, cfg);
-  if (!res.ok) return { ok: false, error: res.error };
+  if (!res.ok) return { ok: false, error: res.error, reason: res.reason, hint: res.hint, image: cfg.image };
   const outDir = path.join(projectDir, ".karajan", "audit-runs", ts());
   await fs.mkdir(outDir, { recursive: true });
   const scorecardPath = path.join(outDir, "scorecard.json");
@@ -39,7 +39,11 @@ export async function runHarnessSection({ projectDir, harnessConfig = null, runA
 
 export function formatHarnessSection(summary) {
   if (!summary || summary.skipped) return "";
-  if (!summary.ok) return `## Harness Scorecard\n\n_skipped: ${summary.error}_\n`;
+  if (!summary.ok) {
+    const reason = summary.reason ? ` (${summary.reason})` : "";
+    const hint = summary.hint ? `\n\n${summary.hint}\n` : "";
+    return `## Harness Scorecard\n\n_skipped${reason}: ${summary.error}_${hint}\n`;
+  }
   const lines = [
     `## Harness Health Score: ${summary.score}/100 (${summary.grade})`,
     "",