karajan-code 2.31.0 → 2.33.0

package/README.md

@@ -345,6 +345,22 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 
 ## Recent releases
 
+> **v2.33.0 released** — Minor. **AI Harness Scorecard golden metric (KJC-PCS-0051, Plan B)** — every `kj audit` now boots a Docker one-shot of `addyosmani/ai-harness-scorecard`, gets a deterministic 0–100 score + A–F grade, persists it to a per-project `audit-history.db`, and on the next run renders the delta vs the previous baseline plus an optional Unicode-bar trend sparkline. One golden number for "how AI-friendly is this repo today vs last week," zero LLM tokens spent.
+>
+> - **Harness Docker one-shot** (PR #877, KJC-TSK-0470): `src/audit/harness-runner.js` runs `docker run --rm -v <repo>:/repo addyosmani/ai-harness-scorecard analyze`, parses the verdict, auto-skips on missing Docker. `--no-harness` opts out.
+> - **`kj audit` integrates the score** (PR #878, KJC-TSK-0471): new harness-section renderer; JSON output gains `harnessScore`; runs during the deterministic phase so `--deterministic-only` users get it too.
+> - **Per-project audit history** (PR #879, KJC-TSK-0472): `.karajan/audit-history.db` (better-sqlite3 + WAL + `PRAGMA user_version=1`) persists every run. SEA bundle stubbed (degrades gracefully); npm install unlocks history.
+> - **Diff + trend sparkline** (PR #880, KJC-TSK-0473): `src/audit/audit-history-display.js` (pure module, safe in SEA) computes overall delta + per-category deltas + biggest improvement/regression + stale-baseline flag (>30 days). New `--trend` flag prints a `▁▂▃▄▅▆▇█` sparkline over the last N runs.
+>
+> **v2.32.0 released** — Minor. **AI Harness Scorecard hardening (KJC-PCS-0051)** — Plan A closes five FAILs from the external scorecard audit in one sprint: Prettier `--check`, Coverage v8 reports, Conventional Commits enforcement, nightly drift detection, and an unsafe-code lint policy. Plus two bug fixes shipped alongside.
+>
+> - **Prettier `--check` CI job** (PR #868, KJC-TSK-0464): new `format` job blocks PRs whose formatting drifts from `.prettierrc.json`. Scope narrow at first (`.github/workflows/`, root config); future PRs fold in more dirs under the shrink-budget cap.
+> - **Coverage v8 + CI artifact** (PR #870, KJC-TSK-0465): `vitest.config.js` emits `text + html + lcov` via `@vitest/coverage-v8`. New `coverage` job uploads `coverage/` (14-day retention). Per-glob thresholds enforced when the user opts in; `src/mcp/handlers/**` floor ratcheted to `70/60` to lock the current state — follow-up tracked to climb back to 80/80.
+> - **Conventional Commits on PR head** (PR #872, KJC-TSK-0466): `wagoid/commitlint-github-action@v6` checks every PR commit against `.commitlintrc.json`. CI-side enforcement on top of the pre-commit local hook — bypassing husky no longer escapes the gate.
+> - **Nightly drift workflow** (PR #873, KJC-TSK-0467): new `.github/workflows/nightly.yml` runs the full CI suite every night at 04:17 UTC against `main`. Failures auto-file/update a tracking issue tagged `drift` via `actions/github-script@v8`, so a flaky dep or upstream regression surfaces within 24 h instead of on the next unrelated PR.
+> - **`eslint-plugin-security` policy** (PR #874, KJC-TSK-0468): `eslint.config.js` now blocks `eval`, `new Function`, dynamic `require`, `pseudoRandomBytes` and `mustache`-escape disabling as hard errors; flags `detect-non-literal-regexp` as warn. Noisy members of the recommended preset are intentionally NOT enabled.
+> - **42 tests on `main` repaired** (PR #869, KJC-BUG-0065) and **`await openEditor` race in spec-reviewer refine-loop fixed** (PR #871, KJC-BUG-0066). The hardening sprint sits on a clean `main` again.
+>
 > **v2.31.0 released** — Minor. **Team-shared HU Board** — the full KJC-PRP-0002: opt-in HUs into a `.karajan-shared/` cohort, the board surfaces them with a `shared` badge, and per-HU `assignee` lets multiple machines work the same plan without trampling each other.
 >
 > - **`kj plan share` / `kj plan unshare`** (PRs #860, #862): mueve plans entre `~/.karajan/plans/` (local) y `<projectDir>/.karajan-shared/plans/` (compartido). Idempotente. El loader probará ambos automáticamente.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.31.0",
+  "version": "2.33.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -55,9 +55,12 @@
     "setup": "node scripts/install.js",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "lint:syntax": "((command -v rg >/dev/null 2>&1 && rg --files src tests | rg '\\.js$') || find src tests -type f -name '*.js') | while IFS= read -r f; do node --check \"$f\"; done",
+    "format:check": "prettier --check .",
+    "format:fix": "prettier --write .",
     "typecheck": "npx -p typescript@5 tsc --noEmit -p tsconfig.json",
     "validate": "npm run lint && npm run lint:syntax && npm test",
     "mcp": "node src/mcp/server.js"
@@ -90,9 +93,11 @@
     "esbuild": "^0.28.0",
     "eslint": "^10.2.1",
     "eslint-plugin-import-x": "^4.16.2",
+    "eslint-plugin-security": "^4.0.0",
     "globals": "^17.5.0",
     "lint-staged": "^16.4.0",
     "postject": "^1.0.0-alpha.6",
+    "prettier": "^3.4.2",
     "simple-git-hooks": "^2.13.1",
     "vitest": "^4.0.0"
   }

package/packages/hu-board/public/app.js

@@ -3352,7 +3352,10 @@ async function showConfigEditor(scope = 'global') {
         <span style="font-size:0.85rem;color:var(--text-muted);">${f.value ? 'activado' : 'desactivado'}</span>
       </label>`;
     } else if (f.type === 'number') {
-      input = `<input type="number" id="${id}" data-key="${esc(f.key)}" value="${esc(String(f.value))}"${f.min != null ? ` min="${f.min}"` : ''}${f.max != null ? ` max="${f.max}"` : ''} style="width:120px;padding:6px 8px;background:var(--bg-primary);border:1px solid var(--border);color:var(--text);border-radius:var(--radius-sm);">`;
+      // KJC-BUG-0069 — honour the schema's `step` (e.g. 'any' for floats like
+      // rag.search.alpha=0.6). HTML5 number inputs default to step=1, which
+      // marks any fractional value as stepMismatch and refuses to commit.
+      input = `<input type="number" id="${id}" data-key="${esc(f.key)}" value="${esc(String(f.value))}"${f.min != null ? ` min="${f.min}"` : ''}${f.max != null ? ` max="${f.max}"` : ''}${f.step != null ? ` step="${esc(String(f.step))}"` : ''} style="width:120px;padding:6px 8px;background:var(--bg-primary);border:1px solid var(--border);color:var(--text);border-radius:var(--radius-sm);">`;
     }
     return `
       <div style="margin-bottom:14px;">

package/packages/hu-board/src/config-yaml.js

@@ -235,11 +235,10 @@ export const EDITABLE_FIELDS = [
     help: 'Orquestador IA central: enriquece feedback, comprime outputs y verifica cambios reales. Opt-in.',
     default: false,
   },
-  // v2.30.0 — RAG controls. Sólo se exponen las claves que el código
-  // realmente lee hoy (rag.preload.* en rag-context-stage.js y
-  // rag.embedder.provider en embedders/factory.js). mode/alpha/rerank
-  // se controlan vía flags CLI; cuando se cableen en config se añadirán
-  // aquí (ver task #99).
+  // v2.30.0 — RAG controls. Cubren los tres ejes que afectan al
+  // retrieval en tiempo de pipeline: pre-carga (rag.preload.*),
+  // proveedor de embeddings (rag.embedder.provider) y parámetros de
+  // búsqueda (rag.search.*, cableados al stage en KJC-TSK-0463).
   {
     key: 'ragPreloadEnabled',
     path: 'rag.preload.enabled',
@@ -280,6 +279,42 @@ export const EDITABLE_FIELDS = [
     options: ['ollama', 'openai', 'voyage', 'cohere', 'mistral', 'onnx'],
     default: 'ollama',
   },
+  // KJC-TSK-0463 — search-time knobs ahora cableados al stage.
+  // mode/alpha controlan el fuse semantic vs keyword; rerank activa el
+  // cross-encoder opcional (más calidad, más latencia).
+  {
+    key: 'ragSearchMode',
+    path: 'rag.search.mode',
+    category: 'rag',
+    type: 'select',
+    label: 'Modo de búsqueda RAG',
+    help: '"hybrid" mezcla semántico + BM25 (recomendado). "semantic" sólo embeddings. "keyword" sólo BM25 (útil si los embeddings están desafinados).',
+    options: ['hybrid', 'semantic', 'keyword'],
+    default: 'hybrid',
+  },
+  {
+    key: 'ragSearchAlpha',
+    path: 'rag.search.alpha',
+    category: 'rag',
+    type: 'number',
+    label: 'Alpha del modo hybrid (0-1)',
+    help: 'Peso del scoring semántico vs keyword en modo hybrid. 1.0 = sólo semántico, 0.0 = sólo BM25, 0.6 (default) = inclinado a semántico.',
+    min: 0,
+    max: 1,
+    // KJC-BUG-0069 — number input defaults to step=1 (HTML5), so any
+    // non-integer default fails validity. Allow any fractional value here.
+    step: 'any',
+    default: 0.6,
+  },
+  {
+    key: 'ragSearchRerank',
+    path: 'rag.search.rerank',
+    category: 'rag',
+    type: 'boolean',
+    label: 'Activar rerank cross-encoder',
+    help: 'Re-puntúa los topK supervivientes con un cross-encoder. Mejora calidad pero añade latencia y requiere modelo extra. Opt-in.',
+    default: false,
+  },
   // KJC-PRP-0002 PR5: when the board scans plans, it visits both
   // ~/.karajan/plans/<slug>/ (per-user cache) and .karajan-shared/plans/
   // (team copy). If a planId lives in both, the second pass overwrites

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

@@ -24,12 +24,18 @@ router.get("/stats", (_req, res) => {
   if (!existsSync(path)) return res.json({ ok: true, initialized: false, message: "rag.db not initialized — run `kj rag index <dir>` to start indexing.", embedder: embedder() });
   try {
     const db = new Database(path, { readonly: true, fileMustExist: true });
+    // KJC-BUG-0068 — readonly handler cannot run the project_slug migration
+    // (KJC-TSK-0438). Legacy DBs created pre-v2.27 lack the column; detect
+    // and fall back so the dashboard renders instead of crashing with 500.
+    const hasProjectSlug = db.prepare("PRAGMA table_info(chunks)").all().some((c) => c.name === "project_slug");
     const total_chunks = db.prepare("SELECT COUNT(*) AS n FROM chunks").get().n;
     const by_kind = db.prepare("SELECT kind, COUNT(*) AS n FROM chunks GROUP BY kind").all();
-    const by_project = db.prepare("SELECT COALESCE(project_slug, '(no slug)') AS project, COUNT(*) AS n FROM chunks GROUP BY project_slug ORDER BY n DESC LIMIT 20").all();
+    const by_project = hasProjectSlug
+      ? db.prepare("SELECT COALESCE(project_slug, '(no slug)') AS project, COUNT(*) AS n FROM chunks GROUP BY project_slug ORDER BY n DESC LIMIT 20").all()
+      : [];
     const last_indexed = db.prepare("SELECT MAX(created_at) AS ts FROM chunks").get().ts;
     db.close();
-    res.json({ ok: true, initialized: true, db_path: path, db_size_bytes: statSync(path).size, total_chunks, by_kind, by_project, last_indexed, embedder: embedder() });
+    res.json({ ok: true, initialized: true, db_path: path, db_size_bytes: statSync(path).size, total_chunks, by_kind, by_project, last_indexed, embedder: embedder(), schema_legacy: !hasProjectSlug });
   } catch (err) { res.status(500).json({ ok: false, error: String(err.message || err) }); }
 });
 

package/scripts/ai-attribution-guard.yml

@@ -20,8 +20,12 @@ jobs:
           fetch-depth: 0
 
       - name: Check PR diff for AI attribution
+        # KJC-BUG-0072 — never interpolate ${{ github.* }} directly inside a
+        # `run:` block on pull_request workflows. Pin to env vars instead.
+        env:
+          BASE_REF: ${{ github.base_ref }}
         run: |
-          DIFF=$(git diff origin/${{ github.base_ref }}...HEAD \
+          DIFF=$(git diff "origin/${BASE_REF}...HEAD" \
             -- ':!*.png' ':!*.jpg' ':!*.svg' ':!*.ico' \
                ':!*.lock' ':!package-lock.json' ':!yarn.lock' \
                ':!*.min.js' ':!*.min.css' \
@@ -54,8 +58,11 @@ jobs:
           echo "AI attribution guard: clean"
 
       - name: Check commit messages
+        # KJC-BUG-0072 — same hardening as the diff scan: env-pin the ref.
+        env:
+          BASE_REF: ${{ github.base_ref }}
         run: |
-          COMMITS=$(git log --format='%s%n%b' origin/${{ github.base_ref }}...HEAD)
+          COMMITS=$(git log --format='%s%n%b' "origin/${BASE_REF}...HEAD")
 
           COAUTH='Co-Authored-By:.*\b(Claude|Anthropic|OpenAI|ChatGPT|Copilot|Gemini|Cursor|Windsurf|Codeium)\b'
           ATTR='(Generated|Created|Written|Built|Authored) (by|with|using) .*(Claude|Anthropic|OpenAI|ChatGPT|Copilot|Gemini|Cursor|Windsurf|Codeium)'

package/scripts/esbuild-sea.config.mjs

@@ -191,6 +191,15 @@ const ragStubPlugin = {
   },
 };
 
+// KJC-TSK-0472 — audit-history sqlite stub (same reasoning as rag/hu-board stubs).
+const auditHistoryStubPlugin = {
+  name: "audit-history-stub",
+  setup(b) {
+    b.onResolve({ filter: /[\\/]audit[\\/]audit-history\.js$/ }, (a) => ({ path: a.path, namespace: "ahs" }));
+    b.onLoad({ filter: /.*/, namespace: "ahs" }, () => ({ contents: "module.exports = { __esModule: false, persistAuditRun: () => ({ ok: false, error: 'history disabled in SEA' }), getAuditHistoryDbPath: () => null, openAuditHistoryDb: () => null, recordAuditRun: () => null, listRecentRuns: () => [], countRuns: () => 0, pruneOldRuns: () => 0, getLatestPreviousRun: () => null, getRecentScores: () => [] };", loader: "js" }));
+  },
+};
+
 /** @type {import('esbuild').BuildOptions} */
 export const seaBuildOptions = {
   entryPoints: ["src/cli.js"],
@@ -221,6 +230,6 @@ export const seaBuildOptions = {
   // throws → collector returns available:false. npm installs get knip
   // resolved normally from node_modules.
   external: ["better-sqlite3", "madge", "knip", "oxc-parser", "oxc-resolver"],
-  plugins: [seaTransformPlugin, huBoardStubPlugin, ragStubPlugin],
+  plugins: [seaTransformPlugin, huBoardStubPlugin, ragStubPlugin, auditHistoryStubPlugin],
   logLevel: "info",
 };

package/src/audit/audit-history-display.js

@@ -0,0 +1,61 @@
+// KJC-TSK-0473 — Pure display helpers for audit history (diff + sparkline).
+// No DB / native-module deps; safe to bundle into the SEA binary.
+
+const SPARK_BARS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
+
+function scoreOf(c) {
+  if (!c || typeof c !== "object") return null;
+  return typeof c.score === "number" ? c.score : typeof c.percent === "number" ? c.percent : null;
+}
+
+export function computeHistoryDiff(currentHarness, previousRow) {
+  if (!currentHarness || typeof currentHarness.score !== "number") return null;
+  if (!previousRow || typeof previousRow.score !== "number") return { previousScore: null, firstRun: true };
+  let prevCats = {};
+  try { prevCats = previousRow.categories_json ? JSON.parse(previousRow.categories_json) || {} : {}; } catch { /* keep empty */ }
+  const currCats = currentHarness.categories || {};
+  const categoryDeltas = [];
+  for (const name of Object.keys(currCats)) {
+    const cur = scoreOf(currCats[name]);
+    const prev = scoreOf(prevCats[name]);
+    if (typeof cur === "number" && typeof prev === "number") {
+      categoryDeltas.push({ name, current: cur, previous: prev, delta: cur - prev });
+    }
+  }
+  const sorted = [...categoryDeltas].sort((a, b) => b.delta - a.delta);
+  const t = previousRow.timestamp ? Date.parse(previousRow.timestamp) : NaN;
+  const ageDays = Number.isNaN(t) ? null : Math.floor((Date.now() - t) / 86400000);
+  return {
+    previousScore: previousRow.score,
+    previousGrade: previousRow.grade || null,
+    previousTimestamp: previousRow.timestamp,
+    delta: currentHarness.score - previousRow.score,
+    categoryDeltas,
+    biggestImprovement: sorted.find((c) => c.delta > 0) || null,
+    biggestRegression: [...sorted].reverse().find((c) => c.delta < 0) || null,
+    baselineAgeDays: ageDays,
+    baselineStale: ageDays != null && ageDays > 30,
+  };
+}
+
+export function formatHistoryDiff(diff) {
+  if (!diff) return "";
+  if (diff.firstRun) return "_First run for this project — no baseline yet._";
+  const arrow = diff.delta > 0 ? "↑" : diff.delta < 0 ? "↓" : "=";
+  const sign = diff.delta > 0 ? "+" : "";
+  const prevDate = (diff.previousTimestamp || "").slice(0, 10);
+  const lines = [`**Δ ${sign}${diff.delta} ${arrow} vs run anterior** (${prevDate}, ${diff.previousScore}/100 ${diff.previousGrade || ""})`];
+  if (diff.baselineStale) lines.push(`> ⚠ baseline antigua (${diff.baselineAgeDays} días) — considera ejecutar \`kj audit\` con más frecuencia.`);
+  if (diff.biggestImprovement) lines.push(`- Mayor mejora: **${diff.biggestImprovement.name}** (+${diff.biggestImprovement.delta})`);
+  if (diff.biggestRegression) lines.push(`- Mayor regresión: **${diff.biggestRegression.name}** (${diff.biggestRegression.delta})`);
+  return lines.join("\n");
+}
+
+export function formatTrendSparkline(scores) {
+  const xs = (scores || []).map((r) => (typeof r === "number" ? r : r?.score)).filter((n) => typeof n === "number");
+  if (xs.length === 0) return "";
+  if (xs.length === 1) return `Score trend: ${xs[0]} (single run)`;
+  const min = Math.min(...xs), max = Math.max(...xs), range = max - min || 1;
+  const bars = xs.map((n) => SPARK_BARS[Math.min(SPARK_BARS.length - 1, Math.floor(((n - min) / range) * (SPARK_BARS.length - 1)))]).join("");
+  return `Score trend (last ${xs.length} runs): ${xs[0]} ${bars} ${xs[xs.length - 1]}`;
+}

package/src/audit/audit-history.js

@@ -0,0 +1,102 @@
+// KJC-TSK-0472 — Per-project audit history (sqlite at .karajan/audit-history.db).
+import path from "node:path";
+import fs from "node:fs";
+import Database from "better-sqlite3";
+
+const SCHEMA_VERSION = 1;
+
+export function getAuditHistoryDbPath(projectDir) {
+  return path.join(projectDir, ".karajan", "audit-history.db");
+}
+
+export function openAuditHistoryDb(projectDir) {
+  const dbPath = getAuditHistoryDbPath(projectDir);
+  fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+  const db = new Database(dbPath);
+  db.pragma("journal_mode = WAL");
+  migrate(db);
+  return db;
+}
+
+function migrate(db) {
+  const current = db.pragma("user_version", { simple: true });
+  if (current >= SCHEMA_VERSION) return;
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS audits (
+      run_id TEXT PRIMARY KEY,
+      timestamp TEXT NOT NULL,
+      git_sha TEXT,
+      score INTEGER,
+      grade TEXT,
+      categories_json TEXT,
+      raw_report_path TEXT
+    );
+    CREATE TABLE IF NOT EXISTS findings (
+      run_id TEXT NOT NULL,
+      category TEXT,
+      check_id TEXT,
+      status TEXT,
+      weight REAL,
+      FOREIGN KEY(run_id) REFERENCES audits(run_id) ON DELETE CASCADE
+    );
+    CREATE INDEX IF NOT EXISTS idx_audits_timestamp ON audits(timestamp DESC);
+    CREATE INDEX IF NOT EXISTS idx_findings_run_id ON findings(run_id);
+  `);
+  db.pragma(`user_version = ${SCHEMA_VERSION}`);
+}
+
+// `harness` may be null (--no-harness / docker offline): row still inserted with NULL score.
+export function recordAuditRun(db, { runId, timestamp, gitSha, harness, rawReportPath }) {
+  const categories = harness?.categories ? JSON.stringify(harness.categories) : null;
+  const checks = Array.isArray(harness?.checks) ? harness.checks : [];
+  const insertRun = db.prepare(`INSERT INTO audits (run_id, timestamp, git_sha, score, grade, categories_json, raw_report_path) VALUES (?, ?, ?, ?, ?, ?, ?)`);
+  const insertFinding = db.prepare(`INSERT INTO findings (run_id, category, check_id, status, weight) VALUES (?, ?, ?, ?, ?)`);
+  db.transaction(() => {
+    insertRun.run(runId, timestamp, gitSha || null, harness?.score ?? null, harness?.grade ?? null, categories, rawReportPath || null);
+    for (const c of checks) {
+      insertFinding.run(runId, c.category || null, c.name || c.id || null, c.passed ? "pass" : "fail", typeof c.weight === "number" ? c.weight : null);
+    }
+  })();
+  return { runId, inserted: 1 + checks.length };
+}
+
+export function listRecentRuns(db, limit = 10) {
+  return db.prepare(`SELECT run_id, timestamp, git_sha, score, grade FROM audits ORDER BY timestamp DESC LIMIT ?`).all(limit);
+}
+
+// KJC-TSK-0473 — Fetch previous run (excluding current) for diff rendering.
+export function getLatestPreviousRun(db, currentTimestamp) {
+  return db.prepare(`SELECT run_id, timestamp, git_sha, score, grade, categories_json FROM audits WHERE timestamp < ? AND score IS NOT NULL ORDER BY timestamp DESC LIMIT 1`).get(currentTimestamp || new Date().toISOString()) || null;
+}
+
+// KJC-TSK-0473 — Score timeline (ASC) for sparkline rendering.
+export function getRecentScores(db, limit = 10) {
+  const rows = db.prepare(`SELECT timestamp, score FROM audits WHERE score IS NOT NULL ORDER BY timestamp DESC LIMIT ?`).all(limit);
+  return rows.reverse();
+}
+
+export function countRuns(db) {
+  return db.prepare(`SELECT COUNT(*) AS n FROM audits`).get().n;
+}
+
+export function pruneOldRuns(db, keep = 50) {
+  const ids = db.prepare(`SELECT run_id FROM audits ORDER BY timestamp DESC LIMIT -1 OFFSET ?`).all(keep).map((r) => r.run_id);
+  if (ids.length === 0) return 0;
+  const ph = ids.map(() => "?").join(",");
+  db.transaction(() => { db.prepare(`DELETE FROM findings WHERE run_id IN (${ph})`).run(...ids); db.prepare(`DELETE FROM audits WHERE run_id IN (${ph})`).run(...ids); })();
+  return ids.length;
+}
+
+// High-level helper used by `kj audit`. Errors returned via `ok` so a broken db never breaks the audit.
+export function persistAuditRun(projectDir, payload) {
+  try {
+    const db = openAuditHistoryDb(projectDir);
+    recordAuditRun(db, payload);
+    const n = countRuns(db);
+    db.close();
+    return { ok: true, total: n, pruneHint: n > 100 };
+  } catch (e) {
+    return { ok: false, error: e?.message || String(e) };
+  }
+}
+

package/src/audit/harness-scorecard.js

@@ -0,0 +1,51 @@
+// KJC-TSK-0470 — Bootstrap Docker de ai-harness-scorecard.
+// 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.
+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);
+
+export function normalizeHarnessConfig(h = {}) {
+  return {
+    enabled: h.enabled !== false,
+    image: h.image || D.image,
+    pullTimeoutMs: pos(h.pull_timeout_ms, D.pullTimeoutMs),
+    assessTimeoutMs: pos(h.assess_timeout_ms, D.assessTimeoutMs),
+  };
+}
+
+export async function isDockerAvailable() {
+  try {
+    const r = await runCommand("docker", ["version", "--format", "{{.Server.Version}}"], { timeout: 10000 });
+    return r.exitCode === 0;
+  } catch { return false; }
+}
+
+export async function isHarnessImagePresent(image) {
+  const r = await runCommand("docker", ["images", "-q", image], { timeout: 10000 });
+  return r.exitCode === 0 && r.stdout.trim().length > 0;
+}
+
+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}` };
+  return { pulled: true, reused: false, image: cfg.image };
+}
+
+export async function runHarnessAssess(repoPath, harness = null) {
+  const cfg = normalizeHarnessConfig(harness || {});
+  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}` };
+  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}` }; }
+}

package/src/audit/harness-section.js

@@ -0,0 +1,77 @@
+// KJC-TSK-0471 — Harness Scorecard audit stage.
+// Runs the markmishaev76/ai-harness-scorecard container after the deterministic
+// phase, persists scorecard.json + scorecard-report.md under
+// .karajan/audit-runs/<ts>/, and returns a summary the renderer surfaces as a
+// "Harness Health Score" markdown block. KJC-TSK-0472 will consume the
+// persisted artefacts to build audit-history.db.
+import fs from "node:fs/promises";
+import path from "node:path";
+import { normalizeHarnessConfig, runHarnessAssess } from "./harness-scorecard.js";
+
+const CATEGORIES = [
+  ["architectural_docs", "Architectural Docs", 20],
+  ["mechanical_constraints", "Mechanical Constraints", 25],
+  ["testing_stability", "Testing & Stability", 25],
+  ["review_drift_prevention", "Review & Drift Prevention", 15],
+  ["ai_specific_safeguards", "AI-Specific Safeguards", 15],
+];
+const labelFor = (k) => CATEGORIES.find(([key]) => key === k)?.[1] || k;
+const ts = () => new Date().toISOString().replaceAll(/[:.]/g, "-");
+
+export async function runHarnessSection({ projectDir, harnessConfig = null, runAssess = runHarnessAssess } = {}) {
+  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 };
+  const outDir = path.join(projectDir, ".karajan", "audit-runs", ts());
+  await fs.mkdir(outDir, { recursive: true });
+  const scorecardPath = path.join(outDir, "scorecard.json");
+  const rawReportPath = path.join(outDir, "scorecard-report.md");
+  await fs.writeFile(scorecardPath, JSON.stringify(res.raw, null, 2), "utf8");
+  await fs.writeFile(rawReportPath, res.raw?.report_markdown || res.raw?.markdown || "", "utf8");
+  return {
+    ok: true, score: res.score, grade: res.grade,
+    categories: res.raw?.categories || {},
+    checks: Array.isArray(res.raw?.checks) ? res.raw.checks : [],
+    scorecardPath, rawReportPath, image: cfg.image,
+  };
+}
+
+export function formatHarnessSection(summary) {
+  if (!summary || summary.skipped) return "";
+  if (!summary.ok) return `## Harness Scorecard\n\n_skipped: ${summary.error}_\n`;
+  const lines = [
+    `## Harness Health Score: ${summary.score}/100 (${summary.grade})`,
+    "",
+    "| Category | Weight | Score |",
+    "| --- | --- | --- |",
+  ];
+  for (const [key, label, weight] of CATEGORIES) {
+    const score = summary.categories?.[key]?.score ?? "—";
+    lines.push(`| ${label} | ${weight}% | ${score} |`);
+  }
+  const checks = Array.isArray(summary.checks) ? summary.checks : [];
+  if (checks.length) {
+    const groups = new Map();
+    for (const c of checks) {
+      const k = c.category || "other";
+      if (!groups.has(k)) groups.set(k, []);
+      groups.get(k).push(c);
+    }
+    lines.push("", "### Checks");
+    for (const [k, list] of groups) {
+      lines.push(`- **${labelFor(k)}**`);
+      for (const c of list) lines.push(`  - ${c.passed ? "✓" : "✗"} ${c.name}${c.detail ? ` — ${c.detail}` : ""}`);
+    }
+  }
+  return lines.join("\n") + "\n";
+}
+
+export function harnessSummaryForJson(summary) {
+  if (!summary?.ok || summary.skipped) return null;
+  return {
+    score: summary.score, grade: summary.grade,
+    categories: summary.categories, checks: summary.checks,
+    rawReportPath: summary.rawReportPath, scorecardPath: summary.scorecardPath,
+  };
+}

package/src/checks/harness-scorecard.js

@@ -0,0 +1,41 @@
+// KJC-TSK-0470 — `kj doctor` check for the AI Harness Scorecard image.
+// Reports Disabled / Docker missing / Image not pulled / OK. The image
+// is pulled lazily by `kj audit` on first use; this check is informational.
+import { isDockerAvailable, isHarnessImagePresent, normalizeHarnessConfig } from "../audit/harness-scorecard.js";
+import { STRATEGY } from "./types.js";
+
+function harnessEnabled(config) { return config?.audit?.harness?.enabled !== false; }
+
+function createHarnessScorecardCheck() {
+  return {
+    name: "harness-scorecard",
+    label: "AI Harness Scorecard (audit)",
+    strategy: STRATEGY.NONE,
+    async detect({ config }) {
+      const cfg = normalizeHarnessConfig(config?.audit?.harness || {});
+      if (!harnessEnabled(config)) {
+        return { ok: true, severity: "info", detail: "Disabled in config (audit.harness.enabled=false)" };
+      }
+      let docker; try { docker = await isDockerAvailable(); } catch { docker = false; }
+      if (!docker) return {
+        ok: false, severity: "warn",
+        detail: "Docker not available — kj audit will skip the harness step.",
+        fix: "Install Docker (or run `kj audit --no-harness` to silence this).",
+        extra: { docker: false, image: cfg.image },
+      };
+      let cached; try { cached = await isHarnessImagePresent(cfg.image); } catch { cached = false; }
+      if (!cached) return {
+        ok: true, severity: "info",
+        detail: `Will be pulled on first \`kj audit\` run (${cfg.image}).`,
+        extra: { docker: true, cached: false, image: cfg.image },
+      };
+      return {
+        ok: true, severity: "info",
+        detail: `Image cached locally (${cfg.image}).`,
+        extra: { docker: true, cached: true, image: cfg.image },
+      };
+    },
+  };
+}
+
+export function getHarnessScorecardChecks() { return [createHarnessScorecardCheck()]; }

package/src/cli/register-meta.js

@@ -115,15 +115,25 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--scope <scope>", "plans | code | onboarding | all (default: all)", "all")
     .option("--top-k <n>", "Number of hits to return (default: 5)", "5")
     .option("--project <slug>", "Filter by project slug. Pass 'all' to query across every indexed project. Default: cwd basename")
-    .option("--mode <mode>", "hybrid (default) | semantic (cosine only) | keyword (BM25 only)", "hybrid")
+    // KJC-BUG-0070 — the global `--mode` flag maps to `review_mode` in
+    // src/config/overrides.js. We expose the rag-specific knob under
+    // `--rag-mode` to avoid the collision (which crashed the command on
+    // first call). Internally we rebind to `flags.mode` so the handler
+    // in src/commands/rag.js stays untouched.
+    .option("--rag-mode <mode>", "hybrid (default) | semantic (cosine only) | keyword (BM25 only)", "hybrid")
     .option("--alpha <n>", "Hybrid weight for semantic component (0..1). Default 0.6", "0.6")
     .option("--where <clause>", "Metadata filter, e.g. 'symbol=loadConfig' or 'hu_id=HU-003 AND kind=plan'")
     .option("--rerank", "Apply cross-encoder rerank to top-K (needs @huggingface/transformers, slower but more precise)")
     .option("--rerank-model <name>", "Cross-encoder model id. Default: Xenova/ms-marco-MiniLM-L-6-v2")
     .option("--json", "Output the hits as JSON")
     .action(async (text, flags) => {
+      // Stash the rag-specific mode and remove it from the flags object so
+      // applyScalarAndBooleanOverrides cannot see a `flags.mode` and write
+      // out.review_mode = "hybrid" — that would fail the schema validator.
+      const ragMode = flags.ragMode;
+      delete flags.ragMode;
       await withConfig(pkgVersion, "rag-query", flags, async ({ config, logger }) => {
-        await ragQueryCommand({ text, config, logger, flags });
+        await ragQueryCommand({ text, config, logger, flags: { ...flags, mode: ragMode } });
       });
     });
 
@@ -151,6 +161,8 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--no-sonar", "Skip the SonarQube findings collector (faster, less context). Sonar findings are also skipped automatically when SonarQube is unreachable.")
     .option("--no-osv", "Skip the OSV-Scanner vulnerability collector. Findings are also skipped automatically when osv-scanner is not installed.")
     .option("--no-semgrep", "Skip the Semgrep SAST collector. Findings are also skipped automatically when semgrep is not installed (install via 'pipx install semgrep' or 'brew install semgrep').")
+    .option("--no-harness", "Skip the AI Harness Scorecard stage (Docker one-shot). Auto-skipped when Docker is unavailable. Each run is also persisted to .karajan/audit-history.db (KJC-TSK-0472) for diff/trend tracking.")
+    .option("--trend", "Append a sparkline of the harness score across the last 10 runs (uses .karajan/audit-history.db). KJC-TSK-0473.")
     .option("--report-file <path>", "Write the audit report to disk in addition to stdout. <path> may be a file (extension drives format: .md or .json) or a directory (creates audit-<ISO>.<md|json> inside). $KJ_AUDIT_REPORT_DIR env var is used as default directory if no --report-file is given.")
     .option("--deterministic-only", "Skip the LLM analysis entirely. Print/persist only the deterministic findings (basalCost, sonar, stack, growth-delta, webperf). Zero tokens spent. Compatible with --report-file and --json.")
     .option("-y, --yes", "Auto-confirm the 'Continue with LLM analysis?' prompt. Useful in scripts that want the full audit non-interactively. CI/non-TTY paths already auto-confirm without this flag.")
@@ -172,9 +184,11 @@ export function registerMeta(program, { pkgVersion }) {
           noSonar: flags.sonar === false,
           noOsv: flags.osv === false,
           noSemgrep: flags.semgrep === false,
+          noHarness: flags.harness === false,
           reportFile: flags.reportFile || null,
           deterministicOnly: Boolean(flags.deterministicOnly),
           yes: Boolean(flags.yes),
+          trend: Boolean(flags.trend),
         });
       });
     });

package/src/commands/audit.js

@@ -11,6 +11,9 @@ import { withCliRunLog } from "../utils/cli-run-log.js";
 import { createCliProgressReporter } from "../utils/cli-progress.js";
 import { runAgentReadiness, formatAgentReadinessReport } from "../audit/agent-readiness.js";
 import { formatDeterministicSummary } from "../audit/deterministic-summary.js";
+import { runHarnessSection, formatHarnessSection, harnessSummaryForJson } from "../audit/harness-section.js";
+import { persistAuditRun, openAuditHistoryDb, getLatestPreviousRun, getRecentScores } from "../audit/audit-history.js";
+import { computeHistoryDiff, formatHistoryDiff, formatTrendSparkline } from "../audit/audit-history-display.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -191,20 +194,43 @@ async function buildReportHeader(projectDir, invocation) {
   return lines.join("\n");
 }
 
-function describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, json, deterministicOnly, yes }) {
+function composeHistoryBlock({ diffMd, trendMd }) {
+  const parts = [];
+  if (diffMd) parts.push(diffMd);
+  if (trendMd) parts.push(trendMd);
+  return parts.length ? `\n\n## Harness Score History\n${parts.join("\n\n")}` : "";
+}
+
+// KJC-TSK-0473 — Resolve diff vs previous run + optional trend sparkline.
+// Errors silenced: history is a nice-to-have; a broken db must not break audit.
+function loadAuditHistoryContext(projectDir, currentHarness, { showTrend = false } = {}) {
+  let db;
+  try {
+    db = openAuditHistoryDb(projectDir);
+    if (!db) return { diff: null, diffMd: "", trendMd: "" };
+    const previous = currentHarness?.score != null ? getLatestPreviousRun(db, new Date().toISOString()) : null;
+    const diff = currentHarness?.score != null ? computeHistoryDiff(currentHarness, previous) : null;
+    const trendMd = showTrend ? formatTrendSparkline(getRecentScores(db, 10)) : "";
+    return { diff, diffMd: formatHistoryDiff(diff), trendMd };
+  } catch { return { diff: null, diffMd: "", trendMd: "" }; }
+  finally { try { db?.close(); } catch { /* noop */ } }
+}
+
+function describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, json, deterministicOnly, yes }) {
   const parts = ["kj audit"];
   if (task && task !== "Analyze the full codebase") parts.push(JSON.stringify(task));
   if (dimensions && dimensions !== "all") parts.push(`--dimensions=${dimensions}`);
   if (noSonar) parts.push("--no-sonar");
   if (noOsv) parts.push("--no-osv");
   if (noSemgrep) parts.push("--no-semgrep");
+  if (noHarness) parts.push("--no-harness");
   if (deterministicOnly) parts.push("--deterministic-only");
   if (yes) parts.push("--yes");
   if (json) parts.push("--json");
   return parts.join(" ");
 }
 
-export async function auditCommand({ task, config, logger, dimensions, json, agentReadiness, path: pathArg, noSonar = false, noOsv = false, noSemgrep = false, reportFile = null, deterministicOnly = false, yes = false, promptFn = null }) {
+export async function auditCommand({ task, config, logger, dimensions, json, agentReadiness, path: pathArg, noSonar = false, noOsv = false, noSemgrep = false, noHarness = false, reportFile = null, deterministicOnly = false, yes = false, trend = false, promptFn = null }) {
   // --agent-readiness is a STANDALONE, deterministic, LLM-free audit
   // dimension. It scores any third-party repo for AI-agent readability
   // (llms.txt presence, page token budgets, robots allowlist, etc.).
@@ -247,6 +273,27 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
     const deterministicCtx = await role.collectDeterministic(roleInput);
     const deterministicMd = formatDeterministicSummary(deterministicCtx);
 
+    // KJC-TSK-0471 — Harness Scorecard (Docker one-shot, golden metric).
+    // Runs after the deterministic phase, before the LLM. Auto-skipped on
+    // --no-harness or if `runHarnessSection` surfaces an error (graceful
+    // degradation: a missing Docker daemon must not break `kj audit`).
+    let harnessSummary = null;
+    if (!noHarness) {
+      try {
+        harnessSummary = await runHarnessSection({
+          projectDir: config?.projectDir || process.cwd(),
+          harnessConfig: config?.audit?.harness || null,
+        });
+        if (harnessSummary?.ok && !harnessSummary.skipped) {
+          runLog.logText(`[audit] harness score=${harnessSummary.score}/100 grade=${harnessSummary.grade}`);
+        }
+      } catch (e) {
+        harnessSummary = { ok: false, error: e?.message || String(e) };
+        runLog.logText(`[audit] harness skipped: ${harnessSummary.error}`);
+      }
+    }
+    const harnessMd = formatHarnessSection(harnessSummary);
+
     // --json suppresses the interactive flow regardless: it would mangle
     // a script's stdout. JSON consumers always get the full audit unless
     // they explicitly pass deterministicOnly.
@@ -263,23 +310,28 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
     if (!runLlm) {
       // Deterministic-only path. Produce the report from what we already
       // have, persist it (md or json), and exit. Zero tokens spent.
+      const harnessJson = harnessSummaryForJson(harnessSummary);
+      const currentHarness = harnessSummary?.ok && !harnessSummary.skipped ? harnessSummary : null;
+      const history = loadAuditHistoryContext(config?.projectDir || process.cwd(), currentHarness, { showTrend: trend });
+      const historyMd = composeHistoryBlock(history);
       const stdoutContent = json
-        ? JSON.stringify({ deterministic: deterministicCtx, mode: "deterministic-only" }, null, 2)
-        : (deterministicOnly ? deterministicMd : ""); // already printed above when interactive
-      if (json || deterministicOnly) console.log(stdoutContent);
+        ? JSON.stringify({ deterministic: deterministicCtx, harnessScore: harnessJson, harnessScoreDiff: history.diff, mode: "deterministic-only" }, null, 2)
+        : (deterministicOnly ? `${deterministicMd}\n${harnessMd}${historyMd}` : `${harnessMd}${historyMd}`);
+      if (json || deterministicOnly || harnessMd) console.log(stdoutContent);
 
       if (reportPath) {
         let payload;
         if (reportPath.endsWith(".json")) {
-          payload = JSON.stringify({ deterministic: deterministicCtx, mode: "deterministic-only" }, null, 2);
+          payload = JSON.stringify({ deterministic: deterministicCtx, harnessScore: harnessJson, harnessScoreDiff: history.diff, mode: "deterministic-only" }, null, 2);
         } else {
-          const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, json, deterministicOnly, yes }));
-          payload = header + deterministicMd + "\n";
+          const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, json, deterministicOnly, yes }));
+          payload = `${header}${deterministicMd}\n${harnessMd}${historyMd}`;
         }
         await fs.writeFile(reportPath, payload, "utf8");
         runLog.logText(`[audit] report written (deterministic-only) → ${reportPath}`);
         logger.info(`Audit report written: ${reportPath}`);
       }
+      persistAuditRun(config?.projectDir || process.cwd(), { runId: new Date().toISOString(), timestamp: new Date().toISOString(), gitSha: null, harness: harnessSummary?.ok && !harnessSummary.skipped ? harnessSummary : null, rawReportPath: reportPath });
       logger.info("Audit completed (deterministic-only).");
       return { ok: true, mode: "deterministic-only", reportPath: reportPath || undefined };
     }
@@ -306,18 +358,22 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
       runLog.logText(`[audit] usage tokens=${usage.total_tokens} cost=$${(usage.cost_usd ?? 0).toFixed(4)} duration=${(usage.durationMs / 1000).toFixed(1)}s`);
     }
 
+    const harnessJson = harnessSummaryForJson(harnessSummary);
+    const currentHarness = harnessSummary?.ok && !harnessSummary.skipped ? harnessSummary : null;
+    const history = loadAuditHistoryContext(config?.projectDir || process.cwd(), currentHarness, { showTrend: trend });
+    const historyMd = composeHistoryBlock(history);
     let stdoutContent;
     if (json) {
       const jsonPayload = parsed
-        ? { ...parsed, usage: usage || undefined }
-        : { ...roleResult, usage: usage || undefined };
+        ? { ...parsed, harnessScore: harnessJson, harnessScoreDiff: history.diff, usage: usage || undefined }
+        : { ...roleResult, harnessScore: harnessJson, harnessScoreDiff: history.diff, usage: usage || undefined };
       stdoutContent = JSON.stringify(jsonPayload, null, 2);
     } else if (parsed?.summary?.overallHealth) {
-      stdoutContent = formatAudit(parsed, usage);
+      stdoutContent = `${formatAudit(parsed, usage)}\n${harnessMd}${historyMd}`;
     } else if (parsed?.raw) {
-      stdoutContent = parsed.raw + (usage ? `\n\n${formatUsageSummary(usage) || ""}` : "");
+      stdoutContent = parsed.raw + (usage ? `\n\n${formatUsageSummary(usage) || ""}` : "") + `\n${harnessMd}${historyMd}`;
     } else {
-      stdoutContent = roleResult.summary || "Audit complete.";
+      stdoutContent = `${roleResult.summary || "Audit complete."}\n${harnessMd}${historyMd}`;
     }
     console.log(stdoutContent);
 
@@ -325,11 +381,11 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
       let payload;
       if (reportPath.endsWith(".json")) {
         const jsonPayload = parsed
-          ? { ...parsed, usage: usage || undefined }
-          : { ...roleResult, usage: usage || undefined };
+          ? { ...parsed, harnessScore: harnessJson, harnessScoreDiff: history.diff, usage: usage || undefined }
+          : { ...roleResult, harnessScore: harnessJson, harnessScoreDiff: history.diff, usage: usage || undefined };
         payload = JSON.stringify(jsonPayload, null, 2);
       } else {
-        const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, json, deterministicOnly, yes }));
+        const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, json, deterministicOnly, yes }));
         payload = header + stdoutContent + "\n";
       }
       await fs.writeFile(reportPath, payload, "utf8");
@@ -337,6 +393,7 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
       logger.info(`Audit report written: ${reportPath}`);
     }
 
+    persistAuditRun(config?.projectDir || process.cwd(), { runId: new Date().toISOString(), timestamp: new Date().toISOString(), gitSha: null, harness: harnessSummary?.ok && !harnessSummary.skipped ? harnessSummary : null, rawReportPath: reportPath });
     logger.info("Audit completed.");
     return { ok: true, reportPath: reportPath || undefined };
   });

package/src/commands/doctor.js

@@ -19,6 +19,7 @@ import { getConfigFileChecks } from "../checks/config-files.js";
 import { getBinaryChecks } from "../checks/binaries.js";
 import { getSonarChecks } from "../checks/sonar.js";
 import { getOllamaChecks } from "../checks/ollama.js";
+import { getHarnessScorecardChecks } from "../checks/harness-scorecard.js";
 import { getCiChecks } from "../checks/ci.js";
 import { getRtkChecks } from "../checks/rtk.js";
 import { getNodeChecks } from "../checks/node.js";
@@ -54,6 +55,7 @@ function buildChecks(config, { projectOnly = false } = {}) {
     ...getBinaryChecks(),
     ...getSonarChecks(),
     ...getOllamaChecks(),
+    ...getHarnessScorecardChecks(),
     ...getPortChecks(),
     ...getTokenChecks(config),
     ...getMcpHealthChecks(),

package/src/orchestrator/stages/rag-context-stage.js

@@ -11,8 +11,25 @@ import { query } from "../../rag/retriever.js";
 
 const DEFAULT_TOP_K = 5;
 const DEFAULT_SCOPE = "all";
+const DEFAULT_SEARCH_MODE = "hybrid";
+const DEFAULT_SEARCH_ALPHA = 0.6;
 const MAX_CHUNK_CHARS = 600;
 
+// KJC-TSK-0463 — pull search-time knobs from config so the HU Board
+// modal (rag.search.{mode,alpha,rerank}) actually steers retrieval at
+// pipeline time. Returns the args object query() expects; unset fields
+// fall back to the retriever's own defaults.
+export function resolveSearchOpts(config) {
+  const s = config?.rag?.search ?? {};
+  const out = {
+    mode: typeof s.mode === "string" ? s.mode : DEFAULT_SEARCH_MODE,
+    alpha: Number.isFinite(s.alpha) ? s.alpha : DEFAULT_SEARCH_ALPHA,
+  };
+  if (s.rerank && typeof s.rerank === "object") out.rerankOpts = s.rerank;
+  else if (s.rerank === true) out.rerankOpts = {};
+  return out;
+}
+
 /**
  * Runs the RAG preload stage. Returns:
  *   { skipped: true, reason }                  — when disabled / empty / error
@@ -36,7 +53,8 @@ export async function runRagContextStage({ config, logger, emitter, eventBase, t
       const topK = preload.topK || DEFAULT_TOP_K;
       const scope = preload.scope || DEFAULT_SCOPE;
       const embedder = makeEmbedder(config);
-      const hits = await query(db, embedder, task, { topK, scope });
+      const searchOpts = resolveSearchOpts(config);
+      const hits = await query(db, embedder, task, { topK, scope, ...searchOpts });
       if (hits.length === 0) return { skipped: true, reason: "no-hits" };
       const lines = hits.map((h) => {
         const label = h.metadata?.hu_id || h.metadata?.symbol || h.metadata?.headingPath?.join(" > ") || "block";
@@ -46,7 +64,7 @@ export async function runRagContextStage({ config, logger, emitter, eventBase, t
       const contextBlock = `## Prior context from RAG (auto-retrieved, top ${hits.length})\n\n${lines.join("\n\n")}`;
       emitProgress(emitter, makeEvent("rag-preload:hits", { ...eventBase, stage: "rag-preload" }, {
         message: `RAG preload: injected ${hits.length} chunk(s) into the task context`,
-        detail: { topK, scope, hits: hits.length },
+        detail: { topK, scope, hits: hits.length, mode: searchOpts.mode, alpha: searchOpts.alpha, rerank: Boolean(searchOpts.rerankOpts) },
       }));
       return { skipped: false, contextBlock, hits };
     } finally {

package/src/spec-review/refine-loop.js

@@ -50,7 +50,7 @@ export async function runRefinePass({ spec, findings, role, projectDir, taskFile
   } catch (err) { return { ok: false, error: `persist failed: ${err.message}`, hashChanged: false }; }
 
   const before = sha256(refineRes.refinedSpec);
-  openEditor(v2Path, { logger, openEditorFn });
+  await openEditor(v2Path, { logger, openEditorFn });
   let after;
   try { after = await _fs.readFile(v2Path, "utf8"); }
   catch (err) { return { ok: false, error: `read v2 failed: ${err.message}`, hashChanged: false }; }