karajan-code 3.7.2 → 3.9.0

package/src/prompts/start-decision.js

@@ -0,0 +1,52 @@
+// KJC-TSK-0569 (Onboard B) — prompt + intent schema for the StartDecidor.
+//
+// The decider only DECIDES (one intent from a closed set); the safe HOW is
+// deterministic (0570 maps the intent to a saved command). Keep this prompt
+// tight: it routes, it never executes.
+const PREAMBLE = [
+  "IMPORTANT: You are running as a Karajan sub-agent (the `kj start` decider).",
+  "Do NOT mention Karajan, do NOT use MCP tools, do NOT execute anything.",
+  "Your only job: read the project assessment and pick ONE next-step intent.",
+].join(" ");
+
+/** Closed set of intents. Anything else degrades to ASK_USER. */
+export const INTENTS = new Set([
+  "ASSESS_ONLY",
+  "RECOMMEND_HARDEN",
+  "RECOMMEND_INDEX",
+  "START_TASK",
+  "PROPOSE_PLAN",
+  "ASK_USER",
+]);
+
+const INTENT_GUIDE = [
+  "- ASSESS_ONLY: the project is healthy and the user gave no goal — just report.",
+  "- RECOMMEND_HARDEN: quality gaps exist (no tests/CI, drifting checks, missing config).",
+  "- RECOMMEND_INDEX: the codebase has no knowledge index yet.",
+  "- START_TASK: the user stated a concrete thing to build or fix.",
+  "- PROPOSE_PLAN: legacy/large project, or a goal that needs a modernization/feature plan.",
+  "- ASK_USER: intent is unclear — ask ONE open question to disambiguate.",
+].join("\n");
+
+/**
+ * @param {{userMessage?: string, assessment?: string, instructions?: string}} input
+ * @returns {string}
+ */
+export function buildStartDecisionPrompt({ userMessage = "", assessment = "", instructions } = {}) {
+  const sections = [PREAMBLE];
+  if (instructions) sections.push(instructions);
+  sections.push(
+    "You route the next step for a project the user just opened with `kj start`.",
+    "## Project assessment (read-only signals)",
+    assessment || "(no assessment available)",
+    "## User goal",
+    userMessage.trim() || "(none given)",
+    "## Intents",
+    INTENT_GUIDE,
+    "Pick the single best intent. Prefer a concrete next step over ASK_USER when the assessment is clear.",
+    "If you pick ASK_USER, put the open question in questionToAsk.",
+    "Return a single valid JSON object and nothing else.",
+    'JSON schema: {"intent":"ASSESS_ONLY|RECOMMEND_HARDEN|RECOMMEND_INDEX|START_TASK|PROPOSE_PLAN|ASK_USER","rationale":string,"questionToAsk":string}',
+  );
+  return sections.join("\n\n");
+}

package/src/roles/reviewer-role.js

@@ -2,6 +2,7 @@ import { AgentRole } from "./agent-role.js";
 import { buildRtkInstructions } from "../prompts/rtk-snippet.js";
 import { extractFirstJson } from "../utils/json-extract.js";
 import { section, buildPromptLayout, joinLayout, STABLE, VOLATILE } from "../prompts/prompt-layout.js";
+import { isMutationReviewEnabled, buildReviewerMutationSignal } from "../mutate/reviewer-signal.js";
 
 const MAX_DIFF_LENGTH = 12000;
 
@@ -38,6 +39,11 @@ export class ReviewerRole extends AgentRole {
   // on every review — last. The buckets ride along so ClaudeAgent can
   // ship the stable block via --append-system-prompt (Φ1-D).
   async buildPrompt({ task, diff, reviewRules }) {
+    // Opt-in (KJ_REVIEW_MUTATION): null when off/clean → prompt stays identical.
+    const mutationSignal = await buildReviewerMutationSignal({
+      enabled: isMutationReviewEnabled(),
+      projectDir: this.config?.projectDir,
+    });
     const layout = buildPromptLayout([
       section(SUBAGENT_PREAMBLE, STABLE),
       section(this.instructions, STABLE),
@@ -51,6 +57,7 @@ export class ReviewerRole extends AgentRole {
       section(reviewRules ? `Review rules:\n${reviewRules}` : null, STABLE),
       section(`Task context:\n${task}`, VOLATILE),
       section(`Git diff:\n${truncateDiff(diff)}`, VOLATILE),
+      section(mutationSignal, VOLATILE),
     ]);
     return { prompt: joinLayout(layout), stablePrompt: layout.stable, volatilePrompt: layout.volatile };
   }

package/src/start/assessment.js

@@ -0,0 +1,74 @@
+// KJC-TSK-0569 (Onboard B) — deterministic synthesis of the read-only sweep.
+//
+// Turns the sweep bundle (Onboard A, 0568) into one coherent digest: a
+// human-readable report plus a machine summary the decider (StartDecidorRole)
+// consumes to pick an intent. No LLM here — the costly call is the haiku
+// decider, not a redundant strong-model narration. Reuses the harden advisory
+// formatter so the improvements section reads exactly like `kj harden --report`.
+import { formatAdvisoryReport } from "../harden/advisory.js";
+
+const EMPTY_TALLY = { install: 0, update: 0, review: 0, keep: 0 };
+
+/** Tally harden advisory artifacts by recommendation. */
+function tallyImprovements(improvements) {
+  const tally = { ...EMPTY_TALLY };
+  for (const a of improvements?.artifacts ?? []) {
+    if (a?.recommendation in tally) tally[a.recommendation] += 1;
+  }
+  return tally;
+}
+
+/** Quality/maintenance gaps as short phrases, derived from signals + drift. */
+function collectGaps(signals = {}, drift) {
+  const gaps = [];
+  if (!signals.hasTests) gaps.push("no tests");
+  if (!signals.hasCI) gaps.push("no CI");
+  if (typeof signals.staleDays === "number" && signals.staleDays > 365) {
+    gaps.push(`last commit ${signals.staleDays}d old`);
+  }
+  if (drift && drift.ok === false) {
+    const failed = (drift.checks ?? []).filter((c) => c?.ok === false).length;
+    if (failed > 0) gaps.push(`${failed} harden check(s) drifting`);
+  }
+  return gaps;
+}
+
+/**
+ * @param {object} bundle output of runReadOnlySweep (0568)
+ * @returns {{text: string, summary: object}}
+ */
+export function buildAssessment(bundle) {
+  if (!bundle || typeof bundle !== "object") {
+    throw new TypeError("buildAssessment: bundle must be an object");
+  }
+  const { maturity = {}, signals = {}, drift, improvements, rag, qmd } = bundle;
+  const gaps = collectGaps(signals, drift);
+  const improvementCounts = tallyImprovements(improvements);
+
+  const summary = {
+    maturity: maturity.maturity ?? "unknown",
+    declared: Boolean(maturity.declared),
+    deepHealthRecommended: Boolean(maturity.deepHealthRecommended),
+    gaps,
+    driftOk: drift ? drift.ok !== false : null,
+    improvementCounts,
+    indexed: rag ? Boolean(rag.indexed) : null,
+    qmdAvailable: qmd ? Boolean(qmd.available) : null,
+  };
+
+  const lines = [
+    `Project maturity: ${summary.maturity}${summary.declared ? " (declared)" : " (inferred)"}`,
+    ...(maturity.reasons ?? []).map((r) => `  - ${r}`),
+    "",
+    `Tests: ${signals.hasTests ? "yes" : "no"} · CI: ${signals.hasCI ? "yes" : "no"} · commits: ${signals.commitCount ?? 0}`,
+    `Quality gaps: ${gaps.length ? gaps.join(", ") : "none detected"}`,
+    `Knowledge index: ${summary.indexed === null ? "n/a" : summary.indexed ? "present" : "missing"}` +
+      ` · qmd: ${summary.qmdAvailable === null ? "n/a" : summary.qmdAvailable ? "available" : "absent"}`,
+  ];
+
+  if (improvements) {
+    lines.push("", ...formatAdvisoryReport(improvements));
+  }
+
+  return { text: lines.join("\n"), summary };
+}

package/src/start/maturity.js

@@ -0,0 +1,73 @@
+// KJC-TSK-0568 (Onboard A) — maturity classifier for the Brain (`kj start`).
+//
+// Pure and deterministic: given a bundle of read-only signals it labels the
+// project new | existing | legacy. No LLM, no I/O — the sweep (sweep.js) does
+// the reading; this only decides. The label drives which read-only subset the
+// orchestrator runs and, downstream (0570), whether a deep health pass is worth
+// the cost. A user-declared maturity always wins over inference.
+//
+// Acceptance criteria (KJC-TSK-0568):
+//   - empty repo / scaffolding only       -> new
+//   - code + config + tests/CI            -> existing
+//   - code but missing tests/CI, or very stale -> legacy
+
+/** Last-commit age (days) beyond which a repo counts as stalled/neglected. */
+export const STALE_DAYS_THRESHOLD = 365;
+
+const VALID = new Set(["new", "existing", "legacy"]);
+
+/**
+ * @param {object} signals
+ * @param {("new"|"existing"|"legacy"|null)} [signals.declared] user override
+ * @param {boolean} signals.hasSourceCode  real source files present
+ * @param {boolean} signals.scaffoldingOnly only generator boilerplate, no real code
+ * @param {boolean} signals.hasTests        a test suite is present
+ * @param {boolean} signals.hasCI           CI workflows are present
+ * @param {number}  [signals.commitCount]   number of commits (capped upstream)
+ * @param {number|null} [signals.staleDays] age of the last commit in days
+ * @returns {{maturity: "new"|"existing"|"legacy", reasons: string[], deepHealthRecommended: boolean, declared: boolean}}
+ */
+export function classifyMaturity(signals) {
+  if (!signals || typeof signals !== "object") {
+    throw new TypeError("classifyMaturity: signals must be an object");
+  }
+
+  if (VALID.has(signals.declared)) {
+    const maturity = signals.declared;
+    return {
+      maturity,
+      reasons: [`maturity declared by user as "${maturity}"`],
+      deepHealthRecommended: maturity === "legacy",
+      declared: true,
+    };
+  }
+
+  const reasons = [];
+  let maturity;
+
+  if (!signals.hasSourceCode || signals.scaffoldingOnly) {
+    maturity = "new";
+    reasons.push(signals.scaffoldingOnly ? "only scaffolding present, no real code yet" : "no source code found");
+  } else {
+    const stalled = typeof signals.staleDays === "number" && signals.staleDays > STALE_DAYS_THRESHOLD;
+    const gaps = [];
+    if (!signals.hasTests) gaps.push("no tests");
+    if (!signals.hasCI) gaps.push("no CI");
+    if (stalled) gaps.push(`last commit ${signals.staleDays}d old (stalled)`);
+
+    if (gaps.length > 0) {
+      maturity = "legacy";
+      reasons.push(`code present but neglected: ${gaps.join(", ")}`);
+    } else {
+      maturity = "existing";
+      reasons.push("code with tests and CI, actively maintained");
+    }
+  }
+
+  return {
+    maturity,
+    reasons,
+    deepHealthRecommended: maturity === "legacy",
+    declared: false,
+  };
+}

package/src/start/start-decider-role.js

@@ -0,0 +1,79 @@
+// KJC-TSK-0569 (Onboard B) — the StartDecidor: the only LLM in the Brain's
+// onboarding. Reads the deterministic assessment + user goal, picks ONE intent
+// from a closed set, and never executes (0570 maps the intent to a safe command).
+// Provider falls back to the coder, model defaults to haiku. Unparseable/unknown
+// output degrades to ASK_USER so `kj start` always has a sane next step.
+import { AgentRole } from "../roles/agent-role.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+import { buildStartDecisionPrompt, INTENTS } from "../prompts/start-decision.js";
+
+const FALLBACK_QUESTION = "What would you like to do with this project?";
+
+export class StartDecidorRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "start" });
+  }
+
+  extractInput(input) {
+    const src = typeof input === "string" ? { userMessage: input } : input || {};
+    return {
+      userMessage: src.userMessage || "",
+      assessment: src.assessment || "",
+      onOutput: src.onOutput || null,
+      ...src,
+    };
+  }
+
+  async buildPrompt({ userMessage, assessment }) {
+    return {
+      prompt: buildStartDecisionPrompt({ userMessage, assessment, instructions: this.instructions }),
+    };
+  }
+
+  parseOutput(raw) {
+    return extractFirstJson(raw);
+  }
+
+  buildSuccessResult(parsed, provider) {
+    const intent = INTENTS.has(parsed.intent) ? parsed.intent : "ASK_USER";
+    const rationale = String(parsed.rationale || "").trim();
+    const questionToAsk = String(parsed.questionToAsk || "").trim();
+    const degraded = intent !== parsed.intent;
+    return {
+      intent,
+      rationale: rationale || (degraded ? "Unrecognized intent, asking the user." : "No rationale provided."),
+      questionToAsk: intent === "ASK_USER" ? questionToAsk || FALLBACK_QUESTION : "",
+      provider,
+    };
+  }
+
+  buildSummary(parsed) {
+    const intent = INTENTS.has(parsed.intent) ? parsed.intent : "ASK_USER";
+    return `Start decision: ${intent}`;
+  }
+
+  handleParseNull(agentResult, provider) {
+    return this.degradedDecision({ agentResult, provider, reason: "no JSON found" });
+  }
+
+  handleParseError(err, agentResult, provider) {
+    return this.degradedDecision({ agentResult, provider, reason: err?.message || "parse error" });
+  }
+
+  // Never block onboarding: garbage in → ask the user one open question.
+  degradedDecision({ agentResult, provider, reason }) {
+    this.logger?.warn?.(`[start] decider output unusable (${reason}) — asking the user.`);
+    return {
+      ok: true,
+      result: {
+        intent: "ASK_USER",
+        rationale: `Could not read a decision (${reason}).`,
+        questionToAsk: FALLBACK_QUESTION,
+        provider,
+        degraded: true,
+      },
+      summary: "Start decision: ASK_USER (fallback)",
+      usage: agentResult.usage,
+    };
+  }
+}

package/src/start/sweep.js

@@ -0,0 +1,112 @@
+// KJC-TSK-0568 (Onboard A) — read-only sweep orchestrator for the Brain.
+//
+// Runs the READ-ONLY signals fitting the project's maturity and aggregates them
+// into one structured bundle for synthesis (Onboard B, 0569). Writes nothing.
+// No LLM: maturity is deterministic and the costly audit is deferred — legacy
+// only flags `deepHealthRecommended` (0570 decides). Subset by maturity: new =
+// brief+tests; existing/legacy = + drift, harden advisory, rag + qmd status.
+// Collaborators are injected (opts.deps) so it stays trivially testable.
+import { existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+
+import { collectAll } from "../onboarder/collectors/index.js";
+import { checkHarden } from "../harden/check.js";
+import { compareHarden } from "../harden/advisory.js";
+import { detectTestFramework } from "../utils/project-detect.js";
+import { detectQmd } from "../utils/qmd-detect.js";
+import {
+  dbPath, openVecStore, projectSlug, countChunks, getLastIndexedCommit,
+} from "../rag/vec-store.js";
+import { classifyMaturity } from "./maturity.js";
+
+const CODE_EXT = new Set([
+  ".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx", ".py", ".go",
+  ".rs", ".java", ".php", ".rb", ".c", ".cc", ".cpp", ".cs",
+]);
+const SCAFFOLD_MAX_FILES = 3;
+const CI_MARKERS = [".github/workflows", ".gitlab-ci.yml"];
+
+const safe = async (fn) => { try { return await fn(); } catch { return null; } };
+
+/** Count real source files in a tree bundle, skipping tests. */
+export function countCodeFiles(tree = []) {
+  let n = 0;
+  for (const node of tree) {
+    if (node.kind === "dir") n += countCodeFiles(node.children);
+    else if (node.kind === "file") {
+      const ext = node.path.slice(node.path.lastIndexOf("."));
+      const isTest = /\.(test|spec)\./.test(node.path) || /(^|\/)(test|tests|__tests__)\//.test(node.path);
+      if (CODE_EXT.has(ext) && !isTest) n += 1;
+    }
+  }
+  return n;
+}
+
+/** Age of the last commit in days, or null on non-git / no commits. */
+function lastCommitAgeDays(projectDir) {
+  try {
+    const out = execFileSync("git", ["log", "-1", "--format=%ct"], {
+      cwd: projectDir, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    if (!out) return null;
+    return Math.floor((Date.now() - Number(out) * 1000) / 86_400_000);
+  } catch { return null; }
+}
+
+/** Read-only RAG index status; null when no index file exists yet. */
+function readRagStatus(projectDir) {
+  try {
+    if (!existsSync(dbPath())) return { indexed: false, chunks: 0, lastIndexedCommit: null };
+    const db = openVecStore();
+    return {
+      indexed: true,
+      chunks: countChunks(db, { kind: "code" }),
+      lastIndexedCommit: getLastIndexedCommit(db, projectSlug(projectDir)),
+    };
+  } catch { return null; }
+}
+
+/**
+ * @param {string} projectDir
+ * @param {{declared?: ("new"|"existing"|"legacy"|null), profile?: string, deps?: object}} [opts]
+ *   declared = user-declared maturity; deps = injected collaborators (defaults = real collectors).
+ */
+export async function runReadOnlySweep(projectDir, { declared = null, profile = "standard", deps = {} } = {}) {
+  const d = {
+    collectAll, detectTestFramework, checkHarden, compareHarden,
+    detectQmd, ragStatus: readRagStatus, gitAgeDays: lastCommitAgeDays, ...deps,
+  };
+
+  const brief = await safe(() => d.collectAll(projectDir));
+  const tests = await safe(() => d.detectTestFramework(projectDir));
+
+  const tree = brief?.tree ?? [];
+  const present = brief?.configs?.present ?? [];
+  const codeFiles = countCodeFiles(tree);
+  const commitCount = brief?.git?.commitCount ?? 0;
+
+  const signals = {
+    hasSourceCode: codeFiles > 0,
+    scaffoldingOnly: codeFiles > 0 && codeFiles <= SCAFFOLD_MAX_FILES && commitCount <= 1,
+    hasTests: Boolean(tests?.hasTests),
+    hasCI: CI_MARKERS.some((m) => present.includes(m)),
+    commitCount,
+    staleDays: d.gitAgeDays(projectDir),
+  };
+
+  const maturity = classifyMaturity({ declared, ...signals });
+  const deep = maturity.maturity !== "new";
+
+  return {
+    projectDir,
+    maturity,
+    signals,
+    brief,
+    tests,
+    drift: deep ? await safe(() => d.checkHarden({ projectDir, profile })) : null,
+    improvements: deep ? await safe(() => d.compareHarden({ projectDir, profile })) : null,
+    rag: deep ? await safe(() => d.ragStatus(projectDir)) : null,
+    qmd: deep ? await safe(() => d.detectQmd()) : null,
+    collectedAt: new Date().toISOString(),
+  };
+}

package/src/utils/update-check.js

@@ -1,11 +1,47 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { isSea } from "node:sea";
 import { getKarajanHome } from "./paths.js";
 
 const CACHE_FILE = "update-check.json";
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
 const PACKAGE_NAME = "karajan-code";
 
+const RAW_BASE = "https://raw.githubusercontent.com/manufosela/karajan-code/main/scripts";
+export const INSTALL_SH_URL = `${RAW_BASE}/install-binary.sh`;
+export const INSTALL_PS1_URL = `${RAW_BASE}/install-binary.ps1`;
+
+/**
+ * Build the "how to update" line for the detected install channel.
+ * Pure and testable — no I/O.
+ * @param {{channel: "sea"|"npm"|"unknown", platform?: string}} opts
+ */
+export function updateInstruction({ channel, platform = process.platform }) {
+  if (channel === "sea") {
+    return platform === "win32"
+      ? `Re-run the installer: irm ${INSTALL_PS1_URL} | iex`
+      : `Re-run the installer: curl -fsSL ${INSTALL_SH_URL} | sh`;
+  }
+  if (channel === "npm") {
+    return `Run: npm install -g ${PACKAGE_NAME}`;
+  }
+  // Channel unknown — offer both paths, never silently pick a wrong one.
+  return `Update: npm install -g ${PACKAGE_NAME}  (or re-run the binary installer — see README)`;
+}
+
+/**
+ * Detect how this kj was installed: "sea" (standalone binary) or "npm"
+ * (global install / source tree). Falls back to "npm" if isSea() throws.
+ */
+export function detectInstallChannel() {
+  try {
+    return isSea() ? "sea" : "npm";
+  } catch {
+    // isSea() unexpectedly threw ⇒ treat as npm / source tree, never block.
+    return "npm";
+  }
+}
+
 /**
  * Check npm for a newer version. Non-blocking, cached for 24h.
  * Returns { updateAvailable, latest, current } or null if check fails/cached.
@@ -61,8 +97,9 @@ export async function checkForUpdate(currentVersion) {
 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}`);
-    console.log(`  Run: npm install -g ${PACKAGE_NAME}\n`);
+    console.log(`  ${updateInstruction({ channel })}\n`);
   }
 }