karajan-code 3.4.2 → 3.5.1

package/README.md

@@ -23,7 +23,7 @@
 
 ---
 
-> **v3.4.2 released** — Hotfix: `npm install karajan-code@3.4.1` crashed at `kj --version` because the bundled `@karajan/core` dragged in `sqlite-vec` (which ships `files: []`) without its entry point. `@karajan/core`'s runtime deps are now `peerDependencies`, so they resolve complete from the consumer's top-level install. Clean install verified end-to-end. Full notes in [CHANGELOG.md](CHANGELOG.md).
+> **v3.5.1 released** — PHP joins the quality harness as a first-class language: `kj harden` now detects `composer.json`, installs PHP-native hooks (`phpstan` / `php-cs-fixer` / `phpunit`), a `phpstan.neon` config and a `setup-php` CI workflow — same as JS/Python/Go, no npm/Node imposed at commit time. Builds on v3.5.0's quality harness (`kj harden` + `kj check`): idempotent git hooks, config, CI gates and agent guidelines for any repo, behind `kj:managed` markers. 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "3.4.2",
+  "version": "3.5.1",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

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,117 @@
+/**
+ * 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 }];
+
+// 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/guidelines-engine.js

@@ -0,0 +1,48 @@
+/**
+ * guidelines-engine — seeds AI-agent guideline files for `kj harden`
+ * (KJC-TSK-0559), absorbing dev-hooks' generate_guidelines without an external
+ * MCP. Writes a kj:managed block into AGENTS.md and CLAUDE.md, preserving any
+ * content the user keeps outside the markers. Idempotent.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { upsertManagedBlock } from "../utils/managed-markers.js";
+import { GUIDELINES_BODY } from "./guidelines-templates.js";
+
+const BLOCK_VERSION = 1;
+const TARGETS = ["AGENTS.md", "CLAUDE.md"];
+const DH_START = "<!-- @manufosela/dev-git-hooks:start -->";
+const DH_END = "<!-- @manufosela/dev-git-hooks:end -->";
+
+/** Remove a legacy dev-hooks managed block, preserving everything else. */
+export function stripDevHooksBlock(source) {
+  const s = source.indexOf(DH_START);
+  if (s === -1) return { content: source, migrated: false };
+  const e = source.indexOf(DH_END, s);
+  if (e === -1) return { content: source, migrated: false };
+  const before = source.slice(0, s).replace(/\n+$/, "");
+  const after = source.slice(e + DH_END.length).replace(/^\n+/, "");
+  const joiner = before && after ? "\n\n" : "";
+  return { content: `${before}${joiner}${after}`, migrated: true };
+}
+
+export function installGuidelines({ projectDir = process.cwd(), dryRun = false } = {}) {
+  const results = [];
+  for (const file of TARGETS) {
+    const target = join(projectDir, file);
+    const raw = existsSync(target) ? readFileSync(target, "utf8") : "";
+    const { content: source, migrated } = stripDevHooksBlock(raw);
+    const { content, action } = upsertManagedBlock({
+      source,
+      blockId: "guidelines",
+      version: BLOCK_VERSION,
+      body: GUIDELINES_BODY,
+      style: "html",
+    });
+    if (!dryRun && (migrated || action !== "unchanged")) writeFileSync(target, content);
+    results.push({ file, action: migrated ? "migrated" : action });
+  }
+  return { dryRun, guidelines: results };
+}

package/src/harden/guidelines-templates.js

@@ -0,0 +1,36 @@
+/**
+ * Distilled AI-agent guidelines for `kj harden` (KJC-TSK-0559).
+ *
+ * A compact, high-signal rule set seeded into AGENTS.md / CLAUDE.md inside a
+ * kj:managed block, so it preserves whatever the user wrote outside it. Kept
+ * deliberately short — these rules enter the agent's context on every run, so
+ * bloat dilutes the signal. Distilled from the dev-toolkit guidelines.
+ */
+
+export const GUIDELINES_BODY = [
+  "# Project guidelines (kj harden)",
+  "",
+  "## Code",
+  "- SOLID, DRY, KISS, YAGNI. `const` by default; arrow callbacks; template literals.",
+  "- ES2025 target: never `var`, `document.write`, `alert`/`confirm`/`prompt`, `escape`/`unescape`, `substr`.",
+  "  Prefer modern APIs (`structuredClone`, `Object.groupBy`, `Array.at`/`findLast`/`toSorted`, optional chaining, `??`).",
+  "- ES modules (`import`/`export`), never `require` in new code. Names in English, descriptive.",
+  "- No silent fallbacks: the system works or fails loudly. Validate and sanitize all input.",
+  "",
+  "## Commits & PRs",
+  "- Conventional Commits (`feat:`/`fix:`/`refactor:`/`docs:`/`test:`/`chore:`). Header <=100 chars, lowercase subject.",
+  '- Never attribute commits or PRs to AI (no `Co-Authored-By`, no "generated by").',
+  "- Atomic PRs: one purpose, small (~150 LOC). Each PR compiles and passes its tests on its own.",
+  "",
+  "## Testing",
+  "- Test-first. Run the tests after each meaningful change. Never skip tests.",
+  "",
+  "## Security",
+  "- Never commit secrets, keys or tokens. Parameterized queries; sanitize output against XSS.",
+  "",
+  "## UI/UX",
+  "- No native `alert`/`confirm`/`prompt` — use the app's modal system. Loading states; accessible; mobile-first.",
+  "",
+  "## Files",
+  "- Edit existing files in place; never overwrite a whole file to make a small change.",
+].join("\n");

package/src/harden/harden-engine.js

@@ -0,0 +1,66 @@
+/**
+ * harden-engine — installs kj-managed git hooks idempotently (KJC-TSK-0555).
+ *
+ * Hooks live under `.karajan/hooks/` and are activated via `core.hooksPath`,
+ * so harden never fights husky/simple-git-hooks nor touches `.git/hooks/`.
+ * Each hook is a shebang + a kj:managed block; re-running is a no-op and any
+ * content outside the block is preserved.
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { upsertManagedBlock } from "../utils/managed-markers.js";
+import { runCommand } from "../utils/process.js";
+import { hookBody, PROFILE_HOOKS, SHEBANG } from "./hook-templates.js";
+
+const BLOCK_VERSION = 1;
+const HOOKS_DIR = join(".karajan", "hooks");
+const HOOK_PREAMBLE = `${SHEBANG}\nset -e\n`;
+
+export function isGitRepo(projectDir) {
+  return existsSync(join(projectDir, ".git"));
+}
+
+/**
+ * Install (or refresh) the profile's hooks under `.karajan/hooks/` and point
+ * `core.hooksPath` there. Idempotent. `dryRun` computes actions without
+ * touching disk or git config. `cmds` supplies stack-aware lint/format/test
+ * commands (npm-script defaults). Returns a per-hook action report.
+ */
+export async function installHooks({
+  projectDir = process.cwd(),
+  profile = "standard",
+  cmds = {},
+  dryRun = false,
+} = {}) {
+  if (!isGitRepo(projectDir)) throw new Error(`Not a git repository: ${projectDir}`);
+  const hooks = PROFILE_HOOKS[profile];
+  if (!hooks) throw new Error(`Unknown harden profile: ${profile}`);
+
+  const absHooksDir = join(projectDir, HOOKS_DIR);
+  const results = [];
+  for (const hook of hooks) {
+    const target = join(absHooksDir, hook);
+    const source = existsSync(target) ? readFileSync(target, "utf8") : HOOK_PREAMBLE;
+    const { content, action } = upsertManagedBlock({
+      source,
+      blockId: `hook:${hook}`,
+      version: BLOCK_VERSION,
+      body: hookBody(hook, cmds),
+      style: "hash",
+    });
+    results.push({ hook, target, action });
+    if (!dryRun && action !== "unchanged") {
+      mkdirSync(absHooksDir, { recursive: true });
+      writeFileSync(target, content);
+      chmodSync(target, 0o755);
+    }
+  }
+
+  if (!dryRun) {
+    await runCommand("git", ["config", "core.hooksPath", HOOKS_DIR], { cwd: projectDir });
+  }
+
+  return { profile, hooksPath: HOOKS_DIR, dryRun, hooks: results };
+}

package/src/harden/hook-commands.js

@@ -0,0 +1,25 @@
+/**
+ * Native lint/format/test commands per language for `kj harden` hooks
+ * (KJC-TSK-0562).
+ *
+ * The installed hooks call the project's OWN toolchain, never npm by default,
+ * so hardening a Go/Python repo never drags Node onto a contributor's machine.
+ * JavaScript/TypeScript is built from package.json scripts by the caller (its
+ * commands depend on what the project defines). Unknown language ⇒ no commands,
+ * leaving only the universal POSIX-shell checks.
+ */
+
+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. */
+export function commandsForLanguage(language) {
+  return COMMANDS_BY_LANGUAGE[language] ?? {};
+}

package/src/harden/hook-templates.js

@@ -0,0 +1,69 @@
+/**
+ * Hook bodies + profile→hooks mapping for `kj harden` (KJC-TSK-0555, 0562).
+ *
+ * A body is the MANAGED portion only; harden-engine adds the shebang and the
+ * kj:managed markers around it. Pure POSIX sh — the universal checks (commit
+ * format, AI-attribution) need no toolchain, and lint/format/test lines call
+ * the project's NATIVE commands (from `cmds`), only when present. No npm/Node
+ * is imposed on non-JS repos. See docs/specs/quality-harness.md §5.
+ */
+
+const CONVENTIONAL_TYPES = "feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert";
+const AI_ATTRIBUTION = "co-authored-by:.*(claude|gpt|copilot|gemini)|(generated|written) (by|with) .*(claude|gpt|copilot)";
+
+export const SHEBANG = "#!/usr/bin/env sh";
+
+/** Hooks enabled per profile. */
+export const PROFILE_HOOKS = {
+  minimal: ["commit-msg"],
+  standard: ["pre-commit", "commit-msg", "pre-push", "post-merge"],
+  strict: ["pre-commit", "commit-msg", "pre-push", "post-merge"],
+};
+
+/** Build the managed body for a single hook. */
+export function hookBody(hook, cmds = {}) {
+  switch (hook) {
+    case "pre-commit": {
+      const lines = ["# Lint + format the working tree with the project's native tools."];
+      if (cmds.lint) lines.push(`${cmds.lint} || { echo 'kj harden: lint failed'; exit 1; }`);
+      if (cmds.format) lines.push(`${cmds.format} || { echo 'kj harden: format check failed'; exit 1; }`);
+      if (!cmds.lint && !cmds.format) lines.push("# (no lint/format command detected for this stack)");
+      return lines.join("\n");
+    }
+    case "commit-msg":
+      // Pure POSIX — Conventional Commits header, length cap, AI-attribution.
+      return [
+        'msg_file="$1"',
+        'header=$(head -n1 "$msg_file")',
+        `if ! printf '%s' "$header" | grep -qE '^(${CONVENTIONAL_TYPES})(\\([a-z0-9._-]+\\))?!?: .+'; then`,
+        "  echo 'kj harden: commit header must follow Conventional Commits (type: subject)'; exit 1",
+        "fi",
+        'if [ "${#header}" -gt 100 ]; then echo \'kj harden: commit header exceeds 100 chars\'; exit 1; fi',
+        `if grep -qiE '${AI_ATTRIBUTION}' "$msg_file"; then`,
+        "  echo 'kj harden: AI attribution is not allowed in commit messages'; exit 1",
+        "fi",
+      ].join("\n");
+    case "pre-push": {
+      const lines = [
+        "# Identity guard — never push without a configured git identity.",
+        'if [ -z "$(git config user.email)" ] || [ -z "$(git config user.name)" ]; then',
+        "  echo 'kj harden: git user.name/user.email not set — refusing to push'; exit 1",
+        "fi",
+        'echo "kj harden: pushing as $(git config user.name) <$(git config user.email)>"',
+        "# Run the test suite before pushing.",
+      ];
+      if (cmds.test) lines.push(`${cmds.test} || { echo 'kj harden: tests failed'; exit 1; }`);
+      else lines.push("# (no test command detected for this stack)");
+      return lines.join("\n");
+    }
+    case "post-merge":
+      return [
+        "# Refresh the local RAG index so retrieval never serves stale code.",
+        "if command -v kj >/dev/null 2>&1; then",
+        "  kj rag index --since auto >/dev/null 2>&1 || true",
+        "fi",
+      ].join("\n");
+    default:
+      throw new Error(`Unknown hook: ${hook}`);
+  }
+}

package/src/harden/stack-roots.js

@@ -0,0 +1,75 @@
+/**
+ * detectStackRoots — find every language root in a (possibly monorepo) tree
+ * for `kj harden` (KJC-TSK-0561).
+ *
+ * Walks the project up to a shallow depth and returns the shallowest
+ * directory where each language appears, e.g. a fullstack repo yields
+ * `[{dir:"frontend",language:"javascript"},{dir:"backend",language:"python"}]`
+ * so lint/format config is seeded on each side. Universal config (handled by
+ * the caller) stays at the project root. Noise dirs are never descended.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const IGNORE_DIRS = new Set([
+  "node_modules",
+  "dist",
+  "build",
+  "coverage",
+  "vendor",
+  "target",
+  "__pycache__",
+  "venv",
+]);
+const DEFAULT_MAX_DEPTH = 2;
+
+/** Identify the language of a single directory by its manifest files. */
+export function languageAt(dir) {
+  if (existsSync(join(dir, "package.json"))) {
+    if (existsSync(join(dir, "tsconfig.json"))) return "typescript";
+    try {
+      const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+      if (deps.typescript || deps["ts-node"]) return "typescript";
+    } catch {
+      /* unreadable package.json → treat as plain JS */
+    }
+    return "javascript";
+  }
+  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 } = {}) {
+  const found = [];
+  function walk(dir, depth) {
+    const language = languageAt(dir);
+    if (language) found.push({ dir: relative(projectDir, dir) || ".", language, depth });
+    if (depth >= maxDepth) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.isDirectory() && !e.name.startsWith(".") && !IGNORE_DIRS.has(e.name)) {
+        walk(join(dir, e.name), depth + 1);
+      }
+    }
+  }
+  walk(projectDir, 0);
+
+  // Keep only the shallowest directory per language.
+  const byLanguage = new Map();
+  for (const f of found) {
+    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));
+}

package/src/harden/workflow-engine.js

@@ -0,0 +1,64 @@
+/**
+ * workflow-engine — seeds CI quality workflows for `kj harden` (KJC-TSK-0557).
+ *
+ * Seed-if-absent into `.github/workflows/`: a workflow the user already wrote
+ * (no kj:managed marker) is left untouched and reported "skipped". kj-managed
+ * workflows refresh in place. Markers ride in YAML `#` comments.
+ */
+
+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";
+
+const BLOCK_VERSION = 1;
+const WORKFLOWS_DIR = join(".github", "workflows");
+
+/** A package.json that ships code (not private, has bin or main) ⇒ publishable. */
+export function isPublishableNpm(projectDir) {
+  const pkgPath = join(projectDir, "package.json");
+  if (!existsSync(pkgPath)) return false;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    return pkg.private !== true && Boolean(pkg.bin || pkg.main);
+  } catch {
+    return false;
+  }
+}
+
+export function installWorkflows({
+  projectDir = process.cwd(),
+  language = null,
+  profile = "standard",
+  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 results = [];
+  for (const wf of all) {
+    const target = join(dir, wf.file);
+    const label = join(WORKFLOWS_DIR, wf.file);
+    const exists = existsSync(target);
+    const source = exists ? readFileSync(target, "utf8") : "";
+    if (exists && !source.includes(`kj:managed:${wf.blockId}`)) {
+      results.push({ file: label, action: "skipped" });
+      continue;
+    }
+    const { content, action } = upsertManagedBlock({
+      source,
+      blockId: wf.blockId,
+      version: BLOCK_VERSION,
+      body: wf.body,
+      style: "hash",
+    });
+    if (!dryRun && action !== "unchanged") {
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(target, content);
+    }
+    results.push({ file: label, action });
+  }
+  return { dryRun, workflows: results };
+}

package/src/harden/workflow-templates.js

@@ -0,0 +1,160 @@
+/**
+ * CI workflow templates for `kj harden` (KJC-TSK-0557).
+ *
+ * Generic, language-agnostic GitHub Actions that `kj harden` seeds into a
+ * target repo's `.github/workflows/`. Bodies are plain strings (NOT template
+ * literals) so the `${{ … }}` GitHub expressions survive verbatim.
+ */
+
+// Blocks AI self-attribution in PR commit messages. Pure bash + grep, no Node.
+// Pins github.base_ref to an env var (never interpolated into the run block).
+export const NO_AI_ATTRIBUTION_WORKFLOW = [
+  "name: Block AI attribution",
+  "on:",
+  "  pull_request:",
+  "    branches: [main]",
+  "permissions:",
+  "  contents: read",
+  "jobs:",
+  "  scan:",
+  "    runs-on: ubuntu-latest",
+  "    steps:",
+  "      - uses: actions/checkout@v4",
+  "        with:",
+  "          fetch-depth: 0",
+  "      - name: Scan commit messages for AI attribution",
+  "        env:",
+  "          BASE_REF: ${{ github.base_ref }}",
+  "        run: |",
+  '          msgs=$(git log --format=%B "origin/${BASE_REF}...HEAD" || true)',
+  "          pat='co-authored-by:.*(claude|anthropic|openai|chatgpt|gpt-[0-9]|copilot|gemini|cursor|windsurf|codeium|deepseek)'",
+  "          pat=\"$pat|(generated|written|authored|assisted|powered) (by|with|using) .*(claude|anthropic|openai|copilot|gemini)\"",
+  '          if printf "%s" "$msgs" | grep -qiE "$pat"; then',
+  '            echo "::error::AI attribution detected in commit messages"; exit 1',
+  "          fi",
+  '          echo "AI attribution scan: clean"',
+].join("\n");
+
+/** Universal workflows (every stack). style:hash ⇒ marker in YAML comments. */
+export const WORKFLOWS = [
+  { file: "kj-no-ai-attribution.yml", blockId: "wf-no-ai", body: NO_AI_ATTRIBUTION_WORKFLOW },
+];
+
+const header = (steps) =>
+  [
+    "name: Quality",
+    "on:",
+    "  pull_request:",
+    "    branches: [main]",
+    "jobs:",
+    "  quality:",
+    "    runs-on: ubuntu-latest",
+    "    steps:",
+    "      - uses: actions/checkout@v4",
+    ...steps,
+  ].join("\n");
+
+const QUALITY_BY_LANGUAGE = {
+  javascript: header([
+    "      - uses: actions/setup-node@v4",
+    "        with:",
+    "          node-version: 22",
+    "      - run: npm ci",
+    "      - run: npm run -s lint --if-present",
+    "      - run: npm test",
+  ]),
+  python: header([
+    "      - uses: actions/setup-python@v5",
+    "        with:",
+    "          python-version: '3.12'",
+    "      - run: pip install ruff pytest",
+    "      - run: ruff check .",
+    "      - run: pytest",
+  ]),
+  go: header([
+    "      - uses: actions/setup-go@v5",
+    "        with:",
+    "          go-version: stable",
+    "      - 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;
+
+/** Stack-aware Quality workflow entry, or null for an unknown language. */
+export function qualityWorkflowFor(language) {
+  const body = QUALITY_BY_LANGUAGE[language];
+  return body ? { file: "kj-quality.yml", blockId: "wf-quality", body } : null;
+}
+
+// Caps the net LOC delta of a PR (strict profile only — it is opinionated).
+export const SHRINK_BUDGET_WORKFLOW = [
+  "name: Shrink budget",
+  "on:",
+  "  pull_request:",
+  "    branches: [main]",
+  "permissions:",
+  "  contents: read",
+  "jobs:",
+  "  budget:",
+  "    runs-on: ubuntu-latest",
+  '    env: { LOC_LIMIT: "200" }',
+  "    steps:",
+  "      - uses: actions/checkout@v4",
+  "        with:",
+  "          fetch-depth: 0",
+  "      - name: Net LOC delta within budget",
+  "        env:",
+  "          BASE_REF: ${{ github.base_ref }}",
+  "        run: |",
+  "          d=$(git diff --numstat \"origin/${BASE_REF}...HEAD\" -- . ':!**/*.md' ':!*.lock' ':!package-lock.json' || true)",
+  '          a=$(printf "%s\\n" "$d" | awk \'$1!="-"{s+=$1}END{print s+0}\')',
+  '          r=$(printf "%s\\n" "$d" | awk \'$2!="-"{s+=$2}END{print s+0}\')',
+  '          net=$((a - r)); echo "net=$net (limit=$LOC_LIMIT)"',
+  '          if [ "$net" -gt "$LOC_LIMIT" ]; then echo "::error::PR adds $net net lines (limit $LOC_LIMIT)"; exit 1; fi',
+].join("\n");
+
+// Packs the tarball and installs it clean — only for publishable npm packages.
+export const PACK_SMOKE_WORKFLOW = [
+  "name: Pack smoke",
+  "on:",
+  "  pull_request:",
+  "    branches: [main]",
+  "permissions:",
+  "  contents: read",
+  "jobs:",
+  "  pack-smoke:",
+  "    runs-on: ubuntu-latest",
+  "    steps:",
+  "      - uses: actions/checkout@v4",
+  "      - uses: actions/setup-node@v4",
+  "        with:",
+  "          node-version: 22",
+  "      - run: npm ci",
+  "      - name: Pack and install the tarball clean",
+  "        run: |",
+  "          tgz=$(npm pack --silent)",
+  "          dir=$(mktemp -d)",
+  '          npm install --prefix "$dir" "$PWD/$tgz" --no-audit --no-fund',
+  '          echo "Tarball installs clean: $tgz"',
+].join("\n");
+
+/** Conditional workflows: shrink-budget on strict, pack-smoke when publishable. */
+export function extraWorkflowsFor({ profile = "standard", publishable = false } = {}) {
+  const extras = [];
+  if (profile === "strict") {
+    extras.push({ file: "kj-shrink-budget.yml", blockId: "wf-shrink", body: SHRINK_BUDGET_WORKFLOW });
+  }
+  if (publishable) {
+    extras.push({ file: "kj-pack-smoke.yml", blockId: "wf-pack-smoke", body: PACK_SMOKE_WORKFLOW });
+  }
+  return extras;
+}

package/src/utils/managed-markers.js

@@ -0,0 +1,93 @@
+/**
+ * Managed-markers — idempotent file-block scaffolding for `kj harden`
+ * (KJC-TSK-0555, design in docs/specs/quality-harness.md §4).
+ *
+ * harden owns ONLY the content between a pair of markers; everything else in
+ * the file is preserved verbatim. Re-running with the same input is a no-op.
+ * Generalises the `KJC-TSK-0455` marker already used by the post-merge hook
+ * installer, and honours the project rule "never overwrite existing files".
+ *
+ * Block shape (comment syntax varies by file type):
+ *   # >>> kj:managed:<id> v<N> >>> (do not edit: regenerated by kj harden)
+ *   …managed body…
+ *   # <<< kj:managed:<id> <<<
+ */
+
+const DEFAULT_NOTE = "do not edit: regenerated by kj harden";
+
+/** Wrap marker payload text in the comment syntax for a given style. */
+const COMMENT = {
+  hash: (text) => `# ${text}`,
+  slash: (text) => `// ${text}`,
+  html: (text) => `<!-- ${text} -->`,
+};
+
+/** Pick a comment style from a file path. Defaults to hash (shell/yaml/conf). */
+export function commentStyleFor(filePath = "") {
+  if (/\.(md|markdown|mdx)$/i.test(filePath)) return "html";
+  if (/\.(m?[jt]sx?|c[jt]s)$/i.test(filePath)) return "slash";
+  return "hash";
+}
+
+const openPayload = (blockId, version) => `>>> kj:managed:${blockId} v${version} >>>`;
+const closePayload = (blockId) => `<<< kj:managed:${blockId} <<<`;
+
+/** Render the full managed block (open marker + body + close marker). */
+export function buildManagedBlock({ blockId, version, body, style = "hash", note = DEFAULT_NOTE }) {
+  const comment = COMMENT[style] ?? COMMENT.hash;
+  const open = comment(`${openPayload(blockId, version)} (${note})`);
+  const close = comment(closePayload(blockId));
+  return `${open}\n${body}\n${close}`;
+}
+
+/**
+ * Locate a managed block by id in `source`, regardless of comment style or
+ * version. Returns line indices and the detected version, or { found:false }.
+ */
+export function findManagedBlock(source = "", blockId) {
+  const lines = source.split("\n");
+  const openTag = `>>> kj:managed:${blockId} v`;
+  const closeTag = `<<< kj:managed:${blockId} <<<`;
+  let startLine = -1;
+  let version = null;
+  for (let i = 0; i < lines.length; i += 1) {
+    const at = lines[i].indexOf(openTag);
+    if (at === -1) continue;
+    const rest = lines[i].slice(at + openTag.length);
+    const end = rest.indexOf(" >>>");
+    const digits = end === -1 ? "" : rest.slice(0, end);
+    if (/^\d+$/.test(digits)) {
+      startLine = i;
+      version = Number(digits);
+      break;
+    }
+  }
+  if (startLine === -1) return { found: false };
+  for (let i = startLine + 1; i < lines.length; i += 1) {
+    if (lines[i].includes(closeTag)) return { found: true, startLine, endLine: i, version };
+  }
+  return { found: false, malformed: true, startLine };
+}
+
+/**
+ * Insert or update the managed block for `blockId` in `source`, preserving all
+ * content outside the markers. Idempotent: identical input → action "unchanged".
+ *
+ * @returns {{content: string, action: "inserted"|"updated"|"unchanged", previousVersion: number|null}}
+ */
+export function upsertManagedBlock({ source = "", blockId, version, body, style = "hash", note }) {
+  const block = buildManagedBlock({ blockId, version, body, style, note });
+  const existing = findManagedBlock(source, blockId);
+
+  if (!existing.found) {
+    const base = source === "" ? "" : source.replace(/\n*$/, "\n");
+    return { content: `${base}${block}\n`, action: "inserted", previousVersion: null };
+  }
+
+  const lines = source.split("\n");
+  const before = lines.slice(0, existing.startLine);
+  const after = lines.slice(existing.endLine + 1);
+  const content = [...before, ...block.split("\n"), ...after].join("\n");
+  if (content === source) return { content, action: "unchanged", previousVersion: existing.version };
+  return { content, action: "updated", previousVersion: existing.version };
+}