karajan-code 3.7.1 → 3.8.0

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(),
+  };
+}