karajan-code 3.7.2 → 3.9.0

package/README.md

@@ -112,6 +112,16 @@ 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.
 
+> **On a bare Linux box, install `curl` first.** The binary and script installers
+> below download with `curl` (or `wget`). macOS already ships `curl` and Windows
+> PowerShell has `irm` built in, but a minimal server or container image often has
+> neither — install it with your package manager, then run the one-liner:
+> - **Debian/Ubuntu**: `sudo apt update && sudo apt install -y curl`
+> - **Fedora/RHEL/CentOS**: `sudo dnf install -y curl`
+> - **Arch**: `sudo pacman -S --noconfirm curl`
+> - **Alpine**: `sudo apk add curl`
+> - **openSUSE**: `sudo zypper install -y curl`
+
 **Standalone binary** (no Node.js needed):
 ```bash
 # macOS (Apple Silicon)
@@ -124,7 +134,28 @@ curl -L https://github.com/manufosela/karajan-code/releases/latest/download/kj-l
 curl -L https://github.com/manufosela/karajan-code/releases/latest/download/kj-win-x64.exe -o kj.exe
 ```
 
-**One-liner** (detects OS, installs via npm):
+**One-liner, binary** (no Node — detects OS/arch, verifies the checksum, installs to `~/.local/bin`):
+```bash
+curl -fsSL https://raw.githubusercontent.com/manufosela/karajan-code/main/scripts/install-binary.sh | sh
+```
+Pin a version or install dir with env vars: `KJ_VERSION=v3.7.2 KJ_INSTALL_DIR=/usr/local/bin`.
+
+**One-liner, binary — Windows** (no Node — verifies the checksum, installs to `%LOCALAPPDATA%\Karajan` and adds it to your user PATH):
+```powershell
+irm https://raw.githubusercontent.com/manufosela/karajan-code/main/scripts/install-binary.ps1 | iex
+```
+
+> **If your OS blocks the binary.** The macOS build is ad-hoc signed and the
+> Windows build is unsigned — neither carries a paid certificate, so a manually
+> downloaded binary may be blocked on first run. The install scripts above clear
+> the flag for you. If you download the binary by hand instead:
+> - **macOS** — Gatekeeper says the binary "cannot be opened": `xattr -d com.apple.quarantine ./kj`, or Control-click the file → **Open**.
+> - **Windows** — SmartScreen shows "Windows protected your PC": click **More info → Run anyway**, or run `Unblock-File .\kj.exe`.
+>
+> Paid notarization (Apple) and Authenticode signing (Windows) are optional and
+> not enabled by default — this is a deliberate cost decision, not an oversight.
+
+**One-liner, npm** (detects OS, installs via npm — needs Node ≥ 18):
 ```bash
 curl -fsSL https://raw.githubusercontent.com/manufosela/karajan-code/main/scripts/install-kj.sh | sh
 ```
@@ -235,8 +266,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.2",
+  "version": "3.9.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/scripts/install-binary.ps1

@@ -0,0 +1,82 @@
+<#
+.SYNOPSIS
+  Karajan Code — standalone binary installer for Windows (no Node required).
+
+.DESCRIPTION
+  Downloads the prebuilt kj.exe for Windows x64 from the GitHub release,
+  verifies its SHA256 checksum, installs it to %LOCALAPPDATA%\Karajan, and
+  adds that folder to the user PATH (idempotently). Re-running updates the
+  binary in place without duplicating PATH entries.
+
+  Run it with:
+    irm https://karajancode.com/install.ps1 | iex
+
+  Override with env vars: $env:KJ_VERSION (e.g. v3.7.2), $env:KJ_INSTALL_DIR.
+
+  KJC-TSK-0594.
+#>
+$ErrorActionPreference = "Stop"
+
+$repo = "manufosela/karajan-code"
+$version = if ($env:KJ_VERSION) { $env:KJ_VERSION } else { "latest" }
+$installDir = if ($env:KJ_INSTALL_DIR) { $env:KJ_INSTALL_DIR } else { Join-Path $env:LOCALAPPDATA "Karajan" }
+$asset = "kj-win-x64.exe"
+
+if ($version -eq "latest") {
+  $base = "https://github.com/$repo/releases/latest/download"
+} else {
+  $base = "https://github.com/$repo/releases/download/$version"
+}
+
+# Download to a temp folder; only install once the checksum matches, so a
+# failure never leaves a half-installed binary behind.
+$tmp = Join-Path ([System.IO.Path]::GetTempPath()) ("kj-install-" + [System.Guid]::NewGuid().ToString("N"))
+New-Item -ItemType Directory -Path $tmp -Force | Out-Null
+try {
+  $binTmp = Join-Path $tmp "kj.exe"
+  $shaTmp = Join-Path $tmp "kj.exe.sha256"
+
+  Write-Host "kj-install: downloading $asset ($version)..."
+  try {
+    Invoke-WebRequest -Uri "$base/$asset" -OutFile $binTmp -UseBasicParsing
+    Invoke-WebRequest -Uri "$base/$asset.sha256" -OutFile $shaTmp -UseBasicParsing
+  } catch {
+    throw "could not download $base/$asset — does that version/asset exist, and is the network reachable? ($_)"
+  }
+
+  # certutil writes a multi-line file; keep only the hex of the hash line.
+  $shaLine = (Get-Content $shaTmp | Where-Object { $_ -notmatch "SHA256|CertUtil" } | Select-Object -First 1)
+  $expected = ($shaLine -replace "[^0-9A-Fa-f]", "").ToLower()
+  $actual = (Get-FileHash -Algorithm SHA256 -Path $binTmp).Hash.ToLower()
+  if ($expected.Length -ne 64 -or $expected -ne $actual) {
+    throw "checksum mismatch (expected '$expected', got '$actual'). Aborting, nothing installed."
+  }
+
+  # Install: move into place, replacing any previous install (idempotent).
+  New-Item -ItemType Directory -Path $installDir -Force | Out-Null
+  $dest = Join-Path $installDir "kj.exe"
+  Move-Item -Path $binTmp -Destination $dest -Force
+
+  # The download carries a "mark of the web" (Zone.Identifier) that makes
+  # SmartScreen warn on first run. The binary is not code-signed with a paid
+  # certificate, so clear the mark on the copy we just verified ourselves.
+  Unblock-File -Path $dest -ErrorAction SilentlyContinue
+
+  $installed = (& $dest --version) 2>$null
+  Write-Host "kj-install: installed kj $installed to $dest"
+
+  # Add to the user PATH only if it is not already there (no duplicates).
+  $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
+  $parts = @()
+  if ($userPath) { $parts = $userPath.Split(";") | Where-Object { $_ -ne "" } }
+  $already = $parts | Where-Object { $_.TrimEnd("\") -ieq $installDir.TrimEnd("\") }
+  if (-not $already) {
+    $newPath = if ($userPath) { "$userPath;$installDir" } else { $installDir }
+    [Environment]::SetEnvironmentVariable("Path", $newPath, "User")
+    Write-Host "kj-install: added '$installDir' to your user PATH. Open a new terminal to use 'kj'."
+  } else {
+    Write-Host "kj-install: '$installDir' is already on your user PATH — run 'kj --help' to get started."
+  }
+} finally {
+  Remove-Item -Path $tmp -Recurse -Force -ErrorAction SilentlyContinue
+}

package/scripts/install-binary.sh

@@ -0,0 +1,103 @@
+#!/bin/sh
+# Karajan Code — standalone binary installer (no Node required).
+#
+#   curl -fsSL https://karajancode.com/install.sh | sh
+#
+# Downloads the prebuilt `kj` binary for your OS/arch from the GitHub
+# release, verifies its SHA256 checksum, and installs it to ~/.local/bin.
+# Override with env vars: KJ_VERSION (e.g. v3.7.2), KJ_INSTALL_DIR.
+#
+# POSIX sh only — no bashisms, no Node. KJC-TSK-0593.
+set -eu
+
+REPO="manufosela/karajan-code"
+VERSION="${KJ_VERSION:-latest}"
+INSTALL_DIR="${KJ_INSTALL_DIR:-$HOME/.local/bin}"
+
+die() {
+  echo "kj-install: $1" >&2
+  exit 1
+}
+
+# --- Detect OS/arch, map to the release asset names we actually build. ---
+os="$(uname -s)"
+arch="$(uname -m)"
+case "$os" in
+  Linux) os="linux" ;;
+  Darwin) os="darwin" ;;
+  *) die "unsupported OS '$os'. Supported: Linux, macOS. Use npm instead: npm install -g karajan-code" ;;
+esac
+case "$arch" in
+  x86_64 | amd64) arch="x64" ;;
+  arm64 | aarch64) arch="arm64" ;;
+  *) die "unsupported architecture '$arch'" ;;
+esac
+
+target="${os}-${arch}"
+case "$target" in
+  linux-x64 | darwin-arm64) ;;
+  *) die "no prebuilt binary for '$target'. Available: linux-x64, darwin-arm64. Use npm instead: npm install -g karajan-code" ;;
+esac
+
+# --- Resolve the download URL for the requested version (or latest). ---
+asset="kj-${target}"
+if [ "$VERSION" = "latest" ]; then
+  base="https://github.com/${REPO}/releases/latest/download"
+else
+  base="https://github.com/${REPO}/releases/download/${VERSION}"
+fi
+
+# --- Pick a downloader. ---
+if command -v curl >/dev/null 2>&1; then
+  fetch() { curl -fsSL "$1" -o "$2"; }
+elif command -v wget >/dev/null 2>&1; then
+  fetch() { wget -qO "$2" "$1"; }
+else
+  die "need curl or wget to download the binary"
+fi
+
+# --- Pick a checksum tool. ---
+if command -v sha256sum >/dev/null 2>&1; then
+  sha256() { sha256sum "$1" | cut -d' ' -f1; }
+elif command -v shasum >/dev/null 2>&1; then
+  sha256() { shasum -a 256 "$1" | cut -d' ' -f1; }
+else
+  die "need sha256sum or shasum to verify the download"
+fi
+
+# --- Download to a temp dir; only install after the checksum matches. ---
+tmp="$(mktemp -d "${TMPDIR:-/tmp}/kj-install.XXXXXX")"
+trap 'rm -rf "$tmp"' EXIT INT TERM
+
+echo "kj-install: downloading ${asset} (${VERSION})..."
+fetch "${base}/${asset}" "${tmp}/kj" || die "could not download ${base}/${asset} — does that version/asset exist?"
+fetch "${base}/${asset}.sha256" "${tmp}/kj.sha256" || die "could not download the checksum for ${asset}"
+
+expected="$(cut -d' ' -f1 <"${tmp}/kj.sha256")"
+actual="$(sha256 "${tmp}/kj")"
+[ "$expected" = "$actual" ] || die "checksum mismatch (expected ${expected}, got ${actual}). Aborting, nothing installed."
+
+# --- Install atomically: chmod on the temp file, then move into place. ---
+chmod +x "${tmp}/kj"
+mkdir -p "$INSTALL_DIR"
+mv -f "${tmp}/kj" "${INSTALL_DIR}/kj"
+
+# On macOS the binary is ad-hoc signed, not notarized with a paid Apple
+# certificate, so Gatekeeper can quarantine it. Clear the flag on the copy
+# we just checksummed ourselves (no-op on Linux / if the flag is absent).
+if [ "$os" = "darwin" ] && command -v xattr >/dev/null 2>&1; then
+  xattr -d com.apple.quarantine "${INSTALL_DIR}/kj" 2>/dev/null || true
+fi
+
+installed="$("${INSTALL_DIR}/kj" --version 2>/dev/null || echo '?')"
+echo "kj-install: installed kj ${installed} to ${INSTALL_DIR}/kj"
+
+# --- Tell the user how to reach it if the dir is not on PATH. ---
+case ":${PATH}:" in
+  *":${INSTALL_DIR}:"*) echo "kj-install: '${INSTALL_DIR}' is on your PATH — run 'kj --help' to get started." ;;
+  *)
+    echo "kj-install: '${INSTALL_DIR}' is not on your PATH. Add it with:"
+    echo "  export PATH=\"${INSTALL_DIR}:\$PATH\""
+    echo "  (add that line to ~/.bashrc, ~/.zshrc or ~/.profile to make it permanent)"
+    ;;
+esac

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