karajan-code 3.7.0 → 3.7.1

package/README.md

@@ -23,7 +23,7 @@
 
 ---
 
-> **v3.7.0 released** — Autonomous delivery: `kj autorun <spec>` chains spec → plan → run every user story → outcome in one command, unattended. An **Arbiter** resolves agent conflicts by picking the least-bad call (acceptance tests > must-fix > nice-to-have), no stage blocks for a human, a wall-clock backstop stops runaways, and it ends with an auditable "delivered, with known defects" report. Autonomy is opt-in (`--autonomous` / `--autonomy <level>`); interactive runs are unchanged. Verified live end-to-end. Full notes in [CHANGELOG.md](CHANGELOG.md).
+> **v3.7.1 released** — Patch: fixes a `kj init` crash when configuring the Plan B fallback, and makes pnpm installs safe — `kj doctor` now flags when pnpm skipped `better-sqlite3`'s native build and tells you exactly how to fix it (`pnpm approve-builds better-sqlite3`). The release gate checks pnpm too. Built on **v3.7.0 — Autonomous delivery**: `kj autorun <spec>` chains spec → plan → run every user story → outcome in one command, unattended, with an **Arbiter** that resolves agent conflicts by picking the least-bad call; autonomy is opt-in, interactive runs are unchanged. 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.
 
@@ -71,6 +71,33 @@ Two technical facts worth keeping straight:
 
 Full write-up with mental mapping for Genkit / Mastra / LangChain / Vercel AI SDK developers: **[docs/COMPARISON.md](./docs/COMPARISON.md)**.
 
+## Loop engineering
+
+Prompt engineering got one good answer from one good prompt. Context engineering
+curated what the model saw. The 2026 frontier is **loop engineering**: you stop
+prompting the agent by hand and design the control system that prompts it, checks
+it, and decides what happens next — until the goal is met or it hands back to you.
+
+Karajan is a loop-engineering runtime, built around the loop before the term
+caught on:
+
+- **Maker / checker split** — a coder against independent reviewer / tester /
+  security roles, with Solomon judging disputes. The maker never grades its own work.
+- **Deterministic verification** — TDD, per-HU acceptance tests, SonarQube gates,
+  and deterministic guards. Checking is tests, not vibes.
+- **The autonomy ladder (L1 → L2 → L3)** — the `interactive | assisted |
+  autonomous` axis (v3.7.0). Report, then assisted fixes, then unattended
+  `kj autorun` — defaulting to `interactive`, so you opt in.
+- **A durable state spine** — sessions, the HU Board, journals, the RAG index and
+  `kj resume` keep the loop alive outside any one conversation.
+
+The honest caveat loop engineering insists on — *unattended loops make unattended
+mistakes* — is designed in: autonomous runs list their residual defects, every HU
+lands behind a PR, and `kj-trash` snapshots destructive operations.
+
+Full mapping of the loop-engineering building blocks onto Karajan:
+**[docs/loop-engineering.md](./docs/loop-engineering.md)**.
+
 ## Install
 
 **npm** (recommended):
@@ -83,6 +110,8 @@ npm install -g karajan-code
 brew install manufosela/tap/karajan-code
 ```
 
+> **Installing with pnpm?** pnpm blocks dependency build scripts by default, so `better-sqlite3`'s native addon won't compile on install and DB-backed commands (`board`, `rag`, cost tracking) will fail. After installing, run `pnpm approve-builds better-sqlite3` — or just use npm. `kj doctor` flags this if it happens.
+
 **Standalone binary** (no Node.js needed):
 ```bash
 # macOS (Apple Silicon)

package/package.json

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

package/scripts/verify-pack.mjs

@@ -50,6 +50,7 @@ function fail(msg, detail) {
 
 let tgzPath = null;
 let tmpDir = null;
+let pnpmTmp = null;
 try {
   console.log(`verify-pack: packing karajan-code@${expectedVersion}…`);
   // --json gives us the exact filename without parsing human output.
@@ -114,8 +115,48 @@ try {
   }
   console.log("verify-pack: kj-trash ships + boots ✓");
 
+  // 5. pnpm install smoke (KJC-TSK-0580). pnpm's layout differs from npm's
+  // (a symlinked virtual store), so it can break resolution of the bundled
+  // @karajan/core the way npm packaging breakage did before (KJC-BUG-0082/0086).
+  // Verify a pnpm install resolves the JS tree and `kj --version` boots — every
+  // release catches a pnpm packaging regression. (pnpm also blocks
+  // better-sqlite3's native build by default, so DB-backed commands need
+  // `pnpm approve-builds`; that's surfaced as a doctor warning, KJC-BUG-0092 —
+  // not a gate failure, since it's inherent to pnpm.) Auto-skips without pnpm.
+  const hasPnpm = spawnSync("pnpm", ["--version"], { encoding: "utf8", env: childEnv }).status === 0;
+  if (!hasPnpm) {
+    console.log("verify-pack: pnpm not installed — skipping pnpm smoke (npm path covered above) ⚠");
+  } else {
+    pnpmTmp = fs.mkdtempSync(path.join(os.tmpdir(), "kj-verify-pnpm-"));
+    fs.writeFileSync(
+      path.join(pnpmTmp, "package.json"),
+      JSON.stringify({ name: "kj-verify-pnpm", private: true }),
+    );
+    console.log(`verify-pack: installing the tarball with pnpm into ${pnpmTmp}…`);
+    // pnpm exits non-zero on ERR_PNPM_IGNORED_BUILDS (it skips native build
+    // scripts by default) — expected here, so don't treat the exit as failure.
+    spawnSync("pnpm", ["add", tgzPath, "--store-dir", path.join(pnpmTmp, ".store")], {
+      encoding: "utf8",
+      env: childEnv,
+      cwd: pnpmTmp,
+    });
+    const pnpmBin = path.join(pnpmTmp, "node_modules", ".bin", "kj");
+    if (!fs.existsSync(pnpmBin)) fail(`kj binary missing after pnpm install: ${pnpmBin}`);
+    let pnpmVersion;
+    try {
+      pnpmVersion = run(pnpmBin, ["--version"], { cwd: pnpmTmp }).trim();
+    } catch (err) {
+      fail("`kj --version` crashed under a pnpm install (packaging regression)", err.stderr || err.message);
+    }
+    if (!pnpmVersion.includes(expectedVersion)) {
+      fail(`kj --version under pnpm returned "${pnpmVersion}", expected ${expectedVersion}`);
+    }
+    console.log(`verify-pack: pnpm install + kj --version → ${pnpmVersion} ✓ (DB build needs \`pnpm approve-builds\`)`);
+  }
+
   console.log(`\n✓ verify-pack: karajan-code@${expectedVersion} installs clean and runs.`);
 } finally {
   if (tgzPath && fs.existsSync(tgzPath)) fs.rmSync(tgzPath, { force: true });
   if (tmpDir && fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+  if (pnpmTmp && fs.existsSync(pnpmTmp)) fs.rmSync(pnpmTmp, { recursive: true, force: true });
 }

package/src/checks/native-build.js

@@ -0,0 +1,64 @@
+/**
+ * Native build availability check (KJC-BUG-0092).
+ *
+ * better-sqlite3 ships a native addon compiled in a postinstall step. pnpm
+ * blocks dependency build scripts by default (ERR_PNPM_IGNORED_BUILDS), so a
+ * `pnpm add -g karajan-code` leaves the addon uncompiled: `kj --version` still
+ * works (it never opens a DB) but any DB-backed command (board, rag, cost
+ * tracking) crashes with "Cannot find module 'better-sqlite3'". This surfaces a
+ * WARN in `kj doctor` with the exact remedy instead of a cryptic runtime crash.
+ */
+
+import { STRATEGY } from "./types.js";
+
+/** pnpm lays packages out under a `.pnpm` virtual store and symlinks them in. */
+function isPnpmInstall() {
+  return (
+    import.meta.url.includes("/.pnpm/") ||
+    (process.env.npm_config_user_agent || "").includes("pnpm")
+  );
+}
+
+/** Force the native binding to load by opening an in-memory database. */
+async function defaultLoadDb() {
+  const Database = (await import("better-sqlite3")).default;
+  new Database(":memory:").close();
+}
+
+export function createNativeBuildCheck({ loadDb = defaultLoadDb, isPnpm = isPnpmInstall } = {}) {
+  return {
+    name: "native-build",
+    label: "native modules (better-sqlite3)",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      try {
+        await loadDb();
+        return {
+          ok: true,
+          severity: "info",
+          detail: "better-sqlite3 native addon loads — DB-backed commands available",
+        };
+      } catch (err) {
+        const firstLine = String(err?.message || err).split("\n")[0];
+        if (isPnpm()) {
+          return {
+            ok: false,
+            severity: "warn",
+            detail: "better-sqlite3 native build was skipped — pnpm blocks dependency build scripts by default",
+            fix: "Approve the build then reinstall: `pnpm approve-builds better-sqlite3` — or install with npm: `npm i -g karajan-code`",
+          };
+        }
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `better-sqlite3 failed to load: ${firstLine}`,
+          fix: "Reinstall to rebuild native modules: `npm i -g karajan-code`",
+        };
+      }
+    },
+  };
+}
+
+export function getNativeBuildChecks() {
+  return [createNativeBuildCheck()];
+}

package/src/commands/doctor.js

@@ -26,6 +26,7 @@ import { getSqueezrChecks } from "../checks/squeezr.js";
 import { getAiTrashChecks } from "../checks/ai-trash.js";
 import { getQmdChecks } from "../checks/qmd.js";
 import { getNodeChecks } from "../checks/node.js";
+import { getNativeBuildChecks } from "../checks/native-build.js";
 import { getPortChecks } from "../checks/ports.js";
 import { getTokenChecks } from "../checks/tokens.js";
 import { getMcpHealthChecks } from "../checks/mcp-health.js";
@@ -54,6 +55,7 @@ function buildChecks(config, { projectOnly = false } = {}) {
   return [
     ...getSystemChecks(),
     ...getNodeChecks(),
+    ...getNativeBuildChecks(),
     ...getHardwareChecks(),
     ...getDirSetupChecks(),
     ...getConfigFileChecks(),

package/src/utils/wizard.js

@@ -1,7 +1,7 @@
 import readline from "node:readline";
 
-export function createWizard(input = process.stdin, output = process.stdout) {
-  const rl = readline.createInterface({ input, output, terminal: false });
+export function createWizard(inputStream = process.stdin, output = process.stdout) {
+  const rl = readline.createInterface({ input: inputStream, output, terminal: false });
 
   function ask(question) {
     return new Promise((resolve) => {
@@ -16,6 +16,12 @@ export function createWizard(input = process.stdin, output = process.stdout) {
     return /^y(es)?$/i.test(answer);
   }
 
+  async function input(question, defaultValue = "") {
+    const hint = defaultValue !== "" ? ` [${defaultValue}]` : "";
+    const answer = await ask(`${question}${hint} `);
+    return answer === "" ? defaultValue : answer;
+  }
+
   async function select(question, options) {
     output.write(`${question}\n`);
     for (let i = 0; i < options.length; i++) {
@@ -33,7 +39,7 @@ export function createWizard(input = process.stdin, output = process.stdout) {
     rl.close();
   }
 
-  return { ask, confirm, select, close };
+  return { ask, confirm, input, select, close };
 }
 
 export function isTTY() {