karajan-code 3.4.1 → 3.5.0

package/README.md

@@ -23,7 +23,7 @@
 
 ---
 
-> **v3.4.1 released** — Post-Phase-1 hardening. The session journal (Cache hits, budget, commits) is now written on EVERY run ending — not just approved ones; the audit role reports its cached tokens (it was the most expensive role and reported 0); and a new preflight check fails fast with an actionable message when Sonar cannot derive a project key, instead of burning coder iterations and dying in `sonar_repeat`. Plus the top of the v3.4.0 self-audit: shared `escapeRegExp()`, 23 dead exports pruned, 4 complex regexes decomposed, and the HU Board API with zero sync fs calls + mtime-cached plan scans. Full notes in [CHANGELOG.md](CHANGELOG.md).
+> **v3.5.0 released** — Quality harness: `kj harden` brings the guardrails Karajan was built with to any repo in one command — idempotent git hooks, lint/format/commit config, CI quality gates and agent guidelines, all stack-aware and behind `kj:managed` markers that never overwrite your content. Native per-language hook commands mean hardening a Go/Python/Java repo never makes Node a commit-time dependency. `kj check` verifies the harness as a CI drift gate, and `kj init` installs it out of the box. Full notes in [CHANGELOG.md](CHANGELOG.md).
 
 You describe what you want to build. Karajan orchestrates multiple AI agents to plan it, implement it, test it, review it with SonarQube, and iterate. No babysitting required.
 

package/node_modules/@karajan/core/package.json

@@ -27,11 +27,22 @@
   "scripts": {
     "test": "vitest run"
   },
-  "dependencies": {
+  "peerDependencies": {
     "better-sqlite3": "^12.10.0",
     "execa": "^9.6.0",
     "sqlite-vec": "^0.1.9"
   },
+  "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    },
+    "execa": {
+      "optional": true
+    },
+    "sqlite-vec": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "vitest": "^4.0.0"
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -71,7 +71,9 @@
     "typecheck": "npx -p typescript@5 tsc --noEmit -p tsconfig.json",
     "validate": "npm run lint && npm run lint:syntax && npm test",
     "mcp": "node src/mcp/server.js",
-    "audit:test-diet": "node scripts/audit-test-diet.mjs"
+    "audit:test-diet": "node scripts/audit-test-diet.mjs",
+    "verify-pack": "node scripts/verify-pack.mjs",
+    "prepublishOnly": "node scripts/verify-pack.mjs"
   },
   "simple-git-hooks": {
     "pre-commit": "npx lint-staged"

package/scripts/verify-pack.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * Pre-publish tarball smoke gate (KJC-TSK-0553).
+ *
+ * WHY: the test suite runs against the linked workspace, where
+ * `@karajan/core` and its deps resolve via symlink — so a broken
+ * PUBLISHED artifact (bundleDependencies dragging in sqlite-vec without
+ * its entry point, KJC-BUG-0082 / 0086) passed CI yet failed on every
+ * clean `npm install`. v3.2.0, v3.3.0 and v3.4.1 all shipped unable to
+ * run even `kj --version`.
+ *
+ * WHAT: pack the real tarball, install it into an isolated tmpdir
+ * (outside the repo, with CLAUDECODE stripped), and assert the binary
+ * actually starts and its native-ish deps resolve. Exit non-zero on any
+ * failure so `prepublishOnly` aborts the publish and CI blocks the PR.
+ *
+ * `npm pack` fires prepack/postpack, NOT prepublishOnly — so invoking
+ * this from prepublishOnly does not recurse.
+ */
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8"));
+const expectedVersion = pkg.version;
+
+// Subprocess env: strip CLAUDECODE (Claude Code blocks nested non-interactive
+// runs otherwise) and force a non-interactive, quiet npm.
+const { CLAUDECODE: _omit, ...cleanEnv } = process.env;
+const childEnv = { ...cleanEnv, npm_config_yes: "true", CI: "1" };
+
+function run(cmd, args, opts = {}) {
+  return execFileSync(cmd, args, {
+    encoding: "utf8",
+    env: childEnv,
+    stdio: ["ignore", "pipe", "pipe"],
+    ...opts,
+  });
+}
+
+function fail(msg, detail) {
+  console.error(`\n✗ verify-pack: ${msg}`);
+  if (detail) console.error(String(detail).split("\n").slice(0, 20).join("\n"));
+  process.exit(1);
+}
+
+let tgzPath = null;
+let tmpDir = null;
+try {
+  console.log(`verify-pack: packing karajan-code@${expectedVersion}…`);
+  // --json gives us the exact filename without parsing human output.
+  const packOut = run("npm", ["pack", "--json", "--silent"], { cwd: repoRoot });
+  const filename = JSON.parse(packOut)[0]?.filename;
+  if (!filename) fail("npm pack did not report a filename", packOut);
+  // npm normalizes scoped names in --json but karajan-code is unscoped;
+  // the file lands in cwd under the reported name.
+  tgzPath = path.join(repoRoot, filename);
+  if (!fs.existsSync(tgzPath)) fail(`packed tarball not found at ${tgzPath}`);
+
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "kj-verify-pack-"));
+  console.log(`verify-pack: installing the tarball into ${tmpDir} (clean, isolated)…`);
+  run("npm", ["install", tgzPath, "--no-audit", "--no-fund", "--silent", "--prefix", tmpDir], {
+    cwd: tmpDir,
+  });
+
+  const binPath = path.join(tmpDir, "node_modules", ".bin", "kj");
+  if (!fs.existsSync(binPath)) fail(`kj binary missing after install: ${binPath}`);
+
+  // 1. kj --version must start AND report the version we just packed.
+  let versionOut;
+  try {
+    versionOut = run(binPath, ["--version"]).trim();
+  } catch (err) {
+    fail("`kj --version` crashed on a clean install", err.stderr || err.message);
+  }
+  if (!versionOut.includes(expectedVersion)) {
+    fail(`kj --version returned "${versionOut}", expected ${expectedVersion}`);
+  }
+  console.log(`verify-pack: kj --version → ${versionOut} ✓`);
+
+  // 2. kj --help must exit 0 (exercises the command tree wiring).
+  try {
+    run(binPath, ["--help"]);
+  } catch (err) {
+    fail("`kj --help` failed on a clean install", err.stderr || err.message);
+  }
+  console.log("verify-pack: kj --help ✓");
+
+  // 3. The deps that broke before must resolve in the installed tree.
+  const installedRoot = path.join(tmpDir, "node_modules", "karajan-code");
+  const checks = [
+    path.join(tmpDir, "node_modules", "sqlite-vec", "index.mjs"),
+    path.join(installedRoot, "node_modules", "@karajan", "core", "src", "vec-store.js"),
+  ];
+  for (const p of checks) {
+    if (!fs.existsSync(p)) fail(`expected resolved path missing in install: ${p}`);
+  }
+  console.log("verify-pack: sqlite-vec + @karajan/core resolve ✓");
+
+  console.log(`\n✓ verify-pack: karajan-code@${expectedVersion} installs clean and runs.`);
+} finally {
+  if (tgzPath && fs.existsSync(tgzPath)) fs.rmSync(tgzPath, { force: true });
+  if (tmpDir && fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+}

package/src/cli/register-meta.js

@@ -14,6 +14,8 @@ import { webperfCommand } from "../commands/webperf.js";
 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 { hardenCommand } from "../commands/harden.js";
 import { telemetryPreviewCommand, telemetryStatusCommand } from "../commands/telemetry.js";
 import { withConfig } from "./_shared.js";
 
@@ -396,4 +398,39 @@ export function registerMeta(program, { pkgVersion }) {
         huDays: flags.huDays ? Number(flags.huDays) : undefined,
       });
     });
+
+  program
+    .command("harden")
+    .description("Install the quality harness (git hooks) into this repo — idempotent")
+    .option("--profile <name>", "minimal | standard | strict", "standard")
+    .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("--dry-run", "Show what would change without writing")
+    .option("--json", "Emit machine-readable JSON")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "harden", flags, async ({ logger }) => {
+        await hardenCommand({
+          profile: flags.profile,
+          config: flags.config !== false,
+          ci: flags.ci !== false,
+          guidelines: flags.guidelines !== false,
+          dryRun: Boolean(flags.dryRun),
+          json: Boolean(flags.json),
+          logger,
+        });
+      });
+    });
+
+  program
+    .command("check")
+    .description("Verify the quality harness installed by kj harden (drift gate)")
+    .option("--profile <name>", "minimal | standard | strict", "standard")
+    .option("--json", "Emit machine-readable JSON")
+    .action(async (flags) => {
+      const code = await withConfig(pkgVersion, "check", flags, async ({ logger }) =>
+        checkCommand({ profile: flags.profile, json: Boolean(flags.json), logger })
+      );
+      if (Number.isInteger(code)) process.exit(code);
+    });
 }

package/src/cli/register-pipeline.js

@@ -30,6 +30,7 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--no-rtk", "Skip the RTK auto-install (token savings on Bash outputs). Karajan still runs but burns more tokens")
     .option("--no-squeezr", "Skip the Squeezr auto-install (context compression). Karajan still runs but burns more tokens")
     .option("--no-qmd", "Skip the QMD auto-install + collection registration (semantic wiki over docs/, .reviews/ and plans/)")
+    .option("--no-harden", "Skip the quality harness (git hooks, lint/commit config, CI gates, agent guidelines)")
     .action(async (flags) => {
       await withConfig(pkgVersion, "init", flags, async ({ config: _config, logger }) => {
         await initCommand({ logger, flags });

package/src/commands/check.js

@@ -0,0 +1,22 @@
+/**
+ * `kj check` — verify the quality harness installed by `kj harden`
+ * (KJC-TSK-0558). Prints a per-category table and returns an exit code so it
+ * works both locally and as a CI drift gate. `--json` for machine output.
+ */
+
+import { checkHarden } from "../harden/check.js";
+
+export async function checkCommand({ projectDir = process.cwd(), profile = "standard", json = false, logger = console } = {}) {
+  const result = await checkHarden({ projectDir, profile });
+
+  if (json) {
+    logger.info?.(JSON.stringify(result));
+    return result.ok ? 0 : 1;
+  }
+
+  logger.info?.(`kj check (${profile})`);
+  for (const c of result.checks) logger.info?.(`  ${c.ok ? "✓" : "✗"} ${c.id}: ${c.detail}`);
+  if (!result.ok) logger.info?.("Harness drift detected — run `kj harden` to repair.");
+  else logger.info?.("Harness OK.");
+  return result.ok ? 0 : 1;
+}

package/src/commands/harden.js

@@ -0,0 +1,107 @@
+/**
+ * `kj harden` — install the quality harness (git hooks) into any repo.
+ *
+ * Thin CLI layer over harden-engine (KJC-TSK-0555): resolves stack-aware
+ * lint/format/test commands, runs the installer and reports. Config files
+ * (eslint/prettier) and CI gates land in later slices (H-C / H-D).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { installConfigsForRoots } from "../harden/config-engine.js";
+import { installGuidelines } from "../harden/guidelines-engine.js";
+import { commandsForLanguage } from "../harden/hook-commands.js";
+import { installHooks } from "../harden/harden-engine.js";
+import { detectStackRoots } from "../harden/stack-roots.js";
+import { installWorkflows } from "../harden/workflow-engine.js";
+import { detectTestFramework } from "../utils/project-detect.js";
+
+const JS_TEST_CMD = {
+  vitest: "npx vitest run",
+  jest: "npx jest",
+  mocha: "npx mocha",
+};
+
+/**
+ * Resolve the hook's lint/format/test commands for the primary language.
+ * Non-JS stacks use their native toolchain (go/ruff/…); JS/TS is built from
+ * the project's own package.json scripts so no npm command is ever assumed.
+ */
+export async function resolveCmds(projectDir, language) {
+  const lang = language ?? detectStackRoots(projectDir)[0]?.language ?? null;
+  const cmds = { ...commandsForLanguage(lang) };
+  if (lang !== "javascript" && lang !== "typescript") return cmds;
+
+  const pkgPath = join(projectDir, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const scripts = JSON.parse(readFileSync(pkgPath, "utf8")).scripts ?? {};
+      if (scripts.lint) cmds.lint = "npm run -s lint";
+      if (scripts["format:check"]) cmds.format = "npm run -s format:check";
+      else if (scripts.format) cmds.format = "npm run -s format";
+      if (scripts.test) cmds.test = "npm test";
+    } catch {
+      /* unreadable package.json → fall back to framework detection */
+    }
+  }
+  if (!cmds.test) {
+    const { framework } = await detectTestFramework(projectDir);
+    if (framework && JS_TEST_CMD[framework]) cmds.test = JS_TEST_CMD[framework];
+  }
+  return cmds;
+}
+
+export async function hardenCommand({
+  projectDir = process.cwd(),
+  profile = "standard",
+  config = true,
+  ci = true,
+  guidelines = true,
+  dryRun = false,
+  json = false,
+  logger = console,
+} = {}) {
+  const roots = detectStackRoots(projectDir);
+  const cmds = await resolveCmds(projectDir, roots[0]?.language ?? null);
+  let result;
+  try {
+    result = await installHooks({ projectDir, profile, cmds, dryRun });
+  } catch (err) {
+    if (json) logger.info?.(JSON.stringify({ ok: false, error: err.message }));
+    else logger.error?.(`kj harden: ${err.message}`);
+    return { ok: false, error: err.message };
+  }
+
+  // Config (lint/format/commit) ships with standard+, per language root so a
+  // fullstack monorepo is hardened on every side, not just one.
+  const withConfig = config && profile !== "minimal";
+  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 })
+    : null;
+  const withGuidelines = guidelines && profile !== "minimal";
+  const gl = withGuidelines ? installGuidelines({ projectDir, dryRun }) : null;
+  const out = {
+    ok: true,
+    ...result,
+    configs: cfg?.configs ?? [],
+    workflows: wf?.workflows ?? [],
+    guidelines: gl?.guidelines ?? [],
+  };
+
+  if (json) {
+    logger.info?.(JSON.stringify(out));
+    return out;
+  }
+
+  const verb = dryRun ? "would install" : "installed";
+  logger.info?.(`kj harden (${profile}) — ${verb} ${result.hooks.length} hook(s) → ${result.hooksPath}`);
+  for (const h of result.hooks) logger.info?.(`  • ${h.hook}: ${h.action}`);
+  for (const c of out.configs) logger.info?.(`  • ${c.file}: ${c.action}`);
+  for (const w of out.workflows) logger.info?.(`  • ${w.file}: ${w.action}`);
+  for (const g of out.guidelines) logger.info?.(`  • ${g.file}: ${g.action}`);
+  if (!dryRun) logger.info?.("core.hooksPath set. Verify later with `kj check` (H-E).");
+  return out;
+}

package/src/commands/init.js

@@ -21,6 +21,8 @@ import { detectAiTrash, installAiTrashHook } from "../utils/ai-trash.js";
 import { detectQmd } from "../utils/qmd-detect.js";
 import { installQmd } from "../utils/qmd-install.js";
 import { registerQmdCollections } from "../utils/qmd-collection.js";
+import { isGitRepo } from "../harden/harden-engine.js";
+import { hardenCommand } from "./harden.js";
 import { detectProjectStack } from "../utils/stack-detect.js";
 import { bootstrapSonarToken } from "../sonar/token-bootstrap.js";
 
@@ -834,6 +836,19 @@ export async function initCommand({ logger, flags = {} }) {
   await setupSonarQube(config, logger, { interactive });
   await scaffoldCiGateway(config, flags, logger);
 
+  // Install the quality harness (git hooks, lint/format/commit config, CI
+  // quality gates, agent guidelines) through the SAME engine as `kj harden`,
+  // so init and harden never drift. Opt-out: --no-harden. Needs a git repo.
+  const skipHarden = flags?.noHarden === true || flags?.harden === false;
+  if (skipHarden) {
+    logger.info("Quality harness skipped (--no-harden).");
+  } else if (isGitRepo(process.cwd())) {
+    logger.info("Installing quality harness (kj harden)...");
+    await hardenCommand({ projectDir: process.cwd(), logger });
+  } else {
+    logger.info("Not a git repository — run `kj harden` after `git init` to add the quality harness.");
+  }
+
   // Persist any changes setupSonarQube made (token, etc.) back to disk.
   // Use writeInitConfig so the deprecated `sonarqube.enabled` key —
   // which setupSonarQube still mutates as an in-memory hint — never

package/src/harden/check.js

@@ -0,0 +1,70 @@
+/**
+ * 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 { 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) {
+      for (const cfg of CONFIGS_BY_LANGUAGE[language] ?? []) {
+        const rel = dir === "." ? cfg.file : join(dir, cfg.file);
+        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,75 @@
+/**
+ * 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 { CONFIGS_BY_LANGUAGE, UNIVERSAL_CONFIGS } from "./config-templates.js";
+
+const BLOCK_VERSION = 1;
+
+function writeFile(target, content) {
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, content);
+}
+
+/** Seed a list of config entries into `targetDir`, labelling each by `prefix`. */
+function seedInto(targetDir, configs, dryRun, prefix, results) {
+  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 (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) {
+    seedInto(join(projectDir, dir), CONFIGS_BY_LANGUAGE[language] ?? [], dryRun, dir, results);
+  }
+  return { dryRun, configs: results };
+}

package/src/harden/config-templates.js

@@ -0,0 +1,112 @@
+/**
+ * Config-file templates for `kj harden` (KJC-TSK-0556).
+ *
+ * Each entry is seeded only when absent (project rule: never overwrite an
+ * existing file); on re-run a kj:managed block is refreshed in place. JSON
+ * formats carry no comment syntax, so they are seed-only (no marker).
+ *
+ * The eslint ES2025 deprecated-API blacklist lands in a follow-up slice.
+ */
+
+export const EDITORCONFIG_BODY = [
+  "root = true",
+  "",
+  "[*]",
+  "charset = utf-8",
+  "end_of_line = lf",
+  "insert_final_newline = true",
+  "trim_trailing_whitespace = true",
+  "indent_style = space",
+  "indent_size = 2",
+].join("\n");
+
+export const PRETTIER_BODY = JSON.stringify(
+  { printWidth: 110, singleQuote: false, trailingComma: "es5", semi: true },
+  null,
+  2
+);
+
+export const COMMITLINT_BODY = [
+  "// Conventional Commits — header <=100 chars, lowercase subject.",
+  "export default {",
+  '  extends: ["@commitlint/config-conventional"],',
+  "  rules: {",
+  '    "header-max-length": [2, "always", 100],',
+  '    "subject-case": [2, "never", ["sentence-case", "start-case", "pascal-case", "upper-case"]],',
+  "  },",
+  "};",
+].join("\n");
+
+// Self-contained flat config (no plugin deps) banning APIs deprecated under
+// an ES2025 target — mirrors the Karajan standard. Seeded only when the
+// project has no eslint config of its own.
+export const ESLINT_BODY = [
+  "export default [",
+  "  {",
+  '    files: ["**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"],',
+  '    languageOptions: { ecmaVersion: 2025, sourceType: "module" },',
+  "    rules: {",
+  '      "no-var": "error",',
+  '      "no-eval": "error",',
+  '      "no-new-func": "error",',
+  '      "no-restricted-globals": [',
+  '        "error",',
+  '        { name: "alert", message: "Use the app modal, not alert()." },',
+  '        { name: "confirm", message: "Use the app modal, not confirm()." },',
+  '        { name: "prompt", message: "Use the app modal, not prompt()." },',
+  '        { name: "escape", message: "Use encodeURIComponent()." },',
+  '        { name: "unescape", message: "Use decodeURIComponent()." },',
+  '        { name: "event", message: "Use the handler parameter, not window.event." },',
+  "      ],",
+  '      "no-restricted-properties": [',
+  '        "error",',
+  '        { object: "document", property: "write", message: "Use DOM nodes / Blob URLs, not document.write." },',
+  '        { object: "document", property: "writeln", message: "Use DOM nodes, not document.writeln." },',
+  '        { property: "substr", message: "Use slice() or substring(), not substr()." },',
+  "      ],",
+  "    },",
+  "  },",
+  "];",
+].join("\n");
+
+// Ruff covers lint + format for Python; `UP` (pyupgrade) is the analogue of
+// the ES2025 deprecated-API ban — it rewrites legacy idioms to modern Python.
+export const RUFF_BODY = [
+  "line-length = 110",
+  'target-version = "py312"',
+  "",
+  "[lint]",
+  'select = ["E", "F", "I", "UP", "B", "SIM"]',
+].join("\n");
+
+export const GOLANGCI_BODY = [
+  "linters:",
+  "  enable:",
+  "    - govet",
+  "    - staticcheck",
+  "    - revive",
+  "    - ineffassign",
+  "    - gofmt",
+].join("\n");
+
+/** Language-agnostic configs (every stack gets these). */
+export const UNIVERSAL_CONFIGS = [
+  { file: ".editorconfig", blockId: "editorconfig", style: "hash", body: EDITORCONFIG_BODY },
+  { file: "commitlint.config.js", blockId: "commitlint", style: "slash", body: COMMITLINT_BODY },
+];
+
+/** `json:true` ⇒ seed-only (no comment syntax for a marker). */
+export const JS_CONFIGS = [
+  { file: "eslint.config.js", blockId: "eslint", style: "slash", body: ESLINT_BODY },
+  { file: ".prettierrc.json", json: true, body: PRETTIER_BODY },
+];
+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 }];
+
+/** 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,
+};