karajan-code 4.8.0 → 4.10.0

package/library/logical-clocks-lamport.md

@@ -0,0 +1,40 @@
+# Logical clocks & happened-before (Lamport, 1978)
+
+## Problem signature
+
+Events across processes/services need a consistent order, and wall clocks
+disagree: "last write wins" flip-flops between replicas, audit logs interleave
+impossibly, a consumer sees an update before the create it depends on.
+
+## Reach for it when
+
+- Two or more writers/emitters produce events whose CAUSAL order matters
+  (A caused B must never be observed as B before A).
+- You are tempted to "fix it with NTP" or timestamps — clock skew makes
+  timestamp ordering a race, not an order.
+- You need to detect concurrent (conflicting) updates, not just order them:
+  that is the vector-clock extension (one counter per node; compare
+  component-wise; incomparable = concurrent — see Dynamo's usage).
+
+## Do NOT reach for it when
+
+- A single writer (or a single database) already totally orders the events —
+  its sequence/autoincrement/WAL IS the clock. Most CRUD apps live here.
+- You only need "roughly recent first" for humans (feeds, logs for reading):
+  wall-clock timestamps are fine and far simpler.
+- You need a TOTAL order agreed by all nodes: logical clocks give a partial
+  causal order; total order needs consensus (Raft/Paxos) or a sequencer.
+
+## Trade-offs
+
+- Lamport clocks are one counter: tiny, but they cannot tell concurrent from
+  ordered. Vector clocks can, at O(nodes) metadata per event that must be
+  carried, stored and pruned.
+- Causality tracking pushes conflict RESOLUTION to the reader (semantic
+  merge, CRDTs, or ask-the-user) — ordering was the easy half.
+
+## Canonical source
+
+Leslie Lamport, "Time, Clocks, and the Ordering of Events in a Distributed
+System", Communications of the ACM, 1978. The happened-before relation and
+the clock condition come verbatim from it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.8.0",
+  "version": "4.10.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -48,6 +48,7 @@
   "files": [
     "src/",
     "bin/",
+    "library/",
     "templates/",
     "scripts/",
     "vendor/tree-sitter-grammars/",
@@ -108,7 +109,7 @@
     "express-rate-limit": "^8.5.0",
     "helmet": "^8.1.0",
     "js-yaml": "^4.2.0",
-    "karajan-core": "^1.0.0",
+    "karajan-core": "^1.4.0",
     "karajan-rag": "^1.2.0",
     "knip": "^6.15.0",
     "madge": "^8.0.0",

package/scripts/esbuild-sea.config.mjs

@@ -146,7 +146,8 @@ const huBoardStubPlugin = {
 const ragStubPlugin = {
   name: "rag-stub",
   setup(build) {
-    build.onResolve({ filter: /[\\/](rag[\\/].+|commands[\\/](rag|watch))\.js$/ }, (args) => ({
+    // KJC-TSK-0704 — src/privacy/* rides this stub too: its engine is redactPII.
+    build.onResolve({ filter: /[\\/](rag[\\/].+|privacy[\\/].+|commands[\\/](rag|watch|privacy))\.js$/ }, (args) => ({
       path: args.path, namespace: "rag-stub",
     }));
     build.onLoad({ filter: /.*/, namespace: "rag-stub" }, () => ({
@@ -192,6 +193,10 @@ const ragStubPlugin = {
           // reached from \`kj rag install-hooks\`, so it degrades like the rest.
           maybeAutoUpdate: async () => ({ skipped: true }),
           installPostMergeHook: notAvailable,
+          // KJC-TSK-0704 — privacy scan (engine = karajan-rag redactPII).
+          privacyScanCommand: notAvailable, loadPrivacyList: notAvailable,
+          scanText: notAvailable, scanPaths: notAvailable, privacyConfigPath: notAvailable,
+          ensurePrivacyList: async () => ({ created: false, reason: "sea-stub" }),
           // KJC-BUG-0100 — the doctor rag-hooks check imports this; it throws
           // here and the check swallows it (degrades to a benign info result).
           resolveHooksDir: notAvailable,

package/scripts/verify-pack.mjs

@@ -85,6 +85,23 @@ try {
   }
   console.log(`verify-pack: kj --version → ${versionOut} ✓`);
 
+  // 1.5 Privacy boundary (KJC-TSK-0706): nothing personal or secret-shaped
+  // ships inside the tarball. Scans the INSTALLED package with the same
+  // engine as the pre-commit gate: denylist + token shapes abort the
+  // publish; generic PII only counts (code trees always carry a few
+  // pattern lookalikes).
+  const { scanPaths, loadPrivacyList } = await import(
+    path.join(repoRoot, "src", "privacy", "scan.js")
+  );
+  const shippedDir = path.join(tmpDir, "node_modules", "karajan-code");
+  const pFindings = scanPaths([shippedDir], { list: loadPrivacyList() });
+  const pBlocks = pFindings.filter((f) => f.severity === "block");
+  if (pBlocks.length > 0) {
+    for (const f of pBlocks) console.error(`✗ [${f.type}] ${path.relative(shippedDir, f.source)}:${f.line} → ${f.masked}`);
+    fail(`${pBlocks.length} personal-data/secret hit(s) INSIDE the tarball — this must not publish`);
+  }
+  console.log(`verify-pack: tarball privacy scan ✓ (${pFindings.length} generic warning(s))`);
+
   // 2. kj --help must exit 0 (exercises the command tree wiring).
   try {
     run(binPath, ["--help"]);

package/src/cli/advanced-commands.js

@@ -30,7 +30,7 @@ export const ADVANCED_GROUPS = [
   { title: "Pipeline (piezas sueltas)", commands: ["autorun", "code", "review", "solomon", "agent", "scan"] },
   { title: "Análisis pre-run", commands: ["discover", "triage", "researcher", "architect", "onboard", "brief"] },
   { title: "Búsqueda / RAG", commands: ["rag", "qmd", "watch"] },
-  { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar"] },
+  { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy"] },
   { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "worktree", "undo", "standby"] },
   { title: "Infra / setup", commands: ["install-tools", "ollama", "skills", "roles", "agents", "env"] },
   { title: "Mantenimiento", commands: ["clean", "sync", "telemetry", "report-issue"] },

package/src/cli/register-meta.js

@@ -134,6 +134,7 @@ export function registerMeta(program, { pkgVersion }) {
     .description("Install/refresh the Karajan playbook for any host agent (CLAUDE.md, AGENTS.md, GEMINI.md)")
     .option("--target <target>", "claude | codex | gemini | all", "all")
     .option("--no-rag", "Skip building the RAG index when the project has none (ENV-E1)")
+    .option("--no-enforce", "Skip installing the git hooks + verdict gate (KJC-BUG-0133 — installing IS activating; skipping this leaves the method narratable)")
     .action(async (flags) => {
       await withConfig(pkgVersion, "env-install", flags, async ({ config, logger }) => {
         const r = await envInstallCommand({ config, logger, flags });
@@ -261,6 +262,17 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // KJC-TSK-0704 — the outbound privacy boundary: audit before anything ships.
+  const privacy = program.command("privacy").description("Personal-data (PII) auditing of outbound boundaries: staged diffs, build outputs, docs trees");
+  privacy.command("scan [paths...]")
+    .description("Scan files/dirs for personal data, always masked in output: denylist hits (~/.karajan/privacy.yml) block with exit 1, generic PII (email/phone/DNI/NIE/IBAN/card via karajan-rag redactPII) warns")
+    .option("--staged", "Scan the ADDED lines of the staged diff instead of paths")
+    .option("--json", "Machine-readable result (stdout carries exactly one JSON document)")
+    .action(async (paths, flags) => {
+      const { privacyScanCommand } = await import("../commands/privacy.js");
+      await privacyScanCommand({ paths, flags });
+    });
+
   const rag = program.command("rag").description("Retrieval-augmented search over Karajan plans, onboarding briefs and project code");
   rag.command("index")
     .description("Index plans + onboarding (and optionally project sources) into the local vector store")
@@ -294,6 +306,7 @@ export function registerMeta(program, { pkgVersion }) {
     .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("--library", "Query the distilled engineering canon (pattern cards shipped with kj + ~/.karajan/library + project .karajan/library) instead of the project corpus. Cards carry problem signatures, when-NOT-to-apply and canonical citations (KJC-TSK-0697).")
     .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")

package/src/commands/env.js

@@ -4,7 +4,7 @@
  * files (CLAUDE.md, AGENTS.md), and make its step 1 real: when the project
  * has no RAG index yet, build it (default ON, `--no-rag` opts out).
  */
-import { installPlaybook } from "../environment/playbook.js";
+import { installPlaybook, renderPlaybook } from "../environment/playbook.js";
 import { renderBrief, listBriefs } from "../environment/briefs.js";
 import { existsSync } from "node:fs";
 import { openVecStore, projectSlug, getLastIndexedCommit, dbPath } from "../rag/vec-store.js";
@@ -12,6 +12,11 @@ import { ragIndexCommand } from "./rag.js";
 import { renderPendingBlock, PENDING_EXIT_CODE } from "../utils/pending-user-action.js";
 import { onnxConfig, persistOnnxChoice, resetEmptyStore } from "../rag/onnx-fallback.js";
 import { verifyBoardAccess } from "../environment/board-access.js";
+import { ensurePrivacyList } from "../privacy/onboarding.js";
+import { createWizard } from "../utils/wizard.js";
+import { hardenCommand } from "./harden.js";
+import { reviewGateCommand } from "./review-gate.js";
+import { join } from "node:path";
 
 function hasRagIndex(config, projectDir) {
   // KJC-BUG-0128: probing must never CREATE the store — openVecStore runs
@@ -66,6 +71,35 @@ export async function envInstallCommand({ config = null, logger = null, flags =
   }
   if (access.backend !== "hu-board") console.log(`✓ board access verified: ${access.via}`);
 
+  // KJC-BUG-0133 — installing IS activating. The setup flow used to order
+  // harden + the verdict gate as TEXT steps the agent runs (or narrates);
+  // a session that skipped them got a decorative method — field case
+  // 2026-08-02: installed karajan, then wrote everything by hand with
+  // nothing to stop it. env install now does them itself, idempotently.
+  if (flags.enforce !== false) {
+    if (!existsSync(join(projectDir, ".git"))) {
+      result.exitCode = PENDING_EXIT_CODE;
+      console.log(renderPendingBlock(
+        [{ tool: "git", action: "needs-user", reason: "the enforcement gates live in git hooks — run `git init` (Karajan's guarantees do not exist without git)" }],
+        { retry: "kj env install" },
+      ));
+      return result;
+    }
+    try {
+      const h = await hardenCommand({ projectDir, logger: console });
+      if (h?.ok === false) throw new Error(h.error || "kj harden failed");
+      await reviewGateCommand({ config, flags: { installGate: true } });
+      console.log("✓ enforcement active: git hooks + cross-AI verdict gate — a commit outside the method is rejected, not narrated");
+    } catch (err) {
+      result.exitCode = PENDING_EXIT_CODE;
+      console.log(renderPendingBlock(
+        [{ tool: "enforcement", action: "needs-user", reason: `hooks/gate could not be installed: ${err.message} — without them the method is narratable` }],
+        { retry: "kj env install" },
+      ));
+      return result;
+    }
+  }
+
   // ENV-E1: RAG-first — the playbook orders "query the RAG before coding",
   // so installing the environment guarantees the index exists. KJC-TSK-0659
   // stop-on-sudo: an index that cannot be built is a BLOCKING condition —
@@ -128,7 +162,19 @@ export async function envInstallCommand({ config = null, logger = null, flags =
     }
   }
   if (result.exitCode !== PENDING_EXIT_CODE) {
+    // KJC-TSK-0707 (PV-D) — privacy onboarding rides the install: kj asks,
+    // kj writes the denylist. Best-effort (stubbed in the SEA binary).
+    try {
+      const wizard = process.stdin.isTTY && process.stdout.isTTY ? createWizard() : null;
+      await ensurePrivacyList({ wizard, logger: console, isTTY: Boolean(wizard) });
+      wizard?.close();
+    } catch { /* privacy onboarding is best-effort */ }
     console.log("  The host agent now follows the method: RAG first, TDD, cross-AI review before commit.");
+    // KJC-BUG-0133 (part 2): a mid-session install lands the playbook in
+    // CLAUDE.md, but the running session loaded its context BEFORE — nobody
+    // re-reads it. Print the method so it enters THIS conversation now.
+    console.log("\n— The Karajan method below is IN EFFECT from this very message. If your session started before this install, apply it from now on:\n");
+    console.log(renderPlaybook({ stateBackend: config?.state_backend || "hu-board", boardName: config?.board?.name || null }));
   }
   return result;
 }

package/src/commands/harden.js

@@ -18,6 +18,7 @@ import { installConfigsForRoots } from "../harden/config-engine.js";
 import { installGuidelines } from "../harden/guidelines-engine.js";
 import { commandsForLanguage } from "../harden/hook-commands.js";
 import { installHooks } from "../harden/harden-engine.js";
+import { installHarnessHooks } from "../harden/harness-hooks.js";
 import { detectStackRoots } from "../harden/stack-roots.js";
 import { installWorkflows } from "../harden/workflow-engine.js";
 import { detectTestFramework } from "../utils/project-detect.js";
@@ -140,6 +141,12 @@ export async function hardenCommand({
   let result;
   try {
     result = await installHooks({ projectDir, profile, cmds, dryRun, baseBranch });
+    // KJC-TSK-0710 — the TOOL gate: rules imposed at tool time (Claude Code
+    // PreToolUse). Standard+ only; minimal stays hooks-lite.
+    if (profile !== "minimal" && !dryRun) {
+      const hh = installHarnessHooks({ projectDir, logger });
+      result.harnessHooks = hh.wired ? "wired" : "script-only";
+    }
   } catch (err) {
     if (json) logger.info?.(JSON.stringify({ ok: false, error: err.message }));
     else logger.error?.(`kj harden: ${err.message}`);

package/src/commands/privacy.js

@@ -0,0 +1,45 @@
+/**
+ * `kj privacy scan` (KJC-TSK-0704) — audit an outbound boundary before it
+ * ships: files/dirs or the staged diff's ADDED lines. Denylist blocks
+ * (exit 1), generic PII warns; findings always come out masked.
+ */
+import { runCommand } from "../utils/process.js";
+import { loadPrivacyList, scanPaths, scanText, privacyConfigPath } from "../privacy/scan.js";
+
+const addedLines = (diff) =>
+  diff.split("\n").filter((l) => l.startsWith("+") && !l.startsWith("+++")).map((l) => l.slice(1)).join("\n");
+
+export async function privacyScanCommand({ paths = [], flags = {}, logger = console } = {}) {
+  const list = loadPrivacyList();
+  let findings;
+  if (flags.staged) {
+    const res = await runCommand("git", ["diff", "--cached", "--no-ext-diff", "--unified=0"]);
+    findings = scanText(addedLines(res.stdout || ""), { list, source: "<staged diff>" });
+  } else {
+    if (paths.length === 0) {
+      logger.error?.("kj privacy scan: pass one or more paths, or --staged");
+      process.exitCode = 2;
+      return { ok: false, findings: [] };
+    }
+    findings = scanPaths(paths, { list });
+  }
+
+  const blocks = findings.filter((f) => f.severity === "block");
+  const warns = findings.filter((f) => f.severity === "warn");
+  const ok = blocks.length === 0;
+  process.exitCode = ok ? 0 : 1;
+  // --json keeps stdout machine-clean: exactly one JSON document, no prose.
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify({ ok, blocks: blocks.length, warns: warns.length, findings })}\n`);
+    return { ok, findings };
+  }
+  for (const f of blocks) logger.error?.(`✗ BLOCK [${f.type}] ${f.source}:${f.line} → ${f.masked}`);
+  for (const f of warns) logger.warn?.(`⚠ warn [${f.type}] ${f.source}:${f.line} → ${f.masked}`);
+  if (!list.present) {
+    logger.info?.(`hint: no personal denylist found — create ${privacyConfigPath()} (personal: [...], allow: [...]) so YOUR data blocks, not just warns`);
+  }
+  logger.info?.(ok
+    ? `privacy scan: clean of denylist hits (${warns.length} generic warning(s))`
+    : `privacy scan: ${blocks.length} personal-data hit(s) — this must not ship`);
+  return { ok, findings };
+}

package/src/commands/rag.js

@@ -7,6 +7,7 @@ import { makeGovernedEmbedder } from "../rag/governed-embedder.js";
 import { indexProject, indexProjectDelta } from "../rag/indexer.js";
 import { query } from "../rag/retriever.js";
 import { installPostMergeHook, maybeAutoUpdate } from "../rag/auto-update.js";
+import { indexLibrary, LIBRARY_PROJECT } from "../rag/library.js";
 import { loadGoldenQueries, runEval } from "../rag/eval.js";
 import { getKarajanHome } from "../utils/paths.js";
 
@@ -47,6 +48,13 @@ export async function ragIndexCommand({ config, logger, flags = {} }) {
       });
     }
     if (totals.head) setLastIndexedCommit(db, slug, totals.head);
+    // KJC-TSK-0697 — the library corpus refreshes on every index run.
+    // Best-effort and cheap: a handful of cards, content-hash dedup.
+    try {
+      await indexLibrary({ db, embedder, logger, projectDir });
+    } catch (err) {
+      logger.warn?.(`[rag] library index failed: ${err.message}`);
+    }
     if (flags.json) {
       process.stdout.write(`${JSON.stringify(totals)}\n`);
     } else {
@@ -87,7 +95,10 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
     // <slug>` overrides. Pre-v2.27 chunks with NULL slug are only visible
     // when no filter is in effect.
     const detected = projectSlug(config?.projectDir || process.cwd());
-    const project = flags.project === "all" ? null : (flags.project || detected || null);
+    // KJC-TSK-0697 — `--library` targets the distilled-canon collection:
+    // its own project namespace plus the kind filter.
+    const library = Boolean(flags.library);
+    const project = library ? LIBRARY_PROJECT : (flags.project === "all" ? null : (flags.project || detected || null));
     // KJC-BUG-0061 follow-up: align the CLI `--json` shape with the MCP
     // handler. The MCP tool responds `{ hits: [], empty: true, topK, scope }`
     // so agents (and the `/kj-rag-query` skill from Camino B) have a
@@ -101,7 +112,12 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
     }
     const mode = flags.mode || "hybrid";
     const alpha = Math.max(0, Math.min(1, Number(flags.alpha) || 0.6));
-    const where = flags.where || null;
+    // Safe by grammar: parseWhere (core where-parser.js) accepts ONLY
+    // AND-joined key=value pairs — an OR or parens never parses, so the
+    // composed clause cannot leak past the kind filter; it fails loudly.
+    const where = library
+      ? (flags.where ? `kind=library AND ${flags.where}` : "kind=library")
+      : (flags.where || null);
     const rerankOpts = flags.rerank ? { model: flags.rerankModel } : null;
     const hits = await query(db, makeGovernedEmbedder(config), text, { topK, scope, project, mode, alpha, where, rerankOpts });
     if (flags.json) {

package/src/commands/review-gate.js

@@ -5,6 +5,8 @@
  * verdict tied to the exact diff (verdict-store), so the pre-commit hook
  * (ENV-C) can verify it. Exit code 0 = approved, 1 = rejected/stale.
  */
+import { existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
 import { runCommand } from "../utils/process.js";
 import { checkVerdict } from "../review/verdict-store.js";
 import { runOneShotReview } from "../review/one-shot-review.js";
@@ -13,6 +15,7 @@ import { ensureGateTrackable } from "../review/gate-gitignore.js";
 import { runSonarPregate, formatSonarFinding } from "../review/sonar-pregate.js";
 import { checkCardFirst } from "../review/card-first.js";
 import { checkTestsWithCode } from "../review/tests-with-code.js";
+import { loadPrivacyList, scanText } from "../privacy/scan.js";
 
 // KJC-TSK-0686 (MG-A): card-first is a gate, not a habit. Runs on --staged
 // (before spending sonar/reviewer effort) AND on --check — the pre-commit
@@ -86,9 +89,8 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
 
   if (flags.installGate) {
     const fs = await import("node:fs/promises");
-    const path = await import("node:path");
-    const marker = path.join(projectDir, ".karajan", "review-gate");
-    await fs.mkdir(path.dirname(marker), { recursive: true });
+    const marker = join(projectDir, ".karajan", "review-gate");
+    await fs.mkdir(join(projectDir, ".karajan"), { recursive: true });
     await fs.writeFile(marker, "# Cross-AI review gate enabled (ENV-C1). Commit this file so the whole team inherits the gate.\n");
     console.log("✓ review gate enabled — commits now require an approved cross-AI verdict (kj review --staged)");
     // KJC-TSK-0646: a `.karajan/` dir-exclude would silently keep the
@@ -135,6 +137,44 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
       }
     }
   }
+  // KJC-TSK-0705 (PV-B): the outbound privacy boundary at commit time.
+  // Denylist data rejects (KJ_ALLOW_PII=1 is the named escape); generic PII
+  // warns (privacy.generic: "block" hardens). Added lines only — deletions
+  // don't publish. In the SEA binary the privacy module is stubbed and
+  // throws: the gate degrades with a note instead of crashing.
+  try {
+    const added = diff.split("\n").filter((l) => l.startsWith("+") && !l.startsWith("+++")).map((l) => l.slice(1)).join("\n");
+    const findings = scanText(added, { list: loadPrivacyList(), source: "<staged diff>" });
+    const blocks = findings.filter((f) => f.severity === "block");
+    const warns = findings.filter((f) => f.severity === "warn");
+    for (const f of warns) console.log(`⚠ privacy: [${f.type}] added line ${f.line} → ${f.masked} — personal data? move it out before it ships`);
+    const hardened = config?.privacy?.generic === "block" && warns.length > 0;
+    if (blocks.length > 0 || hardened) {
+      if (process.env.KJ_ALLOW_PII === "1") {
+        console.log(`⚠ privacy exempt: ${blocks.length} denylist hit(s) — KJ_ALLOW_PII=1 (explicit escape hatch)`);
+      } else {
+        for (const f of blocks) console.log(`✗ privacy: [${f.type}] on added line ${f.line} → ${f.masked}`);
+        const reason = `${blocks.length || warns.length} personal-data finding(s) in the staged diff — this must not reach the repo (KJ_ALLOW_PII=1 to override consciously)`;
+        console.log(`✗ privacy gate: ${reason}`);
+        process.exitCode = 1;
+        return { verdict: "rejected", reviewer: "privacy", issues: [{ severity: "high", description: reason }] };
+      }
+    }
+  } catch (err) {
+    // Known degradation: the SEA stub throws its install-from-npm message.
+    // Anything else fails CLOSED — a silent skip would defeat the guarantee.
+    if (/standalone binary/i.test(err?.message || "")) {
+      console.log("⚠ privacy gate unavailable in this build — skipping");
+    } else if (process.env.KJ_ALLOW_PII === "1") {
+      console.log(`⚠ privacy gate errored (${err.message}) — KJ_ALLOW_PII=1 (explicit escape hatch)`);
+    } else {
+      const reason = `privacy gate error: ${err.message} — refusing to pass the boundary unchecked (KJ_ALLOW_PII=1 to override consciously)`;
+      console.log(`✗ ${reason}`);
+      process.exitCode = 1;
+      return { verdict: "rejected", reviewer: "privacy", issues: [{ severity: "high", description: reason }] };
+    }
+  }
+
   const tests = checkTestsWithCode({ config, stagedFiles: changedFiles });
   if (tests.mode === "warn") console.log(`⚠ tests-with-code: ${tests.reason}`);
   if (tests.mode === "exempt") console.log(`⚠ tests-with-code exempt: ${tests.reason}`);
@@ -145,6 +185,20 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   }
 
   if (flags.check) {
+    // KJC-BUG-0132 (issue #1344): a PURE merge commit stages no content of
+    // its own — everything it brings reached the parent branches already
+    // reviewed, and there is no diff to bind a verdict to, so demanding one
+    // deadlocks the merge. A merge WITH conflict resolutions stages real
+    // content and still requires its verdict below.
+    if (!flags.range && !diff.trim()) {
+      const gitDirRaw = (await runCommand("git", ["rev-parse", "--git-dir"])).stdout?.trim();
+      const gitDir = gitDirRaw && !isAbsolute(gitDirRaw) ? join(projectDir, gitDirRaw) : gitDirRaw;
+      if (gitDir && existsSync(join(gitDir, "MERGE_HEAD"))) {
+        console.log("✓ pure merge commit — empty staged diff, parents already reviewed; gate passes with trail");
+        process.exitCode = 0;
+        return { ok: true, merge: true, reason: "pure merge commit (MERGE_HEAD, empty staged diff)" };
+      }
+    }
     const res = await checkVerdict(projectDir, diff);
     console.log(res.ok
       ? `✓ verdict ok — approved by ${res.verdict.reviewer} (diff ${res.verdict.diffHash.slice(0, 12)})`

package/src/environment/briefs.js

@@ -36,6 +36,7 @@ const B = {
         "Behavior changes carry their test in the same step.",
         "Data-model or API changes never share a step with anything else.",
         "No PR beyond ~150 net lines — partition upfront, not at the gate.",
+        "Non-trivial task? Name at least two approaches — one as if the codebase didn't exist — and say why the winner won.",
       ],
       "numbered-free plan: steps {description, files}, risks, out-of-scope."),
   },
@@ -56,6 +57,8 @@ const B = {
       [
         "Check the ADRs before deciding — never against an accepted one.",
         "Prefer the design that deletes code over the one that adds layers.",
+        "One alternative answers: what would you build as if the codebase didn't exist? Picking the legacy-shaped path is fine — picking it by inertia is not.",
+        "Ground that alternative in the canon: `kj rag query --library \"<problem signature>\"` serves distilled pattern cards with when-NOT-to-apply and citations.",
       ],
       "chosen design, discarded alternatives with reasons, affected boundaries."),
   },

package/src/environment/playbook.js

@@ -72,6 +72,11 @@ Invariants (the git gates enforce these — they are not suggestions):
   it as a proposed ADR (\`kj adr add\`) and ask — never bury it in a PR
   bullet. An oversized-diff warning is not an opinion either: partition,
   or get an explicit OK.
+- A non-trivial plan names at least two approaches — one as if the
+  codebase didn't exist — and says why the winner won. Following the
+  legacy line is a choice, never a default.
+- Publishing ANY artifact (a build's dist/, a docs site, a tarball)?
+  \`kj privacy scan <dir>\` first — nothing personal or secret-shaped ships.
 - Branch first: never commit on the base branch — every change reaches it
   through an atomic PR (~150 net lines, Conventional Commits). More than one
   task, or the base tree must stay untouched? \`kj worktree start <slug>\`

package/src/harden/harness-hooks.js

@@ -0,0 +1,80 @@
+/**
+ * harness-hooks — the TOOL gate (KJC-TSK-0710, from proposal KJC-PRP-0013).
+ * Field case 2026-08-02: text rules were not enough — the environment must
+ * impose them AT TOOL TIME. `kj harden` writes a PreToolUse script and wires
+ * it into the project's `.claude/settings.json` (merged, never clobbered):
+ * Write over an existing file blocks ("use Edit", KJ_ALLOW_WRITE=1 escapes);
+ * Bash that reserializes whole JSON files blocks (KJ_ALLOW_REWRITE=1).
+ * Claude-only v1 — the abstraction arrives with the second host that
+ * supports tool hooks.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const SCRIPT_REL = join(".karajan", "harness", "pretooluse.mjs");
+
+const SCRIPT_BODY = `#!/usr/bin/env node
+// kj tool gate (KJC-TSK-0710) — managed by \`kj harden\`. Exit 2 blocks the
+// tool call (stderr explains why); anything unexpected fails OPEN (exit 0)
+// so a gate bug never bricks the session.
+import { existsSync } from "node:fs";
+let raw = "";
+process.stdin.on("data", (d) => { raw += d; });
+process.stdin.on("end", () => {
+  try {
+    const { tool_name: tool, tool_input: input = {} } = JSON.parse(raw);
+    if (tool === "Write" && process.env.KJ_ALLOW_WRITE !== "1") {
+      if (input.file_path && existsSync(input.file_path)) {
+        console.error("kj tool gate: Write over an EXISTING file destroys unseen changes — use Edit for targeted changes (KJ_ALLOW_WRITE=1 to override consciously).");
+        process.exit(2);
+      }
+    }
+    if (tool === "Bash" && process.env.KJ_ALLOW_REWRITE !== "1") {
+      const cmd = String(input.command || "");
+      const writes = /open\\s*\\([^)]*["'][wa]["']|>\\s*\\S+\\.json\\b/.test(cmd);
+      if (/json\\.dumps?\\s*\\(/.test(cmd) && writes) {
+        console.error("kj tool gate: reserializing a whole JSON file makes the diff unreviewable — make targeted edits instead (KJ_ALLOW_REWRITE=1 to override consciously).");
+        process.exit(2);
+      }
+    }
+  } catch { /* fail open */ }
+  process.exit(0);
+});
+`;
+
+const hookEntry = (matcher) => ({ matcher, hooks: [{ type: "command", command: `node ${SCRIPT_REL}` }] });
+
+/** Write the script and merge the PreToolUse entries into .claude/settings.json. */
+export function installHarnessHooks({ projectDir = process.cwd(), logger = console } = {}) {
+  const scriptAbs = join(projectDir, SCRIPT_REL);
+  mkdirSync(join(projectDir, ".karajan", "harness"), { recursive: true });
+  writeFileSync(scriptAbs, SCRIPT_BODY, { mode: 0o755 });
+
+  const settingsPath = join(projectDir, ".claude", "settings.json");
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+    } catch {
+      logger.warn?.(`kj harden: ${settingsPath} is not valid JSON — leaving it untouched (tool gate script written, wire it manually)`);
+      return { script: scriptAbs, wired: false };
+    }
+  }
+  settings.hooks = settings.hooks || {};
+  // Preserve, never clobber: an existing PreToolUse with an unexpected shape
+  // is the user's business — leave the file alone (same as invalid JSON).
+  if ("PreToolUse" in settings.hooks && !Array.isArray(settings.hooks.PreToolUse)) {
+    logger.warn?.(`kj harden: ${settingsPath} has a non-array hooks.PreToolUse — leaving it untouched (tool gate script written, wire it manually)`);
+    return { script: scriptAbs, wired: false };
+  }
+  const pre = Array.isArray(settings.hooks.PreToolUse) ? settings.hooks.PreToolUse : [];
+  for (const matcher of ["Write", "Bash"]) {
+    const present = pre.some((e) => e?.matcher === matcher && JSON.stringify(e).includes("pretooluse.mjs"));
+    if (!present) pre.push(hookEntry(matcher));
+  }
+  settings.hooks.PreToolUse = pre;
+  mkdirSync(join(projectDir, ".claude"), { recursive: true });
+  writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  return { script: scriptAbs, wired: true };
+}

package/src/privacy/onboarding.js

@@ -0,0 +1,35 @@
+/**
+ * privacy onboarding (KJC-TSK-0707, PV-D) — the user never fills YAML by
+ * hand: `kj env install` asks and kj writes `~/.karajan/privacy.yml`.
+ * Every question skips on Enter; answers are NEVER echoed back.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+import { privacyConfigPath } from "./scan.js";
+
+export async function ensurePrivacyList({ wizard = null, logger = console, isTTY = process.stdout.isTTY } = {}) {
+  const target = privacyConfigPath();
+  if (existsSync(target)) return { created: false, reason: "present" };
+  if (!isTTY || !wizard) {
+    logger.info?.(`⚠ privacy: no personal denylist yet — re-run interactively or create ${target} (personal:/allow:) so YOUR data blocks at every outbound boundary`);
+    return { created: false, reason: "non-interactive" };
+  }
+  logger.info?.("privacy: let's protect your personal data at every outbound boundary (Enter skips any question).");
+  const csv = (s) => String(s || "").split(",").map((x) => x.trim()).filter(Boolean);
+  const personal = [
+    ...csv(await wizard.input("Personal emails that must NEVER be published (comma-separated):")),
+    ...csv(await wizard.input("Personal phone / ID numbers to block (comma-separated, optional):")),
+    ...csv(await wizard.input("Full name to block (optional):")),
+  ];
+  const allow = csv(await wizard.input("Public identities that are FINE to publish (handles, comma-separated):"));
+  if (personal.length === 0 && allow.length === 0) {
+    logger.info?.("privacy: skipped — generic PII detection still warns; create the denylist later to make YOUR data block");
+    return { created: false, reason: "skipped" };
+  }
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, `# kj privacy denylist — GLOBAL, never commit this file to any repo.\n${stringifyYaml({ personal, allow })}`);
+  logger.info?.(`✓ privacy: denylist written to ${target} (${personal.length} entrada(s), values not echoed)`);
+  return { created: true, entries: personal.length };
+}

package/src/privacy/scan.js

@@ -0,0 +1,120 @@
+/**
+ * privacy — the outbound boundary scanner (KJC-TSK-0704, epic KJC-PCS-0070).
+ * Born from a real incident (personal emails published on a landing):
+ * outputs get sanitized at boundaries like inputs do. Engine: karajan-rag's
+ * audited redactPII line by line — detects AND masks in one pass, so a
+ * finding never echoes the datum. On top, the user's denylist from
+ * `~/.karajan/privacy.yml` — GLOBAL, never in a repo: the list is sensitive.
+ */
+
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import os from "node:os";
+import { extname, join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { redactPII } from "karajan-rag";
+
+const SKIP_DIRS = new Set(["node_modules", ".git", ".kj"]);
+const BINARY_EXT = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".ico", ".pdf", ".zip", ".gz", ".tgz", ".woff", ".woff2", ".ttf", ".eot", ".mp4", ".db", ".sqlite"]);
+const MAX_FILE_BYTES = 512 * 1024;
+
+export function privacyConfigPath(home = os.homedir()) {
+  // KJ_PRIVACY_CONFIG: test/CI override of the global denylist location.
+  return process.env.KJ_PRIVACY_CONFIG || join(home, ".karajan", "privacy.yml");
+}
+
+/** Personal denylist + public-identity allowlist. Absent file → generics only. */
+export function loadPrivacyList({ home = os.homedir() } = {}) {
+  try {
+    const raw = parseYaml(readFileSync(privacyConfigPath(home), "utf8")) || {};
+    const clean = (xs) => (Array.isArray(xs) ? xs.map(String).map((s) => s.trim()).filter(Boolean) : []);
+    return { personal: clean(raw.personal), allow: clean(raw.allow), present: true };
+  } catch {
+    return { personal: [], allow: [], present: false };
+  }
+}
+
+const maskValue = (v) => (v.length <= 4 ? "***" : `${v.slice(0, 2)}***${v.slice(-2)}`);
+
+// KJC-TSK-0708 — hardcoded secrets. Known token shapes are never legit in
+// an outbound artifact → block; heuristics (credential assignments and
+// user:pass@ connection strings) warn toward .env / a secret manager.
+const SECRET_SHAPES = [
+  { type: "github-token", re: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g },
+  { type: "openai-key", re: /\bsk-[A-Za-z0-9_-]{20,}\b/g },
+  { type: "aws-key", re: /\bAKIA[0-9A-Z]{16}\b/g },
+  { type: "slack-token", re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g },
+  { type: "google-key", re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+  { type: "private-key", re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/g },
+  { type: "jwt", re: /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g },
+];
+const SECRET_HEURISTICS = [
+  { type: "secret-assignment", re: /\b(?:password|passwd|pwd|secret|token|api[_-]?key|apikey|auth)["']?\s*[:=]\s*["']([^"']{6,})["']/gi },
+  { type: "conn-string", re: /\b[a-z][a-z0-9+.-]*:\/\/[^\s:@/]+:([^\s@/]+)@/gi },
+];
+
+/**
+ * Scan a text. Returns findings — denylist hits as `severity:"block"`
+ * (masked value), generic PII as `severity:"warn"` (line already redacted).
+ */
+export function scanText(text, { list = loadPrivacyList(), source = "<text>" } = {}) {
+  const findings = [];
+  String(text).split("\n").forEach((line, i) => {
+    let probe = line;
+    for (const a of list.allow) probe = probe.split(a).join(" ");
+    for (const p of list.personal) {
+      let at = probe.toLowerCase().indexOf(p.toLowerCase());
+      if (at === -1) continue;
+      findings.push({ severity: "block", type: "denylist", source, line: i + 1, masked: maskValue(p) });
+      // Blank every occurrence so the generics don't double-report it.
+      while (at !== -1) { probe = probe.slice(0, at) + " ".repeat(p.length) + probe.slice(at + p.length); at = probe.toLowerCase().indexOf(p.toLowerCase()); }
+    }
+    for (const { type, re } of SECRET_SHAPES) {
+      re.lastIndex = 0;
+      let m;
+      while ((m = re.exec(probe)) !== null) {
+        findings.push({ severity: "block", type, source, line: i + 1, masked: maskValue(m[0]) });
+        probe = probe.slice(0, m.index) + " ".repeat(m[0].length) + probe.slice(m.index + m[0].length);
+        re.lastIndex = m.index + m[0].length;
+      }
+    }
+    for (const { type, re } of SECRET_HEURISTICS) {
+      re.lastIndex = 0;
+      let m;
+      while ((m = re.exec(probe)) !== null) {
+        findings.push({ severity: "warn", type, source, line: i + 1, masked: `${maskValue(m[1])} — move it to .env or a secret manager` });
+        probe = probe.slice(0, m.index) + " ".repeat(m[0].length) + probe.slice(m.index + m[0].length);
+        re.lastIndex = m.index + m[0].length;
+      }
+    }
+    const red = redactPII(probe);
+    if (red.total > 0) {
+      for (const [type, n] of Object.entries(red.counts)) {
+        if (n > 0) findings.push({ severity: "warn", type, source, line: i + 1, masked: red.text.trim().slice(0, 120) });
+      }
+    }
+  });
+  return findings;
+}
+
+/** Scan files/dirs recursively (skips node_modules/.git, binaries, big files). */
+export function scanPaths(paths, { list = loadPrivacyList() } = {}) {
+  const findings = [];
+  const visit = (p) => {
+    if (!existsSync(p)) return;
+    // Skip symlinks: an ancestor link recurses forever; an outside link ships nothing.
+    const st = lstatSync(p);
+    if (st.isSymbolicLink()) return;
+    if (st.isDirectory()) {
+      for (const name of readdirSync(p)) {
+        if (!SKIP_DIRS.has(name)) visit(join(p, name));
+      }
+      return;
+    }
+    if (BINARY_EXT.has(extname(p).toLowerCase()) || st.size > MAX_FILE_BYTES) return;
+    const content = readFileSync(p);
+    if (content.includes(0)) return; // binary sniff: NUL byte
+    findings.push(...scanText(content.toString("utf8"), { list, source: p }));
+  };
+  for (const p of paths) visit(p);
+  return findings;
+}

package/src/rag/library.js

@@ -0,0 +1,62 @@
+/**
+ * library — the distilled engineering canon as its own RAG collection
+ * (KJC-TSK-0697). Markdown cards from `<pkg>/library/`, `~/.karajan/library/`
+ * and `<project>/.karajan/library/` index into the SAME global rag.db,
+ * isolated by project="library" + kind="library", so `kj rag query --library`
+ * reaches the canon and normal project queries never see it. The architect
+ * consults it to ground the greenfield alternative (KJC-TSK-0696).
+ */
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { extname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import os from "node:os";
+
+import { chunkMarkdown } from "./chunker.js";
+import { insertChunk, deleteChunksBySource, findChunkByHash } from "./vec-store.js";
+
+export const LIBRARY_PROJECT = "library";
+
+const SHIPPED_LIBRARY_DIR = fileURLToPath(new URL("../../library", import.meta.url));
+
+/** Existing library dirs, shipped canon first. */
+export function libraryDirs({ pkgLibraryDir = SHIPPED_LIBRARY_DIR, home = os.homedir(), projectDir = process.cwd() } = {}) {
+  const candidates = [pkgLibraryDir, join(home, ".karajan", "library"), join(projectDir, ".karajan", "library")];
+  return candidates.filter((d) => existsSync(d));
+}
+
+/**
+ * Index every markdown card found in the library dirs. Idempotent: chunks
+ * re-index per source and identical bodies skip the embedder (content-hash
+ * dedup within the library project).
+ */
+export async function indexLibrary({ db, embedder, logger = console, pkgLibraryDir, home, projectDir } = {}) {
+  let indexed = 0, failed = 0, files = 0;
+  for (const dir of libraryDirs({ pkgLibraryDir, home, projectDir })) {
+    for (const name of readdirSync(dir)) {
+      if (extname(name).toLowerCase() !== ".md") continue;
+      const path = join(dir, name);
+      files += 1;
+      const chunks = chunkMarkdown(readFileSync(path, "utf8"), { path, kind: "library" });
+      const hashed = chunks.map((ch) => ({ ch, contentHash: createHash("sha256").update(ch.text).digest("hex") }));
+      // Unchanged card (every chunk body already known) → skip before the
+      // delete, so idempotent re-runs never touch the embedder.
+      if (hashed.length && hashed.every(({ contentHash }) => findChunkByHash(db, contentHash, LIBRARY_PROJECT))) continue;
+      deleteChunksBySource(db, path);
+      for (const { ch, contentHash } of hashed) {
+        try {
+          if (findChunkByHash(db, contentHash, LIBRARY_PROJECT)) continue;
+          const embedding = await embedder.embed(ch.text);
+          insertChunk(db, { source: path, kind: "library", text: ch.text, metadata: ch.metadata, embedding, project: LIBRARY_PROJECT, contentHash });
+          indexed += 1;
+        } catch (err) {
+          failed += 1;
+          logger.warn?.(`[rag-library] embed failed for ${path}: ${err.message}`);
+        }
+      }
+    }
+  }
+  if (files) logger.info?.(`[rag-library] ${files} card(s) → ${indexed} chunk(s) (${failed} failed)`);
+  return { files, indexed, failed };
+}