karajan-code 2.19.3 → 2.20.0

package/README.md

@@ -345,6 +345,26 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 
 ## Recent releases
 
+> **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.
+>
+> KJC-BUG-0060 (PR #797, reported by mjfosela during the v2.19.3 release): `git checkout main` reported `[ahead 27]` of origin/main. Every commit was titled `initial commit`, authored by `manufosela@gmail.com`, and had the **exact same tree as its parent** — completely empty. The reflog held **2 495 such SHAs** accumulated since April 2026. None ever reached origin/main (gh push / CI would have rejected them) so runtime impact was zero, but the local history was noisy and on every release it looked like a sync loss. Root cause: `src/orchestrator/config-init.js::autoInit()` guarded with `!(await exists(projectDir/.git))`, which fails two ways: (a) dogfooding kj on karajan-code itself from a subdir → `exists()` returns false → `git init` re-initializes the *parent's* `.git/` (idempotent, harmless) → `git commit --allow-empty` then resolves upward and lands an empty commit on the parent's main; (b) transient FS hicks (EACCES/ENOENT) flip `exists()` to a false negative. **Fix**: switch the static FS probe for `git rev-parse --is-inside-work-tree`, which performs the same upward search git would use for the commit itself — guard cannot disagree with the operation it guards. And drop the `git commit --allow-empty -m "initial commit"` step entirely: no downstream stage needs a root commit; the 2 495 zombies never broke anything, the seed was decorative and turned out to be the actual user-visible symptom.
+>
+> **If your `kj resume` re-runs researcher/architect, or your `git status` shows mysterious `[ahead N]` after dogfooding kj on a kj-linked source tree, upgrade to v2.19.4.**
+>
 > **v2.19.3 released** — Patch. **HU Board now reads + writes plans from the canonical home dir** (KJC-BUG-0059). Reported by [@aitormf](https://github.com/aitormf): the top card showed `Directorio del proyecto — no detectado` even when the run had a valid `projectDir` and the coder was reading files from it. Root cause: five board call sites still hard-coded `~/.kj/plans/` as their plans root — leftover from the v2.19.0 home consolidation, which fixed `sync.js` but missed the rest. After the auto-migrator ran (or the user created new plans post-v2.19.0), plans landed under `~/.karajan/plans/<slug>/`; the board kept looking under `~/.kj/plans/<slug>/` and silently found nothing — so `GET /api/projects/:id/preflight` could not extract `projectDir` (the literal Aitor saw), `GET /api/projects/:id/plans-outcome` returned `plans: []` for every project, `DELETE /api/projects/:id` swept the wrong path leaving residue on disk, `DELETE /api/plans/:planId` failed silently, `plan-mutations.plansRoot` wrote new per-HU run logs to the legacy root splitting state across both, and `cleanup-zombies` never GC'd zombies under `~/.karajan/plans/`. PR #795 ships three new exports in `packages/hu-board/src/db.js`: `getHuBoardPlansDir()` (canonical, or `KJ_PLANS_DIR` override), `getHuBoardLegacyPlansDir()` (legacy, null when override set), `getHuBoardPlansDirs()` ordered `[canonical, legacy?]` for read callers. Single-write callers (`plan-mutations`) use the canonical root; read / delete / GC iterate both so users mid-migration with plans still under `~/.kj/` don't regress. 29 hu-board test files / 349 tests still green. **If your board shows "Directorio del proyecto — no detectado" on a project that clearly works in CLI, upgrade to v2.19.3.**
 >
 > **v2.19.2 released** — Patch. **SonarQube 401 now triggers automatic token re-bootstrap** instead of failing the run (KJC-BUG-0057). Until v2.19.1, when the Sonar token was missing / stale / revoked / pointed at a recreated Sonar instance, `kj run` / `kj audit` threw `SonarQube authentication failed (HTTP 401)` with the hint "Regenerate with `kj init`" — putting the user in the loop for plumbing Karajan can do itself. PR #793 wires `src/sonar/api.js::sonarFetchOnce` to invoke a new `src/sonar/token-recovery.js::recoverSonarToken()` on the first 401, which reuses `bootstrapSonarToken()` (already shipped in v2.10.2) — probes admin/admin, rotates the default password if still in place, revokes the existing `karajan-cli` token, generates a fresh GLOBAL_ANALYSIS_TOKEN, mutates `config.sonarqube.token` in place AND mirrors it to `~/.karajan/sonar-credentials.json` so future processes pick it up via the normal resolver chain instead of triggering recovery again. The original request retries once with the new token; the user never sees the 401 when recovery succeeds. Per-process latch ensures N endpoints 401-ing trigger ONE bootstrap, not N. Programmatic, **zero LLM involvement** — exactly the kind of plumbing Karajan should never delegate to the agent. Reported by [@aitormf](https://github.com/aitormf).

package/package.json

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

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,7 @@ 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("-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 +101,7 @@ export function registerPlan(program, { pkgVersion }) {
             quick: Boolean(flags.quick),
             yes: Boolean(flags.yes),
             interactive: flags.interactive,
+            preflightHu: flags.preflightHu !== false, // KJC-TSK-0397
           },
         });
       });

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/plan/generate.js

@@ -14,6 +14,7 @@ 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 { formatPlan, formatHuTable } from "./_shared.js";
 
 /**
@@ -414,6 +415,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/orchestrator/config-init.js

@@ -26,17 +26,27 @@ import { exists, ensureDir } from "../utils/fs.js";
  * Called by the orchestrator before the pipeline starts.
  */
 export async function autoInit(projectDir, logger) {
-  // Ensure git repo exists — without git, diff/reviewer/commit won't work
-  const gitDir = path.join(projectDir, ".git");
-  if (!(await exists(gitDir))) {
-    // Audit follow-up: was execSync with constant strings. Inputs are
-    // hardcoded, so injection isn't possible, but the project standard
-    // since #555 is execFileSync everywhere. Migrated for consistency.
-    const { execFileSync } = await import("node:child_process");
+  // Ensure git repo exists — without git, diff/reviewer/commit won't work.
+  //
+  // KJC-BUG-0060: the previous guard `!exists(projectDir/.git)` was insufficient
+  // when projectDir is a subdirectory inside an existing repo (common in dogfooding
+  // scenarios where kj-linked runs from the karajan-code source tree). In that case
+  // `git commit --allow-empty` would resolve upward to the parent repo and land an
+  // empty "initial commit" on the user's main branch. Use `git rev-parse
+  // --is-inside-work-tree` instead — it follows the same upward traversal that git
+  // does naturally, so a subdir inside a repo correctly reports `true` and we don't
+  // touch anything. We also drop the `git commit --allow-empty -m "initial commit"`
+  // step: a root commit is not required for any downstream stage (diff, review,
+  // coder, sonar) and the empty-commit zombie history was the user-visible symptom.
+  const { execFileSync } = await import("node:child_process");
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: projectDir, stdio: "pipe" });
+    // Already inside a git work tree (own .git or parent's). Nothing to do.
+  } catch {
+    // Not inside any repo — create a fresh one. No empty seed commit.
     try {
       execFileSync("git", ["init"], { cwd: projectDir, stdio: "pipe" });
-      execFileSync("git", ["commit", "--allow-empty", "-m", "initial commit"], { cwd: projectDir, stdio: "pipe" });
-      logger.info("Initialized git repository with empty initial commit");
+      logger.info("Initialized git repository (no seed commit)");
     } catch (err) {
       logger.warn(`Failed to init git repo: ${err.message}`);
     }

package/src/orchestrator/drivers/init-context.js

@@ -172,7 +172,13 @@ export async function initFlowContext({ task, config, logger, emitter, askQuesti
     })
   );
 
-  ctx.stageResults = {};
+  // KJC-BUG-0058: on `kj resume`, rehydrate stage results from the loaded
+  // session so completed pre-loop stages (researcher, architect, planner…)
+  // are skipped instead of re-executed. `setStageResult` mirrors writes
+  // into both `stage_results` (full payload) and `stages_completed` (flat
+  // array) — copying `stage_results` here is sufficient because
+  // `runPreLoopStages` only checks membership in `stageResults`.
+  ctx.stageResults = { ...(ctx.session?.stage_results || {}) };
   ctx.sonarState = { issuesInitial: null, issuesFinal: null };
 
   const preLoopResult = await runPreLoopStages({ config, logger, emitter, eventBase: ctx.eventBase, session: ctx.session, flags, pipelineFlags: ctx.pipelineFlags, coderRole: ctx.coderRole, trackBudget: ctx.trackBudget, task, askQuestion, pgTaskId, pgProject, stageResults: ctx.stageResults, brainCtx: ctx.brainCtx });

package/src/orchestrator/drivers/pre-loop.js

@@ -34,6 +34,7 @@ import { refineSkillsSemantically, resolveSkillsMode } from "../../skills/semant
 import { saveSession } from "../../session/store.js";
 import {
   setPreflight, setAutoInstalledSkills, setSkillsRecommended,
+  setStageResult, setStageBundle,
 } from "../../session/mutators.js";
 import {
   runResearcherStage, runArchitectStage, runPlannerStage,
@@ -60,18 +61,42 @@ import { tryCiComment } from "../ci-integration.js";
 import { getIntegration } from "../integrations.js";
 
 export async function runPreLoopStages({ config, logger, emitter, eventBase, session, flags, pipelineFlags, coderRole, trackBudget, task, askQuestion, pgTaskId, pgProject, stageResults, brainCtx }) {
+  // KJC-BUG-0058: on `kj resume` `stageResults` is rehydrated from
+  // `session.stage_results`. Persist after every successful pre-loop stage
+  // and skip the work when the slot is already populated. Cost: one
+  // `await saveSession` per stage; equivalent to the writes the post-loop
+  // path already makes for security / acceptance results.
+  const persistStage = async (name, result) => {
+    if (!result) return;
+    stageResults[name] = result;
+    setStageResult(session, name, result);
+    try { await saveSession(session); } catch (err) {
+      logger.warn(`Could not persist '${name}' stage result: ${err.message}`);
+    }
+  };
+  const resumeSkip = (name) => {
+    if (!stageResults[name]) return false;
+    logger.info(`[resume] skipping pre-loop stage '${name}' — completed in previous session`);
+    emitProgress(emitter, makeEvent("stage:skipped", { ...eventBase, stage: name }, {
+      status: "ok",
+      message: `Stage '${name}' skipped — already completed on previous run`,
+      detail: { cached: true }
+    }));
+    return true;
+  };
+
   // --- HU Reviewer (first stage, before everything else, opt-in) ---
   const huFile = flags.huFile || null;
   if (flags.enableHuReviewer !== undefined) pipelineFlags.huReviewerEnabled = Boolean(flags.enableHuReviewer);
-  if (pipelineFlags.huReviewerEnabled && huFile) {
+  if (pipelineFlags.huReviewerEnabled && huFile && !resumeSkip("huReviewer")) {
     const huResult = await runHuReviewerStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget, huFile, askQuestion, pgStories: null });
-    stageResults.huReviewer = huResult.stageResult;
+    await persistStage("huReviewer", huResult.stageResult);
   }
 
   // --- Intent classifier (deterministic pre-triage, opt-in) ---
-  if (config.guards?.intent?.enabled) {
+  if (config.guards?.intent?.enabled && !resumeSkip("intent")) {
     const intentResult = classifyIntent(task, config);
-    stageResults.intent = intentResult;
+    await persistStage("intent", intentResult);
     if (intentResult.classified) {
       emitProgress(emitter, makeEvent("intent:classified", { ...eventBase, stage: "intent" }, {
         message: `Intent classified: ${intentResult.taskType} (${intentResult.level}) — ${intentResult.message}`,
@@ -82,21 +107,21 @@ export async function runPreLoopStages({ config, logger, emitter, eventBase, ses
 
   // --- Discover (pre-triage, opt-in) ---
   if (flags.enableDiscover !== undefined) pipelineFlags.discoverEnabled = Boolean(flags.enableDiscover);
-  if (pipelineFlags.discoverEnabled) {
+  if (pipelineFlags.discoverEnabled && !resumeSkip("discover")) {
     const discoverResult = await runDiscoverStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget });
-    stageResults.discover = discoverResult.stageResult;
+    await persistStage("discover", discoverResult.stageResult);
   }
 
   // --- Triage (always on) — routed through StageRegistry (TSK-0336) ---
-  // canRun here is `pipelineFlags.triageEnabled !== false`; triageEnabled is
-  // never set to false in production, so behavior matches the previous
-  // unconditional call. If a caller ever flips it off, runStage returns null
-  // and we skip apply+persist with reasonable defaults (no overrides, no
-  // stageResult).
+  // KJC-BUG-0058: NOT skipped on resume. Triage is cheap and emits
+  // `roleOverrides` that downstream stages depend on (Brain decisor + the
+  // pipelineFlags). Re-running it on resume is the safe path; the heavy
+  // stages it gates (researcher, architect, planner) ARE skipped if
+  // already complete.
   const triageCtx = { config, logger, emitter, eventBase, session, coderRole, trackBudget, pipelineFlags };
   const triageResult = await runStage(stageRegistry.get("triage"), triageCtx) ?? { roleOverrides: null, stageResult: null };
   applyTriageOverrides(pipelineFlags, triageResult.roleOverrides);
-  stageResults.triage = triageResult.stageResult;
+  await persistStage("triage", triageResult.stageResult);
 
   // --- Brain decisor (opt-in, intent-driven routing) ---
   //
@@ -188,13 +213,13 @@ export async function runPreLoopStages({ config, logger, emitter, eventBase, ses
 
   // --- Domain Curator (after triage + skill auto-install, before planning phases) ---
   const domainHints = triageResult.stageResult?.domainHints || [];
-  if (domainHints.length > 0 || config.projectDir) {
+  if ((domainHints.length > 0 || config.projectDir) && !resumeSkip("domainCurator")) {
     try {
       const { domainContext, stageResult: dcStageResult } = await runDomainCuratorStage({
         config, logger, emitter, eventBase, session, trackBudget,
         domainHints, askQuestion
       });
-      stageResults.domainCurator = dcStageResult;
+      await persistStage("domainCurator", dcStageResult);
       if (domainContext) {
         config = { ...config, domainContext };
       }
@@ -213,7 +238,7 @@ export async function runPreLoopStages({ config, logger, emitter, eventBase, ses
       pgStories = getIntegration("tracker")?.buildHuStoriesFromCard?.(session.pg_card) ?? null;
     }
     const huResult = await runHuReviewerStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget, huFile: null, askQuestion, pgStories });
-    stageResults.huReviewer = huResult.stageResult;
+    await persistStage("huReviewer", huResult.stageResult);
   }
 
   // --- Auto-simplify pipeline for simple tasks (before explicit flag overrides) ---
@@ -291,7 +316,7 @@ export async function runPreLoopStages({ config, logger, emitter, eventBase, ses
 
 
   // --- Researcher → Planner ---
-  const { plannedTask } = await runPlanningPhases({ config: updatedConfig, logger, emitter, eventBase, session, stageResults, pipelineFlags, coderRole, trackBudget, task, askQuestion, brainCtx });
+  const { plannedTask } = await runPlanningPhases({ config: updatedConfig, logger, emitter, eventBase, session, stageResults, pipelineFlags, coderRole, trackBudget, task, askQuestion, brainCtx, persistStage, resumeSkip });
 
   // --- Update .gitignore with stack-specific entries based on planner/architect output ---
   const projectDir = updatedConfig.projectDir || process.cwd();
@@ -377,7 +402,7 @@ export async function runPreLoopStages({ config, logger, emitter, eventBase, ses
 
   return { plannedTask, updatedConfig };
 }
-async function runPlanningPhases({ config, logger, emitter, eventBase, session, stageResults, pipelineFlags, coderRole, trackBudget, task, askQuestion, brainCtx }) {
+async function runPlanningPhases({ config, logger, emitter, eventBase, session, stageResults, pipelineFlags, coderRole, trackBudget, task, askQuestion, brainCtx, persistStage, resumeSkip }) {
   let researchContext = null;
   let plannedTask = task;
 
@@ -386,41 +411,62 @@ async function runPlanningPhases({ config, logger, emitter, eventBase, session,
     ? (await import("../brain-coordinator.js")).processRoleOutput
     : null;
 
+  // KJC-BUG-0058: on resume, rehydrate cross-stage context from session.
+  // researchContext / architectContext / plannedTask live ONLY in memory
+  // after their owning stage runs; without these the post-loop coder
+  // would lose context even though we skipped the upstream LLM call.
+  const bundles = session?.stage_bundles || {};
+
   if (pipelineFlags.researcherEnabled) {
-    const researcherResult = await runResearcherStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget });
-    researchContext = researcherResult.researchContext;
-    stageResults.researcher = researcherResult.stageResult;
-    if (brainCompress) brainCompress(brainCtx, { roleName: "researcher", output: researcherResult.stageResult, iteration: 0 });
+    if (resumeSkip("researcher")) {
+      researchContext = bundles.researcher?.researchContext || null;
+    } else {
+      const researcherResult = await runResearcherStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget });
+      researchContext = researcherResult.researchContext;
+      setStageBundle(session, "researcher", { stageResult: researcherResult.stageResult, researchContext });
+      await persistStage("researcher", researcherResult.stageResult);
+      if (brainCompress) brainCompress(brainCtx, { roleName: "researcher", output: researcherResult.stageResult, iteration: 0 });
+    }
   }
 
   // --- Architect (between researcher and planner) ---
   let architectContext = null;
   if (pipelineFlags.architectEnabled) {
-    const architectResult = await runArchitectStage({
-      config, logger, emitter, eventBase, session, coderRole, trackBudget,
-      researchContext,
-      discoverResult: stageResults.discover || null,
-      triageLevel: stageResults.triage?.level || null,
-      askQuestion
-    });
-    architectContext = architectResult.architectContext;
-    stageResults.architect = architectResult.stageResult;
-    if (brainCompress) brainCompress(brainCtx, { roleName: "architect", output: architectResult.stageResult, iteration: 0 });
+    if (resumeSkip("architect")) {
+      architectContext = bundles.architect?.architectContext || null;
+    } else {
+      const architectResult = await runArchitectStage({
+        config, logger, emitter, eventBase, session, coderRole, trackBudget,
+        researchContext,
+        discoverResult: stageResults.discover || null,
+        triageLevel: stageResults.triage?.level || null,
+        askQuestion
+      });
+      architectContext = architectResult.architectContext;
+      setStageBundle(session, "architect", { stageResult: architectResult.stageResult, architectContext });
+      await persistStage("architect", architectResult.stageResult);
+      if (brainCompress) brainCompress(brainCtx, { roleName: "architect", output: architectResult.stageResult, iteration: 0 });
+    }
   }
 
   const triageDecomposition = stageResults.triage?.shouldDecompose ? stageResults.triage.subtasks : null;
   if (pipelineFlags.plannerEnabled) {
-    const plannerRole = resolveRole(config, "planner");
-    const plannerResult = await runPlannerStage({ config, logger, emitter, eventBase, session, plannerRole, researchContext, architectContext, triageDecomposition, trackBudget });
-    plannedTask = plannerResult.plannedTask;
-    stageResults.planner = plannerResult.stageResult;
-    if (brainCompress) brainCompress(brainCtx, { roleName: "planner", output: plannerResult.stageResult, iteration: 0 });
-
-    await tryCiComment({
-      config, session, logger,
-      agent: "Planner",
-      body: `Plan: ${plannerResult.stageResult?.summary || plannedTask}`
-    });
+    if (resumeSkip("planner")) {
+      plannedTask = bundles.planner?.plannedTask || task;
+    } else {
+      const plannerRole = resolveRole(config, "planner");
+      const plannerResult = await runPlannerStage({ config, logger, emitter, eventBase, session, plannerRole, researchContext, architectContext, triageDecomposition, trackBudget });
+      plannedTask = plannerResult.plannedTask;
+      setStageBundle(session, "planner", { stageResult: plannerResult.stageResult, plannedTask });
+      await persistStage("planner", plannerResult.stageResult);
+      if (brainCompress) brainCompress(brainCtx, { roleName: "planner", output: plannerResult.stageResult, iteration: 0 });
+
+      await tryCiComment({
+        config, session, logger,
+        agent: "Planner",
+        body: `Plan: ${plannerResult.stageResult?.summary || plannedTask}`
+      });
+    }
   }
 
   return { plannedTask };

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/session/mutators.js

@@ -138,6 +138,37 @@ export function setStatus(session, status) {
   session.status = status;
 }
 
+// --- Stage results (KJC-BUG-0058: resume must skip completed stages) ------
+
+/**
+ * Persist a pre-loop stage result on the session, plus mirror its name in
+ * a flat `stages_completed` array used by `resumeFlow` to know what to skip.
+ *
+ * Both shapes are kept in sync so callers can read either: the rich
+ * `stage_results[name]` for the full payload, or the cheap
+ * `stages_completed` for a fast membership check.
+ */
+export function setStageResult(session, name, result) {
+  if (!session.stage_results) session.stage_results = {};
+  session.stage_results[name] = result;
+  if (!Array.isArray(session.stages_completed)) session.stages_completed = [];
+  if (!session.stages_completed.includes(name)) session.stages_completed.push(name);
+}
+
+/**
+ * Stage *bundles* capture cross-stage context that a stage exports beyond
+ * its stageResult (e.g. researcher → researchContext, architect →
+ * architectContext, planner → plannedTask). Resume needs these to feed
+ * downstream stages without re-running the upstream one. The bundle is
+ * always shaped `{ stageResult, ...extras }` and `setStageBundle` mirrors
+ * the stageResult into `stage_results[name]` so legacy readers keep working.
+ */
+export function setStageBundle(session, name, bundle) {
+  if (!session.stage_bundles) session.stage_bundles = {};
+  session.stage_bundles[name] = bundle;
+  setStageResult(session, name, bundle?.stageResult ?? bundle);
+}
+
 // --- Alternative agent (rate-limit recovery) ------------------------------
 
 export function setAlternativeAgent(session, stage, provider) {