karajan-code 3.6.0 → 3.7.1

package/README.md

@@ -23,7 +23,7 @@
 
 ---
 
-> **v3.6.0 released** — Advisory harden: `kj harden --report` shows what the kj standard would add to an existing repo (per artifact: missing / yours / kj-managed, plus the concrete improvements), and `kj harden --interactive` lets you adopt it piece by piece, default-safe. Plus scope control (`--only`/`--exclude`, demo/fixture dirs ignored), a rounder `kj init` first run (consistent English, glossed terms, clean close), and the `kj-trash` safety net now actually ships to npm installs. Full notes in [CHANGELOG.md](CHANGELOG.md).
+> **v3.7.1 released** — Patch: fixes a `kj init` crash when configuring the Plan B fallback, and makes pnpm installs safe — `kj doctor` now flags when pnpm skipped `better-sqlite3`'s native build and tells you exactly how to fix it (`pnpm approve-builds better-sqlite3`). The release gate checks pnpm too. Built on **v3.7.0 — Autonomous delivery**: `kj autorun <spec>` chains spec → plan → run every user story → outcome in one command, unattended, with an **Arbiter** that resolves agent conflicts by picking the least-bad call; autonomy is opt-in, interactive runs are unchanged. Full notes in [CHANGELOG.md](CHANGELOG.md).
 
 You describe what you want to build. Karajan orchestrates multiple AI agents to plan it, implement it, test it, review it with SonarQube, and iterate. No babysitting required.
 
@@ -71,6 +71,33 @@ Two technical facts worth keeping straight:
 
 Full write-up with mental mapping for Genkit / Mastra / LangChain / Vercel AI SDK developers: **[docs/COMPARISON.md](./docs/COMPARISON.md)**.
 
+## Loop engineering
+
+Prompt engineering got one good answer from one good prompt. Context engineering
+curated what the model saw. The 2026 frontier is **loop engineering**: you stop
+prompting the agent by hand and design the control system that prompts it, checks
+it, and decides what happens next — until the goal is met or it hands back to you.
+
+Karajan is a loop-engineering runtime, built around the loop before the term
+caught on:
+
+- **Maker / checker split** — a coder against independent reviewer / tester /
+  security roles, with Solomon judging disputes. The maker never grades its own work.
+- **Deterministic verification** — TDD, per-HU acceptance tests, SonarQube gates,
+  and deterministic guards. Checking is tests, not vibes.
+- **The autonomy ladder (L1 → L2 → L3)** — the `interactive | assisted |
+  autonomous` axis (v3.7.0). Report, then assisted fixes, then unattended
+  `kj autorun` — defaulting to `interactive`, so you opt in.
+- **A durable state spine** — sessions, the HU Board, journals, the RAG index and
+  `kj resume` keep the loop alive outside any one conversation.
+
+The honest caveat loop engineering insists on — *unattended loops make unattended
+mistakes* — is designed in: autonomous runs list their residual defects, every HU
+lands behind a PR, and `kj-trash` snapshots destructive operations.
+
+Full mapping of the loop-engineering building blocks onto Karajan:
+**[docs/loop-engineering.md](./docs/loop-engineering.md)**.
+
 ## Install
 
 **npm** (recommended):
@@ -83,6 +110,8 @@ npm install -g karajan-code
 brew install manufosela/tap/karajan-code
 ```
 
+> **Installing with pnpm?** pnpm blocks dependency build scripts by default, so `better-sqlite3`'s native addon won't compile on install and DB-backed commands (`board`, `rag`, cost tracking) will fail. After installing, run `pnpm approve-builds better-sqlite3` — or just use npm. `kj doctor` flags this if it happens.
+
 **Standalone binary** (no Node.js needed):
 ```bash
 # macOS (Apple Silicon)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "3.6.0",
+  "version": "3.7.1",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/packages/hu-board/src/db.js

@@ -361,6 +361,17 @@ export function getDb() {
   return db;
 }
 
+/**
+ * Lazily initialise the DB if it isn't open yet (KJC-BUG-0090). The cost
+ * writers run from `kj run`/`kj autorun` paths that may never start the board
+ * (which is what normally calls initDb), so cost writes failed with
+ * "Database not initialized". This makes those writers self-sufficient.
+ */
+export function ensureDb() {
+  if (!db) initDb();
+  return db;
+}
+
 /**
  * Inserts or updates a project record.
  * @param {{ id: string, name?: string, first_seen?: string, last_activity?: string, total_stories?: number }} project

package/scripts/verify-pack.mjs

@@ -50,6 +50,7 @@ function fail(msg, detail) {
 
 let tgzPath = null;
 let tmpDir = null;
+let pnpmTmp = null;
 try {
   console.log(`verify-pack: packing karajan-code@${expectedVersion}…`);
   // --json gives us the exact filename without parsing human output.
@@ -114,8 +115,48 @@ try {
   }
   console.log("verify-pack: kj-trash ships + boots ✓");
 
+  // 5. pnpm install smoke (KJC-TSK-0580). pnpm's layout differs from npm's
+  // (a symlinked virtual store), so it can break resolution of the bundled
+  // @karajan/core the way npm packaging breakage did before (KJC-BUG-0082/0086).
+  // Verify a pnpm install resolves the JS tree and `kj --version` boots — every
+  // release catches a pnpm packaging regression. (pnpm also blocks
+  // better-sqlite3's native build by default, so DB-backed commands need
+  // `pnpm approve-builds`; that's surfaced as a doctor warning, KJC-BUG-0092 —
+  // not a gate failure, since it's inherent to pnpm.) Auto-skips without pnpm.
+  const hasPnpm = spawnSync("pnpm", ["--version"], { encoding: "utf8", env: childEnv }).status === 0;
+  if (!hasPnpm) {
+    console.log("verify-pack: pnpm not installed — skipping pnpm smoke (npm path covered above) ⚠");
+  } else {
+    pnpmTmp = fs.mkdtempSync(path.join(os.tmpdir(), "kj-verify-pnpm-"));
+    fs.writeFileSync(
+      path.join(pnpmTmp, "package.json"),
+      JSON.stringify({ name: "kj-verify-pnpm", private: true }),
+    );
+    console.log(`verify-pack: installing the tarball with pnpm into ${pnpmTmp}…`);
+    // pnpm exits non-zero on ERR_PNPM_IGNORED_BUILDS (it skips native build
+    // scripts by default) — expected here, so don't treat the exit as failure.
+    spawnSync("pnpm", ["add", tgzPath, "--store-dir", path.join(pnpmTmp, ".store")], {
+      encoding: "utf8",
+      env: childEnv,
+      cwd: pnpmTmp,
+    });
+    const pnpmBin = path.join(pnpmTmp, "node_modules", ".bin", "kj");
+    if (!fs.existsSync(pnpmBin)) fail(`kj binary missing after pnpm install: ${pnpmBin}`);
+    let pnpmVersion;
+    try {
+      pnpmVersion = run(pnpmBin, ["--version"], { cwd: pnpmTmp }).trim();
+    } catch (err) {
+      fail("`kj --version` crashed under a pnpm install (packaging regression)", err.stderr || err.message);
+    }
+    if (!pnpmVersion.includes(expectedVersion)) {
+      fail(`kj --version under pnpm returned "${pnpmVersion}", expected ${expectedVersion}`);
+    }
+    console.log(`verify-pack: pnpm install + kj --version → ${pnpmVersion} ✓ (DB build needs \`pnpm approve-builds\`)`);
+  }
+
   console.log(`\n✓ verify-pack: karajan-code@${expectedVersion} installs clean and runs.`);
 } finally {
   if (tgzPath && fs.existsSync(tgzPath)) fs.rmSync(tgzPath, { force: true });
   if (tmpDir && fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+  if (pnpmTmp && fs.existsSync(pnpmTmp)) fs.rmSync(pnpmTmp, { recursive: true, force: true });
 }

package/src/autonomy/arbiter-role.js

@@ -0,0 +1,71 @@
+/**
+ * ArbiterRole — the autonomous decision authority that resolves agent conflicts
+ * by picking the least-bad verdict (KJC-TSK-0573, épica KJC-PCS-0062).
+ *
+ * Extends AgentRole (so it inherits Brain recovery / standby) following the
+ * TriageRole pattern: a cheap decisor model emits a closed-set verdict, and any
+ * parse failure degrades to BLOCK_AND_CONTINUE — the pipeline never crashes and
+ * never blocks on the Arbiter.
+ */
+
+import { AgentRole } from "../roles/agent-role.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+import { buildArbiterPrompt, VERDICTS } from "../prompts/arbiter.js";
+
+const CONSERVATIVE = "BLOCK_AND_CONTINUE";
+const VERDICT_SET = new Set(VERDICTS);
+
+function clampConfidence(value) {
+  const n = Number(value);
+  return Number.isFinite(n) ? Math.min(1, Math.max(0, n)) : 0;
+}
+
+export class ArbiterRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "arbiter" });
+  }
+
+  async buildPrompt(input) {
+    return { prompt: buildArbiterPrompt(input) };
+  }
+
+  parseOutput(raw) {
+    return extractFirstJson(raw);
+  }
+
+  buildSuccessResult(parsed, provider) {
+    const verdict = VERDICT_SET.has(parsed?.verdict) ? parsed.verdict : CONSERVATIVE;
+    return {
+      verdict,
+      confidence: clampConfidence(parsed?.confidence),
+      rationale: String(parsed?.rationale || "").trim() || "no rationale",
+      defect: parsed?.defect ? String(parsed.defect).trim() : null,
+      directive: parsed?.directive ? String(parsed.directive).trim() : null,
+      provider,
+    };
+  }
+
+  buildSummary(parsed) {
+    return `Arbiter: ${VERDICT_SET.has(parsed?.verdict) ? parsed.verdict : CONSERVATIVE}`;
+  }
+
+  // Never crash on garbage: degrade to the conservative verdict so the pipeline
+  // moves on instead of aborting (ok:true keeps the run alive).
+  handleParseNull(agentResult, provider) {
+    return this.degraded(agentResult, provider, "unstructured output");
+  }
+
+  handleParseError(err, agentResult, provider) {
+    return this.degraded(agentResult, provider, err?.message || "parse error");
+  }
+
+  degraded(agentResult, provider, why) {
+    this.logger?.warn?.(`[arbiter] ${why} → ${CONSERVATIVE} (conservative)`);
+    return {
+      ok: true,
+      result: { verdict: CONSERVATIVE, confidence: 0, rationale: `degraded: ${why}`, defect: null, directive: null, provider },
+      summary: `Arbiter: ${CONSERVATIVE} (degraded)`,
+      usage: agentResult.usage,
+    };
+  }
+}

package/src/autonomy/arbiter.js

@@ -0,0 +1,22 @@
+/**
+ * createArbiter — adapt ArbiterRole to the function the decision-resolver
+ * injects (KJC-TSK-0573). The resolver calls `arbiter(req)` and expects
+ * `{ choice, rationale, ... }`; here `choice` is the Arbiter's verdict, which
+ * the resolver then validates against the caller's options (AUTO-A).
+ */
+
+import { ArbiterRole } from "./arbiter-role.js";
+
+export function createArbiter({ config = {}, logger = console, createAgentFn = null } = {}) {
+  return async function arbiter(req) {
+    const role = new ArbiterRole({ config, logger, createAgentFn });
+    const { result } = await role.execute(req);
+    return {
+      choice: result.verdict,
+      rationale: result.rationale,
+      confidence: result.confidence,
+      defect: result.defect,
+      directive: result.directive,
+    };
+  };
+}

package/src/autonomy/decider.js

@@ -0,0 +1,18 @@
+/**
+ * buildDecider — wire the active autonomy level to a ready decision resolver
+ * (KJC-TSK-0572, design in docs/specs/autonomous-delivery.md §5).
+ *
+ * interactive → the human `ask`; assisted/autonomous → the Arbiter (AUTO-B).
+ * Consumers (spec-review, reviewer, checkpoint…) call `resolve(...)` instead of
+ * prompting directly, so the autonomy level decides who answers in one place.
+ */
+
+import { createDecisionResolver } from "./decision-resolver.js";
+import { resolveAutonomy } from "./policy.js";
+import { createArbiter } from "./arbiter.js";
+
+export function buildDecider({ config = {}, flags = {}, ask = null, env = process.env, logger = console, createAgentFn = null } = {}) {
+  const autonomy = resolveAutonomy({ config, flags, env });
+  const arbiter = autonomy === "interactive" ? null : createArbiter({ config, logger, createAgentFn });
+  return { autonomy, resolve: createDecisionResolver({ autonomy, ask, arbiter, logger }) };
+}

package/src/autonomy/decision-resolver.js

@@ -0,0 +1,58 @@
+/**
+ * autonomy/decision-resolver — the single choke point for every pipeline
+ * question (KJC-TSK-0572, design in docs/specs/autonomous-delivery.md §5).
+ *
+ * Today the "ask a human" logic is scattered (spec-review, checkpoint,
+ * reviewer, board-bridge). This unifies it: callers ask `resolveDecision`
+ * instead of prompting directly, and the autonomy level decides who answers —
+ * the human (`ask`) or the Arbiter (`arbiter`, injected by AUTO-B).
+ *
+ * INVARIANT: in `autonomous` mode the resolver NEVER returns a null choice and
+ * NEVER blocks — if the Arbiter can't decide it degrades to the option flagged
+ * `conservative` (or the first option). Decisions are always traced.
+ */
+
+import { RISK, usesArbiter } from "./policy.js";
+
+/** Pick the safe fallback: the option flagged conservative, else the first. */
+function conservativeOf(options) {
+  return options.find((o) => o.conservative) ?? options[0] ?? null;
+}
+
+function decision(choice, rationale, source) {
+  return { choice: choice ?? null, rationale, source };
+}
+
+/**
+ * Build a resolver bound to an autonomy level and its two answer sources.
+ *
+ * @param {object} opts
+ * @param {string} opts.autonomy - interactive | assisted | autonomous
+ * @param {(question: string, context?: object) => Promise<string|null>} [opts.ask] - human prompt
+ * @param {(input: object) => Promise<{choice: string, rationale?: string}>} [opts.arbiter] - AUTO-B
+ * @returns {(req: object) => Promise<{choice, rationale, source}>}
+ */
+export function createDecisionResolver({ autonomy = "interactive", ask = null, arbiter = null, logger = console } = {}) {
+  return async function resolveDecision({ question, options = [], context = null, risk = RISK.LOW } = {}) {
+    const fallback = conservativeOf(options);
+
+    // Human path: interactive, or assisted with a high-risk decision.
+    if (!usesArbiter(autonomy, risk)) {
+      const answer = ask ? await ask(question, context) : null;
+      return decision(answer, "human", "human");
+    }
+
+    // Arbiter path: must always yield a valid choice, never block.
+    if (!arbiter) return decision(fallback?.value, "no arbiter available → conservative", "fallback");
+    let verdict;
+    try {
+      verdict = await arbiter({ question, options, context, risk });
+    } catch (err) {
+      logger.warn?.(`decision-resolver: arbiter failed (${err.message}) → conservative`);
+      return decision(fallback?.value, "arbiter error → conservative", "fallback");
+    }
+    const valid = verdict && options.some((o) => o.value === verdict.choice);
+    if (!valid) return decision(fallback?.value, "arbiter gave no valid choice → conservative", "fallback");
+    return decision(verdict.choice, verdict.rationale ?? "arbiter", "arbiter");
+  };
+}

package/src/autonomy/outcome-report.js

@@ -0,0 +1,55 @@
+/**
+ * outcome-report — the auditable "meets the ask, with known defects" report
+ * for an autonomous run (KJC-TSK-0577, design in docs/specs/autonomous-delivery.md §10).
+ *
+ * Pure: builds a serializable outcome from the run results + Arbiter decisions,
+ * and renders it as lines (or the structure is emitted as --json). The point is
+ * that an imperfect-but-delivered result is explicit and auditable: which HUs
+ * met the ask, what the Arbiter decided, and what debt remains.
+ */
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.planRef]
+ * @param {boolean} opts.delivered - the run met the minimum ask
+ * @param {Array<{id, title?, met: boolean, note?}>} [opts.hus]
+ * @param {Array<{verdict, rationale, hu?, defect?}>} [opts.decisions] - Arbiter log
+ */
+export function buildOutcome({ planRef = null, delivered = false, hus = [], decisions = [] } = {}) {
+  const met = hus.filter((h) => h.met).length;
+  const residualDefects = [
+    ...hus.filter((h) => !h.met).map((h) => ({ hu: h.id, detail: h.note || "acceptance criteria not fully met" })),
+    ...decisions.filter((d) => d.defect).map((d) => ({ hu: d.hu ?? null, detail: d.defect })),
+  ];
+  return {
+    verdict: delivered ? "DELIVERED" : "INCOMPLETE",
+    planRef,
+    hus: { total: hus.length, met, unmet: hus.length - met },
+    decisions,
+    residualDefects,
+  };
+}
+
+/** Render an outcome (from buildOutcome) as human-readable lines. */
+export function formatOutcomeReport(outcome) {
+  const lines = [
+    `kj autorun — outcome: ${outcome.verdict}`,
+    `  plan: ${outcome.planRef ?? "?"}`,
+    `  HUs:  ${outcome.hus.met}/${outcome.hus.total} met the ask`,
+  ];
+  if (outcome.decisions?.length) {
+    lines.push("  Decisions (Arbiter — least-bad calls):");
+    for (const d of outcome.decisions) {
+      lines.push(`    • ${d.verdict}${d.hu ? ` [${d.hu}]` : ""} — ${d.rationale}`);
+    }
+  }
+  if (outcome.residualDefects?.length) {
+    lines.push("  Known defects (delivered with debt):");
+    for (const def of outcome.residualDefects) {
+      lines.push(`    • ${def.hu ? `[${def.hu}] ` : ""}${def.detail}`);
+    }
+  } else {
+    lines.push("  No residual defects recorded.");
+  }
+  return lines;
+}

package/src/autonomy/policy.js

@@ -0,0 +1,41 @@
+/**
+ * autonomy/policy — autonomy levels for Autonomous Delivery (KJC-TSK-0572,
+ * épica KJC-PCS-0062, design in docs/specs/autonomous-delivery.md §4).
+ *
+ * One configurable axis decides who resolves a pipeline question:
+ *   interactive — the human (current behaviour, default)
+ *   assisted    — the human only for high-risk decisions, the Arbiter otherwise
+ *   autonomous  — always the Arbiter; never asks a human, never blocks
+ *
+ * Precedence (most specific wins): CLI flags → env → config → default.
+ */
+
+export const AUTONOMY_LEVELS = Object.freeze(["interactive", "assisted", "autonomous"]);
+
+/** Risk of a decision — drives whether `assisted` escalates to the human. */
+export const RISK = Object.freeze({ LOW: "low", HIGH: "high" });
+
+const DEFAULT_LEVEL = "interactive";
+
+/**
+ * Resolve the active autonomy level. `--autonomous` is sugar for the
+ * `autonomous` level; `--autonomy <level>` sets it explicitly. An unknown
+ * value degrades to the safe default rather than throwing.
+ */
+export function resolveAutonomy({ config = {}, flags = {}, env = {} } = {}) {
+  const raw =
+    flags.autonomy ??
+    (flags.autonomous ? "autonomous" : null) ??
+    env.KJ_AUTONOMY ??
+    config.autonomy ??
+    DEFAULT_LEVEL;
+  const level = String(raw).toLowerCase();
+  return AUTONOMY_LEVELS.includes(level) ? level : DEFAULT_LEVEL;
+}
+
+/** True when the level should route decisions to the Arbiter for `risk`. */
+export function usesArbiter(level, risk = RISK.LOW) {
+  if (level === "autonomous") return true;
+  if (level === "assisted") return risk !== RISK.HIGH;
+  return false; // interactive
+}

package/src/autonomy/stage-ask.js

@@ -0,0 +1,30 @@
+/**
+ * createAutonomyAskQuestion — make the stages' question function non-blocking in
+ * autonomous mode (KJC-TSK-0576, AUTO-E, design in docs/specs/autonomous-delivery.md §9).
+ *
+ * In `autonomous` no stage asks a human or routes to the HU Board: the wrapper
+ * answers in-process with the least-bad "keep going" choice, so the run never
+ * pauses or aborts mid-loop. interactive and assisted keep the human prompts
+ * (baseAsk) unchanged.
+ *
+ * The answer is chosen per stage so the EXISTING branches proceed (verified
+ * against the stage code — no stage logic is touched):
+ *   - architect clarification: null → the stage continues best-effort (a truthy
+ *     answer would force a wasteful architect re-run).
+ *   - everything else (Solomon escalation, checkpoint, …): "continue" → parsed
+ *     as free-text guidance → the stage continues instead of pausing/aborting.
+ */
+export function createAutonomyAskQuestion({ baseAsk = null, autonomy = "interactive", logger = console } = {}) {
+  if (autonomy !== "autonomous") return baseAsk;
+  const auto = async (_question, context = {}) => {
+    const stage = context?.stage ?? null;
+    logger?.info?.(`[autonomy] ${stage ? `${stage}: ` : ""}auto-continue (no human in the loop)`);
+    return stage === "architect" ? null : "continue";
+  };
+  auto.interactive = false;
+  // Marker so the orchestrator can tell an autonomous (unattended) run from an
+  // interactive one even though both carry a truthy askQuestion — the wall-clock
+  // backstop relies on it (KJC-TSK-0575, AUTO-D).
+  auto.unattended = true;
+  return auto;
+}

package/src/checks/native-build.js

@@ -0,0 +1,64 @@
+/**
+ * Native build availability check (KJC-BUG-0092).
+ *
+ * better-sqlite3 ships a native addon compiled in a postinstall step. pnpm
+ * blocks dependency build scripts by default (ERR_PNPM_IGNORED_BUILDS), so a
+ * `pnpm add -g karajan-code` leaves the addon uncompiled: `kj --version` still
+ * works (it never opens a DB) but any DB-backed command (board, rag, cost
+ * tracking) crashes with "Cannot find module 'better-sqlite3'". This surfaces a
+ * WARN in `kj doctor` with the exact remedy instead of a cryptic runtime crash.
+ */
+
+import { STRATEGY } from "./types.js";
+
+/** pnpm lays packages out under a `.pnpm` virtual store and symlinks them in. */
+function isPnpmInstall() {
+  return (
+    import.meta.url.includes("/.pnpm/") ||
+    (process.env.npm_config_user_agent || "").includes("pnpm")
+  );
+}
+
+/** Force the native binding to load by opening an in-memory database. */
+async function defaultLoadDb() {
+  const Database = (await import("better-sqlite3")).default;
+  new Database(":memory:").close();
+}
+
+export function createNativeBuildCheck({ loadDb = defaultLoadDb, isPnpm = isPnpmInstall } = {}) {
+  return {
+    name: "native-build",
+    label: "native modules (better-sqlite3)",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      try {
+        await loadDb();
+        return {
+          ok: true,
+          severity: "info",
+          detail: "better-sqlite3 native addon loads — DB-backed commands available",
+        };
+      } catch (err) {
+        const firstLine = String(err?.message || err).split("\n")[0];
+        if (isPnpm()) {
+          return {
+            ok: false,
+            severity: "warn",
+            detail: "better-sqlite3 native build was skipped — pnpm blocks dependency build scripts by default",
+            fix: "Approve the build then reinstall: `pnpm approve-builds better-sqlite3` — or install with npm: `npm i -g karajan-code`",
+          };
+        }
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `better-sqlite3 failed to load: ${firstLine}`,
+          fix: "Reinstall to rebuild native modules: `npm i -g karajan-code`",
+        };
+      }
+    },
+  };
+}
+
+export function getNativeBuildChecks() {
+  return [createNativeBuildCheck()];
+}

package/src/cli/register-pipeline.js

@@ -114,6 +114,8 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--skip-role <role...>", "Force one or more roles OFF regardless of triage (e.g. --skip-role tester security)")
     .option("--force-role <role...>", "Force one or more roles ON regardless of triage")
     .option("--skip-spec-review", "Bypass the spec-reviewer pre-pipeline audit")
+    .option("--autonomy <level>", "Autonomy level: interactive | assisted | autonomous (default: interactive)")
+    .option("--autonomous", "Shortcut for --autonomy autonomous: the Arbiter resolves every gate, no human prompts")
     .option("--no-rag-update", "Skip the pre-run RAG drift check (KJC-TSK-0455). Same as config.rag.autoUpdate.onRun=false.")
     .option("--dry-run", "Show what would be executed without running anything")
     .option("--json", "Output JSON only (no styled display)")
@@ -143,6 +145,25 @@ export function registerPipeline(program, { pkgVersion }) {
       });
     });
 
+  program
+    .command("autorun")
+    .description("Unattended delivery: spec → plan → run all HUs → outcome (defaults to --autonomous)")
+    .argument("[task]", "Spec/task description (or use --task-file)")
+    .option("--task-file <path>", "Read the spec from a file (e.g. spec.md)")
+    .option("--autonomy <level>", "interactive | assisted | autonomous (default: autonomous)")
+    .option("--autonomous", "Shortcut for --autonomy autonomous")
+    .option("--skip-spec-review", "Bypass the spec-reviewer pre-pipeline audit")
+    .action(async (task, flags) => {
+      const code = await withConfig(pkgVersion, "autorun", flags, async ({ config, logger }) => {
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const { autorunCommand } = await import("../commands/autorun.js");
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        const res = await autorunCommand({ task: resolvedTask, config, logger, flags });
+        return res?.ok ? 0 : 1;
+      });
+      if (Number.isInteger(code)) process.exit(code);
+    });
+
   program
     .command("code")
     .description("Run only coder")

package/src/commands/autorun.js

@@ -0,0 +1,49 @@
+/**
+ * `kj autorun <spec>` — the unattended delivery chain (KJC-TSK-0574, épica
+ * KJC-PCS-0062, design in docs/specs/autonomous-delivery.md §7).
+ *
+ * One command: spec → plan → run all HUs → outcome. It reuses `kj plan` and
+ * `kj run --plan` rather than reimplementing them, and defaults to the
+ * `autonomous` level so the Arbiter resolves every gate (no human in the loop).
+ * The rich outcome report lands in AUTO-F; here we chain + propagate exit code.
+ */
+
+import { planGenerateCommand } from "./plan/generate.js";
+import { runCommandHandler } from "./run.js";
+import { buildOutcome, formatOutcomeReport } from "../autonomy/outcome-report.js";
+
+export async function autorunCommand({
+  task,
+  config,
+  logger = console,
+  flags = {},
+  planFn = planGenerateCommand,
+  runFn = runCommandHandler,
+} = {}) {
+  // autorun implies unattended: default to autonomous unless the user picked a
+  // level explicitly (so `kj autorun --autonomy assisted` still works).
+  const autoFlags = flags.autonomy || flags.autonomous ? flags : { ...flags, autonomous: true };
+
+  logger.info?.("kj autorun — planning…");
+  const plan = await planFn({ task, config, logger, flags: autoFlags });
+  if (!plan?.ok || !plan.planId) {
+    logger.error?.(`kj autorun: planning failed${plan?.reason ? ` (${plan.reason})` : ""}.`);
+    return { ok: false, stage: "plan", reason: plan?.reason ?? "plan-failed" };
+  }
+
+  logger.info?.(`kj autorun — running plan ${plan.ref ?? plan.planId} (${plan.huCount ?? "?"} HUs)…`);
+  const run = await runFn({ config, logger, flags: { ...autoFlags, plan: plan.planId } });
+
+  const ok = run?.ok === true;
+  // AUTO-F: emit the auditable outcome — delivered/incomplete, HUs that met the
+  // ask, Arbiter decisions and residual defects (enriched as the run surfaces
+  // them; baseline today is delivered + plan ref).
+  const outcome = buildOutcome({
+    planRef: plan.ref ?? plan.planId,
+    delivered: ok,
+    hus: run?.hus ?? [],
+    decisions: run?.decisions ?? [],
+  });
+  for (const line of formatOutcomeReport(outcome)) logger.info?.(line);
+  return { ok, stage: ok ? "done" : "run", planId: plan.planId, ref: plan.ref ?? plan.planId, outcome };
+}

package/src/commands/doctor.js

@@ -26,6 +26,7 @@ import { getSqueezrChecks } from "../checks/squeezr.js";
 import { getAiTrashChecks } from "../checks/ai-trash.js";
 import { getQmdChecks } from "../checks/qmd.js";
 import { getNodeChecks } from "../checks/node.js";
+import { getNativeBuildChecks } from "../checks/native-build.js";
 import { getPortChecks } from "../checks/ports.js";
 import { getTokenChecks } from "../checks/tokens.js";
 import { getMcpHealthChecks } from "../checks/mcp-health.js";
@@ -54,6 +55,7 @@ function buildChecks(config, { projectOnly = false } = {}) {
   return [
     ...getSystemChecks(),
     ...getNodeChecks(),
+    ...getNativeBuildChecks(),
     ...getHardwareChecks(),
     ...getDirSetupChecks(),
     ...getConfigFileChecks(),

package/src/commands/plan/generate.js

@@ -457,7 +457,7 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
 
   if (json) {
     console.log(JSON.stringify(plan, null, 2));
-    return { ok: true };
+    return { ok: true, planId, ref: plan.alias || planId, huCount: plan.hus.length };
   }
 
   if (parsed?.approach) {
@@ -524,5 +524,6 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
       console.log(`\nVisualize: kj board start (http://localhost:${config?.hu_board?.port ?? 4000})`);
     }
   }
-  return { ok: true };
+  // KJC-TSK-0574: surface planId/ref so `kj autorun` can chain plan → run.
+  return { ok: true, planId, ref, huCount: plan.hus.length };
 }

package/src/commands/run.js

@@ -17,6 +17,8 @@ import { maybeAutoUpdate } from "../rag/auto-update.js";
 // keep working. KJC-BUG-0081 round 2 split the body into utils/ because
 // resume.js also needs the same contract.
 import { createCliAskQuestion } from "../utils/cli-ask-question.js";
+import { buildDecider } from "../autonomy/decider.js";
+import { createAutonomyAskQuestion } from "../autonomy/stage-ask.js";
 export { createCliAskQuestion };
 
 export async function runCommandHandler({ task, config, logger, flags }) {
@@ -129,12 +131,16 @@ export async function runCommandHandler({ task, config, logger, flags }) {
 
     const askQuestion = createCliAskQuestion({ flags });
 
+    // Autonomy (KJC-PCS-0062): wire the level to a resolver. In autonomous mode
+    // every gate is decided by the Arbiter instead of the human; interactive
+    // keeps the human prompts. The decider is threaded into the gates below.
+    const { autonomy, resolve: decide } = buildDecider({ config, flags, ask: askQuestion, logger });
+
     // Spec-reviewer pre-pipeline audit (KJC-PCS-0048). Runs BEFORE
-    // anything else — surfaces ambiguity / missing scope / missing AC
-    // and lets the user bail out cheap, before any tokens burn.
-    // Bypass with --skip-spec-review. Static import — the role runs
-    // on every kj invocation (modulo bypass), no lazy-load benefit.
-    const reviewResult = await runSpecReview({ spec: task, config, logger, askQuestion, flags });
+    // anything else — surfaces ambiguity / missing scope / missing AC.
+    // In autonomous mode the Arbiter decides (never aborts); interactive
+    // lets the user bail. Bypass with --skip-spec-review.
+    const reviewResult = await runSpecReview({ spec: task, config, logger, askQuestion, flags, resolve: decide, autonomy });
     if (!reviewResult.proceed) {
       logger.info("Aborted by user after spec review.");
       cleanupRegistry();
@@ -145,9 +151,14 @@ export async function runCommandHandler({ task, config, logger, flags }) {
     // user actually approved.
     const effectiveTask = reviewResult.refined && reviewResult.finalSpec ? reviewResult.finalSpec : task;
 
+    // AUTO-E: in autonomous mode the stages never ask a human or block on the
+    // board — they auto-continue with the least-bad choice. interactive/assisted
+    // keep the human prompts.
+    const stageAsk = createAutonomyAskQuestion({ baseAsk: askQuestion, autonomy, logger });
+
     let result;
     try {
-      result = await runFlow({ task: effectiveTask, config, logger, flags, emitter, askQuestion, pgTaskId: pgCardId || null, pgProject: pgProject || null });
+      result = await runFlow({ task: effectiveTask, config, logger, flags, emitter, askQuestion: stageAsk, pgTaskId: pgCardId || null, pgProject: pgProject || null });
     } finally {
       // KJC-TSK-0396: limpia el registro pase lo que pase (éxito,
       // throw, o paused). Los handlers de SIGINT/SIGTERM/exit son
@@ -163,6 +174,12 @@ export async function runCommandHandler({ task, config, logger, flags }) {
       // failed), tell the user the exact command to resume it.
       printResumeHint(result);
     }
-    return { ok: !result?.paused && result?.approved !== false };
+    // Surface per-HU results so `kj autorun` can build a real outcome report
+    // (KJC-BUG-0090: it showed "0/0 met the ask" because only { ok } came back).
+    // The plan run returns them as `huResults` (run-hu-batch finalResult).
+    const hus = Array.isArray(result?.huResults)
+      ? result.huResults.map((r) => ({ id: r.huId, met: r.approved === true }))
+      : [];
+    return { ok: !result?.paused && result?.approved !== false, hus };
   });
 }

package/src/orchestrator/drivers/pre-loop-phases/inject-loaded-plan.js

@@ -316,7 +316,8 @@ function wirePlanCallbacks({ session, loadedPlan, projectDir, syncResultsToPlan,
       await savePlanToDisk(projectDir, loadedPlan);
       if (outcome && Number.isFinite(outcome.cost_usd)) {
         try {
-          const { setStoryCost, setStoryCachedTokens } = await import("../../../../packages/hu-board/src/db.js");
+          const { ensureDb, setStoryCost, setStoryCachedTokens } = await import("../../../../packages/hu-board/src/db.js");
+          ensureDb(); // KJC-BUG-0090: autorun/run may not have started the board
           setStoryCost(huId, outcome.cost_usd);
           // Φ0-G (KJC-TSK-0525): cached/in tokens travel in the same
           // outcome blob as cost. Write them together so the board

package/src/orchestrator/flow-control.js

@@ -128,7 +128,13 @@ export function parseCheckpointAnswer({ trimmedAnswer, checkpointDisabled, confi
 }
 
 export async function checkSessionTimeout({ askQuestion, elapsedMinutes, config, session, emitter, eventBase, i, budgetSummary }) {
-  if (askQuestion || elapsedMinutes <= config.session.max_total_minutes) return;
+  // Enforce the wall-clock when no human is watching the checkpoint: either a
+  // non-interactive run (no askQuestion) OR an autonomous one — where askQuestion
+  // is the auto-continue wrapper (truthy) but nobody is there to stop a runaway.
+  // Interactive runs keep skipping it (the human decides at the checkpoint).
+  // KJC-TSK-0575 (AUTO-D): without this, autonomous runs had NO wall-clock cap.
+  const unattended = !askQuestion || askQuestion.unattended === true;
+  if (!unattended || elapsedMinutes <= config.session.max_total_minutes) return;
 
   await markSessionStatus(session, "failed");
   emitProgress(

package/src/prompts/arbiter.js

@@ -0,0 +1,38 @@
+/**
+ * Arbiter prompt (KJC-TSK-0573, design in docs/specs/autonomous-delivery.md §6).
+ *
+ * The Arbiter is Karajan's autonomous decision authority: given a conflict, it
+ * picks the LEAST-BAD option from a closed set and moves forward — no human.
+ */
+
+/** The closed set of conflict-resolution verdicts. BLOCK_AND_CONTINUE is safe. */
+export const VERDICTS = Object.freeze([
+  "ACCEPT_WITH_DEFECT",
+  "RETRY_DIFFERENT_APPROACH",
+  "DESCOPE_HU",
+  "BLOCK_AND_CONTINUE",
+  "PROCEED",
+]);
+
+export function buildArbiterPrompt({ question, options = [], context = null } = {}) {
+  const allowed = options.length ? options.map((o) => o.value) : VERDICTS;
+  return [
+    "You are the Arbiter — Karajan's autonomous decision authority. There is no human to ask.",
+    "Resolve the conflict below by choosing the LEAST-BAD option and moving forward.",
+    "",
+    "Ground-truth order (what wins when signals disagree):",
+    "  1. Acceptance tests passing — beats any reviewer opinion.",
+    "  2. Must-fix issues (security, correctness, data) — beat style.",
+    "  3. Nice-to-have (style, optional refactors) — never block; record as a defect if dropped.",
+    "Goal: maximize 'the ask is met', minimize irreversible risk. Imperfect-but-delivered beats blocked.",
+    "",
+    `Conflict: ${question}`,
+    context ? `Context: ${JSON.stringify(context)}` : "",
+    "",
+    `Choose exactly one verdict from: ${allowed.join(", ")}`,
+    "Respond with ONLY this JSON (no prose):",
+    '{"verdict":"<one of the allowed>","confidence":0.0,"rationale":"why it is the least-bad option","defect":"residual debt if any, else null","directive":"instruction to the coder when RETRY_DIFFERENT_APPROACH, else null"}',
+  ]
+    .filter(Boolean)
+    .join("\n");
+}

package/src/spec-review/run-spec-review.js

@@ -7,10 +7,30 @@
 import { SpecReviewerRole } from "../roles/spec-reviewer-role.js";
 import { printFindings } from "../utils/display/spec-findings.js";
 import { runRefinePass } from "./refine-loop.js";
+import { RISK } from "../autonomy/policy.js";
 
 const MAX_REFINE_ITERATIONS = 5;
 
-export async function runSpecReview({ spec, config, logger, askQuestion, flags = {} }) {
+/**
+ * Decide the gate action (`continue` | `refine`) autonomously: the Arbiter
+ * picks PROCEED (proceed with the best reading) or RETRY_DIFFERENT_APPROACH
+ * (auto-refine). It is never offered `cancel`, so an autonomous run never
+ * aborts on spec ambiguity (KJC-TSK-0572, closes gap G1).
+ */
+async function decideGateAutonomously(resolve, { severity, findings }) {
+  const { choice } = await resolve({
+    question: `Spec has ${findings.length} finding(s) at severity ${severity}: proceed with the best reading, or auto-refine?`,
+    options: [
+      { value: "PROCEED", label: "proceed with the best reading", conservative: true },
+      { value: "RETRY_DIFFERENT_APPROACH", label: "auto-refine the spec" },
+    ],
+    context: { severity, findingCount: findings.length, categories: [...new Set(findings.map((f) => f.category))] },
+    risk: severity === "fail" ? RISK.HIGH : RISK.LOW,
+  });
+  return choice === "RETRY_DIFFERENT_APPROACH" ? "refine" : "continue";
+}
+
+export async function runSpecReview({ spec, config, logger, askQuestion, flags = {}, resolve = null, autonomy = "interactive" }) {
   // VITEST guard — pre-existing test suites (e.g. tests/commands/command-run.test.js)
   // mock `runFlow` + `assertAgentsAvailable` but predate this role and have
   // no need to exercise it. Auto-skip in vitest unless the test passes
@@ -40,16 +60,24 @@ export async function runSpecReview({ spec, config, logger, askQuestion, flags =
       return { proceed: true, severity: "ok", findings: [], finalSpec: currentSpec, refined: iter > 0 };
     }
     printFindings(findings, severity);
-    if (!askQuestion) return { proceed: true, severity, findings, finalSpec: currentSpec };
 
-    const answer = await askQuestion(
-      `Spec review: ${findings.length} finding${findings.length === 1 ? "" : "s"} at severity ${severity}. [c]ontinue / [r]efine / [x]cancel? (default: continue)`,
-      { detail: { severity, findingCount: findings.length, categories: [...new Set(findings.map((f) => f.category))], iteration: iter + 1 } },
-    );
-    if (answer === null) return { proceed: false, cancelled: true, severity, findings };
-    const n = String(answer).trim().toLowerCase();
-    if (n.startsWith("x") || n === "cancel") return { proceed: false, cancelled: true, severity, findings };
-    if (n.startsWith("r") || n === "refine") {
+    // Autonomous/assisted: the Arbiter decides (continue|refine), never cancels.
+    // Interactive (no resolver): the human answers [c]/[r]/[x] as before.
+    let action;
+    if (resolve && autonomy !== "interactive") {
+      action = await decideGateAutonomously(resolve, { severity, findings });
+    } else {
+      if (!askQuestion) return { proceed: true, severity, findings, finalSpec: currentSpec };
+      const answer = await askQuestion(
+        `Spec review: ${findings.length} finding${findings.length === 1 ? "" : "s"} at severity ${severity}. [c]ontinue / [r]efine / [x]cancel? (default: continue)`,
+        { detail: { severity, findingCount: findings.length, categories: [...new Set(findings.map((f) => f.category))], iteration: iter + 1 } },
+      );
+      if (answer === null) return { proceed: false, cancelled: true, severity, findings };
+      const n = String(answer).trim().toLowerCase();
+      action = n.startsWith("x") || n === "cancel" ? "cancel" : n.startsWith("r") || n === "refine" ? "refine" : "continue";
+    }
+    if (action === "cancel") return { proceed: false, cancelled: true, severity, findings };
+    if (action === "refine") {
       const refine = await runRefinePass({
         spec: currentSpec, findings, role,
         projectDir: config?.projectDir, taskFile: flags.taskFile, logger,

package/src/utils/wizard.js

@@ -1,7 +1,7 @@
 import readline from "node:readline";
 
-export function createWizard(input = process.stdin, output = process.stdout) {
-  const rl = readline.createInterface({ input, output, terminal: false });
+export function createWizard(inputStream = process.stdin, output = process.stdout) {
+  const rl = readline.createInterface({ input: inputStream, output, terminal: false });
 
   function ask(question) {
     return new Promise((resolve) => {
@@ -16,6 +16,12 @@ export function createWizard(input = process.stdin, output = process.stdout) {
     return /^y(es)?$/i.test(answer);
   }
 
+  async function input(question, defaultValue = "") {
+    const hint = defaultValue !== "" ? ` [${defaultValue}]` : "";
+    const answer = await ask(`${question}${hint} `);
+    return answer === "" ? defaultValue : answer;
+  }
+
   async function select(question, options) {
     output.write(`${question}\n`);
     for (let i = 0; i < options.length; i++) {
@@ -33,7 +39,7 @@ export function createWizard(input = process.stdin, output = process.stdout) {
     rl.close();
   }
 
-  return { ask, confirm, select, close };
+  return { ask, confirm, input, select, close };
 }
 
 export function isTTY() {