karajan-code 2.7.3 → 2.8.0

package/src/commands/architect.js

@@ -2,6 +2,7 @@ import { createAgent } from "../agents/index.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { resolveRole } from "../config.js";
 import { buildArchitectPrompt, parseArchitectOutput } from "../prompts/architect.js";
+import { createCliProgressReporter } from "../utils/cli-progress.js";
 
 function formatLayers(layers, lines) {
   lines.push("### Layers");
@@ -67,8 +68,12 @@ export async function architectCommand({ task, config, logger, context, json })
 
     const agent = createAgent(architectRole.provider, config, logger);
     const prompt = await buildArchitectPrompt({ task, researchContext: context });
-    const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
-    const result = await agent.runTask({ prompt, onOutput, role: "architect" });
+    const progress = createCliProgressReporter({ role: "architect" });
+    let result;
+    try {
+      result = await agent.runTask({ prompt, onOutput: progress.onOutput, role: "architect" });
+      progress.finish(result.ok ? "done" : "failed");
+    } catch (err) { progress.finish("failed"); throw err; }
 
     if (!result.ok) {
       throw new Error(result.error || result.output || "Architect failed");
@@ -86,6 +91,28 @@ export async function architectCommand({ task, config, logger, context, json })
     } else {
       console.log(result.output);
     }
+
+    // Persist ADRs from the architect's tradeoffs[] (v2.7.5). One ADR
+    // per tradeoff in Nygard format under `~/.kj/plans/_loose/adrs/`.
+    // Coder/reviewer in subsequent runs can pull the active ADRs into
+    // their prompt for context — done in a follow-up PR.
+    if (parsed?.architecture && config?.projectDir) {
+      try {
+        const { persistAdrsFromArchitecture } = await import("../plan/adr-generator.js");
+        const { adrs, paths } = await persistAdrsFromArchitecture({
+          projectDir: config.projectDir,
+          planId: null,                  // standalone architect → "_loose" bucket
+          architecture: parsed.architecture,
+        });
+        if (paths.length > 0) {
+          console.log(`\n${adrs.length} ADR${adrs.length === 1 ? "" : "s"} written:`);
+          for (const p of paths) console.log(`  - ${p}`);
+        }
+      } catch (err) {
+        logger.warn(`ADR write skipped: ${err.message}`);
+      }
+    }
+
     logger.info("Architect completed.");
     return { ok: true };
   });

package/src/commands/audit.js

@@ -1,8 +1,11 @@
+import path from "node:path";
 import { createAgent } from "../agents/index.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { resolveRole } from "../config.js";
 import { buildAuditPrompt, parseAuditOutput, AUDIT_DIMENSIONS } from "../prompts/audit.js";
 import { withCliRunLog } from "../utils/cli-run-log.js";
+import { createCliProgressReporter } from "../utils/cli-progress.js";
+import { runAgentReadiness, formatAgentReadinessReport } from "../audit/agent-readiness.js";
 
 function formatFindings(findings) {
   const lines = [];
@@ -66,7 +69,24 @@ function formatAudit(parsed) {
   return lines.join("\n");
 }
 
-export async function auditCommand({ task, config, logger, dimensions, json }) {
+export async function auditCommand({ task, config, logger, dimensions, json, agentReadiness, path: pathArg }) {
+  // --agent-readiness is a STANDALONE, deterministic, LLM-free audit
+  // dimension. It scores any third-party repo for AI-agent readability
+  // (llms.txt presence, page token budgets, robots allowlist, etc.).
+  // Per addyosmani/agentic-seo. Issue #542.
+  if (agentReadiness) {
+    const rootDir = path.resolve(pathArg || config?.projectDir || process.cwd());
+    logger.info(`Auditing agent-readiness of ${rootDir}`);
+    const report = runAgentReadiness(rootDir);
+    if (json) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      console.log(formatAgentReadinessReport(report, rootDir));
+    }
+    // Exit code: 0 always (audit succeeded). The score is the signal.
+    return;
+  }
+
   return withCliRunLog("audit", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
     const auditRole = resolveRole(config, "audit");
     await assertAgentsAvailable([auditRole.provider]);
@@ -79,8 +99,12 @@ export async function auditCommand({ task, config, logger, dimensions, json }) {
       : null;
 
     const prompt = buildAuditPrompt({ task: task || "Analyze the full codebase", dimensions: dimList });
-    const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
-    const result = await agent.runTask({ prompt, onOutput, role: "audit" });
+    const progress = createCliProgressReporter({ role: "auditor" });
+    let result;
+    try {
+      result = await agent.runTask({ prompt, onOutput: progress.onOutput, role: "audit" });
+      progress.finish(result.ok ? "done" : "failed");
+    } catch (err) { progress.finish("failed"); throw err; }
 
     if (!result.ok) {
       throw new Error(result.error || result.output || "Audit failed");

package/src/commands/board.js

@@ -1,8 +1,10 @@
 import fs from "node:fs";
+import http from "node:http";
 import path from "node:path";
 import net from "node:net";
 import { spawn } from "node:child_process";
 import { getKarajanHome } from "../utils/paths.js";
+import { getPortOccupant } from "../utils/port-occupant.js";
 
 const BOARD_DIR = path.resolve(import.meta.dirname, "../../packages/hu-board");
 const PID_FILE = path.join(getKarajanHome(), "hu-board.pid");
@@ -25,6 +27,27 @@ function isProcessAlive(pid) {
   }
 }
 
+/**
+ * HTTP-probe the board's /api/dashboard. Returns true when it
+ * responds with 2xx within ~750ms. Used as a fallback when the PID
+ * file is missing/stale to detect "board is up, just untracked".
+ */
+async function isBoardReachable(port, timeoutMs = 750) {
+  return new Promise((resolve) => {
+    const req = http.request(
+      { host: '127.0.0.1', port, path: '/api/dashboard', method: 'GET', timeout: timeoutMs },
+      (res) => {
+        const ok = res.statusCode >= 200 && res.statusCode < 500;
+        res.resume();   // drain
+        resolve(ok);
+      }
+    );
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+    req.end();
+  });
+}
+
 /**
  * Check if a TCP port is available on localhost.
  * Returns true when we can successfully bind (port is free).
@@ -52,11 +75,45 @@ async function findAvailablePort(desiredPort, maxTries = 10) {
   return null;
 }
 
-export async function startBoard(desiredPort = 4000) {
+/**
+ * Build the board URL. When `projectSlug` is provided, the URL points at
+ * the per-project view (`/p/<slug>`) so the caller's project shows up
+ * pre-filtered instead of "All projects".
+ * @param {number} port
+ * @param {string|null} [projectSlug]
+ * @returns {string}
+ */
+function buildBoardUrl(port, projectSlug) {
+  const base = `http://localhost:${port}`;
+  return projectSlug ? `${base}/p/${projectSlug}` : base;
+}
+
+export async function startBoard(desiredPort = 4000, opts = {}) {
+  const { projectSlug = null } = opts;
   const existingPid = readPid();
   if (existingPid && isProcessAlive(existingPid)) {
     // Trust the saved PID — port info comes from the PID file if present
-    return { ok: true, alreadyRunning: true, pid: existingPid, url: `http://localhost:${desiredPort}` };
+    return {
+      ok: true,
+      alreadyRunning: true,
+      pid: existingPid,
+      url: buildBoardUrl(desiredPort, projectSlug),
+    };
+  }
+
+  // Belt-and-suspenders (v2.7.5 fix): even if the PID file is missing
+  // or stale, HTTP-probe the configured port before spawning. If
+  // /api/dashboard responds, a board is already there — reuse it. The
+  // pre-fix scenario: 🔁 self-restart didn't update the PID file
+  // (now fixed), so a `kj plan` afterwards saw a stale PID, spawned
+  // a duplicate board on port 4001, and confused the user.
+  if (await isBoardReachable(desiredPort)) {
+    return {
+      ok: true,
+      alreadyRunning: true,
+      pid: existingPid || null,
+      url: buildBoardUrl(desiredPort, projectSlug),
+    };
   }
 
   // Find a free port starting from desiredPort
@@ -79,34 +136,85 @@ export async function startBoard(desiredPort = 4000) {
   });
   // Swallow spawn errors so an HU Board failure never crashes the pipeline.
   child.on("error", () => { /* non-blocking — caller logs via tryAutoStartBoard catch */ });
-  child.unref();
-
   if (!child.pid) {
     throw new Error("Failed to spawn HU Board server");
   }
   fs.writeFileSync(PID_FILE, String(child.pid));
-  return { ok: true, alreadyRunning: false, pid: child.pid, url: `http://localhost:${port}`, port };
+  // Detach for real: `detached: true` only sets up the new session;
+  // without `unref()` the parent's event loop still holds a reference
+  // to the child handle and `kj board start` hangs at the prompt
+  // instead of returning. Pair this with stdio:"ignore" (already set)
+  // to ensure the parent isn't waiting on any of the child's pipes.
+  child.unref();
+  return { ok: true, alreadyRunning: false, pid: child.pid, url: buildBoardUrl(port, projectSlug), port };
 }
 
-export async function stopBoard() {
+export async function stopBoard(opts = {}) {
+  const { port = 4000 } = opts;
+  // Path 1: live PID in the file → straight SIGTERM. Pre-v2.7.5
+  // this was the only path; if the file was missing or stale (e.g.
+  // user ran a board built before the server-writes-own-PID fix in
+  // PR #508) we'd return "wasn't running" while the ghost server
+  // happily kept serving requests. The fallbacks below close that gap.
   const pid = readPid();
-  if (!pid || !isProcessAlive(pid)) {
-    try { fs.unlinkSync(PID_FILE); } catch { /* ignore */ }
-    return { ok: true, wasRunning: false };
+  if (pid && isProcessAlive(pid)) {
+    try { process.kill(pid, "SIGTERM"); } catch { /* race with dying process */ }
+    fs.rmSync(PID_FILE, { force: true });
+    return { ok: true, wasRunning: true, pid, via: "pidfile" };
   }
+  fs.rmSync(PID_FILE, { force: true });
 
-  try {
-    process.kill(pid, "SIGTERM");
-  } catch { /* process already dead */
-    // already dead
+  // Path 2: HTTP-ask the server to exit cleanly. Works for any
+  // running server that has the /api/board/shutdown endpoint —
+  // even when there's no PID file, no process tree to walk, etc.
+  const shutdownUrl = `/api/board/shutdown`;
+  const shutdownOk = await postBoardShutdown(port, shutdownUrl);
+  if (shutdownOk) {
+    return { ok: true, wasRunning: true, pid: null, via: "api" };
   }
-  try { fs.unlinkSync(PID_FILE); } catch { /* ignore */ }
-  return { ok: true, wasRunning: true, pid };
+
+  // Path 3: there's something on the port and the API didn't take it
+  // down. Find its PID via lsof / ss / netstat and SIGTERM it.
+  // Works against truly old servers that don't have the shutdown
+  // endpoint, with the cost of one extra subprocess call.
+  try {
+    const occupant = await getPortOccupant(port);
+    if (occupant?.pid) {
+      try { process.kill(occupant.pid, "SIGTERM"); } catch { /* gone */ }
+      return { ok: true, wasRunning: true, pid: occupant.pid, via: "port-occupant" };
+    }
+  } catch { /* lsof not installed etc — fall through */ }
+
+  return { ok: true, wasRunning: false };
+}
+
+/**
+ * Best-effort POST to the board's shutdown endpoint. Returns true
+ * when the server acks (and is presumably exiting); false on any
+ * error so the caller falls through to the next strategy.
+ */
+function postBoardShutdown(port, urlPath, timeoutMs = 750) {
+  return new Promise((resolve) => {
+    const req = http.request(
+      { host: '127.0.0.1', port, path: urlPath, method: 'POST', timeout: timeoutMs,
+        headers: { 'Content-Type': 'application/json', 'Content-Length': '2' } },
+      (res) => {
+        const ok = res.statusCode >= 200 && res.statusCode < 400;
+        res.resume();
+        resolve(ok);
+      }
+    );
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+    req.write('{}');
+    req.end();
+  });
 }
 
 export async function boardStatus(port = 4000) {
   const pid = readPid();
   const running = pid !== null && isProcessAlive(pid);
+
   return {
     ok: true,
     running,
@@ -115,27 +223,46 @@ export async function boardStatus(port = 4000) {
   };
 }
 
+// Strip ANSI escapes so we can measure the actual on-screen width of a
+// styled string. Used to size the rules around the banner content.
+const ANSI_RE = /\[[0-9;]*m/g;
+const visibleWidth = (s) => s.replace(ANSI_RE, "").length;
+
 /**
- * Render a highlighted cyan box with the HU Board URL + optional project name.
- * Centralizes the banner used by both the init-time auto-start (flow-runner.js)
- * and the post-planner auto-HU generation safety net so they stay in sync.
+ * Render a HU Board announcement framed by two horizontal rules of EQUAL
+ * length. Pre-v2.7.5 we used a fixed 50-char rounded box drawn with
+ * corners + verticals — fine when the URL fit, but a project slug
+ * pushed past the right wall and the box looked broken. The user's
+ * verdict: "looks worse than no box at all when it overflows".
+ *
+ * New rule: just an over-and-under rule sized to the longest visible
+ * content line. No left/right verticals, no fixed width. Always tidy.
  *
  * @param {Object} params
  * @param {string} params.url           - "http://localhost:4000"
  * @param {string} params.status        - "started" | "already running"
  * @param {string} [params.projectName] - optional project label
- * @returns {string} ANSI-escaped box ready for console.log
+ * @returns {string} ANSI-coloured banner ready for console.log
  */
 export function renderBoardBanner({ url, status, projectName }) {
-  const title = projectName ? `  Project: \u001b[1m${projectName}\u001b[0m` : null;
-  const lines = [
-    "",
-    "\u001b[36m\u256d\u2500 HU Board \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e",
-    `\u001b[36m\u2502\u001b[0m  \u001b[1m${status}\u001b[0m  \u001b[4m${url}\u001b[0m`,
-  ];
-  if (title) lines.push(`\u001b[36m\u2502\u001b[0m${title}`);
-  lines.push("\u001b[36m\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\u001b[0m", "");
-  return lines.join("\n");
+  const cyan = (s) => `${s}`;
+  const bold = (s) => `${s}`;
+  const underline = (s) => `${s}`;
+
+  const heading = `  ${bold("HU Board")} · ${status}  →  ${underline(url)}`;
+  const content = [heading];
+  if (projectName) content.push(`  Project: ${bold(projectName)}`);
+
+  // Width = widest visible content line + 2-cell padding. Cap at the
+  // terminal width so a silly-long URL doesn't draw a 200-char rule.
+  const termWidth = (process.stdout.columns && process.stdout.columns > 20)
+    ? process.stdout.columns
+    : 100;
+  const longest = Math.max(...content.map(visibleWidth));
+  const ruleWidth = Math.min(longest + 2, termWidth);
+  const rule = cyan("─".repeat(ruleWidth));
+
+  return ["", rule, ...content, rule, ""].join("\n");
 }
 
 export async function boardCommand({ action = "start", port = 4000, logger }) {
@@ -150,9 +277,11 @@ export async function boardCommand({ action = "start", port = 4000, logger }) {
       return result;
     }
     case "stop": {
-      const result = await stopBoard();
+      const result = await stopBoard({ port });
       if (result.wasRunning) {
-        logger.info(`HU Board stopped (PID ${result.pid})`);
+        const pidPart = result.pid ? ` (PID ${result.pid})` : "";
+        const viaPart = result.via && result.via !== "pidfile" ? ` [via ${result.via}]` : "";
+        logger.info(`HU Board stopped${pidPart}${viaPart}`);
       } else {
         logger.info("HU Board was not running");
       }
@@ -174,6 +303,7 @@ export async function boardCommand({ action = "start", port = 4000, logger }) {
         await startBoard(port);
       }
       const url = `http://localhost:${port}`;
+      // eslint-disable-next-line import-x/no-unresolved -- optional peer; the .catch handles its absence
       const { default: open } = await import("open").catch(() => ({ default: null }));
       if (open) {
         await open(url);

package/src/commands/clean.js

@@ -0,0 +1,83 @@
+/**
+ * `kj clean` — manual garbage collector.
+ *
+ * Shows or deletes accumulated state under `~/.kj/plans/` and
+ * `~/.karajan/` (sessions, HU story batches). Dry-run by default so
+ * the user can eyeball the plan before committing to it.
+ *
+ * Usage:
+ *   kj clean                         # dry-run, shows what would be removed
+ *   kj clean --yes                   # actually delete
+ *   kj clean --plan-days 60          # keep finalised plans for 60 days instead of 30
+ *   kj clean --draft-days 90         # keep drafts for 90 days instead of 60
+ *   kj clean --session-days 14       # keep finalised sessions for 14 days instead of 7
+ *   kj clean --hu-days 30            # keep HU batches for 30 days instead of 14
+ *
+ * The auto-GC that runs at the start of every `kj run` / `kj plan`
+ * uses the same retention defaults; tweaking them here lets the user
+ * sweep more or less aggressively without editing config.
+ */
+
+import { runManualGC, summarizeGC, nukeBoardDb } from "../utils/garbage-collector.js";
+
+/**
+ * @param {Object} opts
+ * @param {boolean} [opts.yes=false]           - when false, dry-run only
+ * @param {boolean} [opts.nuke=false]          - retention=0 for every bucket + wipe board DB
+ * @param {number}  [opts.planDays=30]
+ * @param {number}  [opts.draftDays=60]
+ * @param {number}  [opts.sessionDays=7]
+ * @param {number}  [opts.huDays=14]
+ * @param {Object}  [opts.logger]
+ */
+export async function cleanCommand(opts = {}) {
+  const dryRun = !opts.yes;
+  // --nuke forces retention=0 everywhere so drafts / sessions / plans of
+  // any age are swept. Combined with wipeBoardDb this is the "I want it
+  // all gone right now" button.
+  const retention = opts.nuke
+    ? { planRetentionDays: 0, draftRetentionDays: 0, sessionRetentionDays: 0, huRetentionDays: 0 }
+    : {
+      planRetentionDays: opts.planDays,
+      draftRetentionDays: opts.draftDays,
+      sessionRetentionDays: opts.sessionDays,
+      huRetentionDays: opts.huDays,
+    };
+  const result = await runManualGC({ ...retention, dryRun });
+
+  if (opts.nuke) {
+    const boardResult = await nukeBoardDb({ dryRun });
+    result.removed.push(...boardResult.removed);
+    result.bytesFreed += boardResult.bytesFreed;
+    result.errors.push(...boardResult.errors);
+  }
+
+  if (!result.removed.length) {
+    console.log("[clean] nothing to clean — ~/.kj/ and ~/.karajan/ are tidy.");
+    return { ok: true, removed: 0 };
+  }
+
+  const verb = dryRun ? "would remove" : "removed";
+  console.log(`[clean] ${verb} ${result.removed.length} item(s):`);
+  for (const r of result.removed) {
+    console.log(`  - ${r.kind.padEnd(10)} ${r.path}`);
+    console.log(`                 ${r.reason}`);
+  }
+
+  const kb = Math.round(result.bytesFreed / 1024);
+  if (kb) console.log(`[clean] ${verb} ${kb} KiB total`);
+
+  if (result.errors.length) {
+    console.log(`[clean] ${result.errors.length} error(s) (non-blocking):`);
+    for (const e of result.errors) console.log(`  - ${e.path}: ${e.error}`);
+  }
+
+  if (dryRun) {
+    console.log("");
+    console.log("[clean] DRY-RUN — no files touched. Re-run with --yes to actually delete.");
+  } else {
+    console.log(summarizeGC(result));
+  }
+
+  return { ok: true, removed: result.removed.length, bytesFreed: result.bytesFreed };
+}

package/src/commands/code.js

@@ -4,6 +4,7 @@ import { assertAgentsAvailable } from "../agents/availability.js";
 import { buildCoderPrompt } from "../prompts/coder.js";
 import { resolveRole } from "../config.js";
 import { withCliRunLog } from "../utils/cli-run-log.js";
+import { createCliProgressReporter } from "../utils/cli-progress.js";
 
 export async function codeCommand({ task, config, logger }) {
   return withCliRunLog("code", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
@@ -21,8 +22,12 @@ export async function codeCommand({ task, config, logger }) {
       }
     }
     const prompt = await buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology || "tdd" });
-    const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
-    const result = await coder.runTask({ prompt, onOutput, role: "coder" });
+    const progress = createCliProgressReporter({ role: "coder" });
+    let result;
+    try {
+      result = await coder.runTask({ prompt, onOutput: progress.onOutput, role: "coder" });
+      progress.finish(result.ok ? "done" : "failed");
+    } catch (err) { progress.finish("failed"); throw err; }
     if (!result.ok) {
       if (result.error) logger.error(result.error);
       throw new Error(result.error || result.output || `Coder failed (exit ${result.exitCode})`);

package/src/commands/discover.js

@@ -1,6 +1,7 @@
 import { createAgent } from "../agents/index.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { resolveRole } from "../config.js";
+import { createCliProgressReporter } from "../utils/cli-progress.js";
 import { buildDiscoverPrompt, parseDiscoverOutput } from "../prompts/discover.js";
 
 function formatGaps(gaps, lines) {
@@ -71,8 +72,12 @@ export async function discoverCommand({ task, config, logger, mode, json }) {
 
     const agent = createAgent(discoverRole.provider, config, logger);
     const prompt = buildDiscoverPrompt({ task, mode: mode || "gaps" });
-    const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
-    const result = await agent.runTask({ prompt, onOutput, role: "discover" });
+    const progress = createCliProgressReporter({ role: "discover" });
+    let result;
+    try {
+      result = await agent.runTask({ prompt, onOutput: progress.onOutput, role: "discover" });
+      progress.finish(result.ok ? "done" : "failed");
+    } catch (err) { progress.finish("failed"); throw err; }
 
     if (!result.ok) {
       throw new Error(result.error || result.output || "Discover failed");

package/src/commands/init.js

@@ -408,10 +408,10 @@ export async function initCommand({ logger, flags = {} }) {
   // Telemetry: anonymous install event (non-blocking)
   const { sendTelemetryEvent } = await import("../utils/telemetry.js");
   const { readFileSync } = await import("node:fs");
-  const { resolve, dirname } = await import("node:path");
   const { fileURLToPath } = await import("node:url");
   try {
-    const pkgPath = resolve(dirname(fileURLToPath(import.meta.url)), "../../package.json");
+    // TSK-0340: use the already-static `path` default import for resolve/dirname.
+    const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json");
     const version = JSON.parse(readFileSync(pkgPath, "utf8")).version;
     sendTelemetryEvent("install", { version }, config).catch(() => {});
   } catch { /* non-blocking */ }

package/src/commands/plan/_shared.js

@@ -0,0 +1,40 @@
+// ---- Formatting helpers shared across plan sub-commands ----
+
+export function formatPlan(plan) {
+  const lines = [];
+  if (plan.approach) lines.push("## Approach", plan.approach, "");
+  if (plan.steps?.length) {
+    lines.push("## Steps");
+    for (let i = 0; i < plan.steps.length; i++) {
+      const step = plan.steps[i];
+      const commit = step.commit ? ` → \`${step.commit}\`` : "";
+      lines.push(`${i + 1}. ${step.description}${commit}`);
+    }
+    lines.push("");
+  }
+  if (plan.risks?.length) {
+    lines.push("## Risks");
+    for (const risk of plan.risks) lines.push(`- ${risk}`);
+    lines.push("");
+  }
+  if (plan.outOfScope?.length) {
+    lines.push("## Out of scope");
+    for (const item of plan.outOfScope) lines.push(`- ${item}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+export function formatHuTable(hus) {
+  if (!hus?.length) return "  (no HUs)";
+  const lines = [];
+  const maxTitle = Math.min(50, Math.max(...hus.map(h => h.title?.length || 0)));
+  lines.push(`  ${"ID".padEnd(30)} ${"Title".padEnd(maxTitle)} ${"Type".padEnd(10)} ${"Status".padEnd(10)} Deps`);
+  lines.push(`  ${"─".repeat(30)} ${"─".repeat(maxTitle)} ${"─".repeat(10)} ${"─".repeat(10)} ${"─".repeat(15)}`);
+  for (const hu of hus) {
+    const title = (hu.title || "").slice(0, maxTitle).padEnd(maxTitle);
+    const deps = (hu.blocked_by || []).join(", ") || "—";
+    lines.push(`  ${hu.id.padEnd(30)} ${title} ${(hu.task_type || "sw").padEnd(10)} ${(hu.status || "?").padEnd(10)} ${deps}`);
+  }
+  return lines.join("\n");
+}

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

@@ -0,0 +1,21 @@
+/**
+ * kj plan add-hu <planId> --title "..." --type sw --deps hu_xxx
+ */
+export async function planAddHuCommand({ config, planId, title, type, deps, scope }) {
+  const { loadPlan, savePlan } = await import("../../plan/plan-store.js");
+  const { addHu } = 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 hu = addHu(plan, {
+    title: title || "New HU",
+    task_type: type || "sw",
+    scope: scope || null,
+    blocked_by: deps ? deps.split(",").map(d => d.trim()) : []
+  });
+
+  await savePlan(projectDir, plan);
+  console.log(`Added: ${hu.id} — ${hu.title}`);
+}

package/src/commands/plan/delete.js

@@ -0,0 +1,9 @@
+/**
+ * kj plan delete <planId>
+ */
+export async function planDeleteCommand({ config, planId }) {
+  const { deletePlan } = await import("../../plan/plan-store.js");
+  const projectDir = config.projectDir || process.cwd();
+  const ok = await deletePlan(projectDir, planId);
+  console.log(ok ? `Deleted: ${planId}` : `Not found: ${planId}`);
+}