karajan-code 1.11.1 → 1.13.0

package/README.md

@@ -47,6 +47,7 @@ Instead of running one AI agent and manually reviewing its output, `kj` chains a
 - **Rate-limit standby** — when agents hit rate limits, Karajan parses cooldown times, waits with exponential backoff, and auto-resumes instead of failing
 - **Preflight handshake** — `kj_preflight` requires human confirmation of agent assignments before execution, preventing AI from silently overriding your config
 - **3-tier config** — session > project > global config layering with `kj_agents` scoping
+- **Intelligent reviewer mediation** — scope filter auto-defers out-of-scope reviewer issues (files not in the diff) as tracked tech debt instead of stalling; Solomon mediates stalled reviews; deferred context injected into coder prompt
 - **Planning Game integration** — optionally pair with [Planning Game](https://github.com/AgenteIA-Geniova/planning-game) for agile project management (tasks, sprints, estimation) — like Jira, but open-source and XP-native
 
 > **Best with MCP** — Karajan Code is designed to be used as an MCP server inside your AI agent (Claude, Codex, etc.). The agent sends tasks to `kj_run`, gets real-time progress notifications, and receives structured results — no copy-pasting needed.
@@ -74,7 +75,7 @@ triage? ─> researcher? ─> planner? ─> coder ─> refactorer? ─> sonar?
 | **reviewer** | Code review with configurable strictness profiles | **Always on** |
 | **tester** | Test quality gate and coverage verification | **On** |
 | **security** | OWASP security audit | **On** |
-| **solomon** | Session supervisor — monitors iteration health with 4 rules, escalates on anomalies | **On** |
+| **solomon** | Session supervisor — monitors iteration health with 5 rules (incl. reviewer overreach), mediates stalled reviews, escalates on anomalies | **On** |
 | **commiter** | Git commit, push, and PR automation after approval | Off |
 
 Roles marked with `?` are optional and can be enabled per-run or via config.
@@ -477,7 +478,7 @@ Use `kj roles show <role>` to inspect any template. Create a project override to
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Run 1180+ tests with Vitest
+npm test              # Run 1190+ tests with Vitest
 npm run test:watch    # Watch mode
 npm run validate      # Lint + test
 ```

package/docs/README.es.md

@@ -46,6 +46,7 @@ En lugar de ejecutar un agente de IA y revisar manualmente su output, `kj` encad
 - **Standby por rate-limit** — cuando un agente alcanza limites de uso, Karajan parsea el tiempo de espera, espera con backoff exponencial y reanuda automaticamente en vez de fallar
 - **Preflight handshake** — `kj_preflight` requiere confirmacion humana de la configuracion de agentes antes de ejecutar, previniendo que la IA cambie asignaciones silenciosamente
 - **Config de 3 niveles** — sesion > proyecto > global con scoping de `kj_agents`
+- **Mediacion inteligente del reviewer** — el scope filter difiere automaticamente issues del reviewer fuera de scope (ficheros no presentes en el diff) como deuda tecnica rastreada en vez de bloquear; Solomon media reviews estancados; el contexto diferido se inyecta en el prompt del coder
 - **Integracion con Planning Game** — combina opcionalmente con [Planning Game](https://github.com/AgenteIA-Geniova/planning-game) para gestion agil de proyectos (tareas, sprints, estimacion) — como Jira, pero open-source y nativo XP
 
 > **Mejor con MCP** — Karajan Code esta disenado para usarse como servidor MCP dentro de tu agente de IA (Claude, Codex, etc.). El agente envia tareas a `kj_run`, recibe notificaciones de progreso en tiempo real, y obtiene resultados estructurados — sin copiar y pegar.
@@ -73,7 +74,7 @@ triage? ─> researcher? ─> planner? ─> coder ─> refactorer? ─> sonar?
 | **reviewer** | Revision de codigo con perfiles de exigencia configurables | **Siempre activo** |
 | **tester** | Quality gate de tests y verificacion de cobertura | **On** |
 | **security** | Auditoria de seguridad OWASP | **On** |
-| **solomon** | Supervisor de sesion — monitoriza salud de iteraciones con 4 reglas, escala ante anomalias | **On** |
+| **solomon** | Supervisor de sesion — monitoriza salud de iteraciones con 5 reglas (incl. reviewer overreach), media reviews estancados, escala ante anomalias | **On** |
 | **commiter** | Automatizacion de git commit, push y PR tras aprobacion | Off |
 
 Los roles marcados con `?` son opcionales y se pueden activar por ejecucion o via config.

package/package.json

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

package/src/becaria/dispatch.js

@@ -0,0 +1,99 @@
+/**
+ * BecarIA dispatch client — sends repository_dispatch events via gh CLI
+ * so the BecarIA Gateway can publish comments and reviews on PRs.
+ *
+ * Event types are configurable via becaria config:
+ *   - comment_event (default: "becaria-comment")
+ *   - review_event  (default: "becaria-review")
+ *
+ * Only active when becaria.enabled: true.
+ */
+
+import { runCommand } from "../utils/process.js";
+
+export const VALID_AGENTS = [
+  "Coder",
+  "Reviewer",
+  "Solomon",
+  "Sonar",
+  "Tester",
+  "Security",
+  "Planner"
+];
+
+const VALID_REVIEW_EVENTS = ["APPROVE", "REQUEST_CHANGES"];
+
+function validateCommon({ repo, prNumber }) {
+  if (!repo) throw new Error("repo is required (e.g. 'owner/repo')");
+  if (!prNumber) throw new Error("prNumber is required (positive integer)");
+}
+
+function validateAgent(agent) {
+  if (!VALID_AGENTS.includes(agent)) {
+    throw new Error(
+      `Invalid agent "${agent}". Must be one of: ${VALID_AGENTS.join(", ")}`
+    );
+  }
+}
+
+async function sendDispatch(repo, payload) {
+  const res = await runCommand(
+    "gh",
+    ["api", `repos/${repo}/dispatches`, "--method", "POST", "--input", "-"],
+    { input: JSON.stringify(payload) }
+  );
+
+  if (res.exitCode === 127) {
+    throw new Error(
+      "gh CLI not found. Install GitHub CLI: https://cli.github.com/"
+    );
+  }
+
+  if (res.exitCode !== 0) {
+    throw new Error(
+      `Dispatch failed (exit ${res.exitCode}): ${res.stderr || res.stdout}`
+    );
+  }
+}
+
+/**
+ * Send a comment event so the gateway posts a PR comment.
+ * @param {object} opts
+ * @param {object} [opts.becariaConfig] - becaria config section (optional)
+ */
+export async function dispatchComment({ repo, prNumber, agent, body, becariaConfig }) {
+  validateCommon({ repo, prNumber });
+  validateAgent(agent);
+  if (!body) throw new Error("body is required (comment text)");
+
+  const prefix = becariaConfig?.comment_prefix !== false ? `[${agent}] ` : "";
+  const eventType = becariaConfig?.comment_event || "becaria-comment";
+
+  await sendDispatch(repo, {
+    event_type: eventType,
+    client_payload: { pr_number: prNumber, agent, body: `${prefix}${body}` }
+  });
+}
+
+/**
+ * Send a review event so the gateway submits a formal PR review.
+ * @param {object} opts
+ * @param {object} [opts.becariaConfig] - becaria config section (optional)
+ */
+export async function dispatchReview({ repo, prNumber, event, body, agent, becariaConfig }) {
+  validateCommon({ repo, prNumber });
+  validateAgent(agent);
+  if (!VALID_REVIEW_EVENTS.includes(event)) {
+    throw new Error(
+      `event must be one of: ${VALID_REVIEW_EVENTS.join(", ")} (got "${event}")`
+    );
+  }
+  if (!body) throw new Error("body is required (review text)");
+
+  const eventType = becariaConfig?.review_event || "becaria-review";
+
+  await sendDispatch(repo, {
+    event_type: eventType,
+    client_payload: { pr_number: prNumber, event, body, agent }
+  });
+}

package/src/becaria/index.js

@@ -0,0 +1,3 @@
+export { dispatchComment, dispatchReview, VALID_AGENTS } from "./dispatch.js";
+export { detectRepo, detectPrNumber } from "./repo.js";
+export { getPrDiff } from "./pr-diff.js";

package/src/becaria/pr-diff.js

@@ -0,0 +1,26 @@
+/**
+ * Read PR diff via gh CLI for BecarIA Gateway flow.
+ * The reviewer reads the PR diff instead of local git diff.
+ */
+
+import { runCommand } from "../utils/process.js";
+
+/**
+ * Get the diff of a PR via `gh pr diff <number>`.
+ * Returns the diff string or throws on failure.
+ */
+export async function getPrDiff(prNumber) {
+  if (!prNumber) throw new Error("prNumber is required");
+
+  const res = await runCommand("gh", [
+    "pr",
+    "diff",
+    String(prNumber)
+  ]);
+
+  if (res.exitCode !== 0) {
+    throw new Error(`gh pr diff ${prNumber} failed: ${res.stderr || res.stdout}`);
+  }
+
+  return res.stdout;
+}

package/src/becaria/repo.js

@@ -0,0 +1,45 @@
+/**
+ * Detect GitHub repo and PR number from local git context.
+ */
+
+import { runCommand } from "../utils/process.js";
+
+/**
+ * Detect owner/repo from the git remote URL (origin).
+ * Supports HTTPS, SSH, and custom SSH aliases (e.g. github.com-user).
+ * Returns null if not a GitHub repo or not a git repo.
+ */
+export async function detectRepo() {
+  const res = await runCommand("git", [
+    "remote",
+    "get-url",
+    "origin"
+  ]);
+  if (res.exitCode !== 0) return null;
+
+  const url = res.stdout.trim();
+  // SSH: git@github.com:owner/repo.git  or  git@github.com-alias:owner/repo.git
+  const sshMatch = url.match(/github\.com[^:]*:([^/]+\/[^/]+?)(?:\.git)?$/);
+  if (sshMatch) return sshMatch[1];
+
+  // HTTPS: https://github.com/owner/repo.git
+  const httpsMatch = url.match(/github\.com\/([^/]+\/[^/]+?)(?:\.git)?$/);
+  if (httpsMatch) return httpsMatch[1];
+
+  return null;
+}
+
+/**
+ * Detect the PR number for a given branch using gh CLI.
+ * Returns null if no PR exists for the branch.
+ */
+export async function detectPrNumber(branch) {
+  const args = ["pr", "view"];
+  if (branch) args.push(branch);
+  args.push("--json", "number", "--jq", ".number");
+  const res = await runCommand("gh", args);
+  if (res.exitCode !== 0) return null;
+
+  const num = parseInt(res.stdout.trim(), 10);
+  return Number.isFinite(num) ? num : null;
+}

package/src/cli.js

@@ -37,6 +37,7 @@ program
   .command("init")
   .description("Initialize config, review rules and SonarQube")
   .option("--no-interactive", "Skip wizard, use defaults (for CI/scripts)")
+  .option("--scaffold-becaria", "Scaffold BecarIA Gateway workflow files")
   .action(async (flags) => {
     await withConfig("init", flags, async ({ config, logger }) => {
       await initCommand({ logger, flags });
@@ -84,6 +85,7 @@ program
   .option("--auto-commit")
   .option("--auto-push")
   .option("--auto-pr")
+  .option("--enable-becaria", "Enable BecarIA Gateway (early PR + dispatch comments/reviews)")
   .option("--branch-prefix <prefix>")
   .option("--methodology <name>")
   .option("--no-auto-rebase")

package/src/commands/doctor.js

@@ -129,7 +129,62 @@ export async function runChecks({ config }) {
     });
   }
 
-  // 8. Review rules / Coder rules
+  // 8. BecarIA Gateway infrastructure
+  if (config.becaria?.enabled) {
+    const projectDir = config.projectDir || process.cwd();
+
+    // Workflow files
+    const workflowDir = path.join(projectDir, ".github", "workflows");
+    const requiredWorkflows = ["becaria-gateway.yml", "automerge.yml", "houston-override.yml"];
+    for (const wf of requiredWorkflows) {
+      const wfPath = path.join(workflowDir, wf);
+      const wfExists = await exists(wfPath);
+      checks.push({
+        name: `becaria:workflow:${wf}`,
+        label: `BecarIA workflow: ${wf}`,
+        ok: wfExists,
+        detail: wfExists ? "Found" : "Not found",
+        fix: wfExists ? null : `Run 'kj init --scaffold-becaria' or copy from karajan-code/templates/workflows/${wf}`
+      });
+    }
+
+    // gh CLI
+    const ghCheck = await checkBinary("gh");
+    checks.push({
+      name: "becaria:gh",
+      label: "BecarIA: gh CLI",
+      ok: ghCheck.ok,
+      detail: ghCheck.ok ? ghCheck.version : "Not found",
+      fix: ghCheck.ok ? null : "Install GitHub CLI: https://cli.github.com/"
+    });
+
+    // Secrets check via gh api (best effort — only works if user has admin access)
+    let secretsOk = false;
+    try {
+      const { detectRepo } = await import("../becaria/repo.js");
+      const repo = await detectRepo();
+      if (repo) {
+        const secretsRes = await runCommand("gh", ["api", `repos/${repo}/actions/secrets`, "--jq", ".secrets[].name"]);
+        if (secretsRes.exitCode === 0) {
+          const names = secretsRes.stdout.split("\n").map((s) => s.trim());
+          const hasAppId = names.includes("BECARIA_APP_ID");
+          const hasKey = names.includes("BECARIA_APP_PRIVATE_KEY");
+          secretsOk = hasAppId && hasKey;
+          checks.push({
+            name: "becaria:secrets",
+            label: "BecarIA: GitHub secrets",
+            ok: secretsOk,
+            detail: secretsOk ? "BECARIA_APP_ID + BECARIA_APP_PRIVATE_KEY found" : `Missing: ${!hasAppId ? "BECARIA_APP_ID " : ""}${!hasKey ? "BECARIA_APP_PRIVATE_KEY" : ""}`.trim(),
+            fix: secretsOk ? null : "Add BECARIA_APP_ID and BECARIA_APP_PRIVATE_KEY as GitHub repository secrets"
+          });
+        }
+      }
+    } catch {
+      // Skip secrets check if we can't access the API
+    }
+  }
+
+  // 9. Review rules / Coder rules
   const projectDir = config.projectDir || process.cwd();
   const reviewRules = await loadFirstExisting(resolveRoleMdPath("reviewer", projectDir));
   const coderRules = await loadFirstExisting(resolveRoleMdPath("coder", projectDir));

package/src/commands/init.js

@@ -177,4 +177,37 @@ export async function initCommand({ logger, flags = {} }) {
   } else {
     logger.info("SonarQube disabled — skipping container setup.");
   }
+
+  // --- BecarIA Gateway scaffolding ---
+  if (config.becaria?.enabled || flags.scaffoldBecaria) {
+    const projectDir = process.cwd();
+    const workflowDir = path.join(projectDir, ".github", "workflows");
+    await ensureDir(workflowDir);
+
+    const templatesDir = path.resolve(import.meta.dirname, "../../templates/workflows");
+    const workflows = ["becaria-gateway.yml", "automerge.yml", "houston-override.yml"];
+
+    for (const wf of workflows) {
+      const destPath = path.join(workflowDir, wf);
+      if (!(await exists(destPath))) {
+        const srcPath = path.join(templatesDir, wf);
+        try {
+          const content = await fs.readFile(srcPath, "utf8");
+          await fs.writeFile(destPath, content, "utf8");
+          logger.info(`Created ${path.relative(projectDir, destPath)}`);
+        } catch (err) {
+          logger.warn(`Could not scaffold ${wf}: ${err.message}`);
+        }
+      } else {
+        logger.info(`${wf} already exists — skipping`);
+      }
+    }
+
+    logger.info("");
+    logger.info("BecarIA Gateway scaffolded. Next steps:");
+    logger.info("  1. Create a GitHub App named 'becaria-reviewer' with pull_request write permissions");
+    logger.info("  2. Install the App on your repository");
+    logger.info("  3. Add secrets: BECARIA_APP_ID and BECARIA_APP_PRIVATE_KEY");
+    logger.info("  4. Push the workflow files and enable 'kj run --enable-becaria'");
+  }
 }

package/src/commands/review.js

@@ -10,8 +10,26 @@ export async function reviewCommand({ task, config, logger, baseRef }) {
   await assertAgentsAvailable([reviewerRole.provider, config.reviewer_options?.fallback_reviewer]);
   logger.info(`Reviewer (${reviewerRole.provider}) starting...`);
   const reviewer = createAgent(reviewerRole.provider, config, logger);
-  const resolvedBase = await computeBaseRef({ baseBranch: config.base_branch, baseRef });
-  const diff = await generateDiff({ baseRef: resolvedBase });
+
+  let diff;
+  if (config.becaria?.enabled) {
+    // BecarIA mode: read diff from open PR
+    const { detectRepo, detectPrNumber } = await import("../becaria/repo.js");
+    const { getPrDiff } = await import("../becaria/pr-diff.js");
+    const repo = await detectRepo();
+    const prNumber = await detectPrNumber();
+    if (!prNumber) {
+      throw new Error("BecarIA enabled but no open PR found for current branch. Create a PR first or disable BecarIA.");
+    }
+    logger.info(`BecarIA: reading PR diff #${prNumber}`);
+    diff = await getPrDiff(prNumber);
+    // Store for dispatch later
+    config._becaria_pr = { repo, prNumber };
+  } else {
+    const resolvedBase = await computeBaseRef({ baseBranch: config.base_branch, baseRef });
+    diff = await generateDiff({ baseRef: resolvedBase });
+  }
+
   const { rules } = await resolveReviewProfile({ mode: config.review_mode, projectDir: process.cwd() });
 
   const prompt = buildReviewerPrompt({ task, diff, reviewRules: rules, mode: config.review_mode });
@@ -23,4 +41,38 @@ export async function reviewCommand({ task, config, logger, baseRef }) {
   }
   console.log(result.output);
   logger.info(`Reviewer completed (exit ${result.exitCode})`);
+
+  // BecarIA: dispatch review result
+  if (config.becaria?.enabled && config._becaria_pr) {
+    try {
+      const { dispatchReview, dispatchComment } = await import("../becaria/dispatch.js");
+      const { repo, prNumber } = config._becaria_pr;
+      const bc = config.becaria;
+
+      // Try to parse structured review from output
+      let review;
+      try {
+        review = JSON.parse(result.output);
+      } catch {
+        review = { approved: true, summary: result.output };
+      }
+
+      const event = review.approved ? "APPROVE" : "REQUEST_CHANGES";
+      await dispatchReview({
+        repo, prNumber, event,
+        body: review.summary || result.output.slice(0, 500),
+        agent: "Reviewer", becariaConfig: bc
+      });
+
+      await dispatchComment({
+        repo, prNumber, agent: "Reviewer",
+        body: `Standalone review: ${event}\n\n${review.summary || result.output.slice(0, 1000)}`,
+        becariaConfig: bc
+      });
+
+      logger.info(`BecarIA: dispatched review for PR #${prNumber}`);
+    } catch (err) {
+      logger.warn(`BecarIA dispatch failed (non-blocking): ${err.message}`);
+    }
+  }
 }

package/src/config.js

@@ -99,6 +99,7 @@ const DEFAULTS = {
   },
   serena: { enabled: false },
   planning_game: { enabled: false, project_id: null, codeveloper: null },
+  becaria: { enabled: false, review_event: "becaria-review", comment_event: "becaria-comment", comment_prefix: true },
   git: { auto_commit: false, auto_push: false, auto_pr: false, auto_rebase: true, branch_prefix: "feat/" },
   output: { report_dir: "./.reviews", log_level: "info" },
   budget: {
@@ -287,6 +288,16 @@ export function applyRunOverrides(config, flags) {
   if (flags.noSonar || flags.sonar === false) out.sonarqube.enabled = false;
   out.serena = out.serena || { enabled: false };
   if (flags.enableSerena !== undefined) out.serena.enabled = Boolean(flags.enableSerena);
+  out.becaria = out.becaria || { enabled: false };
+  if (flags.enableBecaria !== undefined) {
+    out.becaria.enabled = Boolean(flags.enableBecaria);
+    // BecarIA requires git automation (commit + push + PR)
+    if (out.becaria.enabled) {
+      out.git.auto_commit = true;
+      out.git.auto_push = true;
+      out.git.auto_pr = true;
+    }
+  }
   out.planning_game = out.planning_game || {};
   if (flags.pgTask) out.planning_game.enabled = true;
   if (flags.pgProject) out.planning_game.project_id = flags.pgProject;

package/src/git/automation.js

@@ -82,6 +82,67 @@ export function buildPrBody({ task, stageResults }) {
   return sections.join("\n");
 }
 
+/**
+ * Create an early PR after the first coder iteration (BecarIA Gateway flow).
+ * Commits, pushes, and creates a PR before the reviewer runs.
+ * Returns { prNumber, prUrl, commits } or null if nothing to commit.
+ */
+export async function earlyPrCreation({ gitCtx, task, logger, session, stageResults = null }) {
+  if (!gitCtx?.enabled) return null;
+
+  const commitMsg = commitMessageFromTask(task);
+  const commitResult = await commitAll(commitMsg);
+  if (!commitResult.committed) {
+    logger.info("earlyPrCreation: no changes to commit");
+    return null;
+  }
+
+  const commits = commitResult.commit ? [commitResult.commit] : [];
+  await addCheckpoint(session, { stage: "becaria-commit", committed: true });
+
+  await pushBranch(gitCtx.branch);
+  await addCheckpoint(session, { stage: "becaria-push", branch: gitCtx.branch });
+  logger.info(`Pushed branch for early PR: ${gitCtx.branch}`);
+
+  const body = buildPrBody({ task, stageResults });
+  const prUrl = await createPullRequest({
+    baseBranch: gitCtx.baseBranch,
+    branch: gitCtx.branch,
+    title: commitMessageFromTask(task),
+    body
+  });
+  await addCheckpoint(session, { stage: "becaria-pr", branch: gitCtx.branch, pr: prUrl });
+  logger.info(`Early PR created: ${prUrl}`);
+
+  // Extract PR number from URL (e.g. https://github.com/owner/repo/pull/42)
+  const prNumber = parseInt(prUrl.split("/").pop(), 10) || null;
+  return { prNumber, prUrl, commits };
+}
+
+/**
+ * Incremental push after each coder iteration (BecarIA Gateway flow).
+ * Commits and pushes without creating a new PR.
+ */
+export async function incrementalPush({ gitCtx, task, logger, session }) {
+  if (!gitCtx?.enabled) return null;
+
+  const commitMsg = commitMessageFromTask(task);
+  const commitResult = await commitAll(commitMsg);
+  if (!commitResult.committed) {
+    logger.info("incrementalPush: no changes to commit");
+    return null;
+  }
+
+  const commits = commitResult.commit ? [commitResult.commit] : [];
+  await addCheckpoint(session, { stage: "becaria-incremental-commit", committed: true });
+
+  await pushBranch(gitCtx.branch);
+  await addCheckpoint(session, { stage: "becaria-incremental-push", branch: gitCtx.branch });
+  logger.info(`Incremental push: ${gitCtx.branch}`);
+
+  return { commits };
+}
+
 export async function finalizeGitAutomation({ config, gitCtx, task, logger, session, stageResults = null }) {
   if (!gitCtx?.enabled) return { git: "disabled", commits: [] };
 
@@ -114,8 +175,8 @@ export async function finalizeGitAutomation({ config, gitCtx, task, logger, sess
     logger.info(`Pushed branch: ${gitCtx.branch}`);
   }
 
-  let prUrl = null;
-  if (config.git.auto_pr) {
+  let prUrl = session.becaria_pr_url || null;
+  if (config.git.auto_pr && !prUrl) {
     const body = buildPrBody({ task, stageResults });
     prUrl = await createPullRequest({
       baseBranch: gitCtx.baseBranch,
@@ -125,6 +186,8 @@ export async function finalizeGitAutomation({ config, gitCtx, task, logger, sess
     });
     await addCheckpoint(session, { stage: "git-pr", branch: gitCtx.branch, pr: prUrl });
     logger.info("Pull request created");
+  } else if (prUrl) {
+    logger.info(`PR already exists (BecarIA flow): ${prUrl}`);
   }
 
   return { committed, branch: gitCtx.branch, prUrl, pr: prUrl, commits };

package/src/mcp/tools.js

@@ -71,6 +71,7 @@ export const tools = [
         enableSecurity: { type: "boolean" },
         enableTriage: { type: "boolean" },
         enableSerena: { type: "boolean" },
+        enableBecaria: { type: "boolean", description: "Enable BecarIA Gateway (early PR + dispatch comments/reviews)" },
         reviewerFallback: { type: "string" },
         reviewerRetries: { type: "number" },
         mode: { type: "string" },

package/src/orchestrator/iteration-stages.js

@@ -6,6 +6,7 @@ import { addCheckpoint, markSessionStatus, saveSession, pauseSession } from "../
 import { generateDiff } from "../review/diff-generator.js";
 import { evaluateTddPolicy } from "../review/tdd-policy.js";
 import { validateReviewResult } from "../review/schema.js";
+import { filterReviewScope, buildDeferredContext } from "../review/scope-filter.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { runReviewerWithFallback } from "./reviewer-fallback.js";
 import { runCoderWithFallback } from "./agent-fallback.js";
@@ -39,6 +40,7 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
       task: plannedTask,
       reviewerFeedback: session.last_reviewer_feedback,
       sonarSummary: session.last_sonar_summary,
+      deferredContext: buildDeferredContext(session.deferred_issues),
       onOutput: coderStall.onOutput
     });
   } finally {
@@ -390,7 +392,7 @@ export async function runSonarStage({ config, logger, emitter, eventBase, sessio
   return { action: "ok", stageResult };
 }
 
-export async function runReviewerStage({ reviewerRole, config, logger, emitter, eventBase, session, trackBudget, iteration, reviewRules, task, repeatDetector, budgetSummary }) {
+export async function runReviewerStage({ reviewerRole, config, logger, emitter, eventBase, session, trackBudget, iteration, reviewRules, task, repeatDetector, budgetSummary, askQuestion }) {
   logger.setContext({ iteration, stage: "reviewer" });
   emitProgress(
     emitter,
@@ -400,7 +402,14 @@ export async function runReviewerStage({ reviewerRole, config, logger, emitter,
     })
   );
 
-  const diff = await generateDiff({ baseRef: session.session_start_sha });
+  let diff;
+  if (session.becaria_pr_number) {
+    const { getPrDiff } = await import("../becaria/pr-diff.js");
+    diff = await getPrDiff(session.becaria_pr_number);
+    logger.info(`Reviewer reading PR diff #${session.becaria_pr_number}`);
+  } else {
+    diff = await generateDiff({ baseRef: session.session_start_sha });
+  }
   const reviewerOnOutput = ({ stream, line }) => {
     emitProgress(emitter, makeEvent("agent:output", { ...eventBase, stage: "reviewer" }, {
       message: line,
@@ -489,6 +498,39 @@ export async function runReviewerStage({ reviewerRole, config, logger, emitter,
       confidence: 0
     };
   }
+  // --- Scope filter: auto-defer out-of-scope blocking issues ---
+  const { review: filteredReview, demoted, deferred, allDemoted } = filterReviewScope(review, diff);
+  review = filteredReview;
+
+  if (demoted.length > 0) {
+    logger.info(`Scope filter: deferred ${demoted.length} out-of-scope issue(s)${allDemoted ? " — auto-approved" : ""}`);
+
+    // Accumulate deferred issues in session for tracking
+    if (!session.deferred_issues) session.deferred_issues = [];
+    session.deferred_issues.push(...deferred);
+    await saveSession(session);
+
+    emitProgress(
+      emitter,
+      makeEvent("reviewer:scope_filter", { ...eventBase, stage: "reviewer" }, {
+        message: `Scope filter deferred ${demoted.length} out-of-scope issue(s)`,
+        detail: {
+          demotedCount: demoted.length,
+          autoApproved: allDemoted,
+          totalDeferred: session.deferred_issues.length,
+          deferred: deferred.map(d => ({ file: d.file, id: d.id, description: d.description }))
+        }
+      })
+    );
+    await addCheckpoint(session, {
+      stage: "reviewer-scope-filter",
+      iteration,
+      demoted_count: demoted.length,
+      auto_approved: allDemoted,
+      total_deferred: session.deferred_issues.length
+    });
+  }
+
   await addCheckpoint(session, {
     stage: "reviewer",
     iteration,
@@ -518,8 +560,48 @@ export async function runReviewerStage({ reviewerRole, config, logger, emitter,
     const repeatState = repeatDetector.isStalled();
     if (repeatState.stalled) {
       const repeatCounts = repeatDetector.getRepeatCounts();
+
+      // --- Solomon mediation for stalled reviewer ---
+      logger.warn(`Reviewer stalled (${repeatCounts.reviewer} repeats). Invoking Solomon mediation.`);
+      emitProgress(
+        emitter,
+        makeEvent("solomon:escalate", { ...eventBase, stage: "reviewer" }, {
+          message: `Reviewer stalled — Solomon mediating`,
+          detail: { repeats: repeatCounts.reviewer, reason: repeatState.reason }
+        })
+      );
+
+      const solomonResult = await invokeSolomon({
+        config, logger, emitter, eventBase, stage: "reviewer", askQuestion, session, iteration,
+        conflict: {
+          stage: "reviewer",
+          task,
+          iterationCount: repeatCounts.reviewer,
+          maxIterations: config.session?.fail_fast_repeats ?? 2,
+          stalledReason: repeatState.reason,
+          blockingIssues: review.blocking_issues,
+          history: [{ agent: "reviewer", feedback: review.blocking_issues.map(x => x.description).join("; ") }]
+        }
+      });
+
+      if (solomonResult.action === "pause") {
+        await markSessionStatus(session, "stalled");
+        return { review, stalled: true, stalledResult: { paused: true, sessionId: session.id, question: solomonResult.question, context: "reviewer_stalled" } };
+      }
+      if (solomonResult.action === "continue") {
+        repeatDetector.reviewer = { lastHash: null, repeatCount: 0 };
+        if (solomonResult.humanGuidance) {
+          session.last_reviewer_feedback = `Solomon/user guidance: ${solomonResult.humanGuidance}`;
+          await saveSession(session);
+        }
+        return { review };
+      }
+      if (solomonResult.action === "subtask") {
+        return { review, stalled: true, stalledResult: { paused: true, sessionId: session.id, subtask: solomonResult.subtask, context: "reviewer_subtask" } };
+      }
+
+      // Fallback
       const message = `Manual intervention required: reviewer issues repeated ${repeatCounts.reviewer} times.`;
-      logger.warn(message);
       await markSessionStatus(session, "stalled");
       emitProgress(
         emitter,