@karajan-family/code 4.21.0

package/src/harden/config-templates.js

@@ -0,0 +1,122 @@
+/**
+ * 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). `requires` names
+ * the tool the config is for: absent from the project ⇒ the config is omitted
+ * with the install command in the report (KJC-BUG-0137) — a config without its
+ * tool is decorative, and kj never generates a demand it didn't satisfy.
+ */
+export const JS_CONFIGS = [
+  { file: "eslint.config.js", blockId: "eslint", style: "slash", body: ESLINT_BODY, requires: "eslint" },
+  { file: ".prettierrc.json", json: true, body: PRETTIER_BODY, requires: "prettier" },
+];
+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,80 @@
+/**
+ * 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,
+  baseBranch = null,
+} = {}) {
+  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}`);
+
+  // KJC-TSK-0645: setting a repo-local hooksPath ECLIPSES the machine's
+  // global hooks dir — personal guards (AI-attribution commit-msg, protected
+  // branch pre-push) would silently stop applying here. Detect the previous
+  // global dir and have every generated hook chain to it. `~` is emitted as
+  // `$HOME` so the committed hook stays portable across machines (the -x
+  // guard silences it where the dir doesn't exist).
+  let globalHooksDir = null;
+  const globalCfg = await runCommand("git", ["config", "--global", "core.hooksPath"], { cwd: projectDir });
+  const rawGlobal = globalCfg.exitCode === 0 ? globalCfg.stdout.trim() : "";
+  if (rawGlobal && rawGlobal !== HOOKS_DIR) {
+    globalHooksDir = rawGlobal.startsWith("~") ? `$HOME${rawGlobal.slice(1)}` : rawGlobal;
+  }
+
+  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, { globalHooksDir, baseBranch }),
+      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/harness-hooks.js

@@ -0,0 +1,107 @@
+/**
+ * harness-hooks — the TOOL gate (KJC-TSK-0710, from proposal KJC-PRP-0013).
+ * Field case 2026-08-02: text rules were not enough — the environment must
+ * impose them AT TOOL TIME. `kj harden` writes a PreToolUse script and wires
+ * it into the project's `.claude/settings.json` (merged, never clobbered):
+ * Write over an existing file blocks ("use Edit", KJ_ALLOW_WRITE=1 escapes);
+ * Bash that reserializes whole JSON files blocks (KJ_ALLOW_REWRITE=1).
+ * Claude-only v1 — the abstraction arrives with the second host that
+ * supports tool hooks.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const SCRIPT_BODY = `#!/usr/bin/env node
+// kj tool gate (KJC-TSK-0710) — managed by \`kj harden\`. Exit 2 blocks the
+// tool call (stderr explains why); anything unexpected fails OPEN (exit 0)
+// so a gate bug never bricks the session.
+import { existsSync } from "node:fs";
+let raw = "";
+process.stdin.on("data", (d) => { raw += d; });
+process.stdin.on("end", () => {
+  try {
+    const { tool_name: tool, tool_input: input = {} } = JSON.parse(raw);
+    if (tool === "Write" && process.env.KJ_ALLOW_WRITE !== "1") {
+      if (input.file_path && existsSync(input.file_path)) {
+        console.error("kj tool gate: Write over an EXISTING file destroys unseen changes — use Edit for targeted changes (KJ_ALLOW_WRITE=1 to override consciously).");
+        process.exit(2);
+      }
+    }
+    if (tool === "Bash" && process.env.KJ_ALLOW_REWRITE !== "1") {
+      const cmd = String(input.command || "");
+      const writes = /open\\s*\\([^)]*["'][wa]["']|>\\s*\\S+\\.json\\b/.test(cmd);
+      if (/json\\.dumps?\\s*\\(/.test(cmd) && writes) {
+        console.error("kj tool gate: reserializing a whole JSON file makes the diff unreviewable — make targeted edits instead (KJ_ALLOW_REWRITE=1 to override consciously).");
+        process.exit(2);
+      }
+    }
+  } catch { /* fail open */ }
+  process.exit(0);
+});
+`;
+
+/** Write a managed hook script under .karajan/harness/ and return its path. */
+export function writeHarnessScript(projectDir, name, body) {
+  const dir = join(projectDir, ".karajan", "harness");
+  mkdirSync(dir, { recursive: true });
+  const abs = join(dir, name);
+  writeFileSync(abs, body, { mode: 0o755 });
+  return abs;
+}
+
+/**
+ * Merge hook entries into .claude/settings.json. Preserve, never clobber:
+ * invalid JSON or a hook event with an unexpected (non-array) shape is the
+ * user's business — the file is left alone and the caller wires manually.
+ * entries: [{ event, matcher?, script }] where script is a .karajan/harness
+ * basename; an entry is present when that script already appears under the
+ * same event (and matcher, when given).
+ */
+export function mergeClaudeHooks({ projectDir, logger = console, entries }) {
+  const settingsPath = join(projectDir, ".claude", "settings.json");
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+    } catch {
+      logger.warn?.(`kj harden: ${settingsPath} is not valid JSON — leaving it untouched (hook scripts written, wire them manually)`);
+      return { wired: false };
+    }
+  }
+  settings.hooks = settings.hooks || {};
+  for (const { event } of entries) {
+    if (event in settings.hooks && !Array.isArray(settings.hooks[event])) {
+      logger.warn?.(`kj harden: ${settingsPath} has a non-array hooks.${event} — leaving it untouched (hook scripts written, wire them manually)`);
+      return { wired: false };
+    }
+  }
+  for (const { event, matcher, script } of entries) {
+    const list = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
+    const present = list.some(
+      (e) => JSON.stringify(e).includes(script) && (matcher === undefined || e?.matcher === matcher),
+    );
+    if (!present) {
+      const cmd = { type: "command", command: `node ${join(".karajan", "harness", script)}` };
+      list.push(matcher === undefined ? { hooks: [cmd] } : { matcher, hooks: [cmd] });
+    }
+    settings.hooks[event] = list;
+  }
+  mkdirSync(join(projectDir, ".claude"), { recursive: true });
+  writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  return { wired: true };
+}
+
+/** Write the script and merge the PreToolUse entries into .claude/settings.json. */
+export function installHarnessHooks({ projectDir = process.cwd(), logger = console } = {}) {
+  const scriptAbs = writeHarnessScript(projectDir, "pretooluse.mjs", SCRIPT_BODY);
+  const { wired } = mergeClaudeHooks({
+    projectDir,
+    logger,
+    entries: [
+      { event: "PreToolUse", matcher: "Write", script: "pretooluse.mjs" },
+      { event: "PreToolUse", matcher: "Bash", script: "pretooluse.mjs" },
+    ],
+  });
+  return { script: scriptAbs, wired };
+}

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,183 @@
+/**
+ * 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", "prepare-commit-msg", "commit-msg", "pre-push", "post-merge"],
+  strict: ["pre-commit", "prepare-commit-msg", "commit-msg", "pre-push", "post-merge"],
+};
+
+/** Build the managed body for a single hook. */
+// KJC-TSK-0645: `core.hooksPath .karajan/hooks` eclipses the user's global
+// hooks dir, silently disabling personal guards. When a previous global dir
+// is known, every generated hook ends by chaining its namesake there —
+// guarded, so machines without it are unaffected.
+function chainToGlobal(hook, globalHooksDir) {
+  if (!globalHooksDir) return [];
+  return [
+    "# Chain the machine's previous global hook (kj harden keeps it active).",
+    `if [ -x "${globalHooksDir}/${hook}" ]; then`,
+    `  "${globalHooksDir}/${hook}" "$@"; rc=$?`,
+    '  [ "$rc" -eq 0 ] || exit "$rc"',
+    "fi",
+  ];
+}
+
+// KJC-TSK-0648: branch-first, enforced. The first external session of the
+// v4 environment committed on local main following literal instructions —
+// the playbook now orders "branch first" and this guard backs it up.
+function baseBranchGuard(baseBranch) {
+  if (!baseBranch) return [];
+  return [
+    "# Branch-first guard — the base branch only moves via PR.",
+    'if [ "$KJ_ALLOW_BASE_COMMIT" != "1" ]; then',
+    '  current_branch=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")',
+    `  if [ "$current_branch" = "${baseBranch}" ]; then`,
+    `    echo 'kj harden: direct commits on ${baseBranch} are not allowed — create a branch and open a PR (KJ_ALLOW_BASE_COMMIT=1 to override)'; exit 1`,
+    "  fi",
+    "fi",
+  ];
+}
+
+// IDN-C (KJC-TSK-0764, ADR 0005): identity lock at tier B — the declared clone
+// identity (.karajan/identity.local.yml) governs authorship on commit and the
+// gh session on push, on ANY host. Undeclared = advisory only (old clones keep
+// working); the fail-closed default is the Sentinel's (IDN-B).
+function identityGuard(hook) {
+  const head = [
+    "# Identity lock (IDN-C, ADR 0005) — this clone's declared identity governs.",
+    'if [ "$KJ_ALLOW_IDENTITY" != "1" ] && [ -f .karajan/identity.local.yml ]; then',
+  ];
+  const tail = [
+    "elif [ ! -f .karajan/identity.local.yml ]; then",
+    "  echo 'kj harden: no identity declared for this clone — run kj identity set (advisory)'",
+    "fi",
+  ];
+  if (hook === "pre-commit") {
+    return [
+      ...head,
+      "  kj_declared_email=$(sed -n 's/^git_email:[[:space:]]*//p' .karajan/identity.local.yml | head -n1)",
+      "  kj_author=$(git var GIT_AUTHOR_IDENT | sed 's/.*<\\(.*\\)>.*/\\1/')",
+      "  kj_committer=$(git var GIT_COMMITTER_IDENT | sed 's/.*<\\(.*\\)>.*/\\1/')",
+      '  if [ -n "$kj_declared_email" ] && { [ "$kj_author" != "$kj_declared_email" ] || [ "$kj_committer" != "$kj_declared_email" ]; }; then',
+      '    echo "kj harden: identity lock — committing as $kj_author / $kj_committer but this clone is declared as $kj_declared_email (kj identity show; KJ_ALLOW_IDENTITY=1 to override)"; exit 1',
+      "  fi",
+      ...tail,
+    ];
+  }
+  return [
+    ...head,
+    "  kj_declared_gh=$(sed -n 's/^gh_user:[[:space:]]*//p' .karajan/identity.local.yml | head -n1)",
+    '  kj_hosts="${GH_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/gh}/hosts.yml"',
+    "  kj_active_gh=$(awk '/^github.com:/{f=1;next} f&&/^[^[:space:]]/{f=0} f&&/^[[:space:]]*user:/{sub(/^[[:space:]]*user:[[:space:]]*/,\"\");print;exit}' \"$kj_hosts\" 2>/dev/null)",
+    '  if [ -n "$kj_declared_gh" ] && [ "$kj_active_gh" != "$kj_declared_gh" ]; then',
+    '    echo "kj harden: identity lock — gh session is ${kj_active_gh:-none} but this clone is declared as $kj_declared_gh — run: gh auth switch --user $kj_declared_gh (KJ_ALLOW_IDENTITY=1 to override)"; exit 1',
+    "  fi",
+    ...tail,
+  ];
+}
+
+export function hookBody(hook, cmds = {}, { globalHooksDir = null, baseBranch = null } = {}) {
+  const chain = chainToGlobal(hook, globalHooksDir);
+  switch (hook) {
+    case "pre-commit": {
+      const lines = [...baseBranchGuard(baseBranch), ...identityGuard("pre-commit"), "# 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)");
+      lines.push(
+        "# v4 review gate (ENV-C1, opt-in via `kj review --install-gate`):",
+        "# a staged diff only enters with a recorded cross-AI approved verdict.",
+        "if [ -f .karajan/review-gate ]; then",
+        "  if ! command -v kj >/dev/null 2>&1; then",
+        "    echo 'kj: review gate is enabled but kj is not installed — see karajancode.com/docs/getting-started/installation'; exit 1",
+        "  fi",
+        "  kj review --check || { echo 'kj: no approved cross-AI verdict for the staged diff — run `kj review --staged`'; exit 1; }",
+        "fi"
+      );
+      return [...lines, ...chain].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",
+        ...chain,
+      ].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)>"',
+        ...identityGuard("pre-push"),
+        "# 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, ...chain].join("\n");
+    }
+    case "prepare-commit-msg":
+      // KJC-TSK-0692 (MG-F): the branch already carries the card ref
+      // (validated by the card-first gate) — the subject inherits it
+      // automatically. A convention that enforces itself needs no adoption.
+      return [
+        'msg_file="$1"',
+        'branch=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")',
+        "# POSIX-safe extraction (no grep -o): the ref is the leading",
+        "# card-shaped token of the branch's last segment (feat/REF-desc).",
+        "seg=$(printf '%s' \"$branch\" | tr '[:upper:]' '[:lower:]'); seg=\"${seg##*/}\"",
+        String.raw`ref=$(printf '%s' "$seg" | sed -nE 's/^([a-z][a-z0-9]{1,9}(-[a-z][a-z0-9]{1,9})*-[0-9]{1,6})(-.*)?$/\1/p')`,
+        'header=$(head -n1 "$msg_file")',
+        'if [ -n "$ref" ] && [ -n "$header" ]; then',
+        '  case "$header" in',
+        "    Merge*|fixup!*|squash!*) ;;",
+        "    *)",
+        "      # Boundary match — a header mentioning KJW-TSK-00011 must not",
+        "      # suppress the KJW-TSK-0001 stamp. $ref is [a-z0-9-] only by",
+        "      # construction (sed extraction above), safe inside the ERE.",
+        '      if ! printf \'%s\' "$header" | grep -qiE "(^|[^a-zA-Z0-9-])$ref([^a-zA-Z0-9-]|$)"; then',
+        "        stamp=$(printf '%s' \"$ref\" | tr '[:lower:]' '[:upper:]')",
+        '        new_header="$header ($stamp)"',
+        '        if [ "${#new_header}" -le 100 ]; then',
+        String.raw`          { printf '%s\n' "$new_header"; tail -n +2 "$msg_file"; } > "$msg_file.kjtmp" && mv "$msg_file.kjtmp" "$msg_file"`,
+        "        fi",
+        "      fi",
+        "      ;;",
+        "  esac",
+        "fi",
+        ...chain,
+      ].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",
+        ...chain,
+      ].join("\n");
+    default:
+      throw new Error(`Unknown hook: ${hook}`);
+  }
+}