@karajan-family/code 4.21.0

package/src/commands/plan/index.js

@@ -0,0 +1,13 @@
+// Barrel: re-export all plan sub-command handlers.
+export { planGenerateCommand } from "./generate.js";
+export { planListCommand } from "./list.js";
+export { planShowCommand } from "./show.js";
+export { planReadyCommand } from "./ready.js";
+export { planValidateCommand } from "./validate.js";
+export { planDeleteCommand } from "./delete.js";
+export { planAddHuCommand } from "./add-hu.js";
+export { planRemoveHuCommand } from "./remove-hu.js";
+export { planMigrateResultCommand } from "./migrate-result.js";
+export { planFixCommand } from "./fix.js";
+export { planShareCommand } from "./share.js";
+export { planUnshareCommand } from "./unshare.js";

package/src/commands/plan/list.js

@@ -0,0 +1,21 @@
+/**
+ * kj plan list
+ */
+export async function planListCommand({ config }) {
+  const { listPlans } = await import("../../plan/plan-store.js");
+  const projectDir = config.projectDir || process.cwd();
+  const plans = await listPlans(projectDir);
+
+  if (plans.length === 0) {
+    console.log("No plans found. Create one with: kj plan \"your task\"");
+    return;
+  }
+
+  console.log(`Plans for ${projectDir}:\n`);
+  for (const p of plans) {
+    const husInfo = p.huCount > 0 ? ` (${p.huCount} HUs)` : "";
+    const status = p.status !== "draft" ? ` [${p.status}]` : "";
+    console.log(`  ${p.planId}  ${(p.name || p.task || "").slice(0, 50)}${husInfo}${status}`);
+    console.log(`    Created: ${p.createdAt}`);
+  }
+}

package/src/commands/plan/migrate-result.js

@@ -0,0 +1,41 @@
+/**
+ * kj plan migrate-result [--dry-run] — KJC-TSK-0394 step 4.
+ * Siembra `result` en las HUs de los plan files existentes,
+ * deducido del status legacy. Idempotente.
+ */
+import { listPlans, loadPlan, savePlan } from "../../plan/plan-store.js";
+import { migratePlanResult } from "../../plan/plan-migrate-result.js";
+
+export async function planMigrateResultCommand({ config, flags = {} }) {
+  const projectDir = config.projectDir || process.cwd();
+  const dryRun = !!flags.dryRun;
+
+  const plans = await listPlans(projectDir);
+  if (plans.length === 0) {
+    console.log("No hay plans que migrar en este proyecto.");
+    return;
+  }
+
+  let totalPlans = 0;
+  let totalHus = 0;
+  for (const meta of plans) {
+    const plan = await loadPlan(projectDir, meta.planId);
+    if (!plan) continue;
+    const { plan: migrated, changes } = migratePlanResult(plan);
+    if (changes.length === 0) continue;
+    totalPlans += 1;
+    totalHus += changes.length;
+    const summary = changes
+      .map((c) => `${c.huId}→${c.result ?? "null"}`)
+      .join(", ");
+    console.log(`${dryRun ? "[dry-run] " : ""}${meta.planId}: ${changes.length} HU(s) — ${summary}`);
+    if (!dryRun) await savePlan(projectDir, migrated);
+  }
+
+  if (totalPlans === 0) {
+    console.log("Todos los plans ya tienen `result` sembrado. Nada que hacer.");
+  } else {
+    const prefix = dryRun ? "[dry-run] " : "";
+    console.log(`${prefix}Migrados ${totalHus} HU(s) en ${totalPlans} plan(s).`);
+  }
+}

package/src/commands/plan/ready.js

@@ -0,0 +1,46 @@
+/**
+ * kj plan ready <planId>
+ */
+export async function planReadyCommand({ config, planId }) {
+  const { loadPlan, savePlan } = await import("../../plan/plan-store.js");
+  const { certifyAllHus } = await import("../../plan/plan-hu-ops.js");
+  const { validatePlan } = await import("../../plan/plan-schema.js");
+  const projectDir = config.projectDir || process.cwd();
+
+  const plan = await loadPlan(projectDir, planId);
+  if (!plan) { console.error(`Plan not found: ${planId}`); process.exitCode = 1; return; }
+
+  const validation = validatePlan(plan);
+  if (!validation.valid) {
+    console.error("Plan validation failed:");
+    for (const err of validation.errors) console.error(`  - ${err}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (plan.hus.length === 0) {
+    console.error("Cannot approve a plan with 0 HUs.");
+    process.exitCode = 1;
+    return;
+  }
+
+  // Tests-first gate: refuse to certify HUs that have no acceptance_tests.
+  // A "ready" plan must have an executable test contract per HU, otherwise
+  // the coder has nothing to aim for. Flag each offender, then bail so the
+  // user can edit the plan (board ✎ Edit or `kj plan add-hu`) and retry.
+  const missing = plan.hus.filter((h) => !Array.isArray(h.acceptance_tests) || h.acceptance_tests.length === 0);
+  if (missing.length > 0) {
+    console.error(`Cannot mark ready: ${missing.length}/${plan.hus.length} HU(s) have no acceptance_tests:`);
+    for (const h of missing) console.error(`  - ${h.id}  ${(h.title || "").slice(0, 60)}`);
+    console.error("");
+    console.error("Tests-first flow requires a test contract per HU. Edit each HU on the board");
+    console.error("(http://localhost:4000) via the ✎ Edit button, or re-run `kj plan` to regenerate.");
+    process.exitCode = 1;
+    return;
+  }
+
+  const count = certifyAllHus(plan);
+  await savePlan(projectDir, plan);
+  console.log(`✅ ${count} HUs certified. Plan status: ready`);
+  console.log(`Run: kj run --plan ${planId} "${(plan.task || "").slice(0, 40)}..."`);
+}

package/src/commands/plan/remove-hu.js

@@ -0,0 +1,17 @@
+/**
+ * kj plan remove-hu <planId> <huId>
+ */
+export async function planRemoveHuCommand({ config, planId, huId }) {
+  const { loadPlan, savePlan } = await import("../../plan/plan-store.js");
+  const { removeHu } = await import("../../plan/plan-hu-ops.js");
+  const projectDir = config.projectDir || process.cwd();
+
+  const plan = await loadPlan(projectDir, planId);
+  if (!plan) { console.error(`Plan not found: ${planId}`); process.exitCode = 1; return; }
+
+  const ok = removeHu(plan, huId);
+  if (!ok) { console.error(`HU not found: ${huId}`); process.exitCode = 1; return; }
+
+  await savePlan(projectDir, plan);
+  console.log(`Removed: ${huId}`);
+}

package/src/commands/plan/share.js

@@ -0,0 +1,85 @@
+/**
+ * kj plan share <planId>
+ *
+ * Promotes a local plan (under `~/.karajan/plans/<projectSlug>/`) to the
+ * project's shared dir (`<projectDir>/.karajan-shared/plans/`) so teammates
+ * pulling the repo see the same HUs in their HU Board. KJC-PRP-0002 / PR1.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeJsonAtomic } from "../../utils/atomic-write.js";
+import { getSharedPlansDir } from "../../utils/shared-paths.js";
+import { loadPlan } from "../../plan/plan-store.js";
+
+function parseIdList(raw) {
+  if (!raw) return null;
+  const ids = String(raw).split(",").map((s) => s.trim()).filter(Boolean);
+  return ids.length ? ids : null;
+}
+
+export async function planShareCommand({ config, planId, logger, only, exclude }) {
+  const log = logger || console;
+  const projectDir = config.projectDir || process.cwd();
+
+  if (!planId) {
+    log.error?.("kj plan share <planId> — planId is required");
+    process.exitCode = 1;
+    return;
+  }
+
+  const onlyIds = parseIdList(only);
+  const excludeIds = parseIdList(exclude);
+  if (onlyIds && excludeIds) {
+    log.error?.("kj plan share — --only and --exclude are mutually exclusive");
+    process.exitCode = 1;
+    return;
+  }
+
+  const plan = await loadPlan(projectDir, planId);
+  if (!plan) {
+    log.error?.(`Plan not found: ${planId}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // KJC-PRP-0002 PR4: optional per-HU filter. Lets a dev share a curated
+  // subset of HUs without splitting the plan or hand-editing the JSON.
+  let hus = plan.hus || [];
+  let filterSummary = "";
+  if (onlyIds) {
+    hus = hus.filter((h) => onlyIds.includes(h.id));
+    filterSummary = ` [only: ${onlyIds.join(",")}]`;
+  } else if (excludeIds) {
+    hus = hus.filter((h) => !excludeIds.includes(h.id));
+    filterSummary = ` [excluding: ${excludeIds.join(",")}]`;
+  }
+  if ((onlyIds || excludeIds) && hus.length === 0) {
+    log.error?.(`No HUs left after applying filter — aborting share.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const sharedDir = getSharedPlansDir(projectDir);
+  await fs.mkdir(sharedDir, { recursive: true });
+  const targetFile = path.join(sharedDir, `${plan.planId}.json`);
+
+  // Stamp a `shared: true` marker so consumers (board sync, audit, etc.)
+  // can tell promoted copies from local ones without inspecting the path.
+  const sharedPlan = {
+    ...plan,
+    hus,
+    shared: true,
+    sharedAt: new Date().toISOString(),
+  };
+  if (onlyIds || excludeIds) {
+    sharedPlan.sharedFilter = onlyIds
+      ? { only: onlyIds }
+      : { exclude: excludeIds };
+  }
+  await writeJsonAtomic(targetFile, sharedPlan);
+
+  const rel = path.relative(projectDir, targetFile);
+  log.info?.(`✓ Shared plan ${plan.planId} → ${rel}${filterSummary}`);
+  log.info?.(`  Commit '.karajan-shared/' so your team picks it up.`);
+}

package/src/commands/plan/show.js

@@ -0,0 +1,81 @@
+import { formatHuTable } from "./_shared.js";
+
+/**
+ * kj plan show <planId>
+ */
+export async function planShowCommand({ config, planId }) {
+  const { loadPlan } = await import("../../plan/plan-store.js");
+  const projectDir = config.projectDir || process.cwd();
+  const plan = await loadPlan(projectDir, planId);
+
+  if (!plan) {
+    console.error(`Plan not found: ${planId}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`Plan: ${plan.planId}`);
+  console.log(`Task: ${plan.task}`);
+  console.log(`Name: ${plan.name || "—"}`);
+  console.log(`Status: ${plan.status}`);
+  console.log(`Version: ${plan.version}`);
+  console.log(`Created: ${plan.createdAt}`);
+
+  if (plan.approach) {
+    console.log(`\n## Approach\n${plan.approach}`);
+  }
+
+  if (plan.hus?.length > 0) {
+    console.log(`\n## HUs (${plan.hus.length})`);
+    console.log(formatHuTable(plan.hus));
+  } else {
+    console.log("\nNo HUs defined. Add with: kj plan add-hu " + planId);
+  }
+
+  // Reviewer findings (PR D). When the planner ran with the plan
+  // reviewer pass enabled, plan.review carries advisory findings —
+  // missing HUs, missing deps, scope overlaps, parallelisable
+  // groups, order issues. Each section only renders when non-empty
+  // so a clean plan stays clean on screen.
+  if (plan.review) {
+    const r = plan.review;
+    const sections = [];
+    if (r.missing_hus?.length) {
+      sections.push(`### Missing HUs (${r.missing_hus.length})`);
+      for (const m of r.missing_hus) {
+        sections.push(`- §${m.spec_section}: ${m.rationale}`);
+      }
+    }
+    if (r.missing_dependencies?.length) {
+      sections.push(`\n### Missing dependencies (${r.missing_dependencies.length})`);
+      for (const d of r.missing_dependencies) {
+        sections.push(`- ${d.from} should depend on ${d.on} — ${d.rationale}`);
+      }
+    }
+    if (r.scope_overlaps?.length) {
+      sections.push(`\n### Scope overlaps (${r.scope_overlaps.length})`);
+      for (const o of r.scope_overlaps) {
+        sections.push(`- ${o.between.join(" ↔ ")}: ${o.rationale}`);
+      }
+    }
+    if (r.parallelisable_groups?.length) {
+      sections.push(`\n### Parallelisable groups (${r.parallelisable_groups.length})`);
+      for (const g of r.parallelisable_groups) {
+        sections.push(`- ${g.hus.join(" + ")}${g.rationale ? ` — ${g.rationale}` : ""}`);
+      }
+    }
+    if (r.order_issues?.length) {
+      sections.push(`\n### Order issues (${r.order_issues.length})`);
+      for (const o of r.order_issues) {
+        sections.push(`- ${o.hus.join(", ")} (${o.issue}): ${o.rationale}`);
+      }
+    }
+    if (sections.length > 0) {
+      console.log("\n## Reviewer findings");
+      if (r.summary) console.log(`_${r.summary}_\n`);
+      console.log(sections.join("\n"));
+    } else if (r.summary) {
+      console.log(`\n## Reviewer findings\n_${r.summary}_`);
+    }
+  }
+}

package/src/commands/plan/unshare.js

@@ -0,0 +1,41 @@
+/**
+ * kj plan unshare <planId>
+ *
+ * Inverse of `kj plan share`. Removes the plan from the project's shared dir
+ * (`<projectDir>/.karajan-shared/plans/`). The per-user copy at
+ * `~/.karajan/plans/<projectSlug>/<planId>.json` stays untouched, so the dev
+ * keeps the plan locally while the team stops seeing it. KJC-PRP-0002 / PR3.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getSharedPlansDir } from "../../utils/shared-paths.js";
+
+export async function planUnshareCommand({ config, planId, logger }) {
+  const log = logger || console;
+  const projectDir = config.projectDir || process.cwd();
+
+  if (!planId) {
+    log.error?.("kj plan unshare <planId> — planId is required");
+    process.exitCode = 1;
+    return;
+  }
+
+  const sharedDir = getSharedPlansDir(projectDir);
+  const targetFile = path.join(sharedDir, `${planId}.json`);
+
+  try {
+    await fs.unlink(targetFile);
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      log.error?.(`Plan not shared: ${planId} (no file at .karajan-shared/plans/)`);
+      process.exitCode = 1;
+      return;
+    }
+    throw err;
+  }
+
+  const rel = path.relative(projectDir, targetFile);
+  log.info?.(`✓ Unshared plan ${planId} (removed ${rel})`);
+  log.info?.(`  Commit '.karajan-shared/' so your team stops seeing it.`);
+}

package/src/commands/plan/validate.js

@@ -0,0 +1,20 @@
+/**
+ * kj plan validate <planId>
+ */
+export async function planValidateCommand({ config, planId }) {
+  const { loadPlan } = await import("../../plan/plan-store.js");
+  const { validatePlan } = await import("../../plan/plan-schema.js");
+  const projectDir = config.projectDir || process.cwd();
+
+  const plan = await loadPlan(projectDir, planId);
+  if (!plan) { console.error(`Plan not found: ${planId}`); process.exitCode = 1; return; }
+
+  const result = validatePlan(plan);
+  if (result.valid) {
+    console.log(`✅ Plan ${planId} is valid (${plan.hus.length} HUs, status: ${plan.status})`);
+  } else {
+    console.error(`❌ Plan ${planId} has ${result.errors.length} error(s):`);
+    for (const err of result.errors) console.error(`  - ${err}`);
+    process.exitCode = 1;
+  }
+}

package/src/commands/plan.js

@@ -0,0 +1,17 @@
+// Thin shim. The plan command was split into one file per sub-command
+// under `./plan/`. This file remains so existing callers that import
+// `./commands/plan.js` (src/cli.js, tests) keep working without churn.
+export {
+  planGenerateCommand,
+  planListCommand,
+  planShowCommand,
+  planReadyCommand,
+  planValidateCommand,
+  planDeleteCommand,
+  planAddHuCommand,
+  planRemoveHuCommand,
+  planMigrateResultCommand,
+  planFixCommand,
+  planShareCommand,
+  planUnshareCommand,
+} from "./plan/index.js";

package/src/commands/policy.js

@@ -0,0 +1,164 @@
+/**
+ * `kj policy` — PL-A parte 3b (KJC-TSK-0733, épica KJC-PCS-0074). El motor
+ * en modo WARN: eval de una tool call y check del diff staged contra
+ * `.karajan/policy.yml`. En PL-A nada bloquea salvo un fichero de policy
+ * inválido (exit 1: declarar lo inaplicable es error del fichero, no aviso).
+ * `eval --strict` devuelve exit 2 en deny — el contrato para los adaptadores
+ * de hooks de PL-B. Los dientes de check llegan en PL-B/PL-C.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { checkStagedDiff, evalToolCall, loadPolicy } from "../policy/engine.js";
+import { loadStandingExceptions, recordPolicyException } from "../policy/exceptions.js";
+import { verifyDecisionChain } from "@karajan-family/governance";
+
+const execFileAsync = promisify(execFile);
+
+async function stagedFacts(projectDir, gitFn, range = null) {
+  const run =
+    gitFn ||
+    (async (args) => (await execFileAsync("git", args, { cwd: projectDir, maxBuffer: 16 * 1024 * 1024 })).stdout);
+  // PL-C (KJC-TSK-0735): en CI no hay staged — con --range se evalúa
+  // base...head, el MISMO motor sobre el diff del PR (tier C del ADR 0001).
+  const base = range ? ["diff", range] : ["diff", "--cached"];
+  const files = (await run([...base, "--name-only"]))
+    .split("\n")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  let net = 0;
+  for (const line of (await run([...base, "--numstat"])).split("\n")) {
+    const [a, r] = line.trim().split(/\s+/);
+    if (a && a !== "-") net += Number(a) || 0;
+    if (r && r !== "-") net -= Number(r) || 0;
+  }
+  return { files, netLinesAdded: net };
+}
+
+export async function policyCommand({ action, config = {}, flags = {}, logger = console, deps = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const { policy, errors } = loadPolicy({ projectDir, deps });
+  if (errors.length > 0) {
+    for (const e of errors) logger.error?.(`✗ ${e}`);
+    logger.error?.("policy: el fichero declara lo que el motor no puede aplicar — corrígelo (una regla que miente es peor que ninguna)");
+    return 1;
+  }
+
+  // GOV-C2 (KJC-TSK-0749): anclaje temporal sin blockchain — verificar la
+  // cadena ENTERA y sellar su head-hash en un fichero TRACKEADO por git:
+  // reescribir el log de ayer exige reescribir el repo de ayer. Un anchor
+  // previo con más entradas que el log actual = truncado ⇒ no se re-sella.
+  if (action === "anchor") {
+    let raw;
+    try {
+      raw = readFileSync(join(projectDir, ".karajan", "policy-decisions.jsonl"), "utf8");
+    } catch {
+      logger.info?.("policy anchor: sin decisiones que anclar — el log nace con el primer deny/excepción/commit-allow");
+      return 0;
+    }
+    const lines = raw.split("\n").filter((l) => l.trim());
+    // Fichero vacío o solo whitespace = sin decisiones (catch de codex:
+    // lines.at(-1) undefined reventaba el hash en vez de salir limpio).
+    if (lines.length === 0) {
+      logger.info?.("policy anchor: sin decisiones que anclar — el log nace con el primer deny/excepción/commit-allow");
+      return 0;
+    }
+    const chain = verifyDecisionChain(lines);
+    if (!chain.ok) {
+      logger.error?.(`✗ policy anchor: cadena rota en la entrada ${chain.at} (${chain.reason}) — el log ha sido manipulado; NO se sella`);
+      return 1;
+    }
+    const anchorFile = join(projectDir, ".karajan", "policy-anchor.json");
+    try {
+      const prev = JSON.parse(readFileSync(anchorFile, "utf8"));
+      if (Number.isFinite(prev.length) && prev.length > chain.length) {
+        logger.error?.(`✗ policy anchor: el log retrocede (anchor previo=${prev.length} entradas, actual=${chain.length}) — truncado tras el último sello; NO se re-sella`);
+        return 1;
+      }
+    } catch { /* sin anchor previo (o ilegible): primer sello */ }
+    const head = createHash("sha256").update(lines.at(-1), "utf8").digest("hex");
+    writeFileSync(anchorFile, `${JSON.stringify({ head, length: chain.length, ts: new Date().toISOString() }, null, 2)}\n`, "utf8");
+    logger.info?.(`✓ policy anchor: cadena íntegra (${chain.length} decisiones) — head ${head.slice(0, 12)} sellado en .karajan/policy-anchor.json; committéalo para anclarlo en la historia de git`);
+    return 0;
+  }
+
+  // GOV-B (KJC-TSK-0746): conceder una excepción PERMANENTE con el modelo
+  // probatorio completo — quién (identidad), regla exacta, justificación en
+  // el momento y caducidad obligatoria. Los defaults.* del consumidor son
+  // inexcepcionables: no se conceden ni desde aquí.
+  if (action === "grant") {
+    const { rule, until, reason } = flags;
+    if (!rule || !until || !reason?.trim()) {
+      logger.error?.("policy grant: --rule, --until (ISO) y --reason son obligatorios — una excepción sin quién/por qué/hasta cuándo no es una excepción, es un agujero");
+      return 1;
+    }
+    // Inexcepcionable = inexcepcionable TAMBIÉN al conceder (catch de codex):
+    // defaults.*, cualquier cap con class security, y una policy inválida
+    // (sin policy legible no se puede probar que la regla NO es security).
+    const m = /^roles\.([^.]+)\.(write|shell)/.exec(rule);
+    if (rule.startsWith("defaults.") || errors.length > 0 || (m && policy.roles?.[m[1]]?.[m[2]]?.class === "security")) {
+      logger.error?.(`policy grant: "${rule}" es inexcepcionable (default del proyecto o clase security) o la policy no es verificable — no se concede, ni con razón`);
+      return 1;
+    }
+    try {
+      // GOV-E (KJC-TSK-0750, idea del lector): la renovación es SEÑAL — una
+      // regla re-concedida N veces es la política real pidiendo que la
+      // cambien por su cauce. Se cuenta contra TODAS las permanentes previas
+      // (vencidas incluidas: precisamente esas son la sedimentación).
+      const previous = loadStandingExceptions(projectDir).standing.filter((e) => e.rule_id === rule).length;
+      const rec = recordPolicyException({
+        projectDir,
+        entry: { rule_id: rule, justification: reason.trim(), scopeKind: "permanente", expiresAt: until },
+      });
+      logger.info?.(`✓ excepción permanente registrada: [${rec.rule_id}] hasta ${rec.expiresAt} — concedida por ${rec.who?.git ?? "?"} (${rec.who?.grade ?? "?"})`);
+      if (previous >= 1) {
+        logger.warn?.(`⚠ ${previous + 1}ª concesión sobre esta regla — una excepción que se renueva ya no es una excepción: considera cambiar la política por su cauce (PR a .karajan/policy.yml)`);
+      }
+      return 0;
+    } catch (err) {
+      logger.error?.(`policy grant: ${err.message}`);
+      return 1;
+    }
+  }
+
+  if (action === "eval") {
+    let input;
+    try {
+      input = flags.input ? JSON.parse(flags.input) : {};
+    } catch {
+      logger.error?.("policy eval: --input debe ser JSON válido");
+      return 1;
+    }
+    const verdict = evalToolCall(policy, { role: flags.role || "coder", tool: flags.tool, input, root: projectDir });
+    logger.info?.(JSON.stringify(verdict));
+    return verdict.decision === "deny" && flags.strict ? 2 : 0;
+  }
+
+  // check — staged por defecto, base...head con --range (CI). Warn salvo
+  // --strict (PL-C): con --strict, una violación enforcement=deny devuelve
+  // exit 2 nombrando la regla — el contrato merge-blocking del tier C.
+  const facts = await stagedFacts(projectDir, deps.gitFn, flags.range || null);
+  const violations = checkStagedDiff(policy, { role: flags.role || "coder", ...facts });
+  const hard = flags.strict ? violations.filter((v) => v.enforcement === "deny") : [];
+  if (flags.json) {
+    logger.info?.(JSON.stringify({ mode: flags.strict ? "strict" : "warn", violations }));
+    return hard.length > 0 ? 2 : 0;
+  }
+  if (violations.length === 0) {
+    logger.info?.("policy check: limpio");
+    return 0;
+  }
+  for (const v of violations) {
+    const where = v.file ? ` (${v.file})` : "";
+    const mark = flags.strict && v.enforcement === "deny" ? "✗" : "⚠";
+    logger.warn?.(`${mark} policy [${v.rule_id}] ${v.reason}${where}`);
+  }
+  if (hard.length > 0) {
+    logger.error?.(`policy check: ${hard.length} violación(es) con enforcement=deny — el merge no procede (--strict)`);
+    return 2;
+  }
+  logger.warn?.(`policy check: ${violations.length} aviso(s) — check es modo warn, no bloquea; los deny los aplican kj review --staged y el pre-commit (PL-B)`);
+  return 0;
+}

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