karajan-code 3.7.2 → 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.2",
+  "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/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;
+}

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

package/src/config/defaults.js

@@ -27,7 +27,8 @@ const DEFAULTS = {
     triage: { provider: null, model: null },
     discover: { provider: null, model: null },
     architect: { provider: null, model: null },
-    hu_reviewer: { provider: null, model: null }
+    hu_reviewer: { provider: null, model: null },
+    start: { provider: null, model: "haiku" }
   },
   pipeline: {
     planner: { enabled: false },

package/src/config/schema.js

@@ -90,6 +90,7 @@ const RolesMap = v.optional(v.looseObject({
   discover: v.optional(RoleEntry),
   architect: v.optional(RoleEntry),
   hu_reviewer: v.optional(RoleEntry),
+  start: v.optional(RoleEntry),
 }));
 
 const PipelineEntry = v.looseObject({

package/src/guards/secret-redactor.js

@@ -0,0 +1,71 @@
+// KJC-TSK-0583 — Inbound secret redaction for the review boundary.
+//
+// The outbound boundary (output-guard.js) already blocks committing secrets.
+// This closes the *inbound* gap: a hardcoded credential in the working tree
+// would otherwise reach the (possibly cloud) reviewer model verbatim inside the
+// diff. `redactSecrets` masks each credential before the model sees it, reusing
+// the SAME catalog as output-guard — no new patterns, no AI cost, deterministic.
+import { CREDENTIAL_PATTERNS } from "./output-guard.js";
+
+// Families whose match begins with a fixed, identifiable literal prefix. The
+// placeholder keeps that prefix so the reviewer can still tell WHAT kind of
+// secret was redacted (and say "move it to .env") without seeing the value.
+const STABLE_PREFIX_BY_ID = {
+  "aws-key": "AKIA",
+  "npm-token": "npm_",
+  "openai-key": "sk-",
+  "anthropic-key": "sk-ant-",
+  "stripe-key": "sk_live_",
+  "stripe-test": "sk_test_",
+  "google-api-key": "AIza",
+};
+
+// Families with a dynamic prefix: keep the real match up to and including the
+// first separator (ghp_/gho_/…, xoxb-/xoxp-/…), then mask the rest.
+const DYNAMIC_SEPARATOR_BY_ID = {
+  "github-token": "_",
+  "slack-token": "-",
+};
+
+const GENERIC = "***REDACTED-SECRET***";
+const SUFFIX = "***REDACTED***";
+
+function placeholderFor(id, match) {
+  const stable = STABLE_PREFIX_BY_ID[id];
+  if (stable) return `${stable}${SUFFIX}`;
+  const sep = DYNAMIC_SEPARATOR_BY_ID[id];
+  if (sep) {
+    const idx = match.indexOf(sep);
+    return idx >= 0 ? `${match.slice(0, idx + 1)}${SUFFIX}` : GENERIC;
+  }
+  return GENERIC;
+}
+
+// Apply the most specific prefixes first so `sk-ant-` wins over `sk-`; families
+// without a stable prefix keep their catalog order (stable sort) and run last.
+function orderedPatterns() {
+  return [...CREDENTIAL_PATTERNS].sort(
+    (a, b) => (STABLE_PREFIX_BY_ID[b.id]?.length ?? 0) - (STABLE_PREFIX_BY_ID[a.id]?.length ?? 0)
+  );
+}
+
+/**
+ * Mask every credential in `text`, preserving line structure. Pure and
+ * deterministic: clean text is returned untouched (no-op, no cost).
+ * @param {string} text
+ * @returns {string}
+ */
+export function redactSecrets(text) {
+  if (typeof text !== "string" || text.length === 0) return text;
+  let out = text;
+  for (const { id, pattern } of orderedPatterns()) {
+    const flags = pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`;
+    out = out.replace(new RegExp(pattern.source, flags), (match) =>
+      // Idempotent: a broad pattern (generic-secret, hardcoded-key-assignment)
+      // can span an already-masked value; leave the more specific placeholder
+      // in place instead of clobbering it with the generic one.
+      match.includes("REDACTED") ? match : placeholderFor(id, match)
+    );
+  }
+  return out;
+}

package/src/harden/workflow-engine.js

@@ -10,7 +10,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { upsertManagedBlock } from "../utils/managed-markers.js";
-import { extraWorkflowsFor, qualityWorkflowFor, WORKFLOWS } from "./workflow-templates.js";
+import { extraWorkflowsFor, mutationWorkflowFor, qualityWorkflowFor, WORKFLOWS } from "./workflow-templates.js";
 
 const BLOCK_VERSION = 1;
 const WORKFLOWS_DIR = join(".github", "workflows");
@@ -31,12 +31,14 @@ export function installWorkflows({
   projectDir = process.cwd(),
   language = null,
   profile = "standard",
+  mutation = false,
   dryRun = false,
 } = {}) {
   const dir = join(projectDir, WORKFLOWS_DIR);
   const quality = qualityWorkflowFor(language);
   const extras = extraWorkflowsFor({ profile, publishable: isPublishableNpm(projectDir) });
-  const all = [...WORKFLOWS, ...(quality ? [quality] : []), ...extras];
+  const mut = mutation ? mutationWorkflowFor(language) : null;
+  const all = [...WORKFLOWS, ...(quality ? [quality] : []), ...extras, ...(mut ? [mut] : [])];
   const results = [];
   for (const wf of all) {
     const target = join(dir, wf.file);

package/src/harden/workflow-templates.js

@@ -147,6 +147,58 @@ export const PACK_SMOKE_WORKFLOW = [
   '          echo "Tarball installs clean: $tgz"',
 ].join("\n");
 
+// Opt-in nightly/manual mutation audit (KJC-TSK-0589). NEVER a PR gate: it runs
+// on a weekly schedule + manual dispatch, and the mutate step is non-blocking
+// (continue-on-error) so a red run never nags. Only stacks whose `kj mutate`
+// yields a JSON report (stryker/mutmut/infection) get a workflow — no silent
+// scaffold for tools that can't report yet.
+const MUTATION_TOOLCHAIN = {
+  javascript: ["      - run: npm ci"],
+  python: [
+    "      - uses: actions/setup-python@v5",
+    "        with:",
+    "          python-version: '3.12'",
+    "      - run: pip install mutmut pytest",
+  ],
+  php: [
+    "      - uses: shivammathur/setup-php@v2",
+    "        with:",
+    "          php-version: '8.3'",
+    "      - run: composer install --no-interaction --no-progress",
+  ],
+};
+MUTATION_TOOLCHAIN.typescript = MUTATION_TOOLCHAIN.javascript;
+
+/** Opt-in mutation workflow entry, or null for a stack without a JSON report. */
+export function mutationWorkflowFor(language) {
+  const toolchain = MUTATION_TOOLCHAIN[language];
+  if (!toolchain) return null;
+  const body = [
+    "name: Mutation (nightly)",
+    "on:",
+    "  schedule:",
+    "    - cron: '0 4 * * 1'",
+    "  workflow_dispatch:",
+    "permissions:",
+    "  contents: read",
+    "jobs:",
+    "  mutation:",
+    "    runs-on: ubuntu-latest",
+    "    steps:",
+    "      - uses: actions/checkout@v4",
+    "        with:",
+    "          fetch-depth: 0",
+    "      - uses: actions/setup-node@v4",
+    "        with:",
+    "          node-version: 22",
+    ...toolchain,
+    "      - name: Mutation testing (advisory, never blocks a PR)",
+    "        continue-on-error: true",
+    "        run: npx --yes --package karajan-code kj mutate --since HEAD~1",
+  ].join("\n");
+  return { file: "kj-mutation.yml", blockId: "wf-mutation", body };
+}
+
 /** Conditional workflows: shrink-budget on strict, pack-smoke when publishable. */
 export function extraWorkflowsFor({ profile = "standard", publishable = false } = {}) {
   const extras = [];