karajan-code 3.7.1 → 3.8.0

package/README.md

@@ -235,8 +235,22 @@ kj board start                                         # Start web dashboard (po
 kj board open                                          # Start + open in browser
 kj board status                                        # Check if running
 kj board stop                                          # Stop the board
+
+# Quality guardrails
+kj harden                                              # Install hooks, config, CI, guidelines
+kj check                                               # Verify the harness (drift gate)
+kj mutate                                              # Mutation-test the diff (do tests catch mutants?)
 ```
 
+**Mutation testing** (`kj mutate`) closes the gap coverage leaves: it flips the
+logic of the code you just changed and reruns your suite, so a line that ran but
+isn't really tested shows up as a **survivor**. It is diff-scoped by default
+(vs `HEAD~1`), drives the right runner per stack (Stryker/mutmut/Infection/…
+with no silent fallback), and folds into a workflow three ways — on demand,
+as an opt-in reviewer signal (`KJ_REVIEW_MUTATION=1`), or as a non-blocking
+nightly CI job (`kj harden --mutation`). See
+[GETTING-STARTED](docs/GETTING-STARTED.md#mutation-testing--kj-mutate).
+
 ### 2. MCP: inside your AI agent
 
 This is the primary use case. Karajan runs as an MCP server inside Claude Code, Codex, or Gemini. You ask your AI agent to do something, and it delegates the heavy lifting to Karajan's pipeline.

package/package.json

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

package/src/agents/availability.js

@@ -29,3 +29,24 @@ export async function assertAgentsAvailable(agentNames = []) {
   }
   throw new Error(lines.join("\n"));
 }
+
+/**
+ * Non-throwing counterpart to assertAgentsAvailable: probe each agent CLI in
+ * parallel and return the subset whose `--version` succeeds. Used by the
+ * audit fallback (KJC-BUG-0094) to skip uninstalled providers instead of
+ * aborting the whole command when any one is missing.
+ * @param {string[]} agentNames
+ * @returns {Promise<string[]>}
+ */
+export async function filterAvailableAgents(agentNames = []) {
+  const unique = [...new Set(agentNames.filter(Boolean))];
+  const probes = await Promise.all(
+    unique.map(async (name) => {
+      const meta = getAgentMeta(name);
+      if (!meta?.bin) return null;
+      const res = await runCommand(resolveBin(meta.bin), ["--version"]);
+      return res.exitCode === 0 ? name : null;
+    })
+  );
+  return probes.filter(Boolean);
+}

package/src/audit/audit-fallback.js

@@ -0,0 +1,66 @@
+// Resilient provider/model fallback for the `kj audit` CLI (KJC-BUG-0094).
+// The CLI audit calls AuditRole.executeWithDeterministic directly, bypassing
+// the orchestrator's recovery paths, so a dead configured model (e.g. an
+// inherited "claude-fable-5") killed the command. The LLM phase now tries:
+// configured provider+model → same provider default model → remaining known
+// providers. First success wins; the deterministic context is reused.
+import { resolveRole } from "../config.js";
+import { AuditRole } from "../roles/audit-role.js";
+
+const KNOWN_PROVIDERS = ["claude", "codex", "gemini"];
+
+/** Ordered, de-duplicated fallback candidates for the audit role. */
+export function buildAuditFallbackCandidates(config) {
+  const effective = resolveRole(config, "audit");
+  const primary = effective.provider || "claude";
+  const candidates = [{ provider: primary, model: effective.model ?? null }];
+  if (effective.model) candidates.push({ provider: primary, model: null });
+  for (const p of KNOWN_PROVIDERS) {
+    if (p !== primary) candidates.push({ provider: p, model: null });
+  }
+  const seen = new Set();
+  return candidates.filter((c) => {
+    const key = `${c.provider}::${c.model ?? ""}`;
+    return seen.has(key) ? false : (seen.add(key), true);
+  });
+}
+
+// Pin the audit role to a provider/model. Sets BOTH the per-role override and
+// `coder_options.model` (the audit role inherits its model from the coder
+// bucket); a null model neutralizes both so the provider default is used.
+export function withAuditProvider(config, provider, model) {
+  return {
+    ...config,
+    roles: { ...(config?.roles || {}), audit: { ...(config?.roles?.audit || {}), provider, model: model ?? undefined } },
+    coder_options: { ...(config?.coder_options || {}), model: model ?? undefined },
+  };
+}
+
+/** Run the audit LLM phase with automatic provider/model fallback. */
+export async function runAuditWithFallback({
+  config, logger, roleInput, deterministicCtx, available, candidates, onFallback, createRole,
+}) {
+  const makeRole = createRole || ((cfg) => new AuditRole({ config: cfg, logger }));
+  const all = candidates || buildAuditFallbackCandidates(config);
+  const usable = available ? all.filter((c) => available.includes(c.provider)) : all;
+  if (usable.length === 0) {
+    throw new Error("No available audit provider — install claude, codex, or gemini, or set roles.audit.provider");
+  }
+
+  let last = null;
+  let attempts = 0;
+  for (const cand of usable) {
+    attempts += 1;
+    if (attempts > 1) onFallback?.(cand, attempts);
+    const role = makeRole(withAuditProvider(config, cand.provider, cand.model));
+    const meta = { provider: cand.provider, model: cand.model ?? null };
+    try {
+      const result = await role.executeWithDeterministic(roleInput, deterministicCtx);
+      if (result?.ok) return { ...result, ...meta, attempts };
+      last = { ...result, ...meta };
+    } catch (err) {
+      last = { ok: false, result: { error: err.message, provider: cand.provider }, summary: `Audit failed: ${err.message}`, ...meta };
+    }
+  }
+  return { ...last, attempts, exhausted: true };
+}

package/src/cli/advanced-commands.js

@@ -0,0 +1,61 @@
+// KJC-TSK-0582: the flat `kj --help` list had grown to 37 commands, which
+// drowns the handful a newcomer actually needs. This module is the single
+// source of truth for which commands are "core" (always shown in `kj --help`)
+// vs "advanced/specialized" (grouped under `kj advanced`). Nothing is hidden
+// or unregistered — every command stays top-level and invokable for
+// back-compat; this only changes what the help listing surfaces by default.
+
+/** The few commands a newcomer needs. Shown in `kj --help`. */
+export const CORE_COMMANDS = [
+  "start",
+  "init",
+  "run",
+  "plan",
+  "status",
+  "doctor",
+  "harden",
+  "config",
+  "update",
+];
+
+/** Navigation/built-ins that are neither core-basics nor advanced. */
+export const META_COMMANDS = ["advanced", "help"];
+
+/**
+ * Advanced commands grouped by area, in display order. Every advanced
+ * command MUST live in exactly one group — the parity test fails otherwise,
+ * so a newly-registered command can never silently vanish from `kj advanced`.
+ */
+export const ADVANCED_GROUPS = [
+  { title: "Pipeline (piezas sueltas)", commands: ["autorun", "code", "review", "scan"] },
+  { title: "Análisis pre-run", commands: ["discover", "triage", "researcher", "architect", "onboard"] },
+  { title: "Búsqueda / RAG", commands: ["rag", "qmd", "watch"] },
+  { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar"] },
+  { title: "Sesión / board", commands: ["resume", "report", "board", "undo", "standby"] },
+  { title: "Infra / setup", commands: ["install-tools", "ollama", "skills", "roles", "agents"] },
+  { title: "Mantenimiento", commands: ["clean", "sync", "telemetry"] },
+];
+
+/** Flat set of every advanced command name (for fast lookup / filtering). */
+export const ADVANCED_COMMANDS = ADVANCED_GROUPS.flatMap((g) => g.commands);
+
+const ADVANCED_SET = new Set(ADVANCED_COMMANDS);
+const CORE_SET = new Set(CORE_COMMANDS);
+const META_SET = new Set(META_COMMANDS);
+
+/**
+ * Classify a command name. Returns "core" | "advanced" | "meta" | "unknown".
+ * "unknown" means the command is registered but not yet placed in this file —
+ * the parity test treats that as a failure so the listing never drifts.
+ */
+export function classifyCommand(name) {
+  if (CORE_SET.has(name)) return "core";
+  if (ADVANCED_SET.has(name)) return "advanced";
+  if (META_SET.has(name)) return "meta";
+  return "unknown";
+}
+
+/** True when the command should be hidden from the flat `kj --help` list. */
+export function isAdvancedCommand(name) {
+  return ADVANCED_SET.has(name);
+}

package/src/cli/register-meta.js

@@ -3,6 +3,7 @@ import { triageCommand } from "../commands/triage.js";
 import { researcherCommand } from "../commands/researcher.js";
 import { architectCommand } from "../commands/architect.js";
 import { onboardCommand } from "../commands/onboard.js";
+import { startCommand } from "../commands/start.js";
 import { ragIndexCommand, ragQueryCommand, ragInstallHooksCommand, ragEvalCommand } from "../commands/rag.js";
 import { qmdQueryCommand } from "../commands/qmd.js";
 import { ragMcpCommand } from "../commands/rag-mcp.js";
@@ -15,8 +16,10 @@ import { undoCommand } from "../commands/undo.js";
 import { syncCommand } from "../commands/sync.js";
 import { cleanCommand } from "../commands/clean.js";
 import { checkCommand } from "../commands/check.js";
+import { mutateCommand } from "../commands/mutate.js";
 import { hardenCommand } from "../commands/harden.js";
 import { telemetryPreviewCommand, telemetryStatusCommand } from "../commands/telemetry.js";
+import { formatAdvancedIndex } from "../commands/advanced.js";
 import { withConfig } from "./_shared.js";
 
 /**
@@ -105,6 +108,19 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  program
+    .command("start")
+    .description("Single entry point: assess the project and recommend the next step")
+    .argument("[task]", "What you want to do (optional natural-language goal)")
+    .option("--maturity <type>", "Declare project maturity: new|existing|legacy")
+    .option("--yes", "Non-interactive: emit assessment + recommendation, apply nothing")
+    .option("--json", "Output the assessment + decision as JSON")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "start", flags, async ({ config, logger }) => {
+        await startCommand({ task, config, logger, flags });
+      });
+    });
+
   const rag = program.command("rag").description("Retrieval-augmented search over Karajan plans, onboarding briefs and project code");
   rag.command("index")
     .description("Index plans + onboarding (and optionally project sources) into the local vector store")
@@ -406,6 +422,7 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--no-config", "Skip lint/format/commit config files (hooks only)")
     .option("--no-ci", "Skip CI quality workflows")
     .option("--no-guidelines", "Skip AI-agent guideline files (AGENTS.md/CLAUDE.md)")
+    .option("--mutation", "Also seed an opt-in nightly/manual mutation CI job (never a PR gate)")
     .option("--only <dirs...>", "Harden only these language roots (e.g. frontend backend)")
     .option("--exclude <globs...>", "Skip language roots matching these globs (e.g. wrappers)")
     .option("--report", "Read-only: show what kj would add/improve, change nothing")
@@ -419,6 +436,7 @@ export function registerMeta(program, { pkgVersion }) {
           config: flags.config !== false,
           ci: flags.ci !== false,
           guidelines: flags.guidelines !== false,
+          mutation: Boolean(flags.mutation),
           only: flags.only ?? [],
           exclude: flags.exclude ?? [],
           report: Boolean(flags.report),
@@ -441,4 +459,35 @@ export function registerMeta(program, { pkgVersion }) {
       );
       if (Number.isInteger(code)) process.exit(code);
     });
+
+  program
+    .command("mutate")
+    .description("Diff-scoped mutation testing (¿cazan tus tests los mutantes de tu cambio?)")
+    .argument("[path]", "Target explícito a mutar (omite el diff)")
+    .option("--since <ref>", "Ref git contra la que sacar el diff", "HEAD~1")
+    .option("--max-survivors <n>", "Supervivientes tolerados antes de exit 1", "0")
+    .option("--json", "Emitir el resultado normalizado como JSON")
+    .action(async (pathArg, flags) => {
+      const code = await withConfig(pkgVersion, "mutate", flags, async ({ logger }) =>
+        mutateCommand({
+          path: pathArg,
+          since: flags.since,
+          maxSurvivors: Number(flags.maxSurvivors),
+          json: Boolean(flags.json),
+          logger,
+        })
+      );
+      if (Number.isInteger(code)) process.exit(code);
+    });
+
+  // KJC-TSK-0582: index of the advanced/specialized commands kept out of the
+  // flat `kj --help` list. Descriptions are read from commander itself so they
+  // never drift from each command's own --description.
+  program
+    .command("advanced")
+    .description("List advanced & specialized commands, grouped by area")
+    .action(() => {
+      const descriptions = Object.fromEntries(program.commands.map((c) => [c.name(), c.description()]));
+      console.log(formatAdvancedIndex(descriptions));
+    });
 }

package/src/cli.js

@@ -2,8 +2,9 @@
 import path from "node:path";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { Command } from "commander";
+import { Command, Help } from "commander";
 import { loadConfig } from "./config.js";
+import { isAdvancedCommand } from "./cli/advanced-commands.js";
 import { registerPipeline } from "./cli/register-pipeline.js";
 import { registerPlan } from "./cli/register-plan.js";
 import { registerRolesSkills } from "./cli/register-roles-skills.js";
@@ -41,8 +42,20 @@ program
   .allowUnknownOption(true)
   .allowExcessArguments(true);
 
-// KJC-TSK-0571: the command list is long (30+). Orient a newcomer to the few
-// commands they actually need; the rest are advanced/internal.
+// KJC-TSK-0582: the flat list had grown to 37 commands. Show only the core
+// basics in `kj --help`; the advanced/specialized ones live under
+// `kj advanced`. The filter applies to the ROOT help only — subcommand help
+// keeps listing its own subcommands untouched.
+program.configureHelp({
+  visibleCommands(cmd) {
+    const cmds = Help.prototype.visibleCommands.call(this, cmd);
+    if (cmd !== program) return cmds;
+    return cmds.filter((c) => !isAdvancedCommand(c.name()));
+  },
+});
+
+// KJC-TSK-0571/0582: orient a newcomer to the few commands they need and
+// point them at `kj advanced` for everything else.
 program.addHelpText(
   "after",
   `
@@ -53,7 +66,7 @@ Getting started (the basics — start here):
   kj doctor           Check your environment is ready
   kj harden           Add quality git hooks + CI to any repo
 
-Everything else is advanced or internal — you rarely call it directly.`
+  kj advanced         List every advanced/specialized command, grouped by area`
 );
 
 registerPipeline(program, { pkgVersion: PKG_VERSION });

package/src/commands/advanced.js

@@ -0,0 +1,31 @@
+// KJC-TSK-0582: `kj advanced` prints every advanced/specialized command,
+// grouped by area, with the one-line description commander already holds for
+// it. Pure formatter (takes a name→description map) so it's trivially
+// testable without spinning up the whole CLI.
+import { ADVANCED_GROUPS } from "../cli/advanced-commands.js";
+
+const NAME_PAD = 14;
+
+/**
+ * Build the `kj advanced` index text.
+ * @param {Record<string,string>|Map<string,string>} descriptions name → one-line description
+ */
+export function formatAdvancedIndex(descriptions) {
+  const lookup = descriptions instanceof Map ? descriptions : new Map(Object.entries(descriptions || {}));
+  const firstLine = (text) => String(text || "").split("\n")[0].trim();
+
+  const lines = [
+    "Comandos avanzados y especializados (agrupados por área).",
+    "Todos siguen siendo invocables directamente: kj <comando>.",
+    "",
+  ];
+  for (const group of ADVANCED_GROUPS) {
+    lines.push(`${group.title}:`);
+    for (const name of group.commands) {
+      lines.push(`  kj ${name.padEnd(NAME_PAD)} ${firstLine(lookup.get(name))}`.trimEnd());
+    }
+    lines.push("");
+  }
+  lines.push("Usa 'kj <comando> --help' para los detalles de cualquiera de ellos.");
+  return lines.join("\n");
+}

package/src/commands/audit.js

@@ -3,10 +3,11 @@ import fs from "node:fs/promises";
 import readline from "node:readline";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { assertAgentsAvailable } from "../agents/availability.js";
+import { assertAgentsAvailable, filterAvailableAgents } from "../agents/availability.js";
 import { resolveRole } from "../config.js";
 import { AUDIT_DIMENSIONS } from "../prompts/audit.js";
 import { AuditRole } from "../roles/audit-role.js";
+import { buildAuditFallbackCandidates, runAuditWithFallback } from "../audit/audit-fallback.js";
 import { withCliRunLog } from "../utils/cli-run-log.js";
 import { createCliProgressReporter } from "../utils/cli-progress.js";
 import { runAgentReadiness, formatAgentReadinessReport } from "../audit/agent-readiness.js";
@@ -260,7 +261,11 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
 
   return withCliRunLog("audit", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
     const auditRoleConfig = resolveRole(config, "audit");
-    await assertAgentsAvailable([auditRoleConfig.provider]);
+    // KJC-BUG-0094: proceed if any fallback candidate is installed; throw only when NONE are.
+    const fallbackCandidates = buildAuditFallbackCandidates(config);
+    const candidateProviders = [...new Set(fallbackCandidates.map((c) => c.provider))];
+    const available = await filterAvailableAgents(candidateProviders);
+    if (available.length === 0) await assertAgentsAvailable([auditRoleConfig.provider]);
     logger.info(`Audit (${auditRoleConfig.provider}) starting...`);
     runLog.logText(`[audit] provider=${auditRoleConfig.provider} dimensions=${dimensions || "all"} deterministicOnly=${deterministicOnly}`);
 
@@ -347,7 +352,18 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
     const progress = createCliProgressReporter({ role: "auditor" });
     let roleResult;
     try {
-      roleResult = await role.executeWithDeterministic({ ...roleInput, onOutput: progress.onOutput }, deterministicCtx);
+      // KJC-BUG-0094: resilient fallback — if the configured provider/model
+      // is down (e.g. an inherited model like "claude-fable-5" is offline),
+      // degrade to the provider default, then to the next installed provider,
+      // reusing the deterministic context so no static analysis is re-run.
+      roleResult = await runAuditWithFallback({
+        config, logger,
+        roleInput: { ...roleInput, onOutput: progress.onOutput },
+        deterministicCtx,
+        available,
+        candidates: fallbackCandidates,
+        onFallback: (cand) => logger.warn(`Audit provider fallback → ${cand.provider}${cand.model ? ` (${cand.model})` : " (default model)"}`),
+      });
       progress.finish(roleResult.ok ? "done" : "failed");
     } catch (err) { progress.finish("failed"); throw err; }
 

package/src/commands/board.js

@@ -77,15 +77,18 @@ async function findAvailablePort(desiredPort, maxTries = 10) {
 
 /**
  * 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".
+ * the per-project view via the SPA hash route (`#board/<slug>`) so the
+ * caller's project shows up pre-filtered instead of "All projects". The
+ * frontend router is hash-based (see public/utils/init-listeners.js); a
+ * real `/p/<slug>` path is not a route and silently falls back to the
+ * global dashboard. KJC-BUG-0093.
  * @param {number} port
  * @param {string|null} [projectSlug]
  * @returns {string}
  */
-function buildBoardUrl(port, projectSlug) {
+export function buildBoardUrl(port, projectSlug) {
   const base = `http://localhost:${port}`;
-  return projectSlug ? `${base}/p/${projectSlug}` : base;
+  return projectSlug ? `${base}/#board/${projectSlug}` : base;
 }
 
 /**

package/src/commands/harden.js

@@ -76,6 +76,7 @@ export async function hardenCommand({
   config = true,
   ci = true,
   guidelines = true,
+  mutation = false,
   dryRun = false,
   json = false,
   report = false,
@@ -134,7 +135,7 @@ export async function hardenCommand({
   const cfg = withConfig ? installConfigsForRoots({ projectDir, roots, dryRun }) : null;
   const withCi = ci && profile !== "minimal";
   const wf = withCi
-    ? installWorkflows({ projectDir, language: roots[0]?.language ?? null, profile, dryRun })
+    ? installWorkflows({ projectDir, language: roots[0]?.language ?? null, profile, mutation, dryRun })
     : null;
   const withGuidelines = guidelines && profile !== "minimal";
   const gl = withGuidelines ? installGuidelines({ projectDir, dryRun }) : null;

package/src/commands/mutate.js

@@ -0,0 +1,94 @@
+/**
+ * `kj mutate` (KJC-TSK-0587) — diff-scoped mutation testing. Detects language
+ * (M-A registry) → changed lines (M-B diff-scope) → runs the tool (M-C runner)
+ * only over what you just touched. `--json` + exit code make it a gate. No
+ * silent fallback: unsupported language / unreadable report exit non-zero.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { detectProjectStack } from "../utils/stack-detect.js";
+import { getMutationTool } from "../mutate/tool-registry.js";
+import { getDiffScope } from "../mutate/diff-scope.js";
+import { runMutation } from "../mutate/runner.js";
+
+// Per-tool launch detail: subcommand + JSON report path. Tools without a JSON
+// report leave `report` empty → the run surfaces the tool's own output.
+const INVOCATION = {
+  stryker: { base: ["run"], report: "reports/mutation/mutation.json" },
+  mutmut: { base: ["run"], report: "mutmut-report.json" },
+  infection: { base: [], report: "infection.json" },
+  "go-mutesting": { base: [], report: "" },
+  pitest: { base: [], report: "" },
+};
+
+const DEFAULT_SINCE = "HEAD~1";
+
+function makeReadReport(reportFile) {
+  if (!reportFile) return undefined;
+  return async () => JSON.parse(await fs.readFile(reportFile, "utf8"));
+}
+
+/**
+ * `deps` ({detectStack, diffScope, run}) is injectable so tests stay pure.
+ * `since` diffs against a git ref (default HEAD~1); `path` bypasses the diff.
+ * @returns {Promise<number>} process exit code
+ */
+export async function mutateCommand({
+  projectDir = process.cwd(),
+  since,
+  path: pathArg,
+  json = false,
+  maxSurvivors = 0,
+  logger = console,
+  deps = {},
+} = {}) {
+  const detectStack = deps.detectStack ?? detectProjectStack;
+  const diffScope = deps.diffScope ?? getDiffScope;
+  const run = deps.run ?? runMutation;
+  const say = (msg) => logger.info?.(msg);
+
+  const { language } = await detectStack(projectDir);
+  const tool = getMutationTool(language);
+  if (!tool.supported) {
+    say(`kj mutate: lenguaje no soportado (${language ?? "desconocido"}) — ${tool.reason}`);
+    return 2;
+  }
+
+  let scope;
+  if (pathArg) {
+    const args = tool.scope.flag ? [tool.scope.flag, pathArg] : [pathArg];
+    scope = { supported: true, empty: false, args };
+  } else {
+    scope = await diffScope({ since: since ?? DEFAULT_SINCE, language, projectDir });
+  }
+  if (scope.empty) {
+    say("kj mutate: nada que mutar en el diff.");
+    return 0;
+  }
+
+  const invocation = INVOCATION[tool.id] ?? { base: [], report: "" };
+  const reportFile = invocation.report ? path.join(projectDir, invocation.report) : "";
+  const outcome = await run({
+    binary: tool.binary,
+    args: [...invocation.base, ...scope.args],
+    cwd: projectDir,
+    readReport: makeReadReport(reportFile),
+  });
+
+  if (!outcome.result) {
+    say(`kj mutate: la herramienta ${tool.id} no produjo un informe legible.`);
+    if (outcome.stderr) say(outcome.stderr.trim());
+    return 1;
+  }
+
+  const { score, killed, total, survived } = outcome.result;
+  if (json) {
+    say(JSON.stringify(outcome.result));
+  } else {
+    say(`kj mutate (${tool.id}): score ${score ?? "n/a"}% — ${killed}/${total} mutantes cazados`);
+    for (const s of survived) say(`  ✗ superviviente ${s.file}:${s.line} (${s.mutator ?? s.status})`);
+    if (survived.length === 0) say("  ✓ sin supervivientes");
+  }
+  return survived.length > maxSurvivors ? 1 : 0;
+}

package/src/commands/plan/generate.js

@@ -513,8 +513,8 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
       const { projectSlug: slugFor } = await import("../../plan/plan-store.js");
       const boardPort = config?.hu_board?.port ?? 4000;
       // `projectSlug` scopes the board URL to this project's view
-      // (`/p/<slug>`) instead of the global "All projects" dashboard. The
-      // board UI hides multi-project chrome when it sees that prefix.
+      // (`#board/<slug>`) instead of the global "All projects" dashboard.
+      // The hash route opens the board pre-filtered to that project.
       const boardResult = await startBoard(boardPort, { projectSlug: slugFor(projectDir) });
       const status = boardResult.alreadyRunning ? "already running" : "started";
       console.log(renderBoardBanner({ url: boardResult.url, status, projectName: plan.name }));

package/src/commands/start.js

@@ -0,0 +1,117 @@
+// KJC-TSK-0570 (Onboard C) — `kj start`: the single entry point to the Brain.
+// Wires the read-only sweep (0568) → deterministic assessment (0569) → haiku
+// decider (0569), reports the recommended next step, and — interactively only —
+// confirms and dispatches the chosen intent to its saved command
+// (harden/rag/run/plan). --json / --yes / no-TTY stay read-only: emit the
+// assessment + intent and apply nothing. Collaborators are injected for testing.
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execa } from "execa";
+import { runReadOnlySweep } from "../start/sweep.js";
+import { buildAssessment } from "../start/assessment.js";
+import { StartDecidorRole } from "../start/start-decider-role.js";
+import { createWizard, isTTY } from "../utils/wizard.js";
+
+// The recommended next step shown for each intent.
+const NEXT_STEP = {
+  ASSESS_ONLY: "Everything looks healthy — nothing to do.",
+  RECOMMEND_HARDEN: "Suggested: `kj harden --interactive`",
+  RECOMMEND_INDEX: "Suggested: `kj rag index`",
+  START_TASK: 'Suggested: `kj run "<task>"`',
+  PROPOSE_PLAN: 'Suggested: `kj plan "<goal>"`',
+};
+
+// Each writing intent maps to the saved command + args `kj start` dispatches.
+const DISPATCH = {
+  RECOMMEND_HARDEN: () => ["harden", "--interactive"],
+  RECOMMEND_INDEX: () => ["rag", "index"],
+  START_TASK: (task) => ["run", task],
+  PROPOSE_PLAN: (task) => ["plan", task],
+};
+
+const ASK_FALLBACK = "What would you like to do with this project?";
+const CLI_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "cli.js");
+
+// Run a saved `kj` subcommand as a child, inheriting stdio so its own prompts
+// (e.g. `harden --interactive`) drive the real terminal. Never throws here.
+async function spawnKj(args, { cwd }) {
+  await execa("node", [CLI_PATH, ...args.filter(Boolean)], { cwd, stdio: "inherit", reject: false });
+}
+
+// The decider has its own quota/parse recovery; a spawn-level failure (CLI not
+// installed) still throws, so we degrade here too — `kj start` never crashes.
+async function decide({ task, text, config, logger, makeDecider }) {
+  const decider = makeDecider({ config, logger });
+  try {
+    const decision = await decider.execute({ userMessage: task, assessment: text });
+    return decision.result || {};
+  } catch (err) {
+    logger?.warn?.(`[start] decider unavailable (${err?.message || err}) — asking the user.`);
+    return { intent: "ASK_USER", rationale: "Decider unavailable.", questionToAsk: ASK_FALLBACK, degraded: true };
+  }
+}
+
+// Ask one yes/no, always closing the readline interface afterwards.
+async function confirmApply(makeWizard) {
+  const wizard = makeWizard();
+  try {
+    return await wizard.confirm("Apply this?", true);
+  } finally {
+    wizard.close();
+  }
+}
+
+// Print the rationale + recommended step, or the open question for ASK_USER.
+function render(result) {
+  if (result.intent === "ASK_USER") {
+    console.log(`❓ ${result.questionToAsk || ASK_FALLBACK}`);
+    return;
+  }
+  if (result.rationale) console.log(`→ ${result.rationale}`);
+  const step = NEXT_STEP[result.intent];
+  if (step) console.log(`  ${step}`);
+}
+
+export async function startCommand({ task = "", config, logger, flags = {}, deps = {} }) {
+  const sweep = deps.runReadOnlySweep || runReadOnlySweep;
+  const assess = deps.buildAssessment || buildAssessment;
+  const makeDecider = deps.makeDecider || ((opts) => new StartDecidorRole(opts));
+  const tty = deps.isTTY || isTTY;
+  const spawn = deps.spawnKj || spawnKj;
+  const makeWizard = deps.makeWizard || (() => createWizard());
+
+  const bundle = await sweep(config.projectDir, { declared: flags.maturity || null });
+  const { text, summary } = assess(bundle);
+  let result = await decide({ task, text, config, logger, makeDecider });
+
+  if (flags.json) {
+    console.log(JSON.stringify({ maturity: summary.maturity, assessment: text, ...result }, null, 2));
+    return { ok: true, intent: result.intent };
+  }
+
+  console.log(`${text}\n`);
+  const interactive = tty() && !flags.yes;
+  let goal = task;
+
+  // ASK_USER: one interactive re-route — the open answer becomes the goal.
+  if (result.intent === "ASK_USER" && interactive) {
+    const wizard = makeWizard();
+    try {
+      const answer = await wizard.input(`❓ ${result.questionToAsk || ASK_FALLBACK}`);
+      if (answer) {
+        goal = answer;
+        result = await decide({ task: answer, text, config, logger, makeDecider });
+      }
+    } finally {
+      wizard.close();
+    }
+  }
+  render(result);
+
+  // Dispatch the chosen intent to its saved command, confirming first (it writes).
+  const toArgs = DISPATCH[result.intent];
+  if (interactive && toArgs && (await confirmApply(makeWizard))) {
+    await spawn(toArgs(goal), { cwd: config.projectDir });
+  }
+  return { ok: true, intent: result.intent };
+}