karajan-code 2.19.4 → 2.21.0

package/README.md

@@ -345,6 +345,34 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 
 ## Recent releases
 
+> **v2.21.0 released** — Minor. **Brownfield Onboarder role**. Karajan now ships a dedicated path to analyze any existing codebase and produce a Markdown Architecture Brief that the planner can consume as automatic context. Closes KJC-TSK-0384 (3 PRs).
+>
+> KJC-TSK-0384 (PRs #804 + #805 + #806): **`kj onboard`** runs five deterministic collectors over a project root — directory walk (ignoring `node_modules` / `.git` / `dist` / `build`), git log (commits, branches, hot files via `--name-only` over the last 200 commits), 18 well-known config patterns + `package.json` scripts, ADR-style filenames under `docs/adr/`, `docs/adrs/`, `docs/architecture/`, plus a one-shot bundle. Then optionally synthesises a Markdown Architecture Brief via the new OnboarderRole. Output lands at `~/.karajan/onboarding/<slug>.md`. Flags: `--no-synth` (skip the LLM call, dump the raw collectors — useful for CI), `--output <path>` (override default target). Greenfield projects produce `# Project is greenfield` instead of erroring.
+>
+> **New `--use-onboarding` flag on `kj plan generate`**: reads the cached Architecture Brief and prepends it to the planner context under a `## Architecture Brief (from kj onboard)` heading. Silent on cache miss without the flag; loud `warn` when the flag is set but no cache exists, so a missed `kj onboard` invocation surfaces immediately.
+>
+> Workflow:
+>
+> ```bash
+> kj onboard                            # produces ~/.karajan/onboarding/<slug>.md once
+> kj plan generate task.md \
+>     --use-onboarding                  # next plan uses it as context
+> ```
+>
+> **What's next** — The **Project RAG** epic (KJC-PCS-0049) starts in v2.22.0: vector store + Ollama embedder + indexer + retriever + CLI / MCP / HU Board consumers. Onboarder is its prerequisite (the brief feeds the indexer's first pass).
+>
+> **v2.20.0 released** — Minor. **HU Board polish + UX papercuts** cluster: 5 cards closed across two net-new features, two PG housekeeping syncs for work that had already landed, and one docs refresh.
+>
+> KJC-TSK-0397 (PR #801): **`kj plan generate` now prepends a `[PREFLIGHT-000]` HU to every plan** and gates every functional HU on it. The HU's acceptance tests are stack-aware shell commands — Node gets `node --version` + `npm install` + conditional `npm test` / `npm run lint`; Python gets `python --version` + `pip install -r requirements.txt` (or `poetry install`) + `pytest --collect-only`; Firebase projects get `firebase projects:list`; GCP projects get `gcloud auth list`; everyone gets `git status --porcelain`. Idempotent: a plan that already has a HU titled `PREFLIGHT-000` / "verificar entorno" is left untouched. Opt out per-invocation with `--no-preflight-hu`. The point: Karajan owns the plumbing, the user no longer has to remember to add a 'verify env' step to every task file.
+>
+> KJC-TSK-0395 (PR #802): **`kj init` learns a config scope wizard plus `--global` / `--local` flags**. The wizard now asks where the config should land — `~/.karajan/kj.config.yml` (global) or `./.karajan/kj.config.yml` (local override). `loadConfig` refuses to load a project that has a local config without a global counterpart with an actionable message — the override-on-top-of-base invariant. Use case: a repo with `coder=claude`, another with `coder=opencode`, without editing YAML by hand.
+>
+> KJC-TSK-0396 (PG sync, originally PRs #702 + #703): **HU Board `⏹ Stop` button** aborts every `kj run` associated with a plan via SIGTERM → SIGKILL escalation, resets running HUs to pending. Already shipped in v2.10.x; today's release closes the PG card with the canonical commits as evidence.
+>
+> KJC-TSK-0377 (PG sync, originally PR #683): **auto-cleanup ampliado** to also catch `s_*`, `plan-*`, `auto-tmp_*`, `auto-test_*` prefixes during the boot ephemeral-project sweep. Already shipped in v2.12.x.
+>
+> KJC-TSK-0385 (PR #800): **`docs/task-templates/spec-conventions.md` gains Section 8 (`spec_section` REQUIRED when numbered SPEC headings present) and Section 9 (`acceptance_tests` shape, 2-4 tests, gherkin + shell mix)**. Plus `plan-generate.md` switches two stale `~/.kj/plans/` paths to `~/.karajan/plans/`.
+>
 > **v2.19.4 released** — Patch. **`kj resume` now continues from where it stopped** + **autoInit no longer commits zombies on the user's main**. Two bugs closed in one release.
 >
 > KJC-BUG-0058 (PR #798, reported by [@aitormf](https://github.com/aitormf)): a session that stopped during Sonar would re-run the full pre-loop on `kj resume <id>` — HU-reviewer, intent, discover, triage, domainCurator, **researcher, architect, planner** all from scratch — doubling token cost and breaking the value-prop of the command. Root cause: `resumeFlow` (flow-runner.js:280) called `runFlow` without rehydrating stage state, and the session never persisted stage outputs in the first place. **Fix**: two new mutators in `src/session/mutators.js` (`setStageResult` mirrors into `stage_results[name]` + `stages_completed[]`; `setStageBundle` adds `stage_bundles[name]` for cross-stage context like `researchContext`, `architectContext`, `plannedTask`). Two closures inside `runPreLoopStages` (`persistStage` + `resumeSkip`) wrap every cacheable stage. `init-context.js` rehydrates `ctx.stageResults` from the loaded session before invoking the pre-loop. Triage is *not* skipped on resume — it produces `roleOverrides` the Brain decisor depends on and is cheap to re-run.

package/package.json

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

package/src/cli/register-meta.js

@@ -2,6 +2,7 @@ import { discoverCommand } from "../commands/discover.js";
 import { triageCommand } from "../commands/triage.js";
 import { researcherCommand } from "../commands/researcher.js";
 import { architectCommand } from "../commands/architect.js";
+import { onboardCommand } from "../commands/onboard.js";
 import { auditCommand } from "../commands/audit.js";
 import { resumeCommand } from "../commands/resume.js";
 import { boardCommand } from "../commands/board.js";
@@ -86,6 +87,17 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  program
+    .command("onboard")
+    .description("Analyze an existing codebase (brownfield) and produce an Architecture Brief")
+    .option("--no-synth", "Skip the LLM synthesis step, dump raw collectors only")
+    .option("--output <path>", "Override the default ~/.karajan/onboarding/<slug>.md target")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "onboard", flags, async ({ config, logger }) => {
+        await onboardCommand({ config, logger, flags });
+      });
+    });
+
   program
     .command("audit")
     .description("Analyze codebase health (read-only)")

package/src/cli/register-pipeline.js

@@ -23,6 +23,8 @@ export function registerPipeline(program, { pkgVersion }) {
     .description("Initialize config, review rules and SonarQube")
     .option("--no-interactive", "Skip wizard, use defaults (for CI/scripts)")
     .option("--scaffold-ci", "Scaffold Karajan CI Gateway workflow files")
+    .option("--global", "Save config to ~/.karajan/kj.config.yml (skip the scope wizard)")
+    .option("--local", "Save config to ./.karajan/kj.config.yml (skip the scope wizard)")
     .action(async (flags) => {
       await withConfig(pkgVersion, "init", flags, async ({ config: _config, logger }) => {
         await initCommand({ logger, flags });

package/src/cli/register-plan.js

@@ -42,6 +42,8 @@ export function registerPlan(program, { pkgVersion }) {
     .option("--no-plan-review", "Skip the high-level plan reviewer pass (gaps / deps / overlap / order)")
     .option("--skip-spec-review", "Bypass the spec-reviewer pre-pipeline audit")
     .option("--quick", "Sketch mode — skip every quality pass after the initial planner call")
+    .option("--no-preflight-hu", "Skip auto-injection of [PREFLIGHT-000] HU at the top of the generated plan")
+    .option("--use-onboarding", "Inject the cached Architecture Brief (~/.karajan/onboarding/<slug>.md) into the planner context")
     .option("-y, --yes", "Skip the project-name prompt (use the auto-derived default).")
     .option("--no-interactive", "Force non-interactive mode (no prompts, use defaults).")
     .action(async (task, flags) => {
@@ -100,6 +102,8 @@ export function registerPlan(program, { pkgVersion }) {
             quick: Boolean(flags.quick),
             yes: Boolean(flags.yes),
             interactive: flags.interactive,
+            preflightHu: flags.preflightHu !== false, // KJC-TSK-0397
+            useOnboarding: Boolean(flags.useOnboarding), // KJC-TSK-0384 PR 3
           },
         });
       });

package/src/commands/init.js

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { getConfigPath, loadConfig, writeConfig } from "../config.js";
+import { getConfigPath, getProjectConfigPath, loadConfig, writeConfig } from "../config.js";
 import { sonarUp, checkVmMaxMapCount } from "../sonar/manager.js";
 import { exists, ensureDir } from "../utils/fs.js";
 import { getKarajanHome } from "../utils/paths.js";
@@ -579,19 +579,50 @@ async function ensureGitignoreEntries(projectDir, logger) {
   logger.info(`Added to .gitignore: ${missing.map(e => e.pattern).join(", ")}`);
 }
 
+/**
+ * KJC-TSK-0395: decide where the config is written based on the flags
+ * and (when interactive) a wizard prompt. Returns { configPath, scope }.
+ * Throws when both --global and --local are passed (mutually exclusive).
+ */
+export async function resolveConfigScope({ flags, interactive }) {
+  if (flags?.global && flags?.local) {
+    throw new Error("Cannot pass both --global and --local — pick one scope for the config.");
+  }
+  if (flags?.global) return { configPath: getConfigPath(), scope: "global" };
+  if (flags?.local) return { configPath: getProjectConfigPath(process.cwd()), scope: "local" };
+  if (interactive) {
+    const wizard = createWizard();
+    try {
+      const choice = await wizard.select(
+        "Where do you want to save the config? (default: global)",
+        [
+          { value: "global", label: `Global (${getConfigPath()} — applies to all projects)` },
+          { value: "local",  label: `Local  (${getProjectConfigPath(process.cwd())} — overrides global for this project only)` },
+        ]
+      );
+      return { configPath: choice === "local" ? getProjectConfigPath(process.cwd()) : getConfigPath(), scope: choice };
+    } finally {
+      wizard.close();
+    }
+  }
+  // Non-interactive + no flags → legacy behaviour: global. Keeps CI scripts working.
+  return { configPath: getConfigPath(), scope: "global" };
+}
+
 export async function initCommand({ logger, flags = {} }) {
   const karajanHome = getKarajanHome();
   await ensureDir(karajanHome);
   logger.info(`Ensured ${karajanHome} exists`);
 
-  const configPath = getConfigPath();
+  const interactive = flags.noInteractive !== true && isTTY();
+  const { configPath, scope } = await resolveConfigScope({ flags, interactive });
+  logger.info(`Config scope: ${scope} → ${configPath}`);
   const karajanDir = path.join(process.cwd(), ".karajan");
   await ensureDir(karajanDir);
   const reviewRulesPath = path.resolve(karajanDir, "review-rules.md");
   const coderRulesPath = path.resolve(karajanDir, "coder-rules.md");
 
   const { config, exists: configExists } = await loadConfig();
-  const interactive = flags.noInteractive !== true && isTTY();
 
   // Auto-detect language from OS locale for non-interactive mode
   if (!interactive && !configExists) {

package/src/commands/onboard.js

@@ -0,0 +1,35 @@
+// KJC-TSK-0384 PR 2 — `kj onboard` runs collectors + optional LLM synth.
+import { writeFile, mkdir, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { collectAll } from "../onboarder/collectors/index.js";
+import { OnboarderRole } from "../roles/onboarder-role.js";
+import { resolveRole } from "../config.js";
+import { getKarajanHome } from "../utils/paths.js";
+
+export function briefPath(projectDir) {
+  const slug = path.basename(projectDir).replace(/[^a-zA-Z0-9._-]/g, "-").toLowerCase() || "project";
+  return path.join(getKarajanHome(), "onboarding", `${slug}.md`);
+}
+
+export async function onboardCommand({ config, logger, flags = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const out = flags.output || briefPath(projectDir);
+  logger.info(`[onboard] collecting from ${projectDir}`);
+  const bundle = await collectAll(projectDir);
+  await mkdir(path.dirname(out), { recursive: true });
+  if (flags.noSynth) {
+    await writeFile(out, `# Onboarding bundle — ${projectDir}\n\n\`\`\`json\n${JSON.stringify(bundle, null, 2)}\n\`\`\`\n`, "utf8");
+    logger.info(`[onboard] wrote raw bundle to ${out} (--no-synth)`);
+    return { path: out, bundle, brief: null };
+  }
+  const roleCfg = resolveRole(config, "onboarder") || resolveRole(config, "architect");
+  const templatePath = new URL("../../templates/roles/onboarder.md", import.meta.url).pathname;
+  const instructions = existsSync(templatePath) ? await readFile(templatePath, "utf8") : "";
+  const role = new OnboarderRole({ instructions, config, ...roleCfg });
+  const result = await role.run({ bundle });
+  const brief = result?.result?.brief || "# Project is greenfield\n\nNo synth output.\n";
+  await writeFile(out, brief, "utf8");
+  logger.info(`[onboard] wrote Architecture Brief to ${out}`);
+  return { path: out, bundle, brief };
+}

package/src/commands/plan/generate.js

@@ -14,6 +14,8 @@ import { withBrainRecovery } from "../../brain/with-brain-recovery.js";
 import { buildStandbyState } from "../../brain/standby-store.js";
 import { printResumeHint } from "../../utils/display/resume-hint.js";
 import { runSpecReview } from "../../spec-review/run-spec-review.js";
+import { prependPreflightHu } from "../../plan/preflight-hu.js";
+import { readCachedBrief } from "../../onboarder/cache.js";
 import { formatPlan, formatHuTable } from "./_shared.js";
 
 /**
@@ -55,12 +57,29 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
     task = reviewResult.finalSpec; // downstream runs the refined spec
   }
 
+  // KJC-TSK-0384 PR 3: --use-onboarding folds the cached Architecture Brief
+  // from `kj onboard` into the planner's context. Silent when no brief is
+  // cached so users without one don't see noise; loud warn when they passed
+  // the flag explicitly but the cache is empty so the missed wiring surfaces.
+  let resolvedContext = context;
+  if (flags?.useOnboarding) {
+    const brief = await readCachedBrief(config?.projectDir || process.cwd());
+    if (brief.found) {
+      resolvedContext = [
+        resolvedContext, brief.content ? `## Architecture Brief (from kj onboard)\n\n${brief.content}` : null,
+      ].filter(Boolean).join("\n\n");
+      runLog.logText(`[planner] onboarding brief injected from ${brief.path}`);
+    } else {
+      logger?.warn?.(`--use-onboarding passed but no brief at ${brief.path}. Run 'kj onboard' first.`);
+    }
+  }
+
   const plannerRole = resolveRole(config, "planner");
   await assertAgentsAvailable([plannerRole.provider]);
   runLog.logText(`[planner] provider=${plannerRole.provider}`);
 
   const planner = createAgent(plannerRole.provider, config, logger);
-  const prompt = buildPlannerPrompt({ task, context });
+  const prompt = buildPlannerPrompt({ task, context: resolvedContext });
   const silenceTimeoutMs = Number(config?.session?.max_agent_silence_minutes) > 0
     ? Math.round(Number(config.session.max_agent_silence_minutes) * 60 * 1000)
     : undefined;
@@ -414,6 +433,15 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
     }
   }
 
+  // KJC-TSK-0397: inject a [PREFLIGHT-000] HU at the top of the plan so
+  // every functional HU gates on a clean environment (deps + build + tests
+  // + lint + git clean, plus cloud auth when applicable). Idempotent: a
+  // plan that already has a preflight HU is left untouched. Disable with
+  // `--no-preflight-hu`.
+  if (flags.preflightHu !== false) {
+    await prependPreflightHu(plan, projectDir);
+  }
+
   const planId = await savePlan(projectDir, plan);
   const { plansDir } = await import("../../plan/plan-store.js");
   const path = await import("node:path");

package/src/config/loader.js

@@ -114,6 +114,18 @@ export async function loadConfig(projectDir) {
   // Load project config (.karajan/kj.config.yml)
   const projectConfig = await loadProjectConfig(projectDir);
 
+  // KJC-TSK-0395: enforce the local-overrides-global hierarchy. A project
+  // config with no global counterpart is almost always user error (copied
+  // a .karajan dir from another repo, edited the wrong file, etc.) and
+  // would silently behave like a global config without the defaults
+  // people expect. Refuse with an actionable message.
+  if (projectConfig && !globalExists) {
+    throw new Error(
+      `Local config found at ${getProjectConfigPath(projectDir)} but no global config exists.\n` +
+      "Local configs are merged ON TOP of the global one — run `kj init --global` first to create the base."
+    );
+  }
+
   // Merge: DEFAULTS < global < project
   let merged = mergeDeep(DEFAULTS, globalConfig);
   if (projectConfig) {

package/src/onboarder/cache.js

@@ -0,0 +1,24 @@
+// KJC-TSK-0384 PR 3 — read the cached Architecture Brief deterministically.
+// briefPath() is exported by src/commands/onboard.js so the writer and
+// reader share the same slug rule.
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+
+import { briefPath } from "../commands/onboard.js";
+
+/**
+ * Read the cached Architecture Brief for `projectDir`. Returns:
+ *   { found: true,  path, content }  — when the file exists
+ *   { found: false, path }           — when it does not
+ * Never throws.
+ */
+export async function readCachedBrief(projectDir) {
+  const p = briefPath(projectDir);
+  if (!existsSync(p)) return { found: false, path: p };
+  try {
+    const content = await readFile(p, "utf8");
+    return { found: true, path: p, content };
+  } catch {
+    return { found: false, path: p };
+  }
+}

package/src/onboarder/collectors/index.js

@@ -0,0 +1,119 @@
+// Onboarder collectors — deterministic, zero-LLM extractors. Each pure,
+// JSON-serialisable, fail-soft (returns null on the slot, never throws).
+// Output bundle is consumed by PR 2 synthesis or dumped via `--no-synth`.
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { join, relative } from "node:path";
+
+import { detectProjectStack } from "../../utils/stack-detect.js";
+
+const IGNORED_DIRS = new Set(["node_modules", ".git", "dist", "build", "coverage", ".karajan", ".next", "__pycache__"]);
+
+function safeRun(cmd, args, opts = {}) {
+  try { return execFileSync(cmd, args, { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"], ...opts }).trim(); }
+  catch { return null; }
+}
+
+// Tree summary: immediate dirs with rough byte count. Ignores noise dirs.
+export async function collectTree(projectDir, { maxDepth = 2 } = {}) {
+  async function walk(dir, depth) {
+    if (depth > maxDepth) return [];
+    let entries;
+    try { entries = await readdir(dir, { withFileTypes: true }); } catch { return []; }
+    const out = [];
+    for (const ent of entries) {
+      if (ent.name.startsWith(".") && ent.name !== ".github") continue;
+      if (IGNORED_DIRS.has(ent.name)) continue;
+      const sub = join(dir, ent.name);
+      if (ent.isDirectory()) {
+        const children = await walk(sub, depth + 1);
+        let bytes = 0;
+        for (const c of children) bytes += c.bytes || 0;
+        out.push({ path: relative(projectDir, sub), kind: "dir", bytes, children });
+      } else if (ent.isFile()) {
+        try { out.push({ path: relative(projectDir, sub), kind: "file", bytes: statSync(sub).size }); } catch { /* race */ }
+      }
+    }
+    return out;
+  }
+  return walk(projectDir, 0);
+}
+
+// Git log + branches + hot files. Returns null on non-git (greenfield).
+export function collectGitHistory(projectDir, { maxHotFiles = 10 } = {}) {
+  const inside = safeRun("git", ["rev-parse", "--is-inside-work-tree"], { cwd: projectDir });
+  if (inside !== "true") return null;
+  const commitsRaw = safeRun("git", ["log", "--oneline", "-n", "100"], { cwd: projectDir }) || "";
+  const branchesRaw = safeRun("git", ["branch", "--list", "--all", "--format=%(refname:short)"], { cwd: projectDir }) || "";
+  const hotRaw = safeRun("git", ["log", "--name-only", "--pretty=format:", "-n", "200"], { cwd: projectDir }) || "";
+  const counts = {};
+  for (const line of hotRaw.split("\n").map((s) => s.trim()).filter(Boolean)) {
+    counts[line] = (counts[line] || 0) + 1;
+  }
+  const hotFiles = Object.entries(counts)
+    .sort((a, b) => b[1] - a[1]).slice(0, maxHotFiles)
+    .map(([file, touches]) => ({ file, touches }));
+  return {
+    commitCount: commitsRaw ? commitsRaw.split("\n").length : 0,
+    branches: branchesRaw.split("\n").filter(Boolean),
+    hotFiles,
+    headSha: safeRun("git", ["rev-parse", "HEAD"], { cwd: projectDir }) || null,
+  };
+}
+
+// Presence-check of known config files + package.json scripts.
+export function collectConfigs(projectDir) {
+  const configFiles = [
+    "package.json", "pyproject.toml", "Cargo.toml", "go.mod",
+    "tsconfig.json", "jsconfig.json",
+    ".eslintrc.js", ".eslintrc.json", "eslint.config.js",
+    "vitest.config.js", "vitest.config.ts", "jest.config.js", "jest.config.ts",
+    "firebase.json", ".gcloudignore", "Dockerfile", "docker-compose.yml",
+    ".github/workflows", ".gitlab-ci.yml", "Makefile",
+  ];
+  const present = configFiles.filter((f) => existsSync(join(projectDir, f)));
+  let scripts = null;
+  try {
+    const pkg = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8"));
+    scripts = pkg.scripts || null;
+  } catch { /* not a node project */ }
+  return { present, scripts };
+}
+
+// Discover ADR files under docs/adr/, docs/adrs/, docs/architecture/, root.
+export async function collectAdrs(projectDir) {
+  const dirs = ["docs/adr", "docs/adrs", "docs/architecture", "."];
+  const found = [];
+  for (const d of dirs) {
+    const abs = join(projectDir, d);
+    if (!existsSync(abs)) continue;
+    try {
+      const entries = await readdir(abs);
+      for (const f of entries) {
+        if (/^adr-?\d|^\d{4}-.+\.md$/i.test(f) || /architecture.*\.md$/i.test(f)) {
+          found.push(relative(projectDir, join(abs, f)));
+        }
+      }
+    } catch { /* unreadable */ }
+  }
+  return found;
+}
+
+// One-shot bundle: every slot is independent; missing slots → null/[].
+export async function collectAll(projectDir) {
+  const [stack, tree, adrs] = await Promise.all([
+    detectProjectStack(projectDir).catch(() => null),
+    collectTree(projectDir).catch(() => []),
+    collectAdrs(projectDir).catch(() => []),
+  ]);
+  return {
+    projectDir,
+    stack,
+    tree,
+    git: collectGitHistory(projectDir),
+    configs: collectConfigs(projectDir),
+    adrs,
+    collectedAt: new Date().toISOString(),
+  };
+}

package/src/plan/preflight-hu.js

@@ -0,0 +1,102 @@
+/**
+ * KJC-TSK-0397: auto-inject a [PREFLIGHT-000] HU at the top of every
+ * plan generated by `kj plan generate` so the sub-pipeline gates on a
+ * clean environment before burning tokens on functional HUs.
+ *
+ * Design points:
+ *   - Pure shell tests — no Karajan-specific runtime, just commands
+ *     that exit 0 when the environment is ready.
+ *   - Stack-aware: Node, Python and Firebase signals come straight
+ *     from detectProjectStack() + on-disk file probes. Adding a new
+ *     stack is one entry in `composePreflightTests`.
+ *   - Idempotent: re-running over a plan that already has a HU with
+ *     id `PREFLIGHT-000` or a title containing 'preflight' / 'verificar
+ *     entorno' returns the plan unchanged. Required because the same
+ *     planner output may flow through structural-pass + plan-fixer
+ *     before reaching savePlan.
+ *   - All other HUs' `blocked_by` get the PREFLIGHT-000 id appended
+ *     (unless they already have it, again idempotent). Their own
+ *     dependencies are preserved.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { detectProjectStack } from "../utils/stack-detect.js";
+
+const PREFLIGHT_ID = "PREFLIGHT-000";
+
+/**
+ * Compose stack-aware shell acceptance tests. Always includes a
+ * `git status --porcelain` clean-tree check; everything else is
+ * additive based on what the project actually uses.
+ */
+export function composePreflightTests(stack, projectDir = ".") {
+  const tests = [
+    { type: "shell", content: "git status --porcelain | (! grep -q .)" },
+  ];
+  const lang = stack?.language;
+  if (lang === "javascript" || lang === "typescript") {
+    tests.push({ type: "shell", content: "node --version | grep -qE '^v(2[0-9]|[3-9][0-9])'" });
+    if (existsSync(join(projectDir, "package.json"))) {
+      tests.push({ type: "shell", content: "npm install --no-audit --no-fund" });
+      tests.push({ type: "shell", content: "test -z \"$(npm run | grep -E '^  test$')\" || npm test" });
+      tests.push({ type: "shell", content: "test -z \"$(npm run | grep -E '^  lint$')\" || npm run lint" });
+    }
+  } else if (lang === "python") {
+    tests.push({ type: "shell", content: "python --version | grep -qE 'Python 3\\.(1[0-9]|[2-9][0-9])'" });
+    if (existsSync(join(projectDir, "requirements.txt"))) {
+      tests.push({ type: "shell", content: "pip install -r requirements.txt" });
+    } else if (existsSync(join(projectDir, "pyproject.toml"))) {
+      tests.push({ type: "shell", content: "test -f poetry.lock && poetry install || pip install -e ." });
+    }
+    tests.push({ type: "shell", content: "command -v pytest && pytest --collect-only || true" });
+  }
+  if (existsSync(join(projectDir, "firebase.json"))) {
+    tests.push({ type: "shell", content: "firebase projects:list" });
+  }
+  if (existsSync(join(projectDir, ".gcloudignore"))) {
+    tests.push({ type: "shell", content: "gcloud auth list --filter=status:ACTIVE --format='value(account)' | (! test -z \"$(cat)\")" });
+  }
+  return tests;
+}
+
+/**
+ * Return true when the plan already has a preflight-style HU (by id or
+ * title). Pattern-matches conservatively to avoid duplicate injection.
+ */
+export function hasPreflightHu(plan) {
+  if (!plan?.hus?.length) return false;
+  return plan.hus.some((hu) => {
+    if (hu.id === PREFLIGHT_ID) return true;
+    const title = (hu.title || hu.description || "").toLowerCase();
+    return title.includes("preflight-000") || title.includes("verificar entorno") || title.includes("preflight check");
+  });
+}
+
+/**
+ * Prepend a [PREFLIGHT-000] HU to the plan and append its id to the
+ * `blocked_by` of every other HU. Returns the mutated plan reference
+ * for convenience; mutation is in place so callers don't need to
+ * reassign. No-op when the plan already has a preflight HU.
+ */
+export async function prependPreflightHu(plan, projectDir) {
+  if (!plan?.hus) return plan;
+  if (hasPreflightHu(plan)) return plan;
+  const stack = await detectProjectStack(projectDir);
+  const preflight = {
+    id: PREFLIGHT_ID,
+    title: "[PREFLIGHT-000] Verificar entorno de desarrollo listo",
+    description: "[PREFLIGHT-000] Block functional HUs until the project's environment is reproducible: deps installed, build/test/lint passing, git tree clean, cloud auth ready when applicable.",
+    task_type: "infra",
+    blocked_by: [],
+    reuse: [],
+    acceptance_tests: composePreflightTests(stack, projectDir),
+    spec_section: null,
+  };
+  for (const hu of plan.hus) {
+    if (!Array.isArray(hu.blocked_by)) hu.blocked_by = [];
+    if (!hu.blocked_by.includes(PREFLIGHT_ID)) hu.blocked_by.push(PREFLIGHT_ID);
+  }
+  plan.hus.unshift(preflight);
+  return plan;
+}

package/src/roles/onboarder-role.js

@@ -0,0 +1,61 @@
+// KJC-TSK-0384 PR 2 — Onboarder role. Wraps collectors bundle + LLM
+// synthesis into a Markdown Architecture Brief.
+import { AgentRole } from "./agent-role.js";
+
+const FENCE_RE = /^```(?:markdown|md)?\s*\n([\s\S]*?)\n```\s*$/;
+
+export class OnboarderRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "onboarder" });
+  }
+
+  extractInput(input) {
+    if (typeof input === "string") return { bundle: { projectDir: input } };
+    return { bundle: input?.bundle || input || { projectDir: "" } };
+  }
+
+  async buildPrompt({ bundle }) {
+    const instructions = this.instructions || "";
+    const prompt = [
+      instructions,
+      "",
+      "## Bundle (deterministic collectors output)",
+      "",
+      "```json",
+      JSON.stringify(bundle, null, 2),
+      "```",
+      "",
+      "Produce the Architecture Brief now.",
+    ].join("\n");
+    return { prompt };
+  }
+
+  parseOutput(raw) {
+    if (!raw || typeof raw !== "string") return { brief: "" };
+    const trimmed = raw.trim();
+    const fenced = trimmed.match(FENCE_RE);
+    return { brief: fenced ? fenced[1].trim() : trimmed };
+  }
+
+  buildSuccessResult(parsed, provider) {
+    return { brief: parsed.brief, provider };
+  }
+
+  buildSummary(parsed) {
+    const lines = (parsed.brief || "").split("\n").length;
+    return `Architecture brief composed (${lines} line${lines === 1 ? "" : "s"})`;
+  }
+
+  handleParseNull(agentResult, provider) {
+    return {
+      ok: true,
+      result: { brief: agentResult.output || "", provider },
+      summary: "Architecture brief composed (raw)",
+      usage: agentResult.usage,
+    };
+  }
+
+  handleParseError(_err, agentResult, provider) {
+    return this.handleParseNull(agentResult, provider);
+  }
+}

package/templates/roles/onboarder.md

@@ -0,0 +1,36 @@
+# Onboarder
+
+Onboarder role of Karajan. Take a deterministic collectors bundle from a
+brownfield project and emit a concise Markdown **Architecture Brief** for
+downstream roles (planner, architect, researcher, coder).
+
+## Mode
+
+Read-only. NO Bash/Write/Edit/MultiEdit/NotebookEdit. Output the Markdown
+brief as plain text in your response, NOT via tools.
+
+If the project is greenfield (no git, no configs, empty tree) emit
+`# Project is greenfield` plus whatever signal exists. NEVER error out.
+
+## Input
+
+JSON bundle with `projectDir`, `stack`, `tree`, `git` (or null), `configs`,
+`adrs`. Slots may be null/empty.
+
+## Output
+
+Markdown only — skip any section without data:
+
+```markdown
+# Architecture Brief — <projectDir>
+## Stack
+## Layout
+## Configs
+## Git history
+## ADRs
+## Conventions inferred
+## Recommendations for new work
+```
+
+Be conservative: only assert what the bundle shows. "Likely" / "appears to"
+are fine; invention is not. Aim for ~40–80 lines total.