karajan-code 3.13.1 → 3.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "3.13.1",
+  "version": "3.14.1",
   "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

@@ -101,6 +101,8 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--enable-sonarcloud", "Enable SonarCloud scan (complementary to SonarQube)")
     .option("--no-sonarcloud")
     .option("--checkpoint-interval <n>", "Minutes between interactive checkpoints (default: 5)")
+    .option("--step", "Pause after each iteration with a report and ask before continuing")
+    .option("--parallel <n>", "Concurrent HU lanes for plan runs (default: 1, sequential)")
     .option("--pg-task <cardId>", "Planning Game card ID (e.g., KJC-TSK-0042)")
     .option("--pg-project <projectId>", "Planning Game project ID")
     .option("--auto-simplify", "Auto-simplify pipeline for simple tasks (disable reviewer/tester)")

package/src/commands/init.js

@@ -371,6 +371,15 @@ async function runWizard(config, logger) {
     logger.info("Git automation:");
     await askGitAutomation(wizard, config, logger);
 
+    // Iteration gate (KJC-TSK-0628): opt-in step mode, default no.
+    config.session = config.session || {};
+    const stepMode = await wizard.confirm(
+      "Pause after each iteration with a report and ask before continuing (step mode)?",
+      false,
+    );
+    config.session.iteration_gate = stepMode;
+    logger.info(`  -> iteration_gate: ${stepMode}`);
+
     if (enableHuBoard) {
       logger.info("");
       logger.info("HU Board security:");

package/src/config/defaults.js

@@ -176,6 +176,12 @@ const DEFAULTS = {
     role_overrides: {}
   },
   session: {
+    // Opt-in per-iteration supervision (KJC-TSK-0628): pause after each
+    // iteration with a report and ask continue / stop / instructions.
+    iteration_gate: false,
+    // Concurrent HU lanes per plan run (KJC-TSK-0626). 1 = sequential.
+    // Raising it multiplies token burn rate — the plan budget scales with it.
+    max_parallel_hus: 1,
     max_iteration_minutes: 30,
     max_total_minutes: 120,
     max_planner_minutes: 60,

package/src/config/overrides.js

@@ -55,6 +55,7 @@ const SCALAR_FLAGS = [
   ["maxIterationMinutes", (out, v) => { out.session.max_iteration_minutes = Number(v); }],
   ["maxTotalMinutes", (out, v) => { out.session.max_total_minutes = Number(v); }],
   ["checkpointInterval", (out, v) => { out.session.checkpoint_interval_minutes = Number(v); }],
+  ["parallel", (out, v) => { out.session.max_parallel_hus = Number(v); }],
   ["baseBranch", (out, v) => { out.base_branch = v; }],
   ["coderFallback", (out, v) => { out.coder_options.fallback_coder = v; }],
   ["reviewerFallback", (out, v) => { out.reviewer_options.fallback_reviewer = v; }],
@@ -147,6 +148,9 @@ function applyMiscOverrides(out, flags) {
   // The flag is still accepted to avoid breaking scripts; it now emits a
   // warning at run start and is otherwise ignored. See preflight-checks.js
   // and flow-runner.js for the actual gate (resolvedPolicies.sonar).
+  // --step: per-iteration supervision gate (KJC-TSK-0628).
+  if (flags.step === true) out.session.iteration_gate = true;
+
   if (flags.noSonar || flags.sonar === false) {
     out._deprecated = out._deprecated || {};
     out._deprecated.noSonarFlag = true;

package/src/git/hu-automation.js

@@ -113,11 +113,11 @@ export async function prepareHuBranch({ story, huBranches, config, logger }) {
  * @param {object} params.logger
  * @returns {Promise<{committed: boolean, pushed: boolean, prUrl: string|null}>}
  */
-export async function finalizeHuCommit({ story, branchName, config, logger }) {
+export async function finalizeHuCommit({ story, branchName, config, logger, cwd = null }) {
   const result = { committed: false, pushed: false, prUrl: null };
   if (!branchName) return result;
 
-  const changed = await hasChanges();
+  const changed = await hasChanges(cwd);
   if (!changed) {
     logger.info(`HU ${story.id}: no changes to commit`);
     return result;
@@ -126,7 +126,7 @@ export async function finalizeHuCommit({ story, branchName, config, logger }) {
   const title = story.title || story.id;
   const commitMsg = `feat(${story.id}): ${title}`;
   if (config.git?.auto_commit) {
-    const commitRes = await commitAll(commitMsg);
+    const commitRes = await commitAll(commitMsg, cwd);
     if (commitRes) {
       result.committed = true;
       logger.info(`HU ${story.id}: committed on '${branchName}'`);
@@ -135,7 +135,7 @@ export async function finalizeHuCommit({ story, branchName, config, logger }) {
 
   if (config.git?.auto_push && result.committed) {
     try {
-      await pushBranch(branchName);
+      await pushBranch(branchName, cwd);
       result.pushed = true;
       logger.info(`HU ${story.id}: pushed '${branchName}'`);
     } catch (err) {
@@ -157,7 +157,8 @@ export async function finalizeHuCommit({ story, branchName, config, logger }) {
         baseBranch: config.base_branch || "main",
         branch: branchName,
         title: commitMsg,
-        body: prBody
+        body: prBody,
+        cwd
       });
       result.prUrl = url;
       logger.info(`HU ${story.id}: PR created ${url}`);

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

@@ -27,6 +27,7 @@ import {
   setReviewerFeedback, resetRetryCount,
 } from "../../session/mutators.js";
 import { invokeSolomon } from "../solomon-escalation.js";
+import { buildIterationReport, handleIterationGate } from "../iteration-gate.js";
 import {
   handleCiEarlyPrOrPush, handleCiReviewDispatch,
 } from "../ci-integration.js";
@@ -251,6 +252,21 @@ export async function runIterationLoop(ctx, { task: loopTask, askQuestion, emitt
       return iterResult.result;
     }
     if (iterResult.action === "retry") { i -= 1; }
+    else {
+      // Iteration gate (KJC-TSK-0628): opt-in pause with a report before the
+      // next iteration; free-text answers become directives for the coder.
+      const gate = await handleIterationGate({
+        enabled: ctx.config.session?.iteration_gate === true,
+        askQuestion, session: ctx.session, logger,
+        report: buildIterationReport({
+          i, maxIterations: ctx.config.max_iterations, stageResults: ctx.stageResults,
+          budgetTracker: ctx.budgetTracker, maxBudgetUsd: ctx.config.max_budget_usd,
+        }),
+      });
+      if (gate.action === "stop") {
+        return { approved: false, sessionId: ctx.session.id, reason: "user_stopped_at_gate", iteration: i };
+      }
+    }
   }
 
   // Solomon decides whether to extend iterations or stop
@@ -289,6 +305,20 @@ export async function runIterationLoop(ctx, { task: loopTask, askQuestion, emitt
       const iterResult = await runSingleIteration(ctx);
       if (iterResult.action === "return") return iterResult.result;
       if (iterResult.action === "retry") { i -= 1; }
+      else {
+        // Same iteration gate on Solomon-extended iterations (KJC-TSK-0628).
+        const gate = await handleIterationGate({
+          enabled: ctx.config.session?.iteration_gate === true,
+          askQuestion, session: ctx.session, logger,
+          report: buildIterationReport({
+            i, maxIterations: ctx.config.max_iterations, stageResults: ctx.stageResults,
+            budgetTracker: ctx.budgetTracker, maxBudgetUsd: ctx.config.max_budget_usd,
+          }),
+        });
+        if (gate.action === "stop") {
+          return { approved: false, sessionId: ctx.session.id, reason: "user_stopped_at_gate", iteration: i };
+        }
+      }
     }
 
     // Extended iterations also exhausted — final Solomon call

package/src/orchestrator/drivers/iteration-phases/guards.js

@@ -28,7 +28,7 @@ export async function runGuardStages({ config, logger, emitter, eventBase, sessi
   let diff;
   try {
     const baseRef = await computeBaseRef({ baseBranch });
-    diff = await generateDiff({ baseRef });
+    diff = await generateDiff({ baseRef, projectDir: config?.projectDir || null });
   } catch {
     logger.warn("Guards: could not generate diff, skipping");
     return { action: "ok" };

package/src/orchestrator/drivers/iteration-phases/quality-gates.js

@@ -14,6 +14,7 @@
  */
 
 import { generateDiff } from "../../../review/diff-generator.js";
+import { withLock } from "../../../utils/async-lock.js";
 import {
   runTddCheckStage, runSonarStage, runSonarCloudStage,
 } from "../../iteration-stages.js";
@@ -52,10 +53,12 @@ export async function runQualityGateStages({ config, logger, emitter, eventBase,
   // that one file.
   const sonarStageDisabledForTest = config?.testHarness?.disableSonarStage === true;
   if (!sonarStageDisabledForTest && session.resolved_policies?.sonar !== false) {
-    const sonarResult = await runSonarStage({
+    // Serialize across parallel HU lanes (KJC-TSK-0625): the SonarQube
+    // server scans one project key at a time. No-op on sequential runs.
+    const sonarResult = await withLock("sonar-scan", () => runSonarStage({
       config, logger, emitter, eventBase, session, trackBudget, iteration: i,
       repeatDetector, budgetSummary, sonarState, askQuestion, task, brainCtx
-    });
+    }));
     if (sonarResult.action === "stalled" || sonarResult.action === "pause") return { action: "return", result: sonarResult.result };
     if (sonarResult.action === "continue") return { action: "continue" };
     if (sonarResult.stageResult) {
@@ -74,7 +77,7 @@ export async function runQualityGateStages({ config, logger, emitter, eventBase,
   }
 
   if (pipelineFlags?.impeccableEnabled) {
-    const diff = await generateDiff({ baseRef: session.session_start_sha });
+    const diff = await generateDiff({ baseRef: session.session_start_sha, projectDir: config?.projectDir || null });
     const impeccableMode = pipelineFlags?.impeccableMode || "audit";
     const impeccableResult = await runImpeccableStage({
       config, logger, emitter, eventBase, session, coderRole, trackBudget,

package/src/orchestrator/drivers/run-hu-batch.js

@@ -55,7 +55,6 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
   }));
 
   // Per-HU pipeline: focused max_iterations, fresh Brain state, own git branch.
-  const originalMaxIterations = ctx.config.max_iterations;
   const huMaxIterations = ctx.config.hu_max_iterations ?? 3;
   const huBranches = new Map();
   const { prepareHuBranch, finalizeHuCommit } = await import("../../git/hu-automation.js");
@@ -83,15 +82,7 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
 
   const subPipelineResult = await runHuSubPipeline({
     huReviewerResult: ctx.stageResults.huReviewer,
-    runIterationFn: async (huTask, story) => {
-      ctx.config.max_iterations = huMaxIterations;
-      if (ctx.brainCtx?.enabled) {
-        ctx.brainCtx.extensionCount = 0;
-        const { createBrainContext } = await import("../brain-coordinator.js");
-        const fresh = createBrainContext({ enabled: true });
-        ctx.brainCtx.feedbackQueue = fresh.feedbackQueue;
-        ctx.brainCtx.verificationTracker = fresh.verificationTracker;
-      }
+    runIterationFn: async (huTask, story, laneOpts = {}) => {
       // Apply per-HU policies based on task_type (infra skips reviewer/sonar/tdd).
       // KJC-TSK-0400: `effectiveTaskType` mira primero story.task_type y, si
       // no es válido, infiere del prefijo del title ([SPIKE], [DOC]…). Así
@@ -103,15 +94,50 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
         logger.info(`HU ${story.id}: task_type inferido del title → ${resolvedTaskType} (era ${story.task_type || "null"})`);
       }
       const huPolicies = applyPolicies({ taskType: resolvedTaskType, policies: ctx.config.policies });
-      const savedFlags = { ...ctx.pipelineFlags };
-      if (!huPolicies.reviewer) ctx.pipelineFlags.reviewerEnabled = false;
-      if (!huPolicies.tdd) ctx.config.development = { ...ctx.config.development, methodology: "standard", require_test_changes: false };
-      if (!huPolicies.sonar) ctx.config.sonarqube = { ...ctx.config.sonarqube, enabled: false };
-      if (!huPolicies.testsRequired) ctx.pipelineFlags.testerEnabled = false;
       logger.info(`HU ${story.id} (${resolvedTaskType}): policies → reviewer=${huPolicies.reviewer}, tdd=${huPolicies.tdd}, sonar=${huPolicies.sonar}, tests=${huPolicies.testsRequired}`);
 
-      const branchName = await prepareHuBranch({ story, huBranches, config: ctx.config, logger });
-      const projectDir = ctx.config.projectDir || process.cwd();
+      // PAR-E2 PR2 (KJC-TSK-0629): every per-HU adjustment lands on LANE
+      // copies. ctx.config/pipelineFlags/session/brainCtx are shared by all
+      // lanes, so concurrent lanes must never mutate them. This also fixes a
+      // latent leak: max_iterations was mutated on ctx.config and only the
+      // fallback path restored it — the acceptance path returned early and
+      // left it clamped to hu_max_iterations for the rest of the run.
+      const worktreePath = laneOpts?.worktreePath || null;
+      const projectDir = worktreePath || ctx.config.projectDir || process.cwd();
+      const laneConfig = { ...ctx.config, projectDir, max_iterations: huMaxIterations };
+      if (!huPolicies.tdd) laneConfig.development = { ...laneConfig.development, methodology: "standard", require_test_changes: false };
+      if (!huPolicies.sonar) laneConfig.sonarqube = { ...laneConfig.sonarqube, enabled: false };
+      const laneFlags = { ...ctx.pipelineFlags };
+      if (!huPolicies.reviewer) laneFlags.reviewerEnabled = false;
+      if (!huPolicies.testsRequired) laneFlags.testerEnabled = false;
+      // Worktree lanes clone the session so reviewer feedback never leaks
+      // across concurrent HUs. Disk saves still share the session id (last
+      // writer wins) — journal noise at most; in-memory isolation is what
+      // guards correctness.
+      const laneSession = worktreePath ? { ...ctx.session } : ctx.session;
+      let laneBrain = ctx.brainCtx;
+      if (ctx.brainCtx?.enabled) {
+        const { createBrainContext } = await import("../brain-coordinator.js");
+        const fresh = createBrainContext({ enabled: true });
+        if (worktreePath) {
+          laneBrain = { ...ctx.brainCtx, extensionCount: 0, feedbackQueue: fresh.feedbackQueue, verificationTracker: fresh.verificationTracker };
+        } else {
+          ctx.brainCtx.extensionCount = 0;
+          ctx.brainCtx.feedbackQueue = fresh.feedbackQueue;
+          ctx.brainCtx.verificationTracker = fresh.verificationTracker;
+        }
+      }
+      let lanePlannedTask = ctx.plannedTask;
+
+      // A worktree lane skips the main-tree checkout: `git worktree add -b`
+      // already left the worktree checked out on kj-hu-<id>.
+      let branchName;
+      if (worktreePath) {
+        branchName = `kj-hu-${story.id}`;
+        huBranches.set(story.id, branchName);
+      } else {
+        branchName = await prepareHuBranch({ story, huBranches, config: laneConfig, logger });
+      }
 
       // KJC-TSK-0408 step 2: snapshot del workspace ANTES de invocar al
       // coder. Si el usuario hace Undo después, restaura este SHA. El
@@ -142,11 +168,11 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
         // iterations against an irreparable test (the 2026-04-29 bug).
         const failureTracker = createFailureTracker();
 
-        for (let attempt = 1; attempt <= ctx.config.max_iterations; attempt++) {
-          logger.info(`HU ${story.id}: coder iteration ${attempt}/${ctx.config.max_iterations}`);
+        for (let attempt = 1; attempt <= laneConfig.max_iterations; attempt++) {
+          logger.info(`HU ${story.id}: coder iteration ${attempt}/${laneConfig.max_iterations}`);
           emitProgress(emitter, makeEvent("iteration:start", { ...ctx.eventBase, stage: "iteration" }, {
-            message: `Iteration ${attempt}/${ctx.config.max_iterations}`,
-            detail: { iteration: attempt, maxIterations: ctx.config.max_iterations }
+            message: `Iteration ${attempt}/${laneConfig.max_iterations}`,
+            detail: { iteration: attempt, maxIterations: laneConfig.max_iterations }
           }));
 
           // Coder runs with the HU task + any diagnostic feedback from previous attempt.
@@ -155,9 +181,9 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
           // not only after the first failed run.
           const coderResult = await runCoderStage({
             coderRoleInstance: ctx.coderRoleInstance, coderRole: ctx.coderRole,
-            config: ctx.config, logger, emitter, eventBase: ctx.eventBase,
-            session: ctx.session, plannedTask: ctx.plannedTask,
-            trackBudget: ctx.trackBudget, iteration: attempt, brainCtx: ctx.brainCtx,
+            config: laneConfig, logger, emitter, eventBase: ctx.eventBase,
+            session: laneSession, plannedTask: lanePlannedTask,
+            trackBudget: ctx.trackBudget, iteration: attempt, brainCtx: laneBrain,
             acceptanceTests: story.acceptance_tests,
             // PR F (v2.7.5): plan-aware coder context. ADRs are
             // shared across the plan, the rest are scoped to this
@@ -173,11 +199,11 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
           }
 
           // Sonar quality gate (sw task_type only, when policies say sonar=true)
-          if (huPolicies.sonar && ctx.config.sonarqube?.enabled) {
+          if (huPolicies.sonar && laneConfig.sonarqube?.enabled) {
             try {
               const sonarResult = await runSonarStage({
-                config: ctx.config, logger, emitter, eventBase: ctx.eventBase,
-                session: ctx.session, trackBudget: ctx.trackBudget, iteration: attempt,
+                config: laneConfig, logger, emitter, eventBase: ctx.eventBase,
+                session: laneSession, trackBudget: ctx.trackBudget, iteration: attempt,
                 // sonarState is required: runSonarStage reads/writes
                 // .issuesInitial / .issuesFinal on it. Forgetting this
                 // surfaces as `Cannot read properties of undefined
@@ -188,11 +214,11 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
                 sonarState: ctx.sonarState,
                 repeatDetector: ctx.repeatDetector,
                 budgetSummary: ctx.budgetSummary,
-                askQuestion, brainCtx: ctx.brainCtx
+                askQuestion, brainCtx: laneBrain
               });
               if (sonarResult?.action === "continue") {
                 // Sonar failed — add to feedback for next coder attempt
-                ctx.plannedTask = `${huTask}\n\n--- SONAR FAILURE ---\n${ctx.session.last_reviewer_feedback}`;
+                lanePlannedTask = `${huTask}\n\n--- SONAR FAILURE ---\n${laneSession.last_reviewer_feedback}`;
                 continue;
               }
             } catch (err) {
@@ -225,8 +251,8 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
             );
             if (pendingGherkinTests.length === 0) {
               logger.info(`HU ${story.id}: all shell acceptance tests PASSED, no Gherkin to translate — approved`);
-              await finalizeHuCommit({ story, branchName, config: ctx.config, logger });
-              return { approved: true, sessionId: ctx.session.id, reason: "acceptance_tests_passed" };
+              await finalizeHuCommit({ story, branchName, config: laneConfig, logger, cwd: worktreePath });
+              return { approved: true, sessionId: laneSession.id, reason: "acceptance_tests_passed" };
             }
 
             // Shell tests passed; Gherkin needs translation. Invoke the
@@ -236,16 +262,16 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
             const { runTesterStage } = await import("../post-loop-stages.js");
             const shellResults = testResult.results.filter((r) => r.type !== "gherkin");
             const testerOutcome = await runTesterStage({
-              config: ctx.config, logger, emitter, eventBase: ctx.eventBase,
-              session: ctx.session, coderRole: ctx.coderRole, trackBudget: ctx.trackBudget,
+              config: laneConfig, logger, emitter, eventBase: ctx.eventBase,
+              session: laneSession, coderRole: ctx.coderRole, trackBudget: ctx.trackBudget,
               iteration: attempt, task: huTask, diff: null, askQuestion,
               pendingGherkinTests, shellTestResults: shellResults,
             });
             const testerStage = testerOutcome?.stageResult;
             if (testerOutcome?.action !== "continue" && testerStage?.verdict === "pass") {
               logger.info(`HU ${story.id}: tester translated Gherkin and verdict=pass — approved`);
-              await finalizeHuCommit({ story, branchName, config: ctx.config, logger });
-              return { approved: true, sessionId: ctx.session.id, reason: "acceptance_tests_passed" };
+              await finalizeHuCommit({ story, branchName, config: laneConfig, logger, cwd: worktreePath });
+              return { approved: true, sessionId: laneSession.id, reason: "acceptance_tests_passed" };
             }
 
             // Tester rejected (translated tests failed or coverage
@@ -259,8 +285,8 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
               "Fix the implementation so every scenario passes. Do NOT soften the scenarios.",
             ].filter(Boolean).join("\n");
             logger.warn(`HU ${story.id}: tester verdict=fail after Gherkin translation — sending back to coder`);
-            setReviewerFeedback(ctx.session, diagnostic);
-            ctx.plannedTask = `${huTask}\n\n--- GHERKIN TRANSLATION FAILURES ---\n${diagnostic}`;
+            setReviewerFeedback(laneSession, diagnostic);
+            lanePlannedTask = `${huTask}\n\n--- GHERKIN TRANSLATION FAILURES ---\n${diagnostic}`;
             continue;
           }
 
@@ -314,7 +340,7 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
 
           if (repairEscalate) {
             logger.warn(`HU ${story.id}: Repairer escalated — ${repairEscalate}`);
-            return { approved: false, sessionId: ctx.session.id, reason: "repair_escalated" };
+            return { approved: false, sessionId: laneSession.id, reason: "repair_escalated" };
           }
           if (repairedAny) {
             // Tests were rewritten — restart iteration with the fixed
@@ -328,26 +354,24 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
           // No repair happened — normal coder feedback path.
           const diagnostic = buildDiagnosticPrompt(failed);
           logger.warn(`HU ${story.id}: ${failed.length} acceptance test(s) FAILED — sending diagnostic to coder`);
-          setReviewerFeedback(ctx.session, diagnostic);
-          ctx.plannedTask = `${huTask}\n\n--- ACCEPTANCE TEST FAILURES ---\n${diagnostic}`;
+          setReviewerFeedback(laneSession, diagnostic);
+          lanePlannedTask = `${huTask}\n\n--- ACCEPTANCE TEST FAILURES ---\n${diagnostic}`;
         }
 
         // All iterations exhausted
         logger.warn(`HU ${story.id}: max iterations reached with acceptance tests still failing`);
-        return { approved: false, sessionId: ctx.session.id, reason: "acceptance_tests_failed" };
+        return { approved: false, sessionId: laneSession.id, reason: "acceptance_tests_failed" };
       }
 
-      // Fallback: no acceptance_tests → standard pipeline (reviewer/tester)
-      try {
-        const result = await runIterationLoop(ctx, { task: huTask, askQuestion, emitter, logger });
-        if (result?.approved) {
-          await finalizeHuCommit({ story, branchName, config: ctx.config, logger });
-        }
-        return result;
-      } finally {
-        ctx.config.max_iterations = originalMaxIterations;
-        Object.assign(ctx.pipelineFlags, savedFlags);
+      // Fallback: no acceptance_tests → standard pipeline (reviewer/tester).
+      // The loop reads everything through ctx.* — handing it a lane view
+      // keeps the shared ctx untouched (no more mutate-and-restore dance).
+      const laneCtx = { ...ctx, config: laneConfig, pipelineFlags: laneFlags, session: laneSession, brainCtx: laneBrain, plannedTask: lanePlannedTask };
+      const result = await runIterationLoop(laneCtx, { task: huTask, askQuestion, emitter, logger });
+      if (result?.approved) {
+        await finalizeHuCommit({ story, branchName, config: laneConfig, logger, cwd: worktreePath });
       }
+      return result;
     },
     emitter,
     eventBase: ctx.eventBase,

package/src/orchestrator/hu-scheduler.js

@@ -0,0 +1,114 @@
+/**
+ * hu-scheduler — pure scheduling for parallel HU execution (KJC-TSK-0623,
+ * épica KJC-PCS-0065). Decides WHICH HUs may run concurrently; it never
+ * launches anything. Two rules, both conservative by design:
+ *
+ *   1. Dependencies: every blocked_by id must be in completedIds.
+ *   2. Scope isolation: two HUs whose scopes touch the same path prefix are
+ *      never scheduled together — predictable merge conflicts cost more than
+ *      the parallelism they'd buy. An HU with NO scope has an unknown blast
+ *      radius, so it runs alone (exclusive with everything).
+ */
+
+/**
+ * Extract path-like tokens from a free-form scope. The planner writes scope
+ * as prose ("src/auth y tests/auth", "docs/*.md"); we keep anything that
+ * looks like a path or glob, normalized to its base directory.
+ */
+export function scopeTokens(scope) {
+  if (!scope || typeof scope !== "string") return [];
+  const matches = scope.match(/[\w.-]+(?:\/[\w*.{}-]+)+|[\w.-]+\/(?=\s|$|,)/g) || [];
+  return matches
+    .map((raw) => {
+      // Cut the token at its first glob segment: "src/**/*.js" → "src".
+      const segments = raw.replace(/\/+$/, "").split("/");
+      const firstGlob = segments.findIndex((s) => s.includes("*") || s.includes("{"));
+      return (firstGlob === -1 ? segments : segments.slice(0, firstGlob)).join("/");
+    })
+    .filter(Boolean);
+}
+
+/** True when two token lists share a path-prefix relationship. */
+function tokensOverlap(a, b) {
+  for (const ta of a) {
+    for (const tb of b) {
+      if (ta === tb || ta.startsWith(`${tb}/`) || tb.startsWith(`${ta}/`)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * True when two HUs cannot run concurrently: either one has no parseable
+ * scope (unknown blast radius ⇒ exclusive) or their scopes overlap.
+ */
+export function husConflict(huA, huB) {
+  const a = scopeTokens(huA.scope);
+  const b = scopeTokens(huB.scope);
+  if (a.length === 0 || b.length === 0) return true;
+  return tokensOverlap(a, b);
+}
+
+/**
+ * Split one dependency-level group into conflict-free chunks of at most
+ * `maxParallel` HUs (KJC-TSK-0626). Every chunk runs concurrently; chunks
+ * run one after another. maxParallel 1 ⇒ singletons (fully sequential).
+ * Same conservative rules as husConflict: no parseable scope ⇒ runs alone.
+ *
+ * @param {Array<{id: string, scope?: string|null}>} stories - full story list
+ * @param {string[]} groupIds - ids of one dependency-level group, in order
+ * @param {number} maxParallel
+ * @returns {string[][]} chunks of ids
+ */
+export function partitionConflictFree(stories, groupIds, maxParallel = 1) {
+  if (maxParallel <= 1) return groupIds.map((id) => [id]);
+  const byId = new Map(stories.map((s) => [s.id, s]));
+  const chunks = [];
+  for (const id of groupIds) {
+    const story = byId.get(id) ?? { id };
+    const fit = chunks.find(
+      (chunk) => chunk.length < maxParallel && !chunk.some((otherId) => husConflict(story, byId.get(otherId) ?? { id: otherId })),
+    );
+    if (fit) fit.push(id);
+    else chunks.push([id]);
+  }
+  return chunks;
+}
+
+/**
+ * Select the next HUs to launch, order-preserving and greedy.
+ *
+ * @param {object} args
+ * @param {Array<{id: string, blocked_by?: string[], scope?: string|null}>} args.hus - candidates, in plan order
+ * @param {string[]} [args.completedIds] - HUs already done (dependency source)
+ * @param {Array<{id: string, scope?: string|null}>} [args.inFlight] - HUs currently running
+ * @param {number} [args.maxParallel] - total concurrency cap (in-flight included)
+ * @returns {{ selected: object[], blocked: Array<{id: string, reason: string}> }}
+ */
+export function selectRunnableHus({ hus = [], completedIds = [], inFlight = [], maxParallel = 1 } = {}) {
+  const done = new Set(completedIds);
+  const flying = new Set(inFlight.map((h) => h.id));
+  const slots = Math.max(0, maxParallel - inFlight.length);
+  const selected = [];
+  const blocked = [];
+
+  for (const hu of hus) {
+    if (flying.has(hu.id) || done.has(hu.id)) continue;
+    const missing = (hu.blocked_by || []).filter((dep) => !done.has(dep));
+    if (missing.length > 0) {
+      blocked.push({ id: hu.id, reason: `waiting for ${missing.join(", ")}` });
+      continue;
+    }
+    if (selected.length >= slots) {
+      blocked.push({ id: hu.id, reason: "no free slot" });
+      continue;
+    }
+    const rival = [...inFlight, ...selected].find((other) => husConflict(hu, other));
+    if (rival) {
+      blocked.push({ id: hu.id, reason: `scope conflicts with ${rival.id}` });
+      continue;
+    }
+    selected.push(hu);
+  }
+  return { selected, blocked };
+}

package/src/orchestrator/hu-sub-pipeline.js

@@ -7,6 +7,8 @@ import { updateStoryStatus, loadHuBatch, saveHuBatch, HU_STATUS } from "../hu/st
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { refineHuWithContext } from "../hu/lazy-planner.js";
 import { findParallelGroups, createWorktree, mergeWorktree, removeWorktree } from "../hu/parallel-executor.js";
+import { partitionConflictFree } from "./hu-scheduler.js";
+import { createParallelLimiter, planBudgetUsd } from "./parallel-limiter.js";
 
 /**
  * Determine whether the HU reviewer result needs the sub-pipeline path.
@@ -283,7 +285,9 @@ async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emi
   }));
 
   try {
-    const iterResult = await runIterationFn(huTask, story);
+    // PAR-E2 (KJC-TSK-0629): lanes handed a worktree must aim every git and
+    // filesystem touchpoint at it — laneOpts carries that path to the runner.
+    const iterResult = await runIterationFn(huTask, story, { worktreePath: worktreePath || null });
     const approved = Boolean(iterResult?.approved);
 
     // --- Transition to reviewing (post-coder, pre-reviewer evaluation) ---
@@ -459,15 +463,38 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
   // --- Group HUs into parallel batches ---
   const parallelBatches = findParallelGroups(certifiedStories, orderedIds);
 
-  for (const group of parallelBatches) {
+  // Governance (KJC-TSK-0626): the dependency groups above used to launch
+  // UNBOUNDED via Promise.all — a plan with N independent HUs ran N full
+  // pipelines at once, with no cap, no shared budget and no scope checks.
+  // Now each group is partitioned into conflict-free chunks of at most
+  // max_parallel_hus (default 1 = fully sequential, today's safe path) and
+  // a shared limiter gates every launch against the PLAN budget.
+  const maxParallel = Math.max(1, Number(config?.session?.max_parallel_hus ?? 1));
+  const limiter = createParallelLimiter({
+    maxParallel,
+    budgetTracker,
+    planBudgetUsd: planBudgetUsd({ maxBudgetUsd: config?.max_budget_usd, maxParallel }),
+  });
+  let stopReason = null;
+
+  outer: for (const group of parallelBatches) {
+    for (const chunk of partitionConflictFree(batch.stories, group, maxParallel)) {
     // Filter out HUs that were blocked by a failed dependency in a previous batch
-    const runnableIds = group.filter(id => {
+    const runnableIds = chunk.filter(id => {
       const story = batch.stories.find(s => s.id === id);
       return story && story.status !== HU_STATUS.BLOCKED;
     });
 
     if (runnableIds.length === 0) continue;
 
+    const blockReason = limiter.launchBlockReason();
+    if (blockReason) {
+      stopReason = blockReason;
+      allApproved = false;
+      logger.warn(`HU sub-pipeline stopped before launching ${runnableIds.join(", ")}: ${blockReason}`);
+      break outer;
+    }
+
     // Emit parallel batch start event
     emitProgress(emitter, makeEvent("hu:parallel-start", { ...eventBase, stage: "hu-sub-pipeline" }, {
       message: `Starting parallel batch of ${runnableIds.length} HU(s): ${runnableIds.join(", ")}`,
@@ -511,14 +538,20 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
         }
       }
 
-      // Run all HUs in the batch concurrently
+      // Run all HUs in the batch concurrently, each holding a limiter slot
+      // (belt-and-braces: chunks are already ≤ maxParallel).
       const batchPromises = runnableIds.map(async (storyId) => {
-        return runSingleHu({
-          storyId, batch, batchSessionId, runIterationFn,
-          emitter, eventBase, logger, config, results,
-          worktreePath: worktrees.get(storyId),
-          onStatusChange, onOutcome, budgetTracker
-        });
+        await limiter.acquire();
+        try {
+          return await runSingleHu({
+            storyId, batch, batchSessionId, runIterationFn,
+            emitter, eventBase, logger, config, results,
+            worktreePath: worktrees.get(storyId),
+            onStatusChange, onOutcome, budgetTracker
+          });
+        } finally {
+          limiter.release();
+        }
       });
 
       const batchResults = await Promise.all(batchPromises);
@@ -554,7 +587,8 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
 
       await saveHuBatch(batchSessionId, batch);
     }
+    }
   }
 
-  return { approved: allApproved, results, blockedIds };
+  return { approved: allApproved, results, blockedIds, ...(stopReason ? { stopReason } : {}) };
 }

package/src/orchestrator/iteration-gate.js

@@ -0,0 +1,73 @@
+/**
+ * iteration-gate — opt-in per-iteration supervision (KJC-TSK-0628, épica
+ * KJC-PCS-0062). With `--step` (or session.iteration_gate in config) the
+ * pipeline pauses after EVERY iteration with a compact report — what
+ * happened, what the next iteration will do, spend vs cap — and asks the
+ * user: continue, stop, or continue WITH instructions. Free-text answers
+ * are appended to the reviewer feedback the coder reads next iteration
+ * (same channel Solomon's human guidance uses), never overwriting the
+ * reviewer's own must-fix list.
+ */
+
+import { markSessionStatus } from "../session/store.js";
+import { setReviewerFeedback } from "../session/mutators.js";
+
+const STOP_ANSWERS = new Set(["stop", "parar", "para", "no", "n", "4"]);
+const CONTINUE_ANSWERS = new Set(["", "s", "si", "sí", "y", "yes", "1", "continue", "continuar"]);
+
+/** Compact human report of the iteration that just finished. */
+export function buildIterationReport({ i, maxIterations, stageResults = {}, budgetTracker, maxBudgetUsd, reviewVerdict }) {
+  const lines = [`Iteration ${i}/${maxIterations} finished.`];
+  const stages = Object.keys(stageResults);
+  if (stages.length > 0) lines.push(`Stages so far: ${stages.join(", ")}`);
+
+  const review = reviewVerdict ?? stageResults.reviewer ?? null;
+  const mustFix = review?.must_fix ?? review?.issues ?? [];
+  if (review?.approved === true) {
+    lines.push("Reviewer: APPROVED");
+  } else if (mustFix.length > 0) {
+    const shown = mustFix.slice(0, 3).map((f) => `  • ${typeof f === "string" ? f : f.title || f.description || JSON.stringify(f)}`);
+    lines.push(`Reviewer: rejected with ${mustFix.length} must-fix:`, ...shown);
+    if (mustFix.length > 3) lines.push(`  … and ${mustFix.length - 3} more`);
+    lines.push(`Next iteration: the coder tackles those ${mustFix.length} must-fix.`);
+  } else {
+    lines.push("Next iteration: the coder retries against the pending feedback.");
+  }
+
+  const spent = budgetTracker?.total?.().cost_usd ?? 0;
+  const cap = maxBudgetUsd != null ? ` / cap $${Number(maxBudgetUsd).toFixed(2)}` : "";
+  lines.push(`Spend: $${spent.toFixed(2)}${cap}`);
+  return lines.join("\n");
+}
+
+/** Append a user directive without clobbering the reviewer's feedback. */
+export function appendUserDirective(session, text) {
+  const existing = session.last_reviewer_feedback || "";
+  const block = `## User directive (iteration gate)\n${text}`;
+  setReviewerFeedback(session, existing ? `${existing}\n\n${block}` : block);
+}
+
+/**
+ * Ask the user at the gate. Returns { action: "continue" | "stop",
+ * injected?: string }. Disabled gate, missing askQuestion (nobody to ask)
+ * or unattended autonomous runs pass straight through.
+ */
+export async function handleIterationGate({ enabled, askQuestion, session, logger, report }) {
+  if (!enabled || !askQuestion || askQuestion.unattended === true) return { action: "continue" };
+
+  const answer = await askQuestion(
+    `${report}\n\nContinue? [Enter = yes | "stop" = stop | anything else = instructions for the next iteration]`,
+  );
+  const trimmed = (answer || "").trim();
+  const lower = trimmed.toLowerCase();
+
+  if (STOP_ANSWERS.has(lower)) {
+    await markSessionStatus(session, "stopped");
+    return { action: "stop" };
+  }
+  if (CONTINUE_ANSWERS.has(lower)) return { action: "continue" };
+
+  appendUserDirective(session, trimmed);
+  logger?.info?.("Iteration gate: user directive injected for the next iteration.");
+  return { action: "continue", injected: trimmed };
+}

package/src/orchestrator/parallel-limiter.js

@@ -0,0 +1,74 @@
+/**
+ * parallel-limiter — shared concurrency coordinator for parallel HU
+ * execution (KJC-TSK-0624, épica KJC-PCS-0065). One instance per plan run,
+ * shared by every HU lane:
+ *
+ *   - Semaphore: at most maxParallel HUs hold a slot (acquire/release).
+ *   - Plan budget: the whole run shares ONE BudgetTracker; the launch gate
+ *     refuses new lanes once aggregated spend reaches the plan ceiling
+ *     (maxParallel × max_budget_usd — parallelism scales the cap, it never
+ *     multiplies it silently).
+ *   - Cooldown: when any lane hits a provider rate limit it calls
+ *     notifyCooldown(ms); NEW launches pause until it expires while lanes
+ *     already flying finish their work — parallel retry stampedes are the
+ *     fastest way to burn a quota.
+ */
+
+export function createParallelLimiter({ maxParallel = 1, budgetTracker = null, planBudgetUsd = null, now = Date.now } = {}) {
+  let inUse = 0;
+  let cooldownUntil = 0;
+  const waiters = [];
+
+  const overPlanBudget = () => {
+    if (planBudgetUsd == null || !budgetTracker) return false;
+    return (budgetTracker.total?.().cost_usd ?? 0) >= Number(planBudgetUsd);
+  };
+
+  const grantNext = () => {
+    while (waiters.length > 0 && inUse < maxParallel) {
+      inUse += 1;
+      waiters.shift()();
+    }
+  };
+
+  return {
+    /** Why a new lane may not launch right now; null = clear to go. */
+    launchBlockReason() {
+      if (overPlanBudget()) {
+        return `plan budget exhausted ($${(budgetTracker.total().cost_usd).toFixed(2)} ≥ $${Number(planBudgetUsd).toFixed(2)})`;
+      }
+      const waitMs = cooldownUntil - now();
+      if (waitMs > 0) return `provider cooldown for ${Math.ceil(waitMs / 1000)}s`;
+      return null;
+    },
+
+    /** Wait for a free slot. Resolves when this lane may run. */
+    acquire() {
+      if (inUse < maxParallel) {
+        inUse += 1;
+        return Promise.resolve();
+      }
+      return new Promise((resolve) => waiters.push(resolve));
+    },
+
+    release() {
+      inUse = Math.max(0, inUse - 1);
+      grantNext();
+    },
+
+    /** A lane hit a rate limit: pause NEW launches until it expires. */
+    notifyCooldown(ms) {
+      cooldownUntil = Math.max(cooldownUntil, now() + Math.max(0, ms));
+    },
+
+    stats() {
+      return { inUse, waiting: waiters.length, maxParallel, cooldownUntil };
+    },
+  };
+}
+
+/** Plan-level ceiling: parallelism scales the per-run cap, explicitly. */
+export function planBudgetUsd({ maxBudgetUsd, maxParallel = 1 }) {
+  if (maxBudgetUsd == null) return null;
+  return Number(maxBudgetUsd) * Math.max(1, maxParallel);
+}

package/src/orchestrator/stages/coder-stage.js

@@ -68,6 +68,9 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
       // the plan, the rest are scoped to this HU. All four pass through
       // untouched when the caller omits them (legacy single-task runs).
       adrs, specSection, reviewerFindings, huId,
+      // PAR-E2 (KJC-TSK-0629): the stage's config wins over the role's own —
+      // worktree lanes pass a laneConfig whose projectDir is the worktree.
+      projectDir: config?.projectDir || null,
       onOutput: coderStall.onOutput,
       // Lets Brain Recovery persist a standby snapshot if the coder's
       // provider hits a quota cap mid-run (KJC hibernation wiring).
@@ -429,8 +432,10 @@ export async function runTddCheckStage({ config, logger, emitter, eventBase, ses
   logger.setContext({ iteration, stage: "tdd" });
   let tddDiff, untrackedFiles;
   try {
-    tddDiff = await generateDiff({ baseRef: session.session_start_sha });
-    untrackedFiles = await getUntrackedFiles();
+    // PAR-E2 (KJC-TSK-0629): diff where the coder actually worked — a
+    // worktree lane's changes are invisible from the main tree.
+    tddDiff = await generateDiff({ baseRef: session.session_start_sha, projectDir: config?.projectDir || null });
+    untrackedFiles = await getUntrackedFiles(config?.projectDir || null);
   } catch (err) {
     logger.warn(`TDD diff generation failed: ${err.message}`);
     return { action: "continue", stageResult: { ok: false, summary: `TDD check failed: ${err.message}` } };

package/src/orchestrator/stages/reviewer-stage.js

@@ -194,14 +194,14 @@ async function handleReviewerRejection({ review, repeatDetector, config, logger,
   });
 }
 
-export async function fetchReviewDiff(session, logger) {
+export async function fetchReviewDiff(session, logger, projectDir = null) {
   let diff;
   if (session.ci_pr_number) {
     const { getPrDiff } = await import("../../ci/pr-diff.js");
     diff = await getPrDiff(session.ci_pr_number);
     logger.info(`Reviewer reading PR diff #${session.ci_pr_number}`);
   } else {
-    diff = await generateDiff({ baseRef: session.session_start_sha, stageNewFiles: true });
+    diff = await generateDiff({ baseRef: session.session_start_sha, stageNewFiles: true, projectDir });
   }
   // Inbound boundary: mask hardcoded secrets before the diff reaches the
   // (possibly cloud) reviewer model. Runs BEFORE the injection guard below so
@@ -221,7 +221,7 @@ export async function runReviewerStage({ reviewerRole, config, logger, emitter,
 
   let diff;
   try {
-    diff = await fetchReviewDiff(session, logger);
+    diff = await fetchReviewDiff(session, logger, config?.projectDir || null);
   } catch (err) {
     logger.warn(`Review diff generation failed: ${err.message}`);
     return { approved: false, blocking_issues: [{ description: `Diff generation failed: ${err.message}` }], non_blocking_suggestions: [], summary: `Reviewer failed: cannot generate diff — ${err.message}`, confidence: 0 };

package/src/plan/plan-executor.js

@@ -24,6 +24,10 @@ export function planToHuBatch(plan) {
     task_type: hu.task_type || "sw",
     status: hu.status === "certified" ? "certified" : hu.status,
     blocked_by: hu.blocked_by || [],
+    // KJC-BUG-0110: scope must survive as its own field — the parallel
+    // scheduler treats a scopeless story as exclusive, so dropping it
+    // silently degrades --parallel N to sequential.
+    scope: hu.scope || null,
     certified: { text: hu.scope || hu.title },
     acceptance_criteria: hu.acceptance_criteria || [],
     acceptance_tests: hu.acceptance_tests || [],

package/src/plan/preflight-hu.js

@@ -88,6 +88,9 @@ export async function prependPreflightHu(plan, projectDir) {
     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",
+    // KJC-BUG-0108: without an explicit status, `kj plan ready` rejects the
+    // whole plan with "invalid status undefined".
+    status: "pending",
     blocked_by: [],
     reuse: [],
     acceptance_tests: composePreflightTests(stack, projectDir),

package/src/review/diff-generator.js

@@ -105,8 +105,8 @@ export async function generateDiff({ baseRef, stageNewFiles = false, projectDir
   return generateSnapshotDiff(emptySnapshot, null, dir);
 }
 
-export async function getUntrackedFiles() {
-  const result = await run("git", ["ls-files", "--others", "--exclude-standard"]);
+export async function getUntrackedFiles(cwd = null) {
+  const result = await run("git", ["ls-files", "--others", "--exclude-standard"], cwd ? { cwd } : {});
   if (result.exitCode !== 0) return [];
   return result.stdout.trim().split("\n").filter(Boolean);
 }

package/src/roles/coder-role.js

@@ -31,6 +31,7 @@ export class CoderRole extends AgentRole {
         reviewerFeedback: null, sonarSummary: null, deferredContext: null,
         acceptanceTests: null,
         adrs: null, specSection: null, reviewerFindings: null, huId: null,
+        projectDir: null,
         onOutput: null
       };
     }
@@ -52,12 +53,15 @@ export class CoderRole extends AgentRole {
       specSection: input?.specSection || null,
       reviewerFindings: input?.reviewerFindings || null,
       huId: input?.huId || null,
+      // PAR-E2 (KJC-TSK-0629): per-call project root. Worktree lanes pass
+      // their lane dir here; the shared role instance keeps its own config.
+      projectDir: input?.projectDir || null,
       onOutput: input?.onOutput || null
     };
   }
 
-  async buildPrompt({ task, reviewerFeedback, sonarSummary, deferredContext, acceptanceTests, adrs, specSection, reviewerFindings, huId }) {
-    const projectDir = this.config?.projectDir || null;
+  async buildPrompt({ task, reviewerFeedback, sonarSummary, deferredContext, acceptanceTests, adrs, specSection, reviewerFindings, huId, projectDir: laneProjectDir }) {
+    const projectDir = laneProjectDir || this.config?.projectDir || null;
     // KJC sesgo-de-stack: pasar stack/testFramework al prompt para que
     // el coder no asuma JS/vitest en proyectos Python / Go / Rust /
     // Ruby. audit-role.js y tester-role.js ya lo hacen así.

package/src/spec-review/run-spec-review.js

@@ -70,7 +70,11 @@ export async function runSpecReview({ spec, config, logger, askQuestion, flags =
       if (!askQuestion) return { proceed: true, severity, findings, finalSpec: currentSpec };
       const answer = await askQuestion(
         `Spec review: ${findings.length} finding${findings.length === 1 ? "" : "s"} at severity ${severity}. [c]ontinue / [r]efine / [x]cancel? (default: continue)`,
-        { detail: { severity, findingCount: findings.length, categories: [...new Set(findings.map((f) => f.category))], iteration: iter + 1 } },
+        {
+          detail: { severity, findingCount: findings.length, categories: [...new Set(findings.map((f) => f.category))], iteration: iter + 1 },
+          // KJC-BUG-0109: mirrors the interactive default — --yes presses Enter.
+          defaultAnswer: "continue",
+        },
       );
       if (answer === null) return { proceed: false, cancelled: true, severity, findings };
       const n = String(answer).trim().toLowerCase();

package/src/utils/async-lock.js

@@ -0,0 +1,31 @@
+/**
+ * async-lock — named in-process mutex (KJC-TSK-0625, épica KJC-PCS-0065).
+ * Parallel HU lanes run inside ONE kj process; shared single-instance
+ * resources (the SonarQube server scans one project key at a time) must
+ * serialize across lanes. `withLock` chains callers per name in FIFO
+ * order; sequential runs pay nothing (the chain is always settled).
+ */
+
+const locks = new Map(); // name -> { tail: Promise, holders: number }
+
+/** Run `fn` exclusively among every caller sharing `name`. */
+export async function withLock(name, fn) {
+  const entry = locks.get(name) ?? { tail: Promise.resolve(), holders: 0 };
+  entry.holders += 1;
+  locks.set(name, entry);
+
+  const previous = entry.tail;
+  let release;
+  entry.tail = new Promise((resolve) => {
+    release = resolve;
+  });
+
+  await previous;
+  try {
+    return await fn();
+  } finally {
+    release();
+    entry.holders -= 1;
+    if (entry.holders === 0) locks.delete(name);
+  }
+}

package/src/utils/cli-ask-question.js

@@ -30,6 +30,15 @@ export function createCliAskQuestion(opts = {}) {
     const isInteractive = Boolean(process.stdin?.isTTY) && stdinReadable;
     if (!isInteractive) {
       if (flags?.yes) {
+        // KJC-BUG-0109: a question that declares a safe default is answered
+        // with it — --yes means "press Enter for me", not "abort on any
+        // gate". Questions without a declared default keep failing loud.
+        const fallback = typeof context?.defaultAnswer === "string" && context.defaultAnswer.trim()
+          ? context.defaultAnswer.trim() : null;
+        if (fallback) {
+          process.stderr.write(`\n[non-interactive --yes] Auto-answering with declared default "${fallback}": ${question}\n`);
+          return fallback;
+        }
         process.stderr.write(
           `\n[non-interactive --yes] Pipeline asked a question that cannot be auto-answered:\n`
           + `  ❓ ${question}\n`

package/src/utils/git.js

@@ -167,8 +167,8 @@ export function buildBranchName(prefix, task) {
   return `${prefix}${slugifyTask(task) || "task"}-${stamp}`;
 }
 
-export async function hasChanges() {
-  const status = await runGit(["status", "--porcelain"]);
+export async function hasChanges(cwd = null) {
+  const status = await runGit(["status", "--porcelain"], cwd ? { cwd } : {});
   return status.length > 0;
 }
 
@@ -229,12 +229,13 @@ function isNothingToCommit(message) {
   return NOTHING_TO_COMMIT_PATTERNS.some((re) => re.test(m));
 }
 
-export async function commitAll(message) {
-  await runGit(["add", "-A"]);
-  const changed = await hasChanges();
+export async function commitAll(message, cwd = null) {
+  const opts = cwd ? { cwd } : {};
+  await runGit(["add", "-A"], opts);
+  const changed = await hasChanges(cwd);
   if (!changed) return { committed: false };
   try {
-    await runGit(["commit", "-m", message]);
+    await runGit(["commit", "-m", message], opts);
   } catch (err) {
     // `git status --porcelain` and `git commit` disagreed about whether
     // there was anything to commit. Don't escalate — the only outcome
@@ -245,18 +246,18 @@ export async function commitAll(message) {
     }
     throw err;
   }
-  const raw = await runGit(["log", "-1", "--pretty=format:%H%x1f%s"]);
+  const raw = await runGit(["log", "-1", "--pretty=format:%H%x1f%s"], opts);
   const [hash, commitMessage] = raw.split("\x1f");
   return { committed: true, commit: { hash, message: commitMessage } };
 }
 
-export async function pushBranch(branch) {
-  await runGit(["push", "-u", "origin", branch]);
+export async function pushBranch(branch, cwd = null) {
+  await runGit(["push", "-u", "origin", branch], cwd ? { cwd } : {});
 }
 
-export async function createPullRequest({ baseBranch, branch, title, body }) {
+export async function createPullRequest({ baseBranch, branch, title, body, cwd = null }) {
   const args = ["pr", "create", "--base", baseBranch, "--head", branch, "--title", title, "--body", body];
-  const res = await runCommand("gh", args);
+  const res = await runCommand("gh", args, cwd ? { cwd } : {});
   if (res.exitCode !== 0) {
     throw new Error(`gh ${args.join(" ")} failed: ${res.stderr || res.stdout}`);
   }