karajan-code 2.7.3 → 2.8.0

package/src/orchestrator/fs-leak-detector.js

@@ -0,0 +1,156 @@
+/**
+ * KJC-BUG-0032: detect coder writes outside projectDir.
+ *
+ * The coder subprocess runs with `cwd: projectDir`, but its Bash
+ * tool can `cd` anywhere. Real-world repro: a HU titled
+ *   "Initialize project skeleton: create assistant/ directory…"
+ * had Claude run `cd /home/manu/assistant && pnpm init …`. The
+ * resulting 36 MB of code lived in $HOME/assistant — outside the
+ * projectDir, outside any git repo, lost to tracking, commits and
+ * review. The coder was happy, the user only noticed by accident.
+ *
+ * This module is a deterministic guard: snapshot $HOME's top-level
+ * directory entries before the coder runs, scan again after, and
+ * any new entry that isn't projectDir itself is a leak.
+ *
+ * Why top-level only:
+ *   - Catches the realistic failure mode (coder creates a sibling
+ *     `~/something` for the project skeleton).
+ *   - Cheap (single readdirSync) — no `find -newer` traversal of
+ *     $HOME's potentially massive tree.
+ *   - Doesn't thrash on writes to existing dirs like ~/.npm or
+ *     ~/.cache that legitimate node tooling touches.
+ *
+ * What it WON'T catch (acknowledged trade-offs):
+ *   - Writes deep inside existing $HOME subdirs (e.g. modifying
+ *     ~/.bashrc — would need a per-file mtime scan).
+ *   - Writes to /tmp (high false-positive rate; /tmp is ephemeral
+ *     by spec; less risky).
+ *   - Writes to /etc, /var, etc. (would require root anyway).
+ *
+ * The first-pass guard is the right ROI. Subsequent iterations
+ * can extend coverage if real-world cases warrant it.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * Snapshot the immediate children of $HOME. Returns a Set of names
+ * (not full paths) so detectNewHomeEntries can do a quick set
+ * difference. Empty set on any FS error — treats "can't snapshot"
+ * the same as "snapshot OK with nothing".
+ *
+ * @returns {Set<string>}
+ */
+export function snapshotHomeTopLevel() {
+  try {
+    return new Set(fs.readdirSync(os.homedir()));
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * Detect $HOME top-level entries that didn't exist when `before`
+ * was snapshotted. Excludes projectDir itself in case the user
+ * keeps their projects directly under $HOME (no false positive
+ * if `projectDir = $HOME/some-project` already existed).
+ *
+ * @param {Set<string>} before — snapshot from snapshotHomeTopLevel()
+ * @param {string|null} projectDir — current run's projectDir
+ * @returns {string[]} absolute paths of new entries (potential leaks)
+ */
+export function detectNewHomeEntries(before, projectDir) {
+  const home = os.homedir();
+  let after;
+  try {
+    after = fs.readdirSync(home);
+  } catch {
+    return [];
+  }
+  const projectDirAbs = projectDir ? path.resolve(projectDir) : null;
+  const leaks = [];
+  for (const name of after) {
+    if (before.has(name)) continue;
+    const full = path.join(home, name);
+    // Skip projectDir itself (defensive — shouldn't happen since
+    // projectDir is pre-existing, but a paranoid check costs nothing).
+    if (projectDirAbs && path.resolve(full) === projectDirAbs) continue;
+    leaks.push(full);
+  }
+  return leaks;
+}
+
+/**
+ * Issue #546: filter potential leaks by attribution. Snapshot diff
+ * cannot tell coder writes from concurrent writes by other processes
+ * (host AI scratch files, parallel tooling, manual edits). Real-world
+ * 2026-04-29 incident: a host-side write of `~/karajan-status-snapshot.md`
+ * during a kj run aborted HU 003 with a false positive.
+ *
+ * Heuristic: if the coder genuinely created the leaked path, its
+ * transcript will mention the path or its basename — the coder
+ * narrates what it does (Bash commands, file operations, todos). If
+ * neither the absolute path nor the basename appears anywhere in
+ * the transcript, the entry was created by some other process during
+ * the iteration window and should NOT abort the HU.
+ *
+ * False-negative trade-off: a coder that creates a file silently
+ * (e.g. via a script that doesn't echo paths) escapes this filter.
+ * That trade-off is acceptable: the original leak class (coder
+ * skeleton-creating in $HOME) always emits the path in commands; the
+ * silent-write case has never been observed.
+ *
+ * Back-compat: when `transcript` is empty/null/undefined, NO filtering
+ * happens — every detected leak is passed through unchanged. This
+ * preserves the strict behaviour for callers that don't have a
+ * transcript handy.
+ *
+ * @param {string[]} leaks — output of detectNewHomeEntries()
+ * @param {string|null|undefined} transcript — coder's full output text
+ * @returns {string[]} filtered leaks (the subset attributable to coder)
+ */
+export function verifyLeaksAgainstTranscript(leaks, transcript) {
+  if (!Array.isArray(leaks) || leaks.length === 0) return [];
+  if (!transcript || typeof transcript !== "string" || transcript.length === 0) {
+    return leaks; // no transcript ⇒ no filtering, original behaviour
+  }
+  return leaks.filter((p) => {
+    const base = path.basename(p);
+    // Skip artefacts whose basename is too short to be discriminating
+    // (e.g. ".cache") — a 3-char basename matched against a long
+    // transcript is meaningless. For such cases we prefer the strict
+    // behaviour (flag) since they're rare and the user can inspect.
+    if (base.length < 4) return true;
+    return transcript.includes(p) || transcript.includes(base);
+  });
+}
+
+/**
+ * Format a leak list into a multiline plain-Spanish error message.
+ * Includes a hint about how to recover (move-or-delete) so the user
+ * isn't left guessing.
+ *
+ * @param {string[]} leaks — output of detectNewHomeEntries()
+ * @param {string} projectDir
+ * @returns {string}
+ */
+export function formatLeakMessage(leaks, projectDir) {
+  const list = leaks.map((p) => `  - ${p}`).join("\n");
+  return [
+    `El coder creó archivos FUERA del proyecto (${projectDir}).`,
+    "",
+    "Rutas detectadas:",
+    list,
+    "",
+    "Esto suele pasar cuando una HU usa una ruta absoluta o relativa a $HOME y el coder la sigue literalmente. Las rutas SIEMPRE deben ser relativas a la raíz del proyecto.",
+    "",
+    "Qué hacer:",
+    "  1. Inspecciona las rutas listadas. Si tienen código útil, muévelo a tu proyecto manualmente.",
+    "  2. Borra las rutas listadas si son basura.",
+    "  3. Edita el título / scope de la HU para que no contenga rutas absolutas.",
+    "  4. Vuelve a lanzar la HU.",
+  ].join("\n");
+}

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

@@ -9,8 +9,21 @@ import { refineHuWithContext } from "../hu/lazy-planner.js";
 import { findParallelGroups, createWorktree, mergeWorktree, removeWorktree } from "../hu/parallel-executor.js";
 
 /**
- * Determine whether the HU reviewer result requires a sub-pipeline
- * (more than one certified story).
+ * Determine whether the HU reviewer result needs the sub-pipeline path.
+ *
+ * Pre-fix this returned true only when there were > 1 certified stories.
+ * That broke single-HU runs (`kj run --plan <id> --hu <huId>`, the path
+ * the board's per-card ▶ button drives): with exactly one HU certified
+ * the flow fell through to the standard single-task pipeline, which
+ * does NOT call updateStoryStatus / saveHuBatch / emit hu:* events.
+ * Result: the HU stayed forever in `coding` even after the run finished
+ * because nobody persisted "done"/"failed" anywhere — board kanban
+ * showed "1 running…" indefinitely, plan JSON kept the stale status.
+ *
+ * The sub-pipeline already handles a 1-HU batch as a degenerate case
+ * (no dependency graph to resolve, no parallel batching) — so the fix
+ * is to take that path for any non-empty batch, not just >1.
+ *
  * @param {object|null} huReviewerResult - stageResults.huReviewer
  * @returns {boolean}
  */
@@ -19,7 +32,7 @@ export function needsSubPipeline(huReviewerResult) {
   const certified = (huReviewerResult.stories || []).filter(
     s => s.status === "certified"
   );
-  return certified.length > 1;
+  return certified.length >= 1;
 }
 
 /**
@@ -61,6 +74,59 @@ function buildHuTask(story) {
   return `Implement HU ${story.id}`;
 }
 
+/**
+ * Build the per-HU outcome blob from whatever metadata the iteration
+ * loop returned. Tolerant by design — most fields are optional and we
+ * default to safe values so the board can render something useful
+ * even on weird failure modes (HU crashed before producing summary,
+ * runIterationFn missing the commits array, etc.).
+ *
+ * Plain-Spanish summary lives at the bottom of the priority order so
+ * we surface what the run actually said before falling back to
+ * generic phrases.
+ *
+ * @param {object} args
+ * @param {object} args.story
+ * @param {object} args.iterResult — whatever runIterationFn returned
+ * @param {string} args.status — HU_STATUS.* terminal value
+ * @param {number} args.startedAt — Date.now() when runSingleHu started
+ * @returns {object}
+ */
+function buildHuOutcome({ story: _story, iterResult, status, startedAt }) {
+  const r = iterResult || {};
+  const git = r.git || {};
+  // Iterations are tracked in the standard pipeline as
+  // `result.iterations`, in the tests-first pipeline as the loop
+  // counter — fall back to whatever we can find.
+  const iterations = r.iterations ?? r.iteration ?? r.attempts ?? null;
+  const commits = Array.isArray(git.commits)
+    ? git.commits.map((c) => (typeof c === "string" ? c : c.hash || c.sha || "")).filter(Boolean)
+    : (Array.isArray(r.commits) ? r.commits : []);
+  const blockers = [];
+  if (r.error) blockers.push(String(r.error));
+  if (r.reason && r.reason !== "approved") blockers.push(String(r.reason));
+  if (Array.isArray(r.deferredIssues)) {
+    for (const d of r.deferredIssues) blockers.push(typeof d === "string" ? d : d.message || JSON.stringify(d));
+  }
+  // Plain-Spanish, one-or-two sentences.
+  let summary;
+  if (r.review?.summary) summary = String(r.review.summary);
+  else if (status === "done") summary = `HU completada${commits.length ? ` con ${commits.length} commit(s)` : ""}.`;
+  else if (status === "failed") summary = `HU falló${blockers.length ? `: ${blockers[0]}` : ""}.`;
+  else summary = `HU ${status}.`;
+  return {
+    status,
+    iterations: typeof iterations === "number" ? iterations : null,
+    duration_ms: typeof startedAt === "number" ? Date.now() - startedAt : null,
+    branch: r.branch || git.branch || null,
+    commits,
+    pr_url: r.pr_url || r.prUrl || git.pr_url || null,
+    blockers,
+    summary,
+    finishedAt: new Date().toISOString(),
+  };
+}
+
 /**
  * Execute a single HU through the coder→sonar→reviewer sub-pipeline.
  * Extracted to support both sequential and parallel execution paths.
@@ -68,7 +134,29 @@ function buildHuTask(story) {
  * @param {object} params
  * @returns {Promise<{huId: string, approved: boolean, result?: object, error?: string, blockedDependents?: string[]}>}
  */
-async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emitter, eventBase, logger, config, results, worktreePath }) {
+async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emitter, eventBase, logger, config, results, worktreePath, onStatusChange = null, onOutcome = null }) {
+  // PR1 (live HU status): every saveHuBatch should also notify the
+  // plan JSON so the board reflects state in real time. Defined as a
+  // local helper so we don't repeat the try/null-check boilerplate.
+  const notifyStatus = async (huId, status) => {
+    if (typeof onStatusChange !== "function") return;
+    try { await onStatusChange(huId, status); }
+    catch (err) { logger?.warn?.(`onStatusChange(${huId}, ${status}) failed: ${err.message}`); }
+  };
+  // PR3 (per-HU outcome): single notification at the end of the HU
+  // with the rich outcome blob. Plan JSON gets it stamped before
+  // we return, so the board's chokidar fires once and the card
+  // shows its summary indicator.
+  const notifyOutcome = async (huId, outcome) => {
+    if (typeof onOutcome !== "function") return;
+    try { await onOutcome(huId, outcome); }
+    catch (err) { logger?.warn?.(`onOutcome(${huId}) failed: ${err.message}`); }
+  };
+
+  // PR3: capture the start time so duration can be reported in the
+  // outcome (wall-clock per HU is what the user needs in the board,
+  // not internal stage timings).
+  const huStartedAt = Date.now();
   const story = batch.stories.find(s => s.id === storyId);
 
   // --- Lazy refinement ---
@@ -114,6 +202,7 @@ async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emi
 
   updateStoryStatus(batch, story.id, HU_STATUS.CODING);
   await saveHuBatch(batchSessionId, batch);
+  await notifyStatus(story.id, HU_STATUS.CODING);
   emitProgress(emitter, makeEvent("hu:status-change", { ...eventBase, stage: "hu-sub-pipeline" }, {
     message: `HU ${story.id} status → coding`,
     detail: { huId: story.id, status: HU_STATUS.CODING, timestamp: new Date().toISOString() }
@@ -126,6 +215,7 @@ async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emi
     // --- Transition to reviewing (post-coder, pre-reviewer evaluation) ---
     updateStoryStatus(batch, story.id, HU_STATUS.REVIEWING);
     await saveHuBatch(batchSessionId, batch);
+    await notifyStatus(story.id, HU_STATUS.REVIEWING);
     emitProgress(emitter, makeEvent("hu:status-change", { ...eventBase, stage: "hu-sub-pipeline" }, {
       message: `HU ${story.id} status → reviewing`,
       detail: { huId: story.id, status: HU_STATUS.REVIEWING, timestamp: new Date().toISOString() }
@@ -134,6 +224,10 @@ async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emi
     if (approved) {
       updateStoryStatus(batch, story.id, HU_STATUS.DONE);
       await saveHuBatch(batchSessionId, batch);
+      await notifyStatus(story.id, HU_STATUS.DONE);
+      // PR3: build + persist the per-HU outcome.
+      const okOutcome = buildHuOutcome({ story, iterResult, status: HU_STATUS.DONE, startedAt: huStartedAt });
+      await notifyOutcome(story.id, okOutcome);
       emitProgress(emitter, makeEvent("hu:status-change", { ...eventBase, stage: "hu-sub-pipeline" }, {
         message: `HU ${story.id} status → done`,
         detail: { huId: story.id, status: HU_STATUS.DONE, timestamp: new Date().toISOString() }
@@ -141,12 +235,15 @@ async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emi
       emitProgress(emitter, makeEvent("hu:end", { ...eventBase, stage: "hu-sub-pipeline" }, {
         status: "ok",
         message: `HU ${story.id} completed successfully`,
-        detail: { huId: story.id, approved: true }
+        detail: { huId: story.id, approved: true, outcome: okOutcome }
       }));
       return { huId: story.id, approved: true, result: iterResult };
     } else {
       updateStoryStatus(batch, story.id, HU_STATUS.FAILED);
       await saveHuBatch(batchSessionId, batch);
+      await notifyStatus(story.id, HU_STATUS.FAILED);
+      const failOutcome = buildHuOutcome({ story, iterResult, status: HU_STATUS.FAILED, startedAt: huStartedAt });
+      await notifyOutcome(story.id, failOutcome);
       emitProgress(emitter, makeEvent("hu:status-change", { ...eventBase, stage: "hu-sub-pipeline" }, {
         message: `HU ${story.id} status → failed`,
         detail: { huId: story.id, status: HU_STATUS.FAILED, timestamp: new Date().toISOString() }
@@ -154,13 +251,16 @@ async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emi
       emitProgress(emitter, makeEvent("hu:end", { ...eventBase, stage: "hu-sub-pipeline" }, {
         status: "fail",
         message: `HU ${story.id} failed`,
-        detail: { huId: story.id, approved: false, reason: iterResult?.reason }
+        detail: { huId: story.id, approved: false, reason: iterResult?.reason, outcome: failOutcome }
       }));
       return { huId: story.id, approved: false, result: iterResult };
     }
   } catch (err) {
     updateStoryStatus(batch, story.id, HU_STATUS.FAILED);
     await saveHuBatch(batchSessionId, batch);
+    await notifyStatus(story.id, HU_STATUS.FAILED);
+    const errOutcome = buildHuOutcome({ story, iterResult: { error: err.message }, status: HU_STATUS.FAILED, startedAt: huStartedAt });
+    await notifyOutcome(story.id, errOutcome);
     emitProgress(emitter, makeEvent("hu:status-change", { ...eventBase, stage: "hu-sub-pipeline" }, {
       message: `HU ${story.id} status → failed`,
       detail: { huId: story.id, status: HU_STATUS.FAILED, timestamp: new Date().toISOString() }
@@ -187,7 +287,7 @@ async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emi
  * @param {object} params.logger - Logger instance
  * @returns {Promise<{approved: boolean, results: object[], blockedIds: string[]}>}
  */
-export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitter, eventBase, logger, config = null }) {
+export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitter, eventBase, logger, config = null, onStatusChange = null, onOutcome = null }) {
   const batchSessionId = huReviewerResult.batchSessionId;
   let batch;
   try {
@@ -201,6 +301,75 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
     };
   }
 
+  // Plan-driven runs: the plan JSON is the source of truth for the
+  // ENTIRE HU, NOT just status, NOT the on-disk hu-stories batch.
+  //
+  // PR #537 reconciled `status` and fixed the "All HUs completed
+  // successfully for zero work" bug. But status is only ONE field of
+  // the HU. The 2026-04-29 incident hit a different field — a user
+  // edited the plan JSON to fix a broken jq query inside the HU's
+  // `acceptance_tests`, but the persisted batch kept the broken
+  // version, so the acceptance runner used the broken test, the coder
+  // burned every iteration trying to make an irreparable test pass,
+  // and the HU failed.
+  //
+  // Treat the plan as authoritative for ALL content fields the user
+  // might edit between runs (acceptance_tests, title, scope,
+  // blocked_by, spec_section, original.text). In-flight runtime
+  // context that doesn't live in the plan (worktree path, refinement
+  // state, certification quality scores, context_requests) is
+  // preserved.
+  if (huReviewerResult.source?.plan === true && Array.isArray(huReviewerResult.stories)) {
+    // Fields the plan owns. Anything NOT in this set is preserved
+    // from the persisted batch (in-flight runtime state).
+    const PLAN_OWNED_FIELDS = [
+      "status",
+      "title",
+      "scope",
+      "blocked_by",
+      "acceptance_tests",
+      "acceptance_criteria",
+      "spec_section",
+      "task_type",
+      "certified",   // canonical HU body
+      "original",    // original text reference
+    ];
+    const planById = new Map(huReviewerResult.stories.map((s) => [s.id, s]));
+    let statusChanges = 0;
+    let contentChanges = 0;
+    for (const persisted of batch.stories) {
+      const fromPlan = planById.get(persisted.id);
+      if (!fromPlan) continue;
+      for (const field of PLAN_OWNED_FIELDS) {
+        if (!(field in fromPlan)) continue;
+        const before = JSON.stringify(persisted[field]);
+        const after = JSON.stringify(fromPlan[field]);
+        if (before === after) continue;
+        persisted[field] = fromPlan[field];
+        if (field === "status") statusChanges += 1;
+        else contentChanges += 1;
+      }
+    }
+    // Stories present in the plan but missing from disk → append.
+    const persistedIds = new Set(batch.stories.map((s) => s.id));
+    let appended = 0;
+    for (const fromPlan of huReviewerResult.stories) {
+      if (!persistedIds.has(fromPlan.id)) {
+        batch.stories.push(fromPlan);
+        appended += 1;
+      }
+    }
+    const totalChanges = statusChanges + contentChanges + appended;
+    if (totalChanges > 0) {
+      const parts = [];
+      if (statusChanges > 0) parts.push(`${statusChanges} status`);
+      if (contentChanges > 0) parts.push(`${contentChanges} content field(s)`);
+      if (appended > 0) parts.push(`${appended} appended`);
+      logger.info(`HU sub-pipeline: reconciled from plan — ${parts.join(", ")} (disk batch was stale)`);
+      await saveHuBatch(batchSessionId, batch);
+    }
+  }
+
   const certifiedStories = batch.stories.filter(s => s.status === HU_STATUS.CERTIFIED);
   let orderedIds;
   try {
@@ -235,13 +404,22 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
       // Single HU: run as before, no worktree needed
       const singleResult = await runSingleHu({
         storyId: runnableIds[0], batch, batchSessionId, runIterationFn,
-        emitter, eventBase, logger, config, results
+        emitter, eventBase, logger, config, results, onStatusChange, onOutcome
       });
       results.push(singleResult);
       if (!singleResult.approved) {
         allApproved = false;
         const newlyBlocked = blockDependents(batch, singleResult.huId);
         blockedIds.push(...newlyBlocked);
+        // PR1 (live HU status): notify the plan JSON of every newly
+        // BLOCKED HU so the board moves them into the blocked column
+        // without waiting for the run to finish.
+        if (typeof onStatusChange === "function") {
+          for (const blockedHuId of newlyBlocked) {
+            try { await onStatusChange(blockedHuId, HU_STATUS.BLOCKED); }
+            catch (err) { logger?.warn?.(`onStatusChange(${blockedHuId}, blocked) failed: ${err.message}`); }
+          }
+        }
       }
       await saveHuBatch(batchSessionId, batch);
     } else {
@@ -264,7 +442,8 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
         return runSingleHu({
           storyId, batch, batchSessionId, runIterationFn,
           emitter, eventBase, logger, config, results,
-          worktreePath: worktrees.get(storyId)
+          worktreePath: worktrees.get(storyId),
+          onStatusChange, onOutcome
         });
       });
 
@@ -283,6 +462,15 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
           allApproved = false;
           const newlyBlocked = blockDependents(batch, res.huId);
           blockedIds.push(...newlyBlocked);
+          // PR1 (live HU status): same as the single-HU path — push
+          // BLOCKED transitions to the plan JSON immediately so the
+          // board shows them moving to the blocked column live.
+          if (typeof onStatusChange === "function") {
+            for (const blockedHuId of newlyBlocked) {
+              try { await onStatusChange(blockedHuId, HU_STATUS.BLOCKED); }
+              catch (err) { logger?.warn?.(`onStatusChange(${blockedHuId}, blocked) failed: ${err.message}`); }
+            }
+          }
           // Clean up failed worktree
           if (worktrees.has(res.huId)) {
             try { await removeWorktree(projectDir, res.huId); } catch { /* ignore */ }

package/src/orchestrator/integrations.js

@@ -0,0 +1,88 @@
+/**
+ * Integrations registry — single site the orchestrator consults to talk to
+ * external task trackers (Planning Game, future: GitHub Projects, Jira, …).
+ *
+ * TSK-0339 (KJC-PCS-0040) removes the direct coupling between
+ * `src/orchestrator/` and `src/planning-game/`: pre-v2.7.5 there were 8
+ * dynamic `await import("../../planning-game/…")` callsites scattered
+ * across flow-runner, ci-integration, drivers, and architect-stage. Now
+ * the orchestrator calls the registry instead of importing trackers:
+ *
+ *   const tracker = getIntegration("tracker");
+ *   await tracker?.onCommit?.(session, commit);
+ *
+ * `src/planning-game/pipeline-adapter.js` registers itself once at
+ * bootstrap (gated by `config.planning_game.enabled`). Adding a new
+ * tracker means writing a single file under `src/adapters/…` with the
+ * same hook surface; zero orchestrator edits.
+ */
+
+/**
+ * Hook contract (all optional — callers use `adapter?.hook?.(args)`):
+ *
+ *   onSessionStart({ session, config, logger, pgTaskId, pgProject })
+ *     → { pgCard } | void
+ *   onCommit(session, commit)                              — fire-and-forget
+ *   onSessionApproved({ session, config, gitResult, logger, pgCard, pgProject })
+ *     → void
+ *   buildHuStoriesFromCard(card)                           → HuStory[] | null
+ *   handleDecomposition({ triageResult, ... })             → void
+ *   createAdr({ title, context, decision, consequences })  → string | null
+ *
+ * No adapter is required to implement every hook — orchestrator callsites
+ * use optional chaining so missing hooks are a silent skip.
+ *
+ * The registry itself is process-scoped (one map, mutated at bootstrap).
+ * That's fine: adapter identity doesn't vary per-run — the same PG/Jira
+ * backend serves every run in the process. Per-run tracker CONFIG (e.g.
+ * different PG projects) is passed through the hook call, not by
+ * swapping adapters.
+ */
+
+/** @type {Map<string, object>} */
+const registry = new Map();
+
+/**
+ * Register an adapter under `name`. Idempotent: re-registering overwrites
+ * the previous entry (tests use this to swap in fakes).
+ *
+ * @param {string} name
+ * @param {object} adapter
+ */
+export function registerIntegration(name, adapter) {
+  if (!name || typeof name !== "string") {
+    throw new Error("registerIntegration: name must be a non-empty string");
+  }
+  registry.set(name, adapter);
+}
+
+/**
+ * @param {string} name
+ * @returns {object|undefined}
+ */
+export function getIntegration(name) {
+  return registry.get(name);
+}
+
+/**
+ * Remove an adapter. Tests use this to clear state between cases.
+ * @param {string} name
+ */
+export function unregisterIntegration(name) {
+  registry.delete(name);
+}
+
+/**
+ * Clear the registry. Test-only; production never calls this.
+ */
+export function __clearIntegrations() {
+  registry.clear();
+}
+
+/**
+ * List registered integration names. Useful for bootstrap logging.
+ * @returns {string[]}
+ */
+export function listIntegrations() {
+  return [...registry.keys()];
+}

package/src/orchestrator/post-loop-stages.js

@@ -2,7 +2,8 @@ import { TesterRole } from "../roles/tester-role.js";
 import { SecurityRole } from "../roles/security-role.js";
 import { ImpeccableRole } from "../roles/impeccable-role.js";
 import { AuditRole } from "../roles/audit-role.js";
-import { addCheckpoint, saveSession } from "../session-store.js";
+import { addCheckpoint } from "../session/store.js";
+import { resetRetryCount } from "../session/mutators.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { invokeSolomon } from "./solomon-escalation.js";
 
@@ -37,7 +38,7 @@ function isAgentFailure(output) {
  *
  * @returns {{ output, provider, attempts }}
  */
-async function runRoleWithFallback(RoleClass, { roleName, config, logger, emitter, eventBase, task, iteration, diff }) {
+async function runRoleWithFallback(RoleClass, { roleName, config, logger, emitter, eventBase, task, iteration, diff, pendingGherkinTests = null, shellTestResults = null }) {
   const chain = buildFallbackChain(config, roleName);
   const attempts = [];
 
@@ -53,7 +54,10 @@ async function runRoleWithFallback(RoleClass, { roleName, config, logger, emitte
     const start = Date.now();
     let output;
     try {
-      output = await role.run({ task, diff });
+      // Tests-first Phase 3: the tester role accepts optional extra
+      // inputs. Other roles ignore them harmlessly (they destructure
+      // only what they need from the input object).
+      output = await role.run({ task, diff, pendingGherkinTests, shellTestResults });
     } catch (err) {
       output = {
         ok: false,
@@ -93,7 +97,7 @@ async function runRoleWithFallback(RoleClass, { roleName, config, logger, emitte
   };
 }
 
-export async function runTesterStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget, iteration, task, diff, askQuestion }) {
+export async function runTesterStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget, iteration, task, diff, askQuestion: _askQuestion, pendingGherkinTests = null, shellTestResults = null }) {
   logger.setContext({ iteration, stage: "tester" });
   emitProgress(
     emitter,
@@ -106,7 +110,15 @@ export async function runTesterStage({ config, logger, emitter, eventBase, sessi
   const testerStart = Date.now();
   const { output: testerOutput, provider, attempts } = await runRoleWithFallback(
     TesterRole,
-    { roleName: "tester", config, logger, emitter, eventBase, task, iteration, diff }
+    {
+      roleName: "tester", config, logger, emitter, eventBase, task, iteration, diff,
+      // Tests-first Phase 3 (v2.7.5): hand the tester the HU's pending
+      // Gherkin scenarios and the upstream shell-test results so it
+      // translates and reports accurately instead of re-running the
+      // gate or ignoring the behavioural spec.
+      pendingGherkinTests,
+      shellTestResults,
+    }
   );
   const totalDuration = Date.now() - testerStart;
 
@@ -154,8 +166,23 @@ export async function runTesterStage({ config, logger, emitter, eventBase, sessi
     };
   }
 
-  session.tester_retry_count = 0;
-  return { action: "ok", stageResult: { ok: true, summary: testerOutput.summary || "All tests passed" } };
+  resetRetryCount(session, "tester");
+  // Propagate the full tester result (verdict, failing_scenarios,
+  // translated_scenarios, coverage…) — not just {ok, summary}. Callers
+  // in the HU sub-pipeline read `stageResult.verdict === "pass"` to
+  // decide approve-vs-feedback when Gherkin translation is involved;
+  // dropping the verdict here forced every Gherkin-bearing HU into the
+  // "fail" branch even when the tester explicitly returned pass, which
+  // burned all max_iterations and broke the FASE-2 test-diet run.
+  return {
+    action: "ok",
+    stageResult: {
+      ...testerOutput.result,
+      ok: true,
+      summary: testerOutput.summary || "All tests passed",
+      provider: testerProvider,
+    },
+  };
 }
 
 export async function runSecurityStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget, iteration, task, diff, askQuestion, brainCtx }) {
@@ -263,7 +290,7 @@ export async function runSecurityStage({ config, logger, emitter, eventBase, ses
     };
   }
 
-  session.security_retry_count = 0;
+  resetRetryCount(session, "security");
   return { action: "ok", stageResult: { ok: true, summary: securityOutput.summary || "No vulnerabilities found" } };
 }