@karajan-family/code 4.21.0

package/src/audit/semgrep-findings.js

@@ -0,0 +1,129 @@
+/**
+ * Semgrep SAST collector for `kj audit` (KJC-TSK-0366).
+ *
+ * Wraps `semgrep --config auto --json` and feeds structured static-
+ * analysis findings into the audit prompt. Equivalent to the SAST half
+ * of `snyk code` but free for OSS, no account, runs locally. Semgrep
+ * has 2000+ built-in rules across JS/TS/Python/Go/etc. covering OWASP
+ * Top 10, taint analysis, hardcoded secrets, regex misuse and language-
+ * specific anti-patterns.
+ *
+ * Same best-effort pattern as sonar-findings.js and osv-findings.js:
+ *   - Missing binary or timeout returns {available: false, reason}.
+ *   - 120s timeout (semgrep can be slow on large repos with --config auto).
+ *   - Severity-grouped (ERROR / WARNING / INFO) and capped at
+ *     MAX_SEMGREP_FINDINGS_IN_PROMPT (50) total entries with overflow
+ *     markers.
+ *   - The LLM is told these are deterministic and asked to fold them
+ *     into the `security` dimension using the rule ID as the rule field.
+ */
+
+import { runGoverned, jobsCap } from "../utils/tool-governor.js";
+
+const SCAN_TIMEOUT_MS = 120_000;
+const SEVERITY_ORDER = ["ERROR", "WARNING", "INFO"];
+
+/**
+ * Run semgrep on the project and return a structured result.
+ *
+ * @param {string} projectDir - absolute path to the project root
+ * @param {object} [logger]
+ * @returns {Promise<{available: boolean, reason?: string, total?: number, findings?: object[]}>}
+ */
+export async function collectSemgrepFindings(projectDir, logger = null) {
+  // KJC-BUG-0122: a full `--config auto` scan must NEVER fire from the unit
+  // suite — on machines with the complete stack installed (the product
+  // default since v4.1.2) parallel vitest workers each launched a real
+  // whole-repo scan: load average 50, orphaned semgrep-core processes.
+  // E2E tests that genuinely want the real scan opt in explicitly.
+  if (process.env.VITEST && process.env.KJ_ALLOW_REAL_SCANS !== "1") {
+    return { available: false, reason: "real scans disabled under the test runner (set KJ_ALLOW_REAL_SCANS=1 to opt in)" };
+  }
+  let stdout;
+  try {
+    // KJC-TSK-0668: governed run — machine-wide single-flight, --jobs capped
+    // at half the CPUs (semgrep grabs 14 by default), nice +10, and a timeout
+    // that kills the whole process tree (no more orphaned semgrep-core).
+    const { stdout: out } = await runGoverned(
+      "semgrep",
+      ["--config", "auto", "--json", "--quiet", `--jobs=${jobsCap()}`, `--timeout=${Math.floor(SCAN_TIMEOUT_MS / 1000)}`, projectDir || "."],
+      { cwd: projectDir, timeout: SCAN_TIMEOUT_MS + 5000, maxBuffer: 32 * 1024 * 1024 }
+    );
+    stdout = out;
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      if (logger?.warn) logger.warn("semgrep not found in PATH — install via 'pipx install semgrep' or 'brew install semgrep'");
+      return { available: false, reason: "semgrep not installed" };
+    }
+    if (err.killed) {
+      if (logger?.warn) logger.warn(`semgrep timed out after ${SCAN_TIMEOUT_MS}ms`);
+      return { available: false, reason: `semgrep timed out after ${SCAN_TIMEOUT_MS}ms` };
+    }
+    // semgrep exits 1 when it finds blocking rules (ERROR severity), but
+    // still emits a valid JSON report on stdout. Rescue that case.
+    if (typeof err.stdout === "string" && err.stdout.trim().length > 0) {
+      stdout = err.stdout;
+    } else {
+      if (logger?.warn) logger.warn(`semgrep failed: ${err.message}`);
+      return { available: false, reason: `semgrep failed: ${err.message}` };
+    }
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch (err) {
+    if (logger?.warn) logger.warn(`semgrep output not parseable: ${err.message}`);
+    return { available: false, reason: "semgrep output not parseable as JSON" };
+  }
+
+  return { available: true, ...parseSemgrepOutput(parsed, projectDir) };
+}
+
+function relativizeSemgrepPath(p, projectDir) {
+  return p.startsWith(projectDir + "/") ? p.slice(projectDir.length + 1) : p;
+}
+
+/**
+ * Convert semgrep's JSON shape into the flat findings list the prompt
+ * builder consumes. Semgrep emits results[] with rule id, severity,
+ * path, start/end line, message, fix hints.
+ *
+ * @param {object} raw - parsed semgrep --json output
+ * @param {string} [projectDir] - used to make paths repo-relative
+ * @returns {{total: number, findings: object[]}}
+ */
+export function parseSemgrepOutput(raw, projectDir = "") {
+  const results = Array.isArray(raw?.results) ? raw.results : [];
+  const findings = [];
+  for (const r of results) {
+    const file = r.path && projectDir
+      ? relativizeSemgrepPath(r.path, projectDir)
+      : r.path || "";
+    findings.push({
+      rule: r.check_id || "(unknown)",
+      severity: String(r.extra?.severity || "INFO").toUpperCase(),
+      file,
+      line: r.start?.line ?? 0,
+      endLine: r.end?.line ?? 0,
+      message: r.extra?.message || "",
+      fix: r.extra?.fix || r.extra?.fix_regex || null,
+      cwe: r.extra?.metadata?.cwe || null,
+      owasp: r.extra?.metadata?.owasp || null,
+    });
+  }
+  return { total: findings.length, findings };
+}
+
+/**
+ * Group findings by severity in canonical order (ERROR → WARNING → INFO).
+ */
+export function groupFindingsBySeverity(findings) {
+  const groups = Object.fromEntries(SEVERITY_ORDER.map(s => [s, []]));
+  for (const f of findings || []) {
+    const sev = (f.severity || "INFO").toUpperCase();
+    if (groups[sev]) groups[sev].push(f);
+    else groups.INFO.push(f);
+  }
+  return groups;
+}

package/src/audit/sonar-findings.js

@@ -0,0 +1,93 @@
+/**
+ * Sonar findings collector for `kj audit` (KJC-TSK-0361).
+ *
+ * The audit pipeline already pays for SonarQube to exist (kj run + the
+ * SonarStage drive a full scan and gate the pipeline on its result). When
+ * the user runs `kj audit`, we don't want to pay for *another* full scan
+ * (~1-3 min) — we want to read whatever Sonar already knows. This module
+ * does exactly that: ping the configured Sonar host, and if it's
+ * reachable, fetch the current open-issue list + quality-gate status via
+ * the existing sonar/api.js helpers. Both results are best-effort: a
+ * sonar-down host or a never-scanned project quietly returns
+ * `{available: false, reason: "..."}` and the audit continues without
+ * the section.
+ *
+ * Why this matters: the LLM auditor was previously asked to find issues
+ * by reading source code, but Sonar already produces them with rule IDs
+ * (squid:S1234), severity, and line precision. Feeding those in lets the
+ * LLM cross-reference its own findings (high-confidence overlap) and
+ * focus its tokens on patterns Sonar can't see (architecture, naming,
+ * API design).
+ */
+
+import { isSonarReachable } from "../sonar/manager.js";
+import { getOpenIssues, getQualityGateStatus } from "../sonar/api.js";
+import { canResolveSonarProjectKey } from "../sonar/project-key.js";
+
+/**
+ * Collect deterministic Sonar findings for the audit prompt.
+ *
+ * @param {object} config - resolved Karajan config (must have config.sonarqube.host)
+ * @param {object} [logger] - optional logger for warn-level traces
+ * @returns {Promise<{available: boolean, reason?: string, issues?: object[], total?: number, qualityGate?: object}>}
+ */
+export async function collectSonarFindings(config, logger = null) {
+  const sonarConfig = config?.sonarqube || {};
+  const host = sonarConfig.host || "http://localhost:9000";
+  const healthcheckSeconds = sonarConfig.timeouts?.healthcheckSeconds ?? 5;
+
+  // Ping first — avoids surfacing a 30-second timeout into audit runtime
+  // when Docker is simply down or the user opted out of Sonar.
+  const reachable = await isSonarReachable(host, healthcheckSeconds).catch(() => false);
+  if (!reachable) {
+    if (logger?.warn) logger.warn(`sonar audit input skipped: host ${host} not reachable`);
+    return { available: false, reason: `sonar host ${host} not reachable` };
+  }
+
+  // No git remote and no explicit project_key → silent skip. This is the
+  // typical `kj run` in a fresh /tmp/... folder. Reporting it as a
+  // warning treats it like an error (which it isn't — sonar simply
+  // doesn't apply to a remoteless repo).
+  if (!(await canResolveSonarProjectKey(config))) {
+    return {
+      available: false,
+      reason: "not applicable: no git remote and no sonarqube.project_key configured",
+    };
+  }
+
+  let issuesResult;
+  try {
+    issuesResult = await getOpenIssues(config);
+  } catch (err) {
+    if (logger?.warn) logger.warn(`sonar audit input: getOpenIssues failed: ${err?.message || err}`);
+    return { available: false, reason: `getOpenIssues failed: ${err?.message || err}` };
+  }
+
+  let qualityGate = null;
+  try {
+    const qg = await getQualityGateStatus(config);
+    if (qg?.ok) qualityGate = { status: qg.status, conditions: qg.conditions };
+  } catch { /* gate is optional context */ }
+
+  return {
+    available: true,
+    issues: issuesResult.issues || [],
+    total: issuesResult.total || 0,
+    qualityGate,
+  };
+}
+
+/**
+ * Group Sonar issues by severity, preserving Sonar's canonical ordering.
+ * Used by the prompt builder to render the findings section.
+ */
+export function groupIssuesBySeverity(issues) {
+  const order = ["BLOCKER", "CRITICAL", "MAJOR", "MINOR", "INFO"];
+  const groups = Object.fromEntries(order.map(s => [s, []]));
+  for (const issue of issues || []) {
+    const sev = issue.severity || "INFO";
+    if (groups[sev]) groups[sev].push(issue);
+    else groups.INFO.push(issue);
+  }
+  return groups;
+}

package/src/audit/webperf-input.js

@@ -0,0 +1,133 @@
+/**
+ * WebPerf input collector for `kj audit` (KJC-TSK-0360).
+ *
+ * Two modes:
+ *   - "static-hints": no live measurement available, but the project is
+ *     frontend so the LLM should look for frontend-perf patterns in the
+ *     source (bundle bloat, render-blocking, image opt, lazy loading).
+ *     This is the common path because `kj audit` runs against a code
+ *     tree, not a live preview server.
+ *   - "cwv-result": a Core Web Vitals measurement was supplied. Three
+ *     possible sources, in priority order:
+ *       1. `config.webperf.lastResult` — inline {metrics, thresholds, ...}
+ *          (rare; legacy / programmatic injection)
+ *       2. `config.webperf.lastResultPath` — file path written by
+ *          `kj webperf` (KJC-TSK-0149). This is the standard wiring.
+ *       3. `~/.karajan/webperf/<projectSlug>/last.json` — fallback
+ *          discovery when the user ran `kj webperf` but didn't patch
+ *          their kj.config.yml.
+ *     evaluateCwv from src/webperf/cwv-gate.js produces a structured
+ *     verdict the prompt renders verbatim.
+ *
+ * The "live measurement" path is intentionally NOT wired here: the
+ * audit's LLM sub-agent is forbidden from MCP tool use (SUBAGENT_PREAMBLE
+ * in src/prompts/audit.js), and spawning Chrome / launching a preview
+ * server during a read-only audit is wrong layer. `kj webperf` does
+ * the measurement; `kj audit` consumes the persisted result.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { evaluateCwv, CWV_THRESHOLDS } from "../webperf/cwv-gate.js";
+import { getWebperfDir } from "../utils/paths.js";
+
+// Delegated to src/utils/paths.js (KJC-TSK-0420) — respects
+// KARAJAN_HOME / KJ_HOME (with deprecation warning) / VITEST tmp.
+function webperfHome() { return getWebperfDir(); }
+
+function projectSlug(projectDir) {
+  return path.basename(projectDir || process.cwd()).replaceAll(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+/**
+ * Try the three discovery paths in priority order. Returns the parsed
+ * scan object (shape produced by src/webperf/scanner.js) or null.
+ */
+function loadPersistedScan(webperfConfig, projectDir) {
+  // 1. Inline result on the config (back-compat)
+  if (webperfConfig.lastResult && typeof webperfConfig.lastResult === "object" && webperfConfig.lastResult.metrics) {
+    return webperfConfig.lastResult;
+  }
+  // 2. Explicit file path on the config
+  const candidates = [];
+  if (webperfConfig.lastResultPath) candidates.push(webperfConfig.lastResultPath);
+  // 3. Fallback: ~/.karajan/webperf/<slug>/last.json
+  if (projectDir) {
+    candidates.push(path.join(webperfHome(), projectSlug(projectDir), "last.json"));
+  }
+  for (const candidate of candidates) {
+    try {
+      const raw = fs.readFileSync(candidate, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object" && parsed.metrics) return parsed;
+    } catch { /* missing file or unparseable — try next */ }
+  }
+  return null;
+}
+
+/**
+ * Decide what (if anything) to feed the audit prompt about web perf.
+ *
+ * @param {object|null} stack - detectProjectStack output (null when unknown)
+ * @param {object} [config] - resolved Karajan config (config.webperf may carry a stale CWV result)
+ * @returns {{available: boolean, mode?: 'static-hints'|'cwv-result', cwv?: object, reason?: string}}
+ */
+export function collectWebPerfInput(stack, config = {}) {
+  const webperfConfig = config?.webperf || {};
+  const projectDir = config?.projectDir;
+  const persisted = loadPersistedScan(webperfConfig, projectDir);
+
+  if (persisted) {
+    const verdict = persisted.cwv || evaluateCwv(persisted.metrics, persisted.thresholds || webperfConfig.thresholds);
+    return {
+      available: true,
+      mode: "cwv-result",
+      url: persisted.url || webperfConfig.url || null,
+      capturedAt: persisted.capturedAt || null,
+      cwv: verdict,
+      thresholds: persisted.thresholds || webperfConfig.thresholds || CWV_THRESHOLDS,
+    };
+  }
+
+  // No live measurement → static hints only when the project actually has
+  // a frontend layer to audit. Backend-only projects get nothing.
+  const isFrontendish = !stack || stack.isFrontend === true || stack.isFullstack === true;
+  if (!isFrontendish) {
+    return { available: false, reason: "project is backend-only — no frontend-perf hints to give" };
+  }
+
+  return { available: true, mode: "static-hints" };
+}
+
+/**
+ * Render a CWV verdict (from collectWebPerfInput's cwv-result mode) as
+ * concise prompt-friendly markdown. Kept independent from the prompt
+ * builder so it stays unit-testable in isolation.
+ */
+export function formatCwvVerdict(input) {
+  if (!input || input.mode !== "cwv-result" || !input.cwv) return null;
+  const { cwv, url, capturedAt } = input;
+  const lines = [];
+  if (url) lines.push(`- Target URL: ${url}`);
+  if (capturedAt) lines.push(`- Captured: ${capturedAt}`);
+  lines.push(`- Verdict: ${cwv.pass ? "PASS" : "FAIL"}`);
+  if (Object.keys(cwv.scores || {}).length) {
+    lines.push("- Scores:");
+    for (const [metric, score] of Object.entries(cwv.scores)) {
+      lines.push(`  - ${metric.toUpperCase()}: ${score.value} (${score.rating})`);
+    }
+  }
+  if (cwv.blocking?.length) {
+    lines.push("- Blocking metrics (above poor threshold):");
+    for (const b of cwv.blocking) {
+      lines.push(`  - ${b.metric.toUpperCase()} ${b.value} > ${b.threshold}`);
+    }
+  }
+  if (cwv.advisory?.length) {
+    lines.push("- Advisory metrics (between good and poor):");
+    for (const a of cwv.advisory) {
+      lines.push(`  - ${a.metric.toUpperCase()} ${a.value} > good=${a.threshold}`);
+    }
+  }
+  return lines.join("\n");
+}

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