karajan-code 3.5.0 → 3.6.0

package/src/commands/init.js

@@ -91,17 +91,29 @@ async function askAgents(wizard, available, config, logger) {
  * `available.length === 1` short-circuits: every role uses the only CLI
  * available, no point asking.
  */
-async function askPerRoleProviders(wizard, available, config, { coder, reviewer }, logger) {
+async function askPerRoleProviders(wizard, available, config, { coder, reviewer }, logger, ask = true) {
   if (available.length <= 1) return;
 
-  logger.info("");
-  logger.info("Configure provider per role (Enter accepts the default):");
-
   // Make sure containers exist for every role/pipeline key we touch —
   // older configs may have a sparser shape than DEFAULTS.
   config.roles = config.roles || {};
   config.pipeline = config.pipeline || {};
 
+  // KJC-TSK-0571: per-role provider selection is advanced. By default every
+  // role inherits its provider from coder/reviewer — a newcomer has no context
+  // to pick an agent for "refactorer" or "perf". Only init the containers.
+  if (!ask) {
+    for (const role of PER_ROLE_QUESTIONS) {
+      config.roles[role.key] = config.roles[role.key] || { provider: null, model: null };
+      if (role.pipelineKey) config.pipeline[role.pipelineKey] = config.pipeline[role.pipelineKey] || { enabled: false };
+    }
+    logger.info("  Agent routing: every role inherits from your coder/reviewer (default).");
+    return;
+  }
+
+  logger.info("");
+  logger.info("Configure provider per role (Enter accepts the default):");
+
   for (const role of PER_ROLE_QUESTIONS) {
     config.roles[role.key] = config.roles[role.key] || { provider: null, model: null };
     if (role.pipelineKey) {
@@ -150,14 +162,14 @@ async function askFallbackChain(wizard, available, config, { coder, reviewer },
   if (available.length < 2) return;
 
   logger.info("");
-  logger.info("Plan B — fallback automático cuando un provider se queda sin créditos:");
+  logger.info("Plan B — automatic fallback when a provider runs out of credits:");
   const enable = await wizard.confirm(
-    "  ¿Configurar fallback? (default: 12h; si el cooldown supera ese tiempo, switch al provider alternativo)",
+    "  Configure a fallback? (default 12h; if the cooldown exceeds it, switch to the alternate provider)",
     true
   );
   if (!enable) return;
 
-  const maxHoursRaw = await wizard.input("  Máximo tiempo de espera antes de fallback (horas):", "12");
+  const maxHoursRaw = await wizard.input("  Max wait before falling back (hours):", "12");
   const maxHours = Number.parseFloat(maxHoursRaw) || 12;
 
   config.roles = config.roles || {};
@@ -168,18 +180,18 @@ async function askFallbackChain(wizard, available, config, { coder, reviewer },
   ];
   for (const role of KEY_ROLES) {
     config.roles[role.key] = config.roles[role.key] || {};
-    const opts = [{ label: "Sin fallback (hibernar)", value: "__none__", available: true }];
+    const opts = [{ label: "No fallback (hibernate)", value: "__none__", available: true }];
     for (const a of available) {
       if (a.name === role.primary) continue;
       opts.push({ label: a.name, value: a.name, available: true });
     }
-    const choice = await wizard.select(`  Fallback de ${role.label} cuando ${role.primary} se quede sin créditos:`, opts);
+    const choice = await wizard.select(`  Fallback for ${role.label} when ${role.primary} runs out of credits:`, opts);
     if (choice === "__none__") {
       delete config.roles[role.key].fallback;
-      logger.info(`    -> ${role.key}: sin fallback (hibernará)`);
+      logger.info(`    -> ${role.key}: no fallback (will hibernate)`);
     } else {
       config.roles[role.key].fallback = { provider: choice, max_wait_hours: maxHours };
-      logger.info(`    -> ${role.key}: ${role.primary} → ${choice} (tras ${maxHours}h)`);
+      logger.info(`    -> ${role.key}: ${role.primary} → ${choice} (after ${maxHours}h)`);
     }
   }
 }
@@ -206,7 +218,7 @@ async function askLanguages(wizard, config, logger) {
     ...allLangEntries.filter((o) => o.value !== detectedLocale),
   ];
 
-  const pipelineLang = await wizard.select("Pipeline language:", languageOptions);
+  const pipelineLang = await wizard.select("Language for agent messages and reports:", languageOptions);
   config.language = pipelineLang;
   logger.info(`  -> Pipeline language: ${pipelineLang}`);
 
@@ -214,14 +226,14 @@ async function askLanguages(wizard, config, logger) {
     ...allLangEntries.filter((o) => o.value === pipelineLang),
     ...allLangEntries.filter((o) => o.value !== pipelineLang),
   ];
-  const huLang = await wizard.select("HU language (for user stories):", huLangOptions);
+  const huLang = await wizard.select("Language for user stories (HUs):", huLangOptions);
   config.hu_language = huLang;
-  logger.info(`  -> HU language: ${huLang}`);
+  logger.info(`  -> User-story language: ${huLang}`);
 }
 
 async function askGitAutomation(wizard, config, logger) {
   config.git = config.git || {};
-  const autoCommit = await wizard.confirm("Auto-commit per HU? (recommended for `kj run` so commits show up in git log)", false);
+  const autoCommit = await wizard.confirm("Auto-commit per user story? (recommended for `kj run` so commits show up in git log)", false);
   config.git.auto_commit = autoCommit;
   logger.info(`  -> auto_commit: ${autoCommit}`);
 
@@ -268,30 +280,20 @@ async function askBoardSecurity(wizard, config, logger) {
 /**
  * Explicit, opt-in telemetry consent. We do NOT inherit a "Karajan-installed
  * users want to help" assumption — silence and missing config keys both mean
- * "no". The prompt is rendered in the OS locale (EN/ES today; falls back to
- * EN for everything else) so users see it in their own language even before
- * they've set `config.language`. See src/utils/telemetry.js and the
+ * "no". The prompt is English to match the rest of the wizard (KJC-BUG-0088).
+ * See src/utils/telemetry.js and the
  * "Privacy & Telemetry" section of README.md for what gets sent.
  */
 async function askTelemetry(wizard, config, logger) {
-  const locale = detectOsLocale();
-  const prompts = {
-    es: {
-      question: "¿Quieres ayudar a mejorar Karajan enviando telemetría anónima al proyecto?",
-      detail: "  (versión, OS, comandos, duración del pipeline — sin código, sin tareas, sin datos personales)",
-      previewIntro: "  Ejemplo del payload exacto que se enviaría al ejecutar `kj run` (puedes inspeccionar más con `kj telemetry preview`):",
-      enabled: "  -> Telemetría: activada (¡gracias!)",
-      disabled: "  -> Telemetría: desactivada",
-    },
-    en: {
-      question: "Help improve Karajan by sending anonymous telemetry to the project?",
-      detail: "  (version, OS, commands, pipeline duration — no code, no tasks, no personal data)",
-      previewIntro: "  Example of the exact payload that would be sent when you run `kj run` (inspect more with `kj telemetry preview`):",
-      enabled: "  -> Telemetry: enabled (thank you!)",
-      disabled: "  -> Telemetry: disabled",
-    },
+  // English to stay consistent with the rest of the wizard (KJC-BUG-0088); the
+  // user's chosen pipeline/HU language drives `kj run` output, not this prompt.
+  const t = {
+    question: "Help improve Karajan by sending anonymous telemetry to the project?",
+    detail: "  (version, OS, commands, pipeline duration — no code, no tasks, no personal data)",
+    previewIntro: "  Example of the exact payload sent when you run `kj run` (inspect more with `kj telemetry preview`):",
+    enabled: "  -> Telemetry: enabled (thank you!)",
+    disabled: "  -> Telemetry: disabled",
   };
-  const t = prompts[locale] || prompts.en;
   logger.info(t.detail);
   const example = buildTelemetryPayload("cli_command", { version: "x.y.z", command: "run" });
   logger.info(t.previewIntro);
@@ -330,7 +332,7 @@ async function runWizard(config, logger) {
   try {
     const { coder, reviewer } = await askAgents(wizard, available, config, logger);
 
-    const enableTriage = await wizard.confirm("Enable triage (auto-classify task complexity)?", false);
+    const enableTriage = await wizard.confirm("Enable triage (auto-pick a lighter pipeline for simple tasks)?", false);
     config.pipeline.triage = config.pipeline.triage || {};
     config.pipeline.triage.enabled = enableTriage;
     logger.info(`  -> Triage: ${enableTriage ? "enabled" : "disabled"}`);
@@ -339,7 +341,7 @@ async function runWizard(config, logger) {
     config.sonarqube.enabled = enableSonar;
     logger.info(`  -> SonarQube: ${enableSonar ? "enabled" : "disabled"}`);
 
-    const enableHuBoard = await wizard.confirm("Enable HU Board for story tracking?", false);
+    const enableHuBoard = await wizard.confirm("Enable the HU Board — a local web UI to track user stories (HUs)?", false);
     config.hu_board = config.hu_board || {};
     config.hu_board.enabled = enableHuBoard;
     if (enableHuBoard) {
@@ -348,8 +350,19 @@ async function runWizard(config, logger) {
     }
     logger.info(`  -> HU Board: ${enableHuBoard ? "enabled (auto-start on kj run)" : "disabled"}`);
 
-    await askPerRoleProviders(wizard, available, config, { coder, reviewer }, logger);
-    await askFallbackChain(wizard, available, config, { coder, reviewer }, logger);
+    // KJC-TSK-0571: per-role providers + fallback chains are advanced and
+    // collapse a newcomer's first run by ~12 questions. Ask one gate; default
+    // off → every role inherits from coder/reviewer.
+    const advancedRouting =
+      available.length > 1 &&
+      (await wizard.confirm(
+        "Configure advanced agent routing (a different AI per role + fallback chains)? Most users don't need this.",
+        false
+      ));
+    await askPerRoleProviders(wizard, available, config, { coder, reviewer }, logger, advancedRouting);
+    if (advancedRouting) {
+      await askFallbackChain(wizard, available, config, { coder, reviewer }, logger);
+    }
     await askMethodology(wizard, config, logger);
     await askLanguages(wizard, config, logger);
 
@@ -686,16 +699,24 @@ export async function resolveConfigScope({ flags, interactive }) {
   if (flags?.global) return { configPath: getConfigPath(), scope: "global" };
   if (flags?.local) return { configPath: getProjectConfigPath(process.cwd()), scope: "local" };
   if (interactive) {
+    const globalPath = getConfigPath();
+    // KJC-BUG-0087: on a true first run (no global config yet) there is no
+    // meaningful choice — set up the global config and skip a cold question a
+    // newcomer has no context to answer. Only when a global already exists is
+    // "override just for this project?" an actual decision worth asking.
+    if (!(await exists(globalPath))) {
+      return { configPath: globalPath, scope: "global" };
+    }
     const wizard = createWizard();
     try {
       const choice = await wizard.select(
-        "Where do you want to save the config? (default: global)",
+        "You already have a global Karajan config. For this project, do you want to…",
         [
-          { value: "global", label: `Global (${getConfigPath()} — applies to all projects)` },
-          { value: "local",  label: `Local  (${getProjectConfigPath(process.cwd())} — overrides global for this project only)` },
+          { value: "global", label: "Use the global config (your default for every project)" },
+          { value: "local", label: `Override it just for this project (${getProjectConfigPath(process.cwd())})` },
         ]
       );
-      return { configPath: choice === "local" ? getProjectConfigPath(process.cwd()) : getConfigPath(), scope: choice };
+      return { configPath: choice === "local" ? getProjectConfigPath(process.cwd()) : globalPath, scope: choice };
     } finally {
       wizard.close();
     }
@@ -717,7 +738,11 @@ export async function initCommand({ logger, flags = {} }) {
   const reviewRulesPath = path.resolve(karajanDir, "review-rules.md");
   const coderRulesPath = path.resolve(karajanDir, "coder-rules.md");
 
-  const { config, exists: configExists } = await loadConfig();
+  const { config } = await loadConfig();
+  // KJC-BUG-0087: ask "reconfigure?" only when a config exists AT THE CHOSEN
+  // scope path — not when the global cascade has one. Picking local scope in a
+  // fresh dir must not report the unrelated global config as "already exists".
+  const configExists = await exists(configPath);
 
   // Auto-detect language from OS locale for non-interactive mode
   if (!interactive && !configExists) {
@@ -807,7 +832,7 @@ export async function initCommand({ logger, flags = {} }) {
       await installAiTrashHook(logger);
     } else {
       logger.warn("ai-trash kj-trash binary not found — destructive ops unprotected.");
-      logger.warn("  Reinstall karajan-code so kj-trash is on PATH.");
+      logger.warn("  Install karajan-code globally (npm i -g karajan-code) so kj-trash is on PATH.");
     }
   }
 
@@ -864,6 +889,13 @@ export async function initCommand({ logger, flags = {} }) {
     const version = JSON.parse(readFileSync(pkgPath, "utf8")).version;
     sendTelemetryEvent("install", { version }, config).catch(() => {});
   } catch { /* non-blocking */ }
+
+  // Clear close so a first-time user knows setup finished and what to do next,
+  // instead of being left at the end of a wall of detection logs (KJC-BUG-0088).
+  logger.info("");
+  logger.info("✓ Karajan is set up in this project.");
+  logger.info('  Next:  kj run "describe what to build or fix"');
+  logger.info("  More:  kj --help   ·   kj doctor (check your setup)");
 }
 
 // Internal exports for unit testing (KJC-TSK-0367)

package/src/harden/advisory.js

@@ -0,0 +1,168 @@
+/**
+ * advisory — per-artifact comparison engine for `kj harden` advisory mode
+ * (KJC-TSK-0565, épica KJC-PCS-0060). For each artifact harden manages it
+ * classifies the repo state: MISSING (no file nor equivalent), KJ_MANAGED (a
+ * kj:managed block, up to date or outdated vN) or USER_OWNED (the user's own,
+ * possibly in another format). Read-only; never writes or prints. The result
+ * feeds `--report` (Advisory B) / `--interactive` (Advisory C). Per-type
+ * improvement heuristics for USER_OWNED land in the follow-up slice (PR2).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { findManagedBlock } from "../utils/managed-markers.js";
+import { CONFIGS_BY_LANGUAGE, UNIVERSAL_CONFIGS } from "./config-templates.js";
+import { detectStackRoots } from "./stack-roots.js";
+
+const BLOCK_VERSION = 1; // current version every markered config ships at
+
+// Other filenames/formats for the same artifact, so kj never reports a false
+// "missing". `pkgKey` is a package.json field that can hold inline config.
+const EQUIVALENTS = {
+  commitlint: { files: [".commitlintrc", ".commitlintrc.js", ".commitlintrc.json", ".commitlintrc.yaml"], pkgKey: "commitlint" },
+  eslint: { files: ["eslint.config.mjs", ".eslintrc.js", ".eslintrc.cjs", ".eslintrc.json", ".eslintrc.yaml"], pkgKey: "eslintConfig" },
+  prettier: { files: [".prettierrc", ".prettierrc.js", ".prettierrc.yaml", "prettier.config.js"], pkgKey: "prettier" },
+};
+
+// Concrete gains kj's standard would add to a USER_OWNED config, detected by
+// substring probes (no AST parse): each probe absent from the user's content
+// becomes one improvement. Heuristic by design — conservative, never a false
+// "you're missing this" when the signal is clearly present.
+const IMPROVEMENTS = {
+  eslint: [
+    { needle: "no-var", id: "no-var", detail: "bans var (ES2025: const/let)" },
+    { needle: "no-restricted-globals", id: "no-legacy-globals", detail: "bans alert/confirm/prompt, escape/unescape" },
+    { needle: "no-restricted-properties", id: "no-legacy-apis", detail: "bans document.write, substr" },
+  ],
+  commitlint: [
+    { needle: "header-max-length", id: "header-max-length", detail: "caps the commit header at 100 chars" },
+    { needle: "subject-case", id: "subject-case", detail: "enforces a lowercase subject" },
+  ],
+  prettier: [{ needle: "printWidth", id: "print-width", detail: "pins printWidth (consistent wrapping)" }],
+  editorconfig: [
+    { needle: "insert_final_newline", id: "final-newline", detail: "enforces a final newline" },
+    { needle: "charset", id: "charset", detail: "pins charset = utf-8" },
+    { needle: "trim_trailing_whitespace", id: "trim-trailing", detail: "trims trailing whitespace" },
+  ],
+};
+
+/** Improvements kj would add to the user's own config for `artifactId`. */
+function improvementsFor(artifactId, content) {
+  return (IMPROVEMENTS[artifactId] ?? [])
+    .filter((probe) => !content.includes(probe.needle))
+    .map(({ id, detail }) => ({ id, detail }));
+}
+
+/** Build an artifact descriptor from a config-template entry. */
+function toArtifact(cfg) {
+  const id = cfg.blockId ?? "prettier"; // the only marker-less JSON config is prettier
+  return {
+    id,
+    file: cfg.file,
+    blockId: cfg.blockId ?? null,
+    currentVersion: cfg.blockId ? BLOCK_VERSION : null,
+    equivalents: EQUIVALENTS[id]?.files ?? [],
+    pkgKey: EQUIVALENTS[id]?.pkgKey ?? null,
+  };
+}
+
+/** Locate the user's file for an artifact under `searchDir`; null if absent. */
+function findArtifactFile(searchDir, artifact) {
+  for (const rel of [artifact.file, ...artifact.equivalents]) {
+    if (existsSync(join(searchDir, rel))) return rel;
+  }
+  if (artifact.pkgKey && existsSync(join(searchDir, "package.json"))) {
+    try {
+      if (JSON.parse(readFileSync(join(searchDir, "package.json"), "utf8"))[artifact.pkgKey] != null) {
+        return `package.json#${artifact.pkgKey}`;
+      }
+    } catch {
+      /* unreadable package.json → not a match */
+    }
+  }
+  return null;
+}
+
+/** Read the artifact body, or the JSON of an inline package.json key. */
+function readArtifactContent(searchDir, foundAt) {
+  const [file, key] = foundAt.split("#");
+  const raw = readFileSync(join(searchDir, file), "utf8");
+  if (!key) return raw;
+  try {
+    return JSON.stringify(JSON.parse(raw)[key] ?? null);
+  } catch {
+    return raw;
+  }
+}
+
+/** Map a classified state to a recommendation + human rationale. */
+function recommend(state) {
+  if (state.status === "MISSING") return { recommendation: "install", rationale: `kj would add ${state.file}`, mergeable: true };
+  if (state.status === "USER_OWNED") {
+    const n = state.improvements?.length ?? 0;
+    return n === 0
+      ? { recommendation: "keep", rationale: "your own config — already covers the kj standard", mergeable: false }
+      : { recommendation: "review", rationale: `your own config — kj could add ${n} improvement(s)`, mergeable: true };
+  }
+  if (state.upToDate) return { recommendation: "keep", rationale: `managed by kj (v${state.managedVersion}), up to date`, mergeable: false };
+  return { recommendation: "update", rationale: `kj v${state.currentVersion} available (you have v${state.managedVersion})`, mergeable: true };
+}
+
+/** Classify a single artifact found (or not) under `searchDir`. */
+export function classifyArtifact(searchDir, artifact) {
+  const foundAt = findArtifactFile(searchDir, artifact);
+  const base = { foundAt, managedVersion: null, upToDate: null, improvements: [] };
+  let state = { ...base, status: "MISSING" };
+  if (foundAt) {
+    const content = readArtifactContent(searchDir, foundAt);
+    if (artifact.blockId && content.includes(`kj:managed:${artifact.blockId}`)) {
+      const { version } = findManagedBlock(content, artifact.blockId);
+      state = { ...base, status: "KJ_MANAGED", managedVersion: version, upToDate: version != null && version >= artifact.currentVersion };
+    } else {
+      state = { ...base, status: "USER_OWNED", improvements: improvementsFor(artifact.id, content) };
+    }
+  }
+  const head = { id: artifact.id, file: artifact.file, currentVersion: artifact.currentVersion };
+  return { ...head, ...state, ...recommend({ ...state, ...head }) };
+}
+
+/**
+ * Compare the whole repo against the kj standard, artifact by artifact:
+ * universal configs at the root, then each language's lint config inside its
+ * own root (monorepo-aware, mirroring installConfigsForRoots). `minimal`
+ * profile ships no config, so there is nothing to compare.
+ */
+export function compareHarden({ projectDir = process.cwd(), profile = "standard", only = [], exclude = [] } = {}) {
+  if (profile === "minimal") return { artifacts: [] };
+  const artifacts = UNIVERSAL_CONFIGS.map((cfg) => ({ dir: ".", ...classifyArtifact(projectDir, toArtifact(cfg)) }));
+  for (const { dir, language } of detectStackRoots(projectDir, { only, exclude })) {
+    const searchDir = dir === "." ? projectDir : join(projectDir, dir);
+    for (const cfg of CONFIGS_BY_LANGUAGE[language] ?? []) {
+      const res = classifyArtifact(searchDir, toArtifact(cfg));
+      artifacts.push({ dir, ...res, foundAt: res.foundAt && dir !== "." ? join(dir, res.foundAt) : res.foundAt });
+    }
+  }
+  return { artifacts };
+}
+
+const MARK = { install: "+", update: "↑", review: "~", keep: "✓" };
+
+/**
+ * Render a compareHarden() result as human-readable lines (Advisory B). Pure:
+ * returns an array of strings, prints nothing. One line per artifact, indented
+ * bullets for each improvement, then a one-line tally.
+ */
+export function formatAdvisoryReport({ artifacts = [] } = {}) {
+  if (artifacts.length === 0) return ["kj harden — nothing to compare (minimal profile or empty repo)."];
+  const lines = ["kj harden — advisory report (read-only)", ""];
+  const tally = { install: 0, update: 0, review: 0, keep: 0 };
+  for (const a of artifacts) {
+    tally[a.recommendation] = (tally[a.recommendation] ?? 0) + 1;
+    const path = a.foundAt ?? (a.dir === "." ? a.file : join(a.dir, a.file));
+    lines.push(`  ${MARK[a.recommendation] ?? "·"} ${a.recommendation.padEnd(7)} ${path} — ${a.rationale}`);
+    for (const imp of a.improvements ?? []) lines.push(`      • ${imp.detail}`);
+  }
+  lines.push("", `${artifacts.length} artifact(s) · ${tally.install} missing · ${tally.review} to review · ${tally.update} outdated · ${tally.keep} ok`);
+  return lines;
+}

package/src/harden/config-templates.js

@@ -103,10 +103,15 @@ export const JS_CONFIGS = [
 export const PY_CONFIGS = [{ file: "ruff.toml", blockId: "ruff", style: "hash", body: RUFF_BODY }];
 export const GO_CONFIGS = [{ file: ".golangci.yml", blockId: "golangci", style: "hash", body: GOLANGCI_BODY }];
 
+// PHPStan static analysis — the PHP analogue of ruff/golangci.
+export const PHPSTAN_BODY = ["parameters:", "  level: 6", "  paths:", "    - src", "    - tests"].join("\n");
+export const PHP_CONFIGS = [{ file: "phpstan.neon", blockId: "phpstan", style: "hash", body: PHPSTAN_BODY }];
+
 /** Lint/format configs by detected language. Unknown ⇒ universal only. */
 export const CONFIGS_BY_LANGUAGE = {
   javascript: JS_CONFIGS,
   typescript: JS_CONFIGS,
   python: PY_CONFIGS,
   go: GO_CONFIGS,
+  php: PHP_CONFIGS,
 };

package/src/harden/hook-commands.js

@@ -12,6 +12,11 @@
 export const COMMANDS_BY_LANGUAGE = {
   python: { lint: "ruff check .", format: "ruff format --check .", test: "pytest" },
   go: { lint: "go vet ./...", format: 'test -z "$(gofmt -l .)"', test: "go test ./..." },
+  php: {
+    lint: "vendor/bin/phpstan analyse --no-progress",
+    format: "vendor/bin/php-cs-fixer fix --dry-run --diff",
+    test: "vendor/bin/phpunit",
+  },
 };
 
 /** Native commands for a language, or {} when JS/TS or unknown. */

package/src/harden/interactive.js

@@ -0,0 +1,76 @@
+/**
+ * interactive — `kj harden --interactive` (KJC-TSK-0567, épica KJC-PCS-0060).
+ *
+ * Walks the advisory comparison (Advisory A/B) and asks, artifact by artifact,
+ * whether to apply the kj standard — with a safe default of leaving the user's
+ * own config untouched. Only the pieces the user says yes to are written:
+ *
+ *   MISSING                  → add it?      (default yes — same as seed-if-absent)
+ *   KJ_MANAGED outdated      → update it?   (default yes)
+ *   USER_OWNED w/ gaps       → adopt kj's?  (default NO — keep yours)
+ *
+ * The full merge (user's config + kj rules) is out of scope here (v2): adopt
+ * replaces the file with kj's standard. `ask` is injected so the flow is
+ * testable without a TTY; the CLI passes a readline-backed confirm.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { upsertManagedBlock } from "../utils/managed-markers.js";
+import { compareHarden } from "./advisory.js";
+import { CONFIGS_BY_LANGUAGE, UNIVERSAL_CONFIGS } from "./config-templates.js";
+
+const BLOCK_VERSION = 1; // mirrors config-engine.js
+
+// Artifact id (blockId, or "prettier" for the marker-less JSON) → its template.
+const TEMPLATE_BY_ID = new Map();
+for (const cfg of [...UNIVERSAL_CONFIGS, ...Object.values(CONFIGS_BY_LANGUAGE).flat()]) {
+  TEMPLATE_BY_ID.set(cfg.blockId ?? "prettier", cfg);
+}
+
+/** What to ask (and do) for one classified artifact; null = nothing to offer. */
+export function decideAction(a) {
+  if (a.recommendation === "install") return { action: "add", defaultYes: true, prompt: `Add ${a.file}? (${a.rationale})` };
+  if (a.recommendation === "update") return { action: "update", defaultYes: true, prompt: `Update ${a.file} to kj v${a.currentVersion}?` };
+  if (a.recommendation === "review") {
+    return { action: "adopt", defaultYes: false, prompt: `Adopt kj's ${a.file}? Replaces yours, adds ${a.improvements.length} improvement(s). Default keeps yours.` };
+  }
+  return null; // keep / up-to-date — nothing to ask
+}
+
+/** Write an artifact's kj body. `overwrite` discards the user's file (adopt). */
+function applyArtifact(projectDir, dir, cfg, { overwrite }) {
+  const target = join(projectDir, dir === "." ? "" : dir, cfg.file);
+  mkdirSync(dirname(target), { recursive: true });
+  if (cfg.json) {
+    writeFileSync(target, `${cfg.body}\n`);
+    return;
+  }
+  const source = !overwrite && existsSync(target) ? readFileSync(target, "utf8") : "";
+  const { content } = upsertManagedBlock({ source, blockId: cfg.blockId, version: BLOCK_VERSION, body: cfg.body, style: cfg.style });
+  writeFileSync(target, content);
+}
+
+/**
+ * Run the interactive adoption flow. `ask(prompt, defaultYes) → Promise<bool>`.
+ * Returns the list of applied artifacts. Writes nothing the user declines.
+ */
+export async function interactiveHarden({ projectDir = process.cwd(), profile = "standard", only = [], exclude = [], ask, logger = console } = {}) {
+  const { artifacts } = compareHarden({ projectDir, profile, only, exclude });
+  const applied = [];
+  for (const a of artifacts) {
+    const plan = decideAction(a);
+    if (!plan) continue;
+    const yes = await ask(plan.prompt, plan.defaultYes);
+    if (!yes) continue;
+    const cfg = TEMPLATE_BY_ID.get(a.id);
+    if (!cfg) continue;
+    applyArtifact(projectDir, a.dir, cfg, { overwrite: plan.action === "adopt" });
+    const where = a.dir === "." ? a.file : join(a.dir, a.file);
+    applied.push({ file: where, action: plan.action });
+    logger.info?.(`  ✓ ${plan.action} ${where}`);
+  }
+  if (applied.length === 0) logger.info?.("kj harden — nothing applied (kept everything as-is).");
+  return { ok: true, interactive: true, applied };
+}

package/src/harden/stack-roots.js

@@ -21,9 +21,38 @@ const IGNORE_DIRS = new Set([
   "target",
   "__pycache__",
   "venv",
+  // Auxiliary code that isn't the app to harden (KJC-TSK-0564): demo/fixture
+  // dirs ship their own throwaway manifests and must not seed lint/CI config.
+  "examples",
+  "example",
+  "fixtures",
+  "samples",
+  "third_party",
+  "testdata",
+  "__fixtures__",
 ]);
 const DEFAULT_MAX_DEPTH = 2;
 
+/**
+ * Minimal glob for harden scope flags — no dynamic RegExp (eslint security).
+ * Matches on exact equality, directory prefix (`wrappers` ⊇ `wrappers/python`)
+ * and `*` wildcards anchored at both ends unless the `*` is leading/trailing.
+ */
+export function matchesGlob(value, pattern) {
+  if (value === pattern || value.startsWith(`${pattern}/`)) return true;
+  if (!pattern.includes("*")) return false;
+  const pieces = pattern.split("*");
+  let idx = 0;
+  for (let i = 0; i < pieces.length; i += 1) {
+    const piece = pieces[i];
+    if (!piece) continue;
+    const at = value.indexOf(piece, idx);
+    if (at === -1 || (i === 0 && at !== 0)) return false;
+    idx = at + piece.length;
+  }
+  return pattern.endsWith("*") || value.length === idx;
+}
+
 /** Identify the language of a single directory by its manifest files. */
 export function languageAt(dir) {
   if (existsSync(join(dir, "package.json"))) {
@@ -39,10 +68,11 @@ export function languageAt(dir) {
   }
   if (["pyproject.toml", "requirements.txt", "setup.py"].some((f) => existsSync(join(dir, f)))) return "python";
   if (existsSync(join(dir, "go.mod"))) return "go";
+  if (existsSync(join(dir, "composer.json"))) return "php";
   return null;
 }
 
-export function detectStackRoots(projectDir, { maxDepth = DEFAULT_MAX_DEPTH } = {}) {
+export function detectStackRoots(projectDir, { maxDepth = DEFAULT_MAX_DEPTH, only = [], exclude = [] } = {}) {
   const found = [];
   function walk(dir, depth) {
     const language = languageAt(dir);
@@ -68,7 +98,8 @@ export function detectStackRoots(projectDir, { maxDepth = DEFAULT_MAX_DEPTH } =
     const cur = byLanguage.get(f.language);
     if (!cur || f.depth < cur.depth) byLanguage.set(f.language, f);
   }
-  return [...byLanguage.values()]
-    .map(({ dir, language }) => ({ dir, language }))
-    .sort((a, b) => a.dir.localeCompare(b.dir));
+  let roots = [...byLanguage.values()].map(({ dir, language }) => ({ dir, language }));
+  if (only.length) roots = roots.filter((r) => only.some((o) => matchesGlob(r.dir, o)));
+  if (exclude.length) roots = roots.filter((r) => !exclude.some((g) => matchesGlob(r.dir, g)));
+  return roots.sort((a, b) => a.dir.localeCompare(b.dir));
 }

package/src/harden/workflow-templates.js

@@ -78,6 +78,14 @@ const QUALITY_BY_LANGUAGE = {
     "      - run: go vet ./...",
     "      - run: go test ./...",
   ]),
+  php: header([
+    "      - uses: shivammathur/setup-php@v2",
+    "        with:",
+    "          php-version: '8.3'",
+    "      - run: composer install --no-interaction --no-progress",
+    "      - run: vendor/bin/phpstan analyse --no-progress",
+    "      - run: vendor/bin/phpunit",
+  ]),
 };
 QUALITY_BY_LANGUAGE.typescript = QUALITY_BY_LANGUAGE.javascript;
 

package/src/utils/squeezr-detect.js

@@ -8,7 +8,10 @@ export async function detectSqueezr() {
   try {
     const result = await runCommand("squeezr", ["--version"]);
     if (result.exitCode === 0) {
-      const version = (result.stdout || "").trim() || null;
+      // `squeezr --version` may append an "update available" banner box; keep
+      // just the semver so callers never render that noise (KJC-BUG-0088).
+      const raw = (result.stdout || "").trim();
+      const version = raw.match(/\d+\.\d+\.\d+[\w.-]*/)?.[0] || raw.split("\n")[0].trim() || null;
       return { available: true, version };
     }
     return { available: false, version: null };