@karajan-family/code 4.21.0

package/src/guards/policy-resolver.js

@@ -0,0 +1,85 @@
+/**
+ * Policy resolution: map task type + config toggles to concrete pipeline
+ * flags (TDD, Sonar, reviewer retries, tests required, coder required, ...).
+ *
+ * @typedef {import("../types/policy.js").ResolvedPolicies} ResolvedPolicies
+ * @typedef {import("../types/config.js").KarajanConfig} KarajanConfig
+ */
+
+// KJC-TSK-0400: spike y research añadidos como tipos no-code. Comparten
+// las defaults restrictivas (tdd/sonar/testsRequired off) porque NO
+// producen código que medir: un SPIKE es un .md de decisión, un research
+// es una nota de investigación. Forzar Sonar les hace fallar siempre.
+export const VALID_TASK_TYPES = new Set([
+  "sw", "infra", "doc", "add-tests", "refactor",
+  "audit", "analysis", "no-code", "spike", "research",
+]);
+
+export const DEFAULT_POLICIES = {
+  sw:        { tdd: true,  sonar: true,  reviewer: true, testsRequired: true  },
+  infra:     { tdd: false, sonar: false, reviewer: false, testsRequired: false },
+  doc:       { tdd: false, sonar: false, reviewer: true, testsRequired: false },
+  "add-tests": { tdd: false, sonar: true,  reviewer: true, testsRequired: true  },
+  refactor:  { tdd: true,  sonar: true,  reviewer: true, testsRequired: false },
+  audit:     { tdd: false, sonar: false, reviewer: false, testsRequired: false, coderRequired: false },
+  analysis:  { tdd: false, sonar: false, reviewer: false, testsRequired: false, coderRequired: false },
+  "no-code": { tdd: false, sonar: false, reviewer: true, testsRequired: false, coderRequired: true },
+  spike:     { tdd: false, sonar: false, reviewer: true, testsRequired: false, coderRequired: true },
+  research:  { tdd: false, sonar: false, reviewer: true, testsRequired: false, coderRequired: true },
+};
+
+// KJC-TSK-0400: si el title arranca con [SPIKE] / [DOC] / [RESEARCH] /
+// [NOCODE], inferimos el task_type del prefijo. Pensado para casos donde
+// el planner emite task_type='sw' por defecto pero el title declara
+// claramente que la HU no produce código. Devuelve null si no hay match.
+const TITLE_PREFIX_TO_TYPE = {
+  SPIKE: "spike",
+  RESEARCH: "research",
+  DOC: "doc",
+  NOCODE: "no-code",
+  "NO-CODE": "no-code",
+};
+
+export function inferTaskTypeFromTitle(title) {
+  if (typeof title !== "string") return null;
+  const m = title.match(/^\s*\[([A-Z][A-Z-]+)\]/);
+  if (!m) return null;
+  return TITLE_PREFIX_TO_TYPE[m[1].toUpperCase()] || null;
+}
+
+// KJC-TSK-0400: dado un HU del plan, devuelve el task_type efectivo:
+// explícito en story.task_type si es válido, si no inferido del title.
+// Fallback 'sw' (conservador, mantiene gates activos cuando hay duda).
+export function effectiveTaskType(story) {
+  if (!story || typeof story !== "object") return "sw";
+  if (VALID_TASK_TYPES.has(story.task_type)) return story.task_type;
+  return inferTaskTypeFromTitle(story.title) || "sw";
+}
+
+const FALLBACK_TYPE = "sw";
+
+/**
+ * Resolve pipeline policies for a given taskType.
+ * Unknown / null / undefined taskType falls back to "sw" (conservative).
+ * configOverrides optionally merges over defaults per taskType.
+ */
+export function resolvePolicies(taskType, configOverrides) {
+  const resolvedType = VALID_TASK_TYPES.has(taskType) ? taskType : FALLBACK_TYPE;
+  const base = { ...DEFAULT_POLICIES[resolvedType] };
+  const overrides = configOverrides?.[resolvedType];
+  if (overrides && typeof overrides === "object") {
+    Object.assign(base, overrides);
+  }
+  return base;
+}
+
+/**
+ * Resolve policies for a taskType and return a flat object with the resolved
+ * taskType plus all policy flags. This is the main entry point for the
+ * orchestrator to determine which pipeline stages to enable/disable.
+ */
+export function applyPolicies({ taskType, policies } = {}) {
+  const resolvedType = VALID_TASK_TYPES.has(taskType) ? taskType : FALLBACK_TYPE;
+  const resolved = resolvePolicies(taskType, policies);
+  return { taskType: resolvedType, ...resolved };
+}

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/advisory.js

@@ -0,0 +1,203 @@
+/**
+ * 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 { findAlternative } from "./alternatives.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.cjs", ".commitlintrc.mjs", ".commitlintrc.json", ".commitlintrc.yaml", ".commitlintrc.yml", "commitlint.config.mjs", "commitlint.config.cjs", "commitlint.config.ts"], pkgKey: "commitlint" },
+  eslint: { files: ["eslint.config.mjs", "eslint.config.cjs", "eslint.config.ts", "eslint.config.mts", "eslint.config.cts", ".eslintrc.js", ".eslintrc.cjs", ".eslintrc.json", ".eslintrc.yaml", ".eslintrc.yml"], pkgKey: "eslintConfig" },
+  prettier: { files: [".prettierrc", ".prettierrc.js", ".prettierrc.yaml", ".prettierrc.yml", ".prettierrc.json5", ".prettierrc.toml", "prettier.config.js", "prettier.config.mjs", "prettier.config.cjs", "prettier.config.ts"], pkgKey: "prettier" },
+};
+
+/**
+ * KJC-BUG-0119 — same-tool filename variant for `artifactId` in any of
+ * `searchDirs` (file or inline package.json config); null when none exists.
+ * Seeding kj's default filename NEXT TO a variant eclipses the user's real
+ * config (eslint resolves eslint.config.js before .mjs), so config-engine
+ * must consult this before treating an artifact as absent.
+ */
+export function findEquivalentIn(searchDirs, artifactId) {
+  const spec = EQUIVALENTS[artifactId];
+  if (!spec) return null;
+  for (const dir of searchDirs) {
+    for (const rel of spec.files) {
+      if (existsSync(join(dir, rel))) return rel;
+    }
+    if (spec.pkgKey && existsSync(join(dir, "package.json"))) {
+      try {
+        if (JSON.parse(readFileSync(join(dir, "package.json"), "utf8"))[spec.pkgKey] != null) {
+          return `package.json#${spec.pkgKey}`;
+        }
+      } catch {
+        /* unreadable package.json → not a match */
+      }
+    }
+  }
+  return null;
+}
+
+// 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) {
+  if (existsSync(join(searchDir, artifact.file))) return artifact.file;
+  return findEquivalentIn([searchDir], artifact.id);
+}
+
+/** 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 === "SATISFIED_BY_ALTERNATIVE") {
+    return {
+      recommendation: "keep",
+      rationale: `covered by ${state.foundAt} (${state.alternativeTool}) — kj won't add a second linter/formatter`,
+      mergeable: false,
+    };
+  }
+  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`. `altDirs`
+ * widens the cross-tool alternative lookup (a root-level biome.json covers a
+ * monorepo's language roots); the user's OWN config of the same tool still
+ * wins over an alternative.
+ */
+export function classifyArtifact(searchDir, artifact, altDirs = [searchDir]) {
+  const foundAt = findArtifactFile(searchDir, artifact);
+  const base = { foundAt, managedVersion: null, upToDate: null, improvements: [] };
+  let state = { ...base, status: "MISSING" };
+  if (!foundAt) {
+    const alt = findAlternative(altDirs, artifact.id);
+    if (alt) state = { ...base, status: "SATISFIED_BY_ALTERNATIVE", foundAt: alt.foundAt, alternativeTool: alt.tool };
+  }
+  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), [searchDir, projectDir]);
+      // Alternative matches may live at the repo root — keep their path unprefixed.
+      const prefix = res.foundAt && dir !== "." && res.status !== "SATISFIED_BY_ALTERNATIVE";
+      artifacts.push({ dir, ...res, foundAt: prefix ? 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/alternatives.js

@@ -0,0 +1,50 @@
+/**
+ * Cross-tool alternatives for `kj harden` (KJC-TSK-0614).
+ *
+ * A user's Biome config replaces BOTH eslint and prettier — seeding kj's
+ * configs next to biome.json installs a second, conflicting linter/formatter
+ * that fights the user's own hooks. The advisory's EQUIVALENTS map only
+ * covers same-tool filename variants; this map covers whole-tool
+ * substitutions, and the three surfaces (advisory, config-engine, check)
+ * consult it before treating an artifact as missing.
+ *
+ * Detection is config-file based on purpose: deterministic, and a false
+ * negative just means kj proposes its default (the pre-0614 behaviour),
+ * never that it overwrites the user's tool.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const ALTERNATIVES = {
+  eslint: [{ tool: "biome", files: ["biome.json", "biome.jsonc"] }],
+  prettier: [{ tool: "biome", files: ["biome.json", "biome.jsonc"] }],
+};
+
+/**
+ * First alternative tool that satisfies `artifactId`, searching each dir in
+ * order (a language root first, then the repo root — a root-level biome.json
+ * covers the whole monorepo). Null when none applies.
+ *
+ * @param {string[]} searchDirs
+ * @param {string} artifactId - "eslint" | "prettier" | ...
+ * @returns {{ tool: string, foundAt: string }|null}
+ */
+export function findAlternative(searchDirs, artifactId) {
+  for (const alt of ALTERNATIVES[artifactId] ?? []) {
+    for (const dir of searchDirs) {
+      for (const rel of alt.files) {
+        if (existsSync(join(dir, rel))) return { tool: alt.tool, foundAt: rel };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Artifact id for a config-template entry — same convention as the
+ * advisory's toArtifact: prettier is the only marker-less JSON config.
+ */
+export function artifactIdForConfig(cfg) {
+  return cfg.blockId ?? "prettier";
+}

package/src/harden/check.js

@@ -0,0 +1,81 @@
+/**
+ * checkHarden — verify the quality harness installed by `kj harden`
+ * (KJC-TSK-0558). Detects drift: a deleted hook, a hook that lost its kj
+ * marker or its executable bit, or a core.hooksPath that no longer points at
+ * `.karajan/hooks`. Returns a per-check report; the CLI maps it to exit 0/≠0.
+ *
+ * Config, workflow and language-advisory checks land in the next slice.
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { runCommand } from "../utils/process.js";
+import { artifactIdForConfig, findAlternative } from "./alternatives.js";
+import { CONFIGS_BY_LANGUAGE, UNIVERSAL_CONFIGS } from "./config-templates.js";
+import { PROFILE_HOOKS } from "./hook-templates.js";
+import { detectStackRoots } from "./stack-roots.js";
+import { qualityWorkflowFor, WORKFLOWS } from "./workflow-templates.js";
+
+const HOOKS_DIR = join(".karajan", "hooks");
+const WORKFLOWS_DIR = join(".github", "workflows");
+
+/** A config/workflow file just needs to be present (it may be user-owned). */
+function presence(projectDir, rel, id, miss) {
+  const ok = existsSync(join(projectDir, rel));
+  return { id, ok, detail: ok ? "ok" : miss };
+}
+
+export async function checkHarden({ projectDir = process.cwd(), profile = "standard" } = {}) {
+  const checks = [];
+
+  const res = await runCommand("git", ["config", "--local", "core.hooksPath"], { cwd: projectDir });
+  const hooksPath = (res.stdout ?? "").trim();
+  checks.push({
+    id: "core.hooksPath",
+    ok: hooksPath === HOOKS_DIR,
+    detail: hooksPath === HOOKS_DIR ? "ok" : hooksPath || "(unset) — run kj harden",
+  });
+
+  for (const hook of PROFILE_HOOKS[profile] ?? []) {
+    const target = join(projectDir, HOOKS_DIR, hook);
+    const exists = existsSync(target);
+    const executable = exists && (statSync(target).mode & 0o100) !== 0;
+    const marked = exists && readFileSync(target, "utf8").includes(`kj:managed:hook:${hook}`);
+    const detail = !exists ? "missing" : !executable ? "not executable" : !marked ? "no kj marker" : "ok";
+    checks.push({ id: `hook:${hook}`, ok: exists && executable && marked, detail });
+  }
+
+  // Config + workflows ship with standard+ — and surface the greenfield gap:
+  // a language now present but never hardened ⇒ its config shows as missing.
+  if (profile !== "minimal") {
+    const roots = detectStackRoots(projectDir);
+    for (const cfg of UNIVERSAL_CONFIGS) {
+      checks.push(presence(projectDir, cfg.file, `config:${cfg.file}`, "missing — run kj harden"));
+    }
+    for (const { dir, language } of roots) {
+      const rootDir = dir === "." ? projectDir : join(projectDir, dir);
+      for (const cfg of CONFIGS_BY_LANGUAGE[language] ?? []) {
+        const rel = dir === "." ? cfg.file : join(dir, cfg.file);
+        // A config covered by the user's own tool (biome.json ⇒ eslint+prettier)
+        // is not drift — kj must not demand a second linter/formatter (KJC-TSK-0614).
+        if (!existsSync(join(projectDir, rel))) {
+          const alt = findAlternative([rootDir, projectDir], artifactIdForConfig(cfg));
+          if (alt) {
+            checks.push({ id: `config:${rel}`, ok: true, detail: `covered by ${alt.foundAt} (${alt.tool})` });
+            continue;
+          }
+        }
+        checks.push(presence(projectDir, rel, `config:${rel}`, `missing for ${language} — run kj harden`));
+      }
+    }
+    const expectedWf = [...WORKFLOWS];
+    const quality = qualityWorkflowFor(roots[0]?.language ?? null);
+    if (quality) expectedWf.push(quality);
+    for (const wf of expectedWf) {
+      checks.push(presence(projectDir, join(WORKFLOWS_DIR, wf.file), `workflow:${wf.file}`, "missing — run kj harden"));
+    }
+  }
+
+  return { ok: checks.every((c) => c.ok), checks };
+}

package/src/harden/config-engine.js

@@ -0,0 +1,128 @@
+/**
+ * config-engine — seeds/refreshes lint/format/commit config for `kj harden`
+ * (KJC-TSK-0556). Seed-if-absent: a config the user already authored (no
+ * kj:managed marker) is left untouched and reported as "skipped". Markered
+ * files refresh in place; JSON files (no comment syntax) are seed-only.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { upsertManagedBlock } from "../utils/managed-markers.js";
+import { findEquivalentIn } from "./advisory.js";
+import { artifactIdForConfig, findAlternative } from "./alternatives.js";
+import { CONFIGS_BY_LANGUAGE, UNIVERSAL_CONFIGS } from "./config-templates.js";
+
+const BLOCK_VERSION = 1;
+
+// KJC-BUG-0137 (issue #1357): is the tool a config demands actually installed?
+// Declared dependency or a resolvable bin both count; an unreadable
+// package.json is no evidence of the tool.
+function hasTool(dirs, tool) {
+  for (const d of dirs) {
+    if (existsSync(join(d, "node_modules", ".bin", tool))) return true;
+    const pkgPath = join(d, "package.json");
+    if (!existsSync(pkgPath)) continue;
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+      if (pkg.devDependencies?.[tool] || pkg.dependencies?.[tool]) return true;
+    } catch {
+      /* unreadable ⇒ keep looking */
+    }
+  }
+  return false;
+}
+
+function writeFile(target, content) {
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, content);
+}
+
+/**
+ * Seed a list of config entries into `targetDir`, labelling each by `prefix`.
+ * `altDirs` widens the cross-tool alternative lookup (KJC-TSK-0614): a config
+ * covered by the user's own tool (biome.json ⇒ eslint+prettier) is never
+ * seeded — kj must not install a second, conflicting linter/formatter.
+ */
+function seedInto(targetDir, configs, dryRun, prefix, results, altDirs = [targetDir]) {
+  for (const cfg of configs) {
+    const target = join(targetDir, cfg.file);
+    const exists = existsSync(target);
+    const file = prefix === "." ? cfg.file : join(prefix, cfg.file);
+
+    if (!exists) {
+      const alt = findAlternative(altDirs, artifactIdForConfig(cfg));
+      if (alt) {
+        results.push({ file, action: "covered", by: alt.foundAt });
+        continue;
+      }
+      // KJC-BUG-0119: a same-tool variant (eslint.config.mjs, .eslintrc.json,
+      // package.json#eslintConfig…) means the config already EXISTS — seeding
+      // kj's default filename next to it would silently ECLIPSE the user's
+      // real config (eslint resolves eslint.config.js before .mjs).
+      const variant = findEquivalentIn(altDirs, artifactIdForConfig(cfg));
+      if (variant) {
+        results.push({ file, action: "covered", by: variant });
+        continue;
+      }
+      // KJC-BUG-0137: no tool ⇒ no config — report the actionable gap instead.
+      if (cfg.requires && !hasTool(altDirs, cfg.requires)) {
+        results.push({
+          file,
+          action: "omitted",
+          note: `${cfg.requires} is not installed — npm i -D ${cfg.requires}, then re-run kj harden`,
+        });
+        continue;
+      }
+    }
+
+    if (cfg.json) {
+      const action = exists ? "skipped" : "inserted";
+      if (!dryRun && !exists) writeFile(target, `${cfg.body}\n`);
+      results.push({ file, action });
+      continue;
+    }
+
+    const source = exists ? readFileSync(target, "utf8") : "";
+    if (exists && !source.includes(`kj:managed:${cfg.blockId}`)) {
+      results.push({ file, action: "skipped" });
+      continue;
+    }
+    const { content, action } = upsertManagedBlock({
+      source,
+      blockId: cfg.blockId,
+      version: BLOCK_VERSION,
+      body: cfg.body,
+      style: cfg.style,
+    });
+    if (!dryRun && action !== "unchanged") writeFile(target, content);
+    results.push({ file, action });
+  }
+}
+
+/**
+ * Single-directory seed: universal (.editorconfig, commitlint) plus the
+ * language's lint/format config, all at `projectDir`. Unknown language ⇒
+ * universal only. `dryRun` computes actions without writing.
+ */
+export function installConfigs({ projectDir = process.cwd(), language = "javascript", dryRun = false } = {}) {
+  const results = [];
+  seedInto(projectDir, [...UNIVERSAL_CONFIGS, ...(CONFIGS_BY_LANGUAGE[language] ?? [])], dryRun, ".", results);
+  return { dryRun, configs: results };
+}
+
+/**
+ * Monorepo seed: universal config once at the root, then each language's
+ * lint/format config inside its own root (from detectStackRoots). A fullstack
+ * repo gets eslint in frontend/, ruff in backend/, etc.
+ */
+export function installConfigsForRoots({ projectDir = process.cwd(), roots = [], dryRun = false } = {}) {
+  const results = [];
+  seedInto(projectDir, UNIVERSAL_CONFIGS, dryRun, ".", results);
+  for (const { dir, language } of roots) {
+    const rootDir = join(projectDir, dir);
+    // A root-level biome.json covers every language root of the monorepo.
+    seedInto(rootDir, CONFIGS_BY_LANGUAGE[language] ?? [], dryRun, dir, results, [rootDir, projectDir]);
+  }
+  return { dryRun, configs: results };
+}