karajan-code 2.31.0 → 2.32.0

package/README.md

@@ -345,6 +345,15 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 
 ## Recent releases
 
+> **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.32.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/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 } });
       });
     });
 

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