karajan-code 4.59.1 → 4.60.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.59.1",
+  "version": "4.60.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -39,7 +39,8 @@
     "packages/core",
     "packages/hu-board",
     "packages/governance",
-    "packages/console"
+    "packages/console",
+    "packages/atril"
   ],
   "imports": {
     "#utils/*": "./src/utils/*",

package/src/checks/rulesync.js

@@ -0,0 +1,65 @@
+/**
+ * HU-0005 (ADR 0022, decision 6): the rulesync range kj was tested with, and
+ * the doctor check that says when a project's rulesync falls outside it.
+ * kj compiles its rules through rulesync (src/utils/rulesync.js), so a
+ * version it never ran against is said, never assumed to work.
+ */
+import { runCommand } from "../utils/process.js";
+import { detectRulesync, rulesyncCommand } from "../utils/rulesync.js";
+import { isNewerVersion } from "../utils/update-check.js";
+import { STRATEGY } from "./types.js";
+
+/** Tested with rulesync 16.14.0; any later 16.x release is accepted, 17 is not. */
+export const RULESYNC_TESTED_RANGE = { min: "16.14.0", nextMajor: 17 };
+
+const EXPECTED = `>=${RULESYNC_TESTED_RANGE.min} <${RULESYNC_TESTED_RANGE.nextMajor}`;
+const FIX = `install rulesync@"${EXPECTED}" as a dev dependency`;
+// A cold `npx --no-install` can exceed the runner's 5 s default.
+const VERSION_TIMEOUT_MS = 10_000;
+const VERSION_RE = /(\d+)\.(\d+)\.(\d+)(-\S+)?/;
+
+const parse = (text) => {
+  const m = VERSION_RE.exec(String(text));
+  return m ? { parts: m.slice(1, 4).map(Number), prerelease: Boolean(m[4]), text: m[0] } : null;
+};
+
+/** True for a release at least the tested minimum and below the next major; prereleases are untested. */
+export function inTestedRange(version) {
+  const v = parse(version);
+  if (!v || v.prerelease || v.parts[0] >= RULESYNC_TESTED_RANGE.nextMajor) return false;
+  return !isNewerVersion(RULESYNC_TESTED_RANGE.min, v.text);
+}
+
+async function readVersion(projectDir, run) {
+  const [cmd, args] = rulesyncCommand(projectDir, ["--version"]);
+  try {
+    const res = await run(cmd, args, { cwd: projectDir, timeout: VERSION_TIMEOUT_MS });
+    if (res.exitCode !== 0) return { error: res.stderr?.trim() || `exit code ${res.exitCode}` };
+    const version = parse(res.stdout);
+    return version ? { version: version.text } : { error: `unexpected output "${res.stdout.trim()}"` };
+  } catch (err) {
+    return { error: err.message };
+  }
+}
+
+const warn = (detail) => ({ ok: false, severity: "warn", detail, fix: FIX });
+
+function createRulesyncCheck({ projectDir, run }) {
+  return {
+    name: "rulesync",
+    label: "Rulesync",
+    strategy: STRATEGY.MANUAL,
+    detectTimeoutMs: VERSION_TIMEOUT_MS + 5_000,
+    async detect() {
+      if (!detectRulesync(projectDir)) return { ok: true, severity: "info", detail: "not used in this project" };
+      const { version, error } = await readVersion(projectDir, run);
+      if (error) return warn(`the project uses rulesync but its version could not be read (${error}); tested range ${EXPECTED}`);
+      if (!inTestedRange(version)) return warn(`rulesync ${version} is outside the range kj was tested with (${EXPECTED})`);
+      return { ok: true, severity: "info", detail: `rulesync ${version} (tested range ${EXPECTED})` };
+    },
+  };
+}
+
+export function getRulesyncChecks({ projectDir = process.cwd(), run = runCommand } = {}) {
+  return [createRulesyncCheck({ projectDir, run })];
+}

package/src/cli/advanced-commands.js

@@ -34,7 +34,7 @@ export const ADVANCED_GROUPS = [
   { title: "Pipeline (piezas sueltas)", commands: ["autorun", "code", "review", "solomon", "agent", "scan", "tournament"] },
   { title: "Análisis pre-run", commands: ["discover", "triage", "researcher", "architect", "onboard", "brief"] },
   { title: "Búsqueda / RAG", commands: ["rag", "qmd", "watch"] },
-  { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy", "release", "policy", "rules", "claims", "steward", "pr-size"] },
+  { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy", "release", "policy", "rules", "rulesync", "claims", "steward", "pr-size"] },
   { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "worktree", "undo", "standby", "sentinel", "identity", "security", "handoff"] },
   { title: "Infra / setup", commands: ["install-tools", "ollama", "skills", "roles", "agents", "env"] },
   { title: "Mantenimiento", commands: ["clean", "sync", "telemetry", "report-issue"] },

package/src/cli/register-meta.js

@@ -35,6 +35,7 @@ import { reportIssueCommand } from "../commands/report-issue.js";
 import { huCommand, HU_STATUSES } from "../commands/hu.js";
 import { worktreeCommand } from "../commands/worktree.js";
 import { addAdr, listAdrs } from "../environment/adr.js";
+import { settleRulesyncEntry } from "../utils/rulesync.js";
 import { formatAdvancedIndex } from "../commands/advanced.js";
 import { policyAddCommand } from "../policy/add.js";
 import { withConfig } from "./_shared.js";
@@ -376,6 +377,19 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // HU-0003 (ADR 0022): settle a .rulesync/ ledger entry edited by hand.
+  const rulesyncCmd = program.command("rulesync").description("The .rulesync/ ownership ledger (ADR 0022)");
+  for (const [action, what] of [["adopt", "Take the entry's current content as kj's"], ["release", "Hand kj's entry to you: kj stops writing it, and later installs stop on it until you adopt it"]]) {
+    rulesyncCmd.command(`${action} <key>`).description(`${what} (key as in .rulesync/.owners.json)`)
+      .option("--json", "Machine-readable output")
+      .action(async (key, flags) => {
+        await withConfig(pkgVersion, "rulesync", flags, async ({ config }) => {
+          const res = settleRulesyncEntry({ projectDir: config?.projectDir || process.cwd(), key, action });
+          console.log(flags.json ? JSON.stringify(res) : `✓ ${key} is now ${res.owner === "kj" ? "kj's" : "yours"}`);
+        });
+      });
+  }
+
   // MDR-A2 (KJC-TSK-0942, ADR 0016): the rules of the governing MD files, each with an id.
   const rules = program.command("rules").description("Rules written in the MD files that govern a session (ADR 0016)");
   rules.command("list")

package/src/cli/register-pipeline.js

@@ -37,6 +37,8 @@ export function registerPipeline(program, { pkgVersion }) {
     .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)")
+    .option("--rulesync", "Adopt rulesync without asking (rulesync init + import; kj's rules move to .rulesync/rules/karajan.md)")
+    .option("--no-rulesync", "Do not adopt rulesync; kj keeps writing its rules into CLAUDE.md/AGENTS.md")
     .option("--no-sonar", "Do not start the SonarQube container (Docker). The review gate still needs it: start it later with 'kj sonar start'")
     .option("--json", "Emit a machine-readable summary of what init did (AB-B: for host agents)")
     .action(async (flags) => {

package/src/commands/doctor.js

@@ -28,6 +28,7 @@ import { getSqueezrChecks } from "../checks/squeezr.js";
 import { getAiTrashChecks } from "../checks/ai-trash.js";
 import { getQmdChecks } from "../checks/qmd.js";
 import { getRagHooksChecks } from "../checks/rag-hooks.js";
+import { getRulesyncChecks } from "../checks/rulesync.js";
 import { getNodeChecks } from "../checks/node.js";
 import { getNativeBuildChecks } from "../checks/native-build.js";
 import { getPortChecks } from "../checks/ports.js";
@@ -55,7 +56,7 @@ import { getMethodChecks } from "../checks/method.js";
 function buildChecks(config, { projectOnly = false } = {}) {
   const projectDir = config?.projectDir || process.cwd();
   if (projectOnly) {
-    return getProjectChecks({ projectDir });
+    return [...getProjectChecks({ projectDir }), ...getRulesyncChecks({ projectDir })];
   }
   return [
     ...getSystemChecks(),
@@ -81,6 +82,7 @@ function buildChecks(config, { projectOnly = false } = {}) {
     ...getMethodChecks(),
     ...getQmdChecks(),
     ...getRagHooksChecks({ projectDir }),
+    ...getRulesyncChecks({ projectDir }),
     ...getProjectChecks({ projectDir }),
   ];
 }

package/src/commands/init.js

@@ -12,6 +12,7 @@ import { getKarajanHome } from "../utils/paths.js";
 import { getTemplatesRoot } from "../utils/templates-root.js";
 import { detectAvailableAgents } from "../utils/agent-detect.js";
 import { createWizard, isTTY } from "../utils/wizard.js";
+import { offerRulesyncAdoption } from "../utils/rulesync-adopt.js";
 import { runCommand } from "../utils/process.js";
 import { getInstallCommand } from "../utils/os-detect.js";
 import { detectOsLocale, SUPPORTED_LANGUAGES } from "../utils/locale.js";
@@ -822,6 +823,12 @@ export function ensureGitRepo({ projectDir, logger, gitFn = null }) {
   }
 }
 
+/** One yes/no question through a wizard of its own, closed after the answer. */
+const askOnce = (question) => {
+  const wizard = createWizard();
+  return wizard.confirm(question, false).finally(() => wizard.close());
+};
+
 export async function initCommand({ logger, flags = {} }) {
   // AB-B (KJC-TSK-0656): with --json, stdout is a machine contract — every
   // human log moves to stderr so the only stdout line is the summary object.
@@ -982,6 +989,10 @@ export async function initCommand({ logger, flags = {} }) {
   }
   await scaffoldCiGateway(config, flags, logger);
 
+  // HU-0004 (ADR 0022): before the harness writes kj's rules, so they land in
+  // rulesync's source when the project adopts it.
+  await offerRulesyncAdoption({ projectDir: process.cwd(), flags, interactive, logger, confirm: askOnce });
+
   // 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.

package/src/environment/playbook.js

@@ -12,7 +12,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { upsertManagedBlock } from "../utils/managed-markers.js";
-import { detectRulesync, RULESYNC_RULE, rulesyncRuleSeed } from "../utils/rulesync.js";
+import { detectRulesync, RULESYNC_RULE, rulesyncRuleSeed, writeRulesyncBlock } from "../utils/rulesync.js";
 import { panelLine } from "./panel.js";
 
 // AB-A (KJC-TSK-0650): any agent can be the brain. AGENTS.md is the
@@ -126,15 +126,21 @@ export async function installPlaybook({ projectDir, target = "all", version = "1
   const rulesync = detectRulesync(projectDir);
   for (const file of rulesync ? [RULESYNC_RULE] : TARGET_FILES[target]) {
     const fullPath = path.join(projectDir, file);
-    let source = rulesync ? rulesyncRuleSeed() : "";
-    try { source = await fs.readFile(fullPath, "utf8"); } catch { /* new file */ }
-    const { content, action } = upsertManagedBlock({
+    const render = (source) => upsertManagedBlock({
       source, blockId: "playbook", version, body: renderPlaybook({ stateBackend, boardName, config }), style: "html",
       note: "do not edit: regenerated by kj env install",
     });
-    if (action !== "unchanged") {
-      await fs.mkdir(path.dirname(fullPath), { recursive: true });
-      await fs.writeFile(fullPath, content);
+    if (rulesync) {
+      // HU-0002: read, checked and written under the ownership ledger's lock.
+      writeRulesyncBlock({ projectDir, blockId: "playbook", render: (previous) => render(previous ?? rulesyncRuleSeed()) });
+    } else {
+      let source = "";
+      try { source = await fs.readFile(fullPath, "utf8"); } catch { /* new file */ }
+      const { content, action } = render(source);
+      if (action !== "unchanged") {
+        await fs.mkdir(path.dirname(fullPath), { recursive: true });
+        await fs.writeFile(fullPath, content);
+      }
     }
     files.push(file);
   }

package/src/harden/guidelines-engine.js

@@ -9,7 +9,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 import { upsertManagedBlock } from "../utils/managed-markers.js";
-import { detectRulesync, RULESYNC_RULE, rulesyncRuleSeed } from "../utils/rulesync.js";
+import { detectRulesync, RULESYNC_RULE, rulesyncRuleSeed, writeRulesyncBlock } from "../utils/rulesync.js";
 import { guidelinesBody } from "./guidelines-templates.js";
 
 const BLOCK_VERSION = 1;
@@ -45,10 +45,7 @@ export function installGuidelines({ projectDir = process.cwd(), dryRun = false,
   // KJC-TSK-0879: with Rulesync, its source is the file of truth; writing into
   // CLAUDE.md/AGENTS.md would be erased by the next `rulesync generate`.
   const rulesync = detectRulesync(projectDir);
-  for (const file of rulesync ? [RULESYNC_RULE] : TARGETS) {
-    const target = join(projectDir, file);
-    const seed = rulesync ? rulesyncRuleSeed() : "";
-    const raw = existsSync(target) ? readFileSync(target, "utf8") : seed;
+  const render = (raw) => {
     const { content: source, migrated } = stripDevHooksBlock(raw);
     const { content, action } = upsertManagedBlock({
       source,
@@ -65,11 +62,24 @@ export function installGuidelines({ projectDir = process.cwd(), dryRun = false,
     // KJC-BUG-0232: decir CUALES se van, o el aviso obliga a salir a git diff.
     const kept = new Set(nonEmpty(content));
     const removed = shrank ? nonEmpty(raw).filter((l) => !kept.has(l) && !l.includes("kj:managed:")) : [];
-    if (!dryRun && (migrated || action !== "unchanged")) {
-      mkdirSync(dirname(target), { recursive: true });
-      writeFileSync(target, content);
+    return { content, action: migrated ? "migrated" : action, ...(shrank ? { shrank: true, removed } : {}) };
+  };
+  for (const file of rulesync ? [RULESYNC_RULE] : TARGETS) {
+    const target = join(projectDir, file);
+    const seed = rulesync ? rulesyncRuleSeed() : "";
+    let res;
+    if (rulesync && !dryRun) {
+      // HU-0002: read, checked and written under the ownership ledger's lock.
+      res = writeRulesyncBlock({ projectDir, blockId: "guidelines", render: (previous) => render(previous ?? seed) });
+    } else {
+      res = render(existsSync(target) ? readFileSync(target, "utf8") : seed);
+      if (!dryRun && res.action !== "unchanged") {
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, res.content);
+      }
     }
-    results.push({ file, action: migrated ? "migrated" : action, ...(shrank ? { shrank: true, removed } : {}) });
+    const { content: _content, ...summary } = res;
+    results.push({ file, ...summary });
   }
   return { dryRun, guidelines: results };
 }

package/src/utils/rulesync-adopt.js

@@ -0,0 +1,96 @@
+// HU-0004 (ADR 0022, decision 5): kj init offers rulesync and asks. kj's blocks
+// leave the agent files before `rulesync import`, so the import never repeats them.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { findManagedBlock } from "./managed-markers.js";
+import { ADOPTION_PENDING, defaultRun, detectRulesync, RULESYNC_RULE, rulesyncCommand, rulesyncRuleSeed, writeRulesyncBlock } from "./rulesync.js";
+
+// Each agent file kj writes into, with the rulesync target that imports it.
+const AGENT_FILES = [["CLAUDE.md", "claudecode"], ["AGENTS.md", "agentsmd"]];
+const KJ_BLOCKS = ["playbook", "guidelines"];
+const INSTALL = "npm install --save-dev rulesync";
+/** Run one adoption step; on failure, stop naming it and what to run by hand. */
+const step = (name, byHand, action) => {
+  try {
+    action();
+  } catch (error) {
+    throw new Error(`kj: rulesync adoption stopped at "${name}": ${error.message}\nRun by hand: ${byHand}`, { cause: error });
+  }
+};
+
+/** Split kj's block out of `text`: its lines, and the text without them. */
+const takeBlock = (text, blockId) => {
+  const block = findManagedBlock(text, blockId);
+  if (!block.found) return { block: null, rest: text };
+  const lines = text.split("\n");
+  return {
+    block: lines.slice(block.startLine, block.endLine + 1).join("\n"),
+    rest: [...lines.slice(0, block.startLine), ...lines.slice(block.endLine + 1)].join("\n"),
+  };
+};
+
+/** Move kj's blocks from the agent files into its ledger-owned rule. */
+function moveKjBlocks(projectDir) {
+  const paths = AGENT_FILES.map(([file]) => join(projectDir, file)).filter((path) => existsSync(path));
+  const texts = new Map(paths.map((path) => [path, readFileSync(path, "utf8")]));
+  for (const blockId of KJ_BLOCKS) {
+    let moved = null;
+    for (const [path, text] of texts) {
+      const { block, rest } = takeBlock(text, blockId);
+      moved ??= block; // first copy wins: harden re-renders the block anyway
+      texts.set(path, rest);
+    }
+    if (moved === null) continue;
+    writeRulesyncBlock({
+      projectDir, blockId,
+      // A resumed adoption may find the block already here: replace it, never repeat it.
+      render: (previous) => ({ content: `${takeBlock(previous ?? rulesyncRuleSeed(), blockId).rest.replace(/\n*$/, "\n")}${moved}\n` }),
+    });
+  }
+  for (const [path, text] of texts) writeFileSync(path, text);
+}
+
+/** Adopt rulesync: init, kj's blocks to its rule, then import what the agent files keep. */
+function adoptRulesync({ projectDir, logger, run }) {
+  const exec = (args) => run(...rulesyncCommand(projectDir, args), projectDir);
+  try {
+    exec(["--version"]);
+  } catch {
+    logger.warn(`kj: rulesync is not installed, so it was not adopted. Install it with: ${INSTALL}, then run kj init again`);
+    return { adopted: false, reason: "not-installed" };
+  }
+  const execStep = (args) => {
+    const [cmd, fullArgs] = rulesyncCommand(projectDir, args);
+    step(`rulesync ${args.join(" ")}`, `${[cmd, ...fullArgs].join(" ")}, then kj init to finish it`, () => run(cmd, fullArgs, projectDir));
+  };
+  mkdirSync(join(projectDir, ".rulesync"), { recursive: true });
+  writeFileSync(join(projectDir, ADOPTION_PENDING), "kj init: rulesync adoption in progress\n");
+  execStep(["init"]);
+  step(`move kj's blocks into ${RULESYNC_RULE}`, `fix ${RULESYNC_RULE} or kj's blocks in CLAUDE.md/AGENTS.md, then kj init`, () => moveKjBlocks(projectDir));
+  for (const [file, target] of AGENT_FILES) {
+    if (existsSync(join(projectDir, file))) execStep(["import", "--targets", target]);
+  }
+  rmSync(join(projectDir, ADOPTION_PENDING));
+  logger.info(`kj: rulesync adopted; kj's rules now live in ${RULESYNC_RULE}`);
+  return { adopted: true };
+}
+
+/**
+ * Ask whether to adopt rulesync. `flags.rulesync` (--rulesync / --no-rulesync)
+ * answers without asking; with no TTY and no flag, nothing is adopted.
+ */
+export async function offerRulesyncAdoption({ projectDir, flags = {}, interactive, confirm, logger = console, run = defaultRun }) {
+  if (detectRulesync(projectDir)) return { adopted: false, reason: "already" };
+  const halfDone = existsSync(join(projectDir, ADOPTION_PENDING));
+  const verb = halfDone ? "finish the half-done adoption" : "adopt it";
+  if (flags.rulesync === undefined && !interactive) {
+    logger.info(`kj: rulesync not adopted (nobody to ask); pass --rulesync to ${verb}, or --no-rulesync to keep the agent files`);
+    return { adopted: false, reason: "no-answer" };
+  }
+  const question = halfDone
+    ? "Finish adopting rulesync? A previous kj init stopped halfway (rulesync init + import)"
+    : "Adopt rulesync? One source in .rulesync/ for every agent's rules (rulesync init + import)";
+  const answer = flags.rulesync ?? await confirm(question);
+  if (answer !== true) return { adopted: false, reason: "declined" };
+  return adoptRulesync({ projectDir, logger, run });
+}

package/src/utils/rulesync-ledger.js

@@ -0,0 +1,102 @@
+/**
+ * HU-0001 (ADR 0022, decision 3) — the ownership ledger of `.rulesync/`. The
+ * user, kj and atril share one rulesync source; each owns what it wrote (a
+ * per-file feature keyed by its path relative to `.rulesync/`, e.g.
+ * `rules/karajan.md`, or `rules/karajan.md#<block>` for a writer's managed
+ * block; an entry of hooks/mcp/permissions by key), and the ledger is the
+ * single source of their hashes. No entry means the user's, unless a writer
+ * finds its marker there (it claims it, once); an entry released to the user
+ * (HU-0003) is owned by "user", so no writer claims it again. The
+ * format is a contract atril implements in its own package: hashed entries are
+ * serialized canonically (JSON, keys sorted) by every writer.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { writeJsonAtomicSync } from "./atomic-write.js";
+
+export const LEDGER_FILE = join(".rulesync", ".owners.json");
+export const LOCK_FILE = join(".rulesync", ".owners.lock");
+export const LEDGER_VERSION = 1;
+export const USER_OWNER = "user";
+const HASH_RE = /^sha256:[0-9a-f]{64}$/;
+
+export const mcpKey = (server) => `mcp:${server}`;
+export const permissionKey = (rule) => `permissions:${rule}`;
+export function hookKey(event, id) {
+  if (event.includes(":")) throw new Error(`hook event "${event}" contains ":", which would make its ledger key ambiguous`);
+  return `hooks:${event}:${id}`;
+}
+
+export const hashContent = (content) => `sha256:${createHash("sha256").update(content).digest("hex")}`;
+
+function validate(file, ledger) {
+  if (ledger?.version !== LEDGER_VERSION) {
+    throw new Error(`${file}: version ${ledger?.version} is not supported (expected ${LEDGER_VERSION})`);
+  }
+  if (typeof ledger.entries !== "object" || ledger.entries === null || Array.isArray(ledger.entries)) {
+    throw new Error(`${file}: entries must be an object of key → { owner, hash }`);
+  }
+  for (const [key, entry] of Object.entries(ledger.entries)) {
+    if (typeof entry?.owner !== "string" || !entry.owner || typeof entry.hash !== "string" || !HASH_RE.test(entry.hash)) {
+      throw new Error(`${file}: entry "${key}" needs a non-empty owner and a sha256:<hex> hash`);
+    }
+  }
+}
+
+/** The ledger, or an empty one when absent. A broken, malformed or unknown one fails loudly. */
+export function readLedger(projectDir) {
+  const file = join(projectDir, LEDGER_FILE);
+  if (!existsSync(file)) return { version: LEDGER_VERSION, entries: {} };
+  let ledger;
+  try { ledger = JSON.parse(readFileSync(file, "utf8")); } catch (err) {
+    throw new Error(`${file}: not valid JSON (${err.message})`, { cause: err });
+  }
+  validate(file, ledger);
+  return ledger;
+}
+
+function takeLock(lock, owner) {
+  try {
+    writeFileSync(lock, `${owner} ${process.pid}`, { flag: "wx" });
+  } catch (err) {
+    if (err.code === "ENOENT") throw new Error(`${dirname(lock)}: .rulesync/ is missing (run rulesync init)`, { cause: err });
+    if (err.code !== "EEXIST") throw err;
+    let holder = "unknown";
+    try { holder = readFileSync(lock, "utf8").trim() || holder; } catch { /* released meanwhile */ }
+    throw new Error(`${lock}: held by ${holder} — another writer is updating the ledger; retry when it ends `
+      + `(if no writer is running, delete ${lock})`, { cause: err });
+  }
+}
+
+/**
+ * Read, change and write the ledger under its lock, so two writers never
+ * interleave. The write is atomic; a change that throws writes nothing. A
+ * lock left by a crashed writer is never stolen: the error says how to clear it.
+ * @param {string} projectDir
+ * @param {string} owner - who takes the lock, named to whoever finds it held
+ * @param {(ledger: object) => void} change - mutates the ledger in place
+ */
+export function withLedger(projectDir, owner, change) {
+  if (typeof owner !== "string" || !owner) throw new Error("withLedger: owner must be a non-empty string");
+  const lock = join(projectDir, LOCK_FILE);
+  takeLock(lock, owner);
+  try {
+    const ledger = readLedger(projectDir);
+    change(ledger);
+    validate(join(projectDir, LEDGER_FILE), ledger);
+    writeJsonAtomicSync(join(projectDir, LEDGER_FILE), ledger);
+    return ledger;
+  } finally {
+    rmSync(lock, { force: true });
+  }
+}
+
+/**
+ * "ok" when the content still matches its recorded hash, "edited" when it
+ * changed by hand (the writer must stop), "unowned" when no writer recorded it.
+ */
+export function verifyEntry(ledger, key, content) {
+  if (!Object.hasOwn(ledger.entries, key)) return "unowned";
+  return ledger.entries[key].hash === hashContent(content) ? "ok" : "edited";
+}

package/src/utils/rulesync.js

@@ -8,8 +8,10 @@
  * source instead, with the same managed markers.
  */
 import { execFileSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { findManagedBlock } from "./managed-markers.js";
+import { hashContent, USER_OWNER, verifyEntry, withLedger } from "./rulesync-ledger.js";
 
 export const RULESYNC_RULE = join(".rulesync", "rules", "karajan.md");
 
@@ -25,16 +27,28 @@ const FRONTMATTER = [
   "",
 ].join("\n");
 
-/** The project uses Rulesync when it has `.rulesync/` or `rulesync.jsonc`. */
+// HU-0011: kj init writes this before adopting rulesync and removes it after the
+// last import. While it exists the adoption is half done, so nothing in kj treats
+// the project as a rulesync one. Local state: never commit it.
+export const ADOPTION_PENDING = join(".rulesync", ".kj-adoption-pending");
+
+/** The project uses Rulesync when it has `.rulesync/` or `rulesync.jsonc`, and no adoption is half done. */
 export function detectRulesync(projectDir) {
+  if (existsSync(join(projectDir, ADOPTION_PENDING))) return false;
   return existsSync(join(projectDir, ".rulesync")) || existsSync(join(projectDir, "rulesync.jsonc"));
 }
 
 /** What a brand-new karajan.md starts with, before kj's managed blocks. */
 export const rulesyncRuleSeed = () => FRONTMATTER;
 
+/** The project's own rulesync binary, or npx without installing: kj never runs a package fetched on the fly. */
+export function rulesyncCommand(projectDir, args) {
+  const local = join(projectDir, "node_modules", ".bin", "rulesync");
+  return existsSync(local) ? [local, args] : ["npx", ["--no-install", "rulesync", ...args]];
+}
+
 const GENERATE_ARGS = ["generate", "--targets", "*", "--features", "*"];
-const defaultRun = (cmd, args, cwd) => execFileSync(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" });
+export const defaultRun = (cmd, args, cwd) => execFileSync(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" });
 
 /**
  * Compile kj's rules out to every agent, only when the project declared
@@ -48,8 +62,7 @@ export function maybeRulesyncGenerate({ projectDir, config, logger = console, ru
     logger.info?.(`kj: its rules are in ${RULESYNC_RULE}; run rulesync generate to reach your agents, or declare rulesync.generate: true`);
     return { ran: false, reason: "not-opted-in" };
   }
-  const local = join(projectDir, "node_modules", ".bin", "rulesync");
-  const [cmd, args] = existsSync(local) ? [local, GENERATE_ARGS] : ["npx", ["--no-install", "rulesync", ...GENERATE_ARGS]];
+  const [cmd, args] = rulesyncCommand(projectDir, GENERATE_ARGS);
   try {
     run(cmd, args, projectDir);
     logger.info?.("kj: rulesync generate spread kj's rules to every agent");
@@ -59,3 +72,94 @@ export function maybeRulesyncGenerate({ projectDir, config, logger = console, ru
     return { ran: false, reason: "failed" };
   }
 }
+
+// HU-0002 (ADR 0022, decision 3): kj owns its managed blocks of karajan.md,
+// not the file — the team's own rules outside them stay free.
+const blockText = (text, blockId) => {
+  const block = findManagedBlock(text, blockId);
+  return block.found ? text.split("\n").slice(block.startLine, block.endLine + 1).join("\n") : null;
+};
+
+/**
+ * Write one of kj's blocks of a rulesync rule through the ownership ledger.
+ * The file is read, checked and written under the ledger's lock: `render`
+ * gets its current text (null when absent) and returns `{ content, ... }`.
+ * A block kj wrote before the ledger existed is claimed once, and said; an
+ * owned block edited, broken or deleted by hand stops the write.
+ * @returns {object} what `render` returned, plus `claimed` when it was claimed.
+ */
+export function writeRulesyncBlock({ projectDir, file = RULESYNC_RULE, blockId, render, logger = console }) {
+  // Ledger keys are a contract with atril: always posix.
+  const key = `${relative(".rulesync", file).split(sep).join("/")}#${blockId}`;
+  const target = join(projectDir, file);
+  let result;
+  withLedger(projectDir, "kj", (ledger) => {
+    const previous = existsSync(target) ? readFileSync(target, "utf8") : null;
+    const current = previous === null ? null : blockText(previous, blockId);
+    const owned = Object.hasOwn(ledger.entries, key);
+    const owner = ledger.entries[key]?.owner;
+    if (owned && owner !== "kj") {
+      throw new Error(`${file}: "${key}" belongs to ${owner}; kj will not touch it`
+        + (owner === USER_OWNER ? ` (kj rulesync adopt ${key} gives it back to kj)` : ""));
+    }
+    if (current === null ? owned : verifyEntry(ledger, key, current) === "edited") {
+      throw new Error(`${file}: kj's ${blockId} block was edited by hand; kj will not overwrite it. `
+        + `Restore kj's block as it was, run kj rulesync adopt ${key} to keep the edit as kj's, `
+        + `or kj rulesync release ${key} to make the block yours`);
+    }
+    const claimed = current !== null && !owned;
+    if (claimed) logger.info(`kj: claimed ${key}, written by kj before the ownership ledger existed`);
+    result = { ...render(previous), ...(claimed ? { claimed } : {}) };
+    const written = blockText(result.content, blockId);
+    if (written === null) throw new Error(`${file}: rendering kj's ${blockId} block left it out; nothing written`);
+    if (result.content !== previous) {
+      // Rule first, ledger second (withLedger writes it on return): a crash in
+      // between reads as "edited" next time — loud, never a silent overwrite.
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(`${target}.tmp`, result.content);
+      try {
+        renameSync(`${target}.tmp`, target);
+      } catch (err) {
+        rmSync(`${target}.tmp`, { force: true });
+        throw err;
+      }
+    }
+    ledger.entries[key] = { owner: "kj", hash: hashContent(written) };
+  });
+  return result;
+}
+
+// The current content of a rules file (`rules/x.md`) or of a managed block
+// in one (`rules/x.md#<block>`), as its ledger entry hashes it.
+function entryContent(projectDir, key) {
+  if (/^(mcp|permissions|hooks):/.test(key)) throw new Error(`"${key}": kj only adopts rules files and their blocks`);
+  const [path, blockId, ...rest] = key.split("#");
+  if (rest.length || path.startsWith("/") || path.split("/").includes("..")) throw new Error(`"${key}": not a key inside .rulesync/`);
+  const file = join(projectDir, ".rulesync", ...path.split("/"));
+  if (!existsSync(file)) throw new Error(`${file}: missing, nothing to adopt for "${key}"`);
+  const text = readFileSync(file, "utf8");
+  const content = blockId === undefined ? text : blockText(text, blockId);
+  if (content === null) throw new Error(`${file}: no complete ${blockId} block, nothing to adopt for "${key}"`);
+  return content;
+}
+
+/**
+ * HU-0003: settle a ledger entry. `adopt` records its current content as
+ * kj's (also taking back one released to the user); `release` hands kj's
+ * entry to the user, who then owns it: kj never claims it again.
+ * @param {{ projectDir: string, key: string, action: "adopt"|"release" }} args
+ * @returns {{ key: string, owner: string, hash: string }}
+ */
+export function settleRulesyncEntry({ projectDir, key, action }) {
+  const from = { adopt: ["kj", USER_OWNER], release: ["kj"] }[action];
+  if (!from) throw new Error(`rulesync: unknown action "${action}" (adopt | release)`);
+  const { entries } = withLedger(projectDir, "kj", (ledger) => {
+    const owner = ledger.entries[key]?.owner;
+    if (!owner) throw new Error(`"${key}" is not in .rulesync/.owners.json: it has no owner to ${action} from`);
+    if (!from.includes(owner)) throw new Error(`"${key}" is owned by ${owner}; kj cannot ${action} it`);
+    ledger.entries[key] = action === "adopt"
+      ? { owner: "kj", hash: hashContent(entryContent(projectDir, key)) }
+      : { ...ledger.entries[key], owner: USER_OWNER };
+  });
+  return { key, ...entries[key] };
+}

package/src/utils/update-check.js

@@ -161,15 +161,22 @@ export async function checkForUpdate(currentVersion) {
 
 /**
  * Print update notice if available. Call at CLI startup, non-blocking.
+ * KJC-BUG-0389: on stderr. It prints after the command's output, and on stdout it
+ * trailed every --json document and the verdict the rules hook parses.
  */
 export async function printUpdateNotice(currentVersion) {
   const result = await checkForUpdate(currentVersion);
   if (result?.updateAvailable) {
     const channel = detectInstallChannel();
-    console.log(`\n  Update available: v${result.current} → v${result.latest}`);
-    if (result.highlight) console.log(`  What it brings: ${result.highlight}`);
-    console.log(`  ${updateInstruction({ channel })}`);
-    console.log("  Agent: tell your user and ask before updating — never update on your own.\n");
+    const lines = [
+      "",
+      `  Update available: v${result.current} → v${result.latest}`,
+      ...(result.highlight ? [`  What it brings: ${result.highlight}`] : []),
+      `  ${updateInstruction({ channel })}`,
+      "  Agent: tell your user and ask before updating — never update on your own.",
+      "",
+    ];
+    process.stderr.write(`${lines.join("\n")}\n`);
   }
 }