@karajan-family/code 4.21.0

package/src/commands/harden.js

@@ -0,0 +1,203 @@
+/**
+ * `kj harden` — install the quality harness (git hooks) into any repo.
+ *
+ * Thin CLI layer over harden-engine (KJC-TSK-0555): resolves stack-aware
+ * lint/format/test commands, runs the installer and reports. Config files
+ * (eslint/prettier) and CI gates land in later slices (H-C / H-D).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { loadConfig } from "../config.js";
+import { resolveTestOnPush } from "../harden/test-on-push.js";
+import { compareHarden, formatAdvisoryReport } from "../harden/advisory.js";
+import { interactiveHarden } from "../harden/interactive.js";
+import { createWizard, isTTY } from "../utils/wizard.js";
+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 { installSentinelHooks } from "../harden/sentinel-hooks.js";
+import { detectStackRoots } from "../harden/stack-roots.js";
+import { installWorkflows } from "../harden/workflow-engine.js";
+import { detectTestFramework } from "../utils/project-detect.js";
+import { ensureIdentity } from "../identity/bootstrap.js";
+
+const JS_TEST_CMD = {
+  vitest: "npx vitest run",
+  jest: "npx jest",
+  mocha: "npx mocha",
+};
+
+/**
+ * Per-repo harden scope, persisted in package.json `kj.harden` so a repo with
+ * sub-tools (e.g. a python wrapper) excludes them once instead of on every
+ * invocation (KJC-TSK-0564). CLI flags are merged on top.
+ */
+function readHardenConfig(projectDir) {
+  const pkgPath = join(projectDir, "package.json");
+  if (!existsSync(pkgPath)) return {};
+  try {
+    return JSON.parse(readFileSync(pkgPath, "utf8")).kj?.harden ?? {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Resolve the hook's lint/format/test commands for the primary language.
+ * Non-JS stacks use their native toolchain (go/ruff/…); JS/TS is built from
+ * the project's own package.json scripts so no npm command is ever assumed.
+ */
+export async function resolveCmds(projectDir, language) {
+  const lang = language ?? detectStackRoots(projectDir)[0]?.language ?? null;
+  const cmds = { ...commandsForLanguage(lang) };
+  if (lang !== "javascript" && lang !== "typescript") return cmds;
+
+  const pkgPath = join(projectDir, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const scripts = JSON.parse(readFileSync(pkgPath, "utf8")).scripts ?? {};
+      if (scripts.lint) cmds.lint = "npm run -s lint";
+      if (scripts["format:check"]) cmds.format = "npm run -s format:check";
+      else if (scripts.format) cmds.format = "npm run -s format";
+      if (scripts.test) cmds.test = "npm test";
+    } catch {
+      /* unreadable package.json → fall back to framework detection */
+    }
+  }
+  if (!cmds.test) {
+    const { framework } = await detectTestFramework(projectDir);
+    if (framework && JS_TEST_CMD[framework]) cmds.test = JS_TEST_CMD[framework];
+  }
+  return cmds;
+}
+
+export async function hardenCommand({
+  projectDir = process.cwd(),
+  profile = "standard",
+  config = true,
+  ci = true,
+  guidelines = true,
+  mutation = false,
+  dryRun = false,
+  json = false,
+  report = false,
+  interactive = false,
+  only = [],
+  exclude = [],
+  logger = console,
+} = {}) {
+  const repoCfg = readHardenConfig(projectDir);
+  const onlyDirs = [...(repoCfg.only ?? []), ...only];
+  const excludeDirs = [...(repoCfg.exclude ?? []), ...exclude];
+
+  // --report is read-only: compare against the kj standard and print/emit the
+  // advisory (Advisory B, KJC-TSK-0566), honouring the same scope as an install
+  // so it never proposes a root that `kj harden` would skip. Writes nothing.
+  if (report) {
+    const result = compareHarden({ projectDir, profile, only: onlyDirs, exclude: excludeDirs });
+    if (json) logger.info?.(JSON.stringify(result));
+    else for (const line of formatAdvisoryReport(result)) logger.info?.(line);
+    return { ok: true, report: true, ...result };
+  }
+
+  // --interactive: adopt the kj standard piece by piece, default-safe (keep the
+  // user's own). Only meaningful with a TTY — without one (CI, --json) we fall
+  // through to the normal seed-if-absent install so nothing breaks (KJC-TSK-0567).
+  if (interactive && isTTY() && !json) {
+    const wizard = createWizard();
+    try {
+      return await interactiveHarden({
+        projectDir,
+        profile,
+        only: onlyDirs,
+        exclude: excludeDirs,
+        ask: (prompt, def) => wizard.confirm(prompt, def),
+        logger,
+      });
+    } finally {
+      wizard.close();
+    }
+  }
+
+  const roots = detectStackRoots(projectDir, { only: onlyDirs, exclude: excludeDirs });
+  const cmds = await resolveCmds(projectDir, roots[0]?.language ?? null);
+  // KJC-TSK-0647: CI already running the suite per PR ⇒ pre-push drops its
+  // test command (false-red source under local parallelism); opt back in
+  // via package.json kj.harden.test_on_push.
+  const top = resolveTestOnPush({ projectDir, repoCfg, testCmd: cmds.test });
+  if (top.reason) {
+    logger.info?.(`kj harden: ${top.reason}`);
+    cmds.test = undefined;
+  }
+  // KJC-TSK-0648: branch-first guard — the base branch only moves via PR.
+  // Resolved from the project's kj config (default "main"); best-effort so
+  // harden keeps working on repos that never ran kj init.
+  let baseBranch = "main";
+  try {
+    baseBranch = (await loadConfig(projectDir))?.base_branch || "main";
+  } catch { /* no kj config — default stands */ }
+  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";
+      // KJC-TSK-0713 — the Sentinel: method state + Stop gate (turn cannot
+      // end red). Same Claude-only harness surface as the tool gate.
+      const sh = installSentinelHooks({ projectDir, logger });
+      result.sentinelHooks = sh.wired ? "wired" : "script-only";
+    }
+  } catch (err) {
+    if (json) logger.info?.(JSON.stringify({ ok: false, error: err.message }));
+    else logger.error?.(`kj harden: ${err.message}`);
+    return { ok: false, error: err.message };
+  }
+
+  // Config (lint/format/commit) ships with standard+, per language root so a
+  // fullstack monorepo is hardened on every side, not just one.
+  const withConfig = config && profile !== "minimal";
+  const cfg = withConfig ? installConfigsForRoots({ projectDir, roots, dryRun }) : null;
+  const withCi = ci && profile !== "minimal";
+  const wf = withCi
+    ? installWorkflows({ projectDir, language: roots[0]?.language ?? null, profile, mutation, dryRun })
+    : null;
+  const withGuidelines = guidelines && profile !== "minimal";
+  const gl = withGuidelines ? installGuidelines({ projectDir, dryRun }) : null;
+  const out = {
+    ok: true,
+    ...result,
+    configs: cfg?.configs ?? [],
+    workflows: wf?.workflows ?? [],
+    guidelines: gl?.guidelines ?? [],
+  };
+
+  if (json) {
+    logger.info?.(JSON.stringify(out));
+    return out;
+  }
+
+  const verb = dryRun ? "would install" : "installed";
+  logger.info?.(`kj harden (${profile}) — ${verb} ${result.hooks.length} hook(s) → ${result.hooksPath}`);
+  for (const h of result.hooks) logger.info?.(`  • ${h.hook}: ${h.action}`);
+  for (const c of out.configs) {
+    const note = c.note ? ` (${c.note})` : "";
+    logger.info?.(`  • ${c.file}: ${c.action}${note}`);
+  }
+  for (const w of out.workflows) logger.info?.(`  • ${w.file}: ${w.action}`);
+  for (const g of out.guidelines) logger.info?.(`  • ${g.file}: ${g.action}`);
+  if (!dryRun) logger.info?.("core.hooksPath set. Verify later with `kj check`.");
+  // IDN-A (KJC-TSK-0762): a hardened clone declares who works it. Captured
+  // only with a human confirming; headless runs get the pending command.
+  if (!dryRun) {
+    const id = await ensureIdentity({ projectDir, logger });
+    out.identity = id.declared ? id.identity : null;
+    if (id.pending) out.identityPending = id.pending;
+  }
+  return out;
+}

package/src/commands/hu.js

@@ -0,0 +1,210 @@
+/**
+ * `kj hu add|move|list` (AB-H, KJC-TSK-0658) — board writes for the brain.
+ * The v4 playbook orders "card first", but until now only the headless
+ * planner could create HUs. These commands operate on a per-project
+ * "brain-backlog" plan (created on first use) so any host agent can track
+ * work in the HU Board without the subprocess pipeline.
+ */
+import { addHu, updateHuStatus } from "../plan/plan-hu-ops.js";
+import { generatePlanId } from "../plan/plan-id.js";
+import { savePlan, listPlans, loadPlan } from "../plan/plan-store.js";
+import { detectHostAgent } from "../utils/agent-detect.js";
+
+// KJC-TSK-0661 (Jorge's friction): every HU records WHO created it — the
+// board must never show work nobody can trace. Host agent env → that agent;
+// a human typing in a terminal → "human"; anything else headless → "agent".
+export function creatorLabel() {
+  return detectHostAgent() || (process.stdin.isTTY ? "human" : "agent");
+}
+
+export const HU_STATUSES = ["pending", "running", "done", "failed", "skipped"];
+const BACKLOG_NAME = "brain-backlog";
+
+// KJC-TSK-0675 (issue #1288): agents that skip `kj hu list` created twins of
+// existing work — sometimes in a DIFFERENT plan. Titles are compared
+// normalized (case/punctuation-insensitive) across every live HU of every
+// plan: identical → refuse; mostly-overlapping tokens → warn with candidates.
+const normTitle = (t) => String(t || "").toLowerCase().replaceAll(/[^\p{L}\p{N}]+/gu, " ").trim();
+const titleTokens = (t) => new Set(normTitle(t).split(" ").filter((w) => w.length > 2));
+
+export function findTitleMatches(title, allHus) {
+  const norm = normTitle(title);
+  const toks = titleTokens(title);
+  const identical = [];
+  const similar = [];
+  for (const h of allHus) {
+    if (h.status === "skipped") continue; // discarded cards don't reserve titles
+    if (normTitle(h.title) === norm) { identical.push(h); continue; }
+    const other = titleTokens(h.title);
+    const shared = [...toks].filter((w) => other.has(w)).length;
+    const smaller = Math.min(toks.size, other.size);
+    if (smaller > 0 && shared / smaller >= 0.8) similar.push(h);
+  }
+  return { identical, similar };
+}
+
+async function backlogPlan(projectDir) {
+  const plans = await listPlans(projectDir);
+  const existing = plans.find((p) => p.alias === BACKLOG_NAME || p.name === BACKLOG_NAME);
+  if (existing) return loadPlan(projectDir, existing.planId);
+  const plan = {
+    version: 2, planId: generatePlanId(), name: BACKLOG_NAME,
+    task: "Host-agent tracked work (v4 environment)",
+    status: "ready", hus: [], createdAt: new Date().toISOString(),
+  };
+  const planId = await savePlan(projectDir, plan);
+  return loadPlan(projectDir, planId);
+}
+
+export async function huCommand({ config = null, action, args = [], flags = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const emit = (obj, human) => { console.log(flags.json ? JSON.stringify(obj) : human); return obj; };
+
+  // KJC-TSK-0684 (issue #1287): with an external board declared, kj never
+  // maintains a parallel HU Board — writes are refused with the pointer.
+  if (config?.state_backend === "external" && (action === "add" || action === "move")) {
+    const name = config?.board?.name || "an external board";
+    throw new Error(
+      `this project's board lives in ${name} (state_backend: external) — create and move cards there, `
+      + `through your agent's MCP/tools. kj does not mirror external boards.`
+    );
+  }
+
+  if (action === "list") {
+    const plans = await listPlans(projectDir);
+    const rows = [];
+    for (const meta of plans) {
+      const plan = await loadPlan(projectDir, meta.planId);
+      for (const h of plan.hus || []) {
+        rows.push({
+          id: h.id, short_id: h.short_id, title: h.title, status: h.status,
+          plan: plan.alias || plan.planId,
+          // KJC-TSK-0661: provenance — where a card came from is part of
+          // the card. Older HUs predate the stamp: shown as "?".
+          created_by: h.created_by || null, created_at: h.createdAt || null,
+        });
+      }
+    }
+    if (flags.json) { console.log(JSON.stringify(rows)); return rows; }
+    for (const r of rows) {
+      const origin = `${r.plan} · by ${r.created_by || "?"}${r.created_at ? ` · ${r.created_at.slice(0, 10)}` : ""}`;
+      console.log(`${(r.short_id || r.id).padEnd(28)} ${r.status.padEnd(8)} ${r.title}  [${origin}]`);
+    }
+    if (rows.length === 0) console.log("no HUs yet — create one with: kj hu add \"<story>\"");
+    else console.log("→ work one: ask your agent, or kj run --plan <plan> · discard one: kj hu move <id> skipped");
+    return rows;
+  }
+
+  if (action === "add") {
+    const title = args[0];
+    if (!title || !title.trim()) throw new Error("kj hu add requires a title: kj hu add \"<story>\"");
+    // Cross-plan title dedup (KJC-TSK-0675) — check BEFORE creating anything.
+    const allHus = [];
+    for (const meta of await listPlans(projectDir)) {
+      const p = await loadPlan(projectDir, meta.planId);
+      for (const h of p.hus || []) allHus.push({ ...h, plan: p.alias || p.name || p.planId });
+    }
+    const { identical, similar } = findTitleMatches(title, allHus);
+    if (identical.length > 0) {
+      const ref = identical[0];
+      throw new Error(
+        `An HU with this title already exists: ${ref.short_id || ref.id} (status: ${ref.status}, plan: ${ref.plan}). `
+        + `HUs are never duplicated — work that card, move it with: kj hu move ${ref.short_id || ref.id} <status>, `
+        + `or run kj hu list before adding.`
+      );
+    }
+    if (similar.length > 0) {
+      const plural = similar.length === 1 ? "" : "s";
+      const candidates = similar.map((h) => `  · ${h.short_id || h.id} (${h.status}, plan: ${h.plan}) "${h.title}"`).join("\n");
+      console.warn(`⚠ possible duplicate${plural} — check before working it:\n${candidates}`);
+    }
+    const plan = await backlogPlan(projectDir);
+    // KJC-TSK-0669 (absolute rule): cards are permanent. The delete-and-
+    // recreate "fix" an agent improvises loses history and duplicates ids —
+    // refuse it with the norm spelled out.
+    if (flags.id) {
+      const dup = (plan.hus || []).find((h) => h.short_id === flags.id);
+      if (dup) {
+        throw new Error(
+          `HU "${flags.id}" already exists (status: ${dup.status}). HUs are never deleted or recreated — `
+          + `update its state with: kj hu move ${flags.id} <pending|running|done|failed|skipped>, `
+          + `or discard it with: kj hu move ${flags.id} skipped`
+        );
+      }
+    }
+    // KJC-TSK-0678 (issue #1296): complete HUs in ONE call. --ac / --tests
+    // are repeatable AND accept multiline strings; --criteria stays as the
+    // legacy single-criterion alias.
+    const TASK_TYPES = ["sw", "infra", "doc", "add-tests", "refactor"];
+    if (flags.taskType && !TASK_TYPES.includes(flags.taskType)) {
+      throw new Error(`invalid --task-type "${flags.taskType}" — valid: ${TASK_TYPES.join(", ")}`);
+    }
+    const splitLines = (v) => (Array.isArray(v) ? v : v ? [v] : [])
+      .flatMap((s) => String(s).split("\n")).map((s) => s.trim()).filter(Boolean);
+    const hu = addHu(plan, {
+      title,
+      short_id: flags.id || null,
+      acceptance_criteria: [...splitLines(flags.ac), ...splitLines(flags.criteria)],
+      acceptance_tests: splitLines(flags.tests),
+      scope: flags.scope || null,
+      task_type: flags.taskType || undefined,
+    });
+    hu.created_by = creatorLabel();
+    await savePlan(projectDir, plan);
+    const missing = [];
+    if (hu.acceptance_criteria.length === 0) missing.push("acceptance criteria (--ac \"...\")");
+    if (hu.acceptance_tests.length === 0) missing.push("tests (--tests \"...\")");
+    if (missing.length > 0) {
+      console.warn(`⚠ incomplete spec — kj run's spec review will flag it. Missing: ${missing.join(", ")}`);
+    }
+    return emit({
+      id: hu.id, short_id: hu.short_id, status: hu.status, created_by: hu.created_by,
+      acceptance_criteria: hu.acceptance_criteria, acceptance_tests: hu.acceptance_tests,
+      scope: hu.scope, task_type: hu.task_type,
+    }, `✓ HU created: ${hu.short_id || hu.id} (pending, by ${hu.created_by}) — it shows up in \`kj board\``);
+  }
+
+  if (action === "move") {
+    const [ref, status] = args;
+    if (!ref || !status) throw new Error("usage: kj hu move <id> <status>");
+    if (!HU_STATUSES.includes(status)) {
+      throw new Error(`invalid status "${status}" — valid: ${HU_STATUSES.join(", ")}`);
+    }
+    // Exact canonical id wins outright (it IS the disambiguator); only then
+    // fall back to short_id matches — which can repeat between plans, so
+    // silently moving the first hit could move the wrong card.
+    const byId = [];
+    const byShort = [];
+    const running = [];
+    for (const meta of await listPlans(projectDir)) {
+      const plan = await loadPlan(projectDir, meta.planId);
+      for (const hu of plan.hus || []) {
+        if (hu.id === ref) byId.push({ plan, hu });
+        else if (hu.short_id === ref) byShort.push({ plan, hu });
+        if (hu.status === "running") running.push(hu);
+      }
+    }
+    const matches = byId.length > 0 ? byId : byShort;
+    if (matches.length === 0) throw new Error(`HU "${ref}" not found — see kj hu list`);
+    if (matches.length > 1) {
+      const ids = matches.map((m) => m.hu.id).join(", ");
+      throw new Error(`"${ref}" is ambiguous (${matches.length} matches: ${ids}) — use the full id`);
+    }
+    const { plan, hu } = matches[0];
+    // KJC-TSK-0688 (MG-C): the nudge fires AT the deviation — a second
+    // concurrent task belongs in its own lane, not in the shared tree.
+    const others = running.filter((r) => r.id !== hu.id);
+    if (status === "running" && hu.status !== "running" && others.length > 0) {
+      const slug = String(hu.short_id || hu.id).toLowerCase();
+      console.warn(
+        `⚠ ${others.map((r) => r.short_id || r.id).join(", ")} ${others.length === 1 ? "is" : "are"} already running — `
+        + `a second concurrent task should live in its own lane: kj worktree start ${slug}`
+      );
+    }
+    updateHuStatus(plan, hu.id, status);
+    await savePlan(projectDir, plan);
+    return emit({ id: hu.id, status }, `✓ ${hu.short_id || hu.id} → ${status}`);
+  }
+
+  throw new Error(`unknown action "${action}" — use: add | move | list`);
+}

package/src/commands/identity.js

@@ -0,0 +1,60 @@
+/**
+ * `kj identity show|set` (IDN-A, KJC-TSK-0762, epic KJC-PCS-0079).
+ *
+ *   show  — declared identity vs what is ACTIVE now; exit 2 on mismatch or
+ *           when nothing is declared (scriptable: the gate and hooks reuse it).
+ *   set   — capture the effective gh account + git email (or --gh/--email),
+ *           confirm on a TTY, write .karajan/identity.local.yml. Never invents:
+ *           no session and no flags → exit 1.
+ */
+
+import { readIdentity, writeIdentity } from "../identity/store.js";
+import { activeGhUser, effectiveGitEmail } from "../identity/detect.js";
+import { compareIdentity } from "../identity/compare.js";
+import { createWizard, isTTY } from "../utils/wizard.js";
+
+export async function identityCommand({ action = "show", config, flags = {}, deps = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const log = deps.log || console.log;
+  const tty = deps.isTTY || isTTY;
+  const detectOpts = { hostsPath: deps.hostsPath, gitFn: deps.gitFn };
+  const effective = {
+    gh_user: activeGhUser(detectOpts.hostsPath ? { hostsPath: detectOpts.hostsPath } : {}),
+    git_email: effectiveGitEmail(projectDir, detectOpts.gitFn ? { gitFn: detectOpts.gitFn } : {}),
+  };
+
+  if (action === "set") {
+    const candidate = { gh_user: flags.gh || effective.gh_user, git_email: flags.email || effective.git_email };
+    if (!candidate.gh_user || !candidate.git_email) {
+      log(`kj identity: cannot declare — gh account: ${candidate.gh_user ?? "no session"}, git email: ${candidate.git_email ?? "none"}. Log in / set git config, or pass --gh <user> --email <email>.`);
+      return 1;
+    }
+    if (tty() && !flags.yes) {
+      const wizard = (deps.makeWizard || createWizard)();
+      try {
+        const ok = await wizard.confirm(`Bind this clone to gh ${candidate.gh_user} / git ${candidate.git_email}?`, true);
+        if (!ok) { log("kj identity: not declared."); return 1; }
+      } finally { wizard.close(); }
+    } else if (!flags.gh || !flags.email) {
+      // Proven live on day one: the active gh session had been flipped by
+      // ANOTHER session, and --yes bound the clone to the wrong account.
+      // Binding without confirmation is allowed, but never silent.
+      log("kj identity: WARNING — binding the ACTIVE session as-is without confirmation (another session may have switched it); prefer --gh/--email explicitly and verify with `kj identity show`.");
+    }
+    writeIdentity(projectDir, candidate);
+    log(`kj identity: declared gh ${candidate.gh_user} / git ${candidate.git_email} → .karajan/identity.local.yml (ignored by git).`);
+    return 0;
+  }
+
+  const declared = readIdentity(projectDir);
+  const result = compareIdentity(declared, effective);
+  if (!declared) {
+    log("kj identity: no identity declared for this clone — run `kj identity set`.");
+    return 2;
+  }
+  const mark = (field) => (result.mismatches.some((m) => m.field === field) ? "DISTINTA" : "ACTIVA");
+  log(`gh_user    ${declared.gh_user}  [${mark("gh_user")}: ${effective.gh_user ?? "no session"}]`);
+  log(`git_email  ${declared.git_email}  [${mark("git_email")}: ${effective.git_email ?? "none"}]`);
+  for (const m of result.mismatches) log(`  → ${m.remedy}`);
+  return result.ok ? 0 : 2;
+}