karajan-code 1.12.0 → 1.13.1

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.12.0",
+  "version": "1.13.1",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/agents/claude-agent.js

@@ -120,7 +120,7 @@ export class ClaudeAgent extends BaseAgent {
 
     // Use stream-json when onOutput is provided to get real-time feedback
     if (task.onOutput) {
-      args.push("--output-format", "stream-json");
+      args.push("--output-format", "stream-json", "--verbose");
       const streamFilter = createStreamJsonFilter(task.onOutput);
       const res = await runCommand(resolveBin("claude"), args, cleanExecaOpts({
         onOutput: streamFilter,
@@ -141,7 +141,7 @@ export class ClaudeAgent extends BaseAgent {
   }
 
   async reviewTask(task) {
-    const args = ["-p", task.prompt, "--allowedTools", ...ALLOWED_TOOLS, "--output-format", "stream-json"];
+    const args = ["-p", task.prompt, "--allowedTools", ...ALLOWED_TOOLS, "--output-format", "stream-json", "--verbose"];
     const model = this.getRoleModel(task.role || "reviewer");
     if (model) args.push("--model", model);
     const res = await runCommand(resolveBin("claude"), args, cleanExecaOpts({

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

@@ -402,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,

package/src/orchestrator.js

@@ -17,7 +17,9 @@ import { emitProgress, makeEvent } from "./utils/events.js";
 import { BudgetTracker, extractUsageMetrics } from "./utils/budget.js";
 import {
   prepareGitAutomation,
-  finalizeGitAutomation
+  finalizeGitAutomation,
+  earlyPrCreation,
+  incrementalPush
 } from "./git/automation.js";
 import { resolveRoleMdPath, loadFirstExisting } from "./roles/base-role.js";
 import { resolveReviewProfile } from "./review/profiles.js";
@@ -288,6 +290,23 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
     const plannerResult = await runPlannerStage({ config, logger, emitter, eventBase, session, plannerRole, researchContext, triageDecomposition, trackBudget });
     plannedTask = plannerResult.plannedTask;
     stageResults.planner = plannerResult.stageResult;
+
+    // BecarIA: dispatch planner comment (only on resume where PR already exists)
+    if (Boolean(config.becaria?.enabled) && session.becaria_pr_number) {
+      try {
+        const { dispatchComment } = await import("./becaria/dispatch.js");
+        const { detectRepo } = await import("./becaria/repo.js");
+        const repo = await detectRepo();
+        if (repo) {
+          const p = plannerResult.stageResult;
+          await dispatchComment({
+            repo, prNumber: session.becaria_pr_number, agent: "Planner",
+            body: `Plan: ${p?.summary || plannedTask}`,
+            becariaConfig: config.becaria
+          });
+        }
+      } catch { /* non-blocking */ }
+    }
   }
 
   const gitCtx = await prepareGitAutomation({ config, task, logger, session });
@@ -393,6 +412,7 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
 
     eventBase.iteration = i;
     const iterStart = Date.now();
+    const becariaEnabled = Boolean(config.becaria?.enabled) && gitCtx?.enabled;
     logger.setContext({ iteration: i, stage: "iteration" });
 
     emitProgress(
@@ -483,6 +503,75 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
       }
       if (sonarResult.stageResult) {
         stageResults.sonar = sonarResult.stageResult;
+        // BecarIA: dispatch sonar comment
+        if (becariaEnabled && session.becaria_pr_number) {
+          try {
+            const { dispatchComment } = await import("./becaria/dispatch.js");
+            const { detectRepo } = await import("./becaria/repo.js");
+            const repo = await detectRepo();
+            if (repo) {
+              const s = sonarResult.stageResult;
+              await dispatchComment({
+                repo, prNumber: session.becaria_pr_number, agent: "Sonar",
+                body: `SonarQube scan: ${s.summary || "completed"}`,
+                becariaConfig: config.becaria
+              });
+            }
+          } catch { /* non-blocking */ }
+        }
+      }
+    }
+
+    // --- BecarIA Gateway: early PR or incremental push ---
+    if (becariaEnabled) {
+      try {
+        const { dispatchComment } = await import("./becaria/dispatch.js");
+        const { detectRepo } = await import("./becaria/repo.js");
+        const repo = await detectRepo();
+
+        if (!session.becaria_pr_number) {
+          // First iteration: commit + push + create PR
+          const earlyPr = await earlyPrCreation({ gitCtx, task, logger, session, stageResults });
+          if (earlyPr) {
+            session.becaria_pr_number = earlyPr.prNumber;
+            session.becaria_pr_url = earlyPr.prUrl;
+            session.becaria_commits = earlyPr.commits;
+            await saveSession(session);
+            emitProgress(emitter, makeEvent("becaria:pr-created", { ...eventBase, stage: "becaria" }, {
+              message: `Early PR created: #${earlyPr.prNumber}`,
+              detail: { prNumber: earlyPr.prNumber, prUrl: earlyPr.prUrl }
+            }));
+
+            // Post coder comment on new PR
+            if (repo) {
+              const commitList = earlyPr.commits.map((c) => `- \`${c.hash.slice(0, 7)}\` ${c.message}`).join("\n");
+              await dispatchComment({
+                repo, prNumber: earlyPr.prNumber, agent: "Coder",
+                body: `Iteración ${i} completada.\n\nCommits:\n${commitList}`,
+                becariaConfig: config.becaria
+              });
+            }
+          }
+        } else {
+          // Subsequent iterations: incremental push + comment
+          const pushResult = await incrementalPush({ gitCtx, task, logger, session });
+          if (pushResult) {
+            session.becaria_commits = [...(session.becaria_commits || []), ...pushResult.commits];
+            await saveSession(session);
+
+            if (repo) {
+              const feedback = session.last_reviewer_feedback || "N/A";
+              const commitList = pushResult.commits.map((c) => `- \`${c.hash.slice(0, 7)}\` ${c.message}`).join("\n");
+              await dispatchComment({
+                repo, prNumber: session.becaria_pr_number, agent: "Coder",
+                body: `Issues corregidos:\n${feedback}\n\nCommits:\n${commitList}`,
+                becariaConfig: config.becaria
+              });
+            }
+          }
+        }
+      } catch (err) {
+        logger.warn(`BecarIA early PR/push failed (non-blocking): ${err.message}`);
       }
     }
 
@@ -576,11 +665,74 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
             }
           }
         }
+
+        // BecarIA: dispatch solomon comment
+        if (becariaEnabled && session.becaria_pr_number) {
+          try {
+            const { dispatchComment } = await import("./becaria/dispatch.js");
+            const { detectRepo } = await import("./becaria/repo.js");
+            const repo = await detectRepo();
+            if (repo) {
+              const alerts = rulesResult.alerts || [];
+              const alertMsg = alerts.length > 0
+                ? alerts.map(a => `- [${a.severity}] ${a.message}`).join("\n")
+                : "No anomalies detected";
+              await dispatchComment({
+                repo, prNumber: session.becaria_pr_number, agent: "Solomon",
+                body: `Supervisor check iteración ${i}: ${alertMsg}`,
+                becariaConfig: config.becaria
+              });
+            }
+          } catch { /* non-blocking */ }
+        }
       } catch (err) {
         logger.warn(`Solomon rules evaluation failed: ${err.message}`);
       }
     }
 
+    // --- BecarIA Gateway: dispatch review result ---
+    if (becariaEnabled && session.becaria_pr_number) {
+      try {
+        const { dispatchReview, dispatchComment } = await import("./becaria/dispatch.js");
+        const { detectRepo } = await import("./becaria/repo.js");
+        const repo = await detectRepo();
+        if (repo) {
+          const bc = config.becaria;
+          // Formal review (APPROVE / REQUEST_CHANGES)
+          if (review.approved) {
+            await dispatchReview({
+              repo, prNumber: session.becaria_pr_number,
+              event: "APPROVE", body: review.summary || "Approved", agent: "Reviewer", becariaConfig: bc
+            });
+          } else {
+            const blocking = review.blocking_issues?.map((x) => `- ${x.id || "ISSUE"} [${x.severity || ""}] ${x.description}`).join("\n") || "";
+            await dispatchReview({
+              repo, prNumber: session.becaria_pr_number,
+              event: "REQUEST_CHANGES",
+              body: blocking || review.summary || "Changes requested",
+              agent: "Reviewer", becariaConfig: bc
+            });
+          }
+
+          // Detailed comment
+          const status = review.approved ? "APPROVED" : "REQUEST_CHANGES";
+          const blocking = review.blocking_issues?.map((x) => `- ${x.id || "ISSUE"} [${x.severity || ""}] ${x.description}`).join("\n") || "";
+          const suggestions = review.non_blocking_suggestions?.map((s) => `- ${typeof s === "string" ? s : `${s.id || ""} ${s.description || s}`}`).join("\n") || "";
+          let reviewBody = `Review iteración ${i}: ${status}`;
+          if (blocking) reviewBody += `\n\n**Blocking:**\n${blocking}`;
+          if (suggestions) reviewBody += `\n\n**Suggestions:**\n${suggestions}`;
+          await dispatchComment({
+            repo, prNumber: session.becaria_pr_number, agent: "Reviewer",
+            body: reviewBody, becariaConfig: bc
+          });
+
+          logger.info(`BecarIA: dispatched review for PR #${session.becaria_pr_number}`);
+        }
+      } catch (err) {
+        logger.warn(`BecarIA dispatch failed (non-blocking): ${err.message}`);
+      }
+    }
+
     if (review.approved) {
       session.reviewer_retry_count = 0;
 
@@ -600,6 +752,22 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
         }
         if (testerResult.stageResult) {
           stageResults.tester = testerResult.stageResult;
+          // BecarIA: dispatch tester comment
+          if (becariaEnabled && session.becaria_pr_number) {
+            try {
+              const { dispatchComment } = await import("./becaria/dispatch.js");
+              const { detectRepo } = await import("./becaria/repo.js");
+              const repo = await detectRepo();
+              if (repo) {
+                const t = testerResult.stageResult;
+                await dispatchComment({
+                  repo, prNumber: session.becaria_pr_number, agent: "Tester",
+                  body: `Tests: ${t.summary || "completed"}`,
+                  becariaConfig: config.becaria
+                });
+              }
+            } catch { /* non-blocking */ }
+          }
         }
       }
 
@@ -616,6 +784,22 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
         }
         if (securityResult.stageResult) {
           stageResults.security = securityResult.stageResult;
+          // BecarIA: dispatch security comment
+          if (becariaEnabled && session.becaria_pr_number) {
+            try {
+              const { dispatchComment } = await import("./becaria/dispatch.js");
+              const { detectRepo } = await import("./becaria/repo.js");
+              const repo = await detectRepo();
+              if (repo) {
+                const s = securityResult.stageResult;
+                await dispatchComment({
+                  repo, prNumber: session.becaria_pr_number, agent: "Security",
+                  body: `Security scan: ${s.summary || "completed"}`,
+                  becariaConfig: config.becaria
+                });
+              }
+            } catch { /* non-blocking */ }
+          }
         }
       }
 

package/templates/roles/coder.md

@@ -7,9 +7,20 @@ You are the **Coder** in a multi-role AI pipeline. Your job is to write code and
 - Follow TDD methodology when `methodology=tdd` is configured.
 - Write tests BEFORE implementation when using TDD.
 - Keep changes minimal and focused on the task.
+- "Minimal" means no unnecessary changes — it does NOT mean avoiding new files. If the task requires creating new files (pages, components, modules, tests), you MUST create them. Updating references/links without creating the actual files is an incomplete implementation.
 - Do not modify code unrelated to the task.
+- Before creating a new utility or helper, check if a similar one already exists in the codebase. Reuse existing code over creating duplicates.
 - Follow existing code conventions and patterns in the repository.
 
+## Task completeness
+
+Before reporting done, verify that ALL parts of the task are addressed:
+- Re-read the task description and acceptance criteria.
+- Check every requirement — if the task says "create pages X and Y", both must exist.
+- If the task lists multiple deliverables, each one must be implemented, not just some.
+- Run the test suite after implementation to verify nothing is broken.
+- An incomplete implementation is worse than an error — never report success if parts are missing.
+
 ## File modification safety
 
 - NEVER overwrite existing files entirely. Always make targeted, minimal edits.
@@ -18,13 +29,6 @@ You are the **Coder** in a multi-role AI pipeline. Your job is to write code and
 - If unintended changes are detected, revert immediately with `git checkout -- <file>`.
 - Pay special attention to CSS, HTML, and config files where full rewrites destroy prior work.
 
-## Multi-agent environment
-
-- Multiple developers and AI agents may be committing and modifying code simultaneously.
-- ALWAYS run `git fetch origin main` and check recent commits before starting work.
-- Before pushing or merging, rebase on the latest main: `git rebase origin/main`.
-- Create a dedicated branch per task and merge via PR, never push directly to main.
-
 ## Output format
 
 Return a JSON object:

package/templates/roles/planner.md

@@ -20,6 +20,8 @@ You are the **Planner** in a multi-role AI pipeline. Your job is to create an im
 ## Rules
 
 - Each step should be small and independently verifiable.
+- Steps must list ALL files involved: both files to modify AND new files to create. If a step requires creating a new file, list it explicitly in the `files` array.
+- The plan must cover ALL requirements from the task. Re-read the task description before finalizing — if something is mentioned in the task, it must appear in a step.
 - Identify the testing strategy (unit, integration, E2E).
 - Consider backward compatibility.
 - Reference research findings when available.

package/templates/roles/refactorer.md

@@ -5,7 +5,7 @@ You are the **Refactorer** in a multi-role AI pipeline. Your job is to improve c
 ## Constraints
 
 - Do NOT change any observable behavior or API contracts.
-- Do NOT expand the scope of changes beyond what was already modified.
+- Focus on the files that were already modified in this session. You may create new files when extracting code (e.g., extracting a helper to a new module), but do not refactor unrelated parts of the codebase.
 - Keep all existing tests passing — run tests after every change.
 - Follow existing code conventions and patterns in the repository.
 - Do NOT add new features or fix unrelated bugs.

package/templates/roles/reviewer.md

@@ -2,6 +2,12 @@
 
 You are the **Reviewer** in a multi-role AI pipeline. Your job is to review code changes against task requirements and quality standards.
 
+## Scope constraint
+
+- **ONLY review files present in the diff.** Do not flag issues in files that were not changed.
+- If you notice problems in untouched files, mention them as `non_blocking_suggestions` with a note that they are outside the current scope — never as `blocking_issues`.
+- Your job is to review THIS change, not audit the entire codebase.
+
 ## Review priorities (in order)
 
 1. **Security** — vulnerabilities, exposed secrets, injection vectors
@@ -13,9 +19,10 @@ You are the **Reviewer** in a multi-role AI pipeline. Your job is to review code
 ## Rules
 
 - Focus on security, correctness, and tests first.
-- Only raise blocking issues for concrete production risks.
+- Only raise blocking issues for concrete production risks in the changed files.
 - Keep non-blocking suggestions separate.
 - Style preferences NEVER block approval.
+- Confidence threshold: reject only if < 0.70.
 
 ## File overwrite detection (BLOCKING)
 
@@ -31,7 +38,7 @@ Return a strict JSON object:
   "result": {
     "approved": true,
     "blocking_issues": [],
-    "suggestions": ["Optional improvement ideas"],
+    "non_blocking_suggestions": ["Optional improvement ideas"],
     "confidence": 0.95
   },
   "summary": "Approved: all changes look correct and well-tested"
@@ -45,9 +52,9 @@ When rejecting:
   "result": {
     "approved": false,
     "blocking_issues": [
-      { "file": "src/foo.js", "line": 42, "severity": "critical", "issue": "SQL injection vulnerability" }
+      { "id": "R-1", "file": "src/foo.js", "line": 42, "severity": "critical", "description": "SQL injection vulnerability", "suggested_fix": "Use parameterized queries instead of string concatenation" }
     ],
-    "suggestions": [],
+    "non_blocking_suggestions": [],
     "confidence": 0.9
   },
   "summary": "Rejected: 1 critical security issue found"

package/templates/workflows/automerge.yml

@@ -0,0 +1,30 @@
+# Auto-merge PRs approved by BecarIA reviewer.
+# Merges when becaria-reviewer[bot] approves and all checks pass.
+
+name: Auto-merge (BecarIA)
+
+on:
+  pull_request_review:
+    types: [submitted]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  automerge:
+    if: >
+      github.event.review.state == 'approved' &&
+      contains(github.event.review.user.login, 'becaria-reviewer')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Enable auto-merge
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.pulls.merge({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.payload.pull_request.number,
+              merge_method: 'squash'
+            });

package/templates/workflows/becaria-gateway.yml

@@ -0,0 +1,58 @@
+# BecarIA Gateway — publishes PR comments and reviews from repository_dispatch events.
+# Triggered by Karajan Code pipeline via `gh api repos/{owner}/{repo}/dispatches`.
+#
+# Required secrets:
+#   BECARIA_APP_ID          — GitHub App ID for becaria-reviewer
+#   BECARIA_APP_PRIVATE_KEY — PEM private key for the GitHub App
+
+name: BecarIA Gateway
+
+on:
+  repository_dispatch:
+    types:
+      - becaria-comment
+      - becaria-review
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  gateway:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Generate App Token
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.BECARIA_APP_ID }}
+          private-key: ${{ secrets.BECARIA_APP_PRIVATE_KEY }}
+
+      - name: Post Comment
+        if: github.event.action == 'becaria-comment'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ steps.app-token.outputs.token }}
+          script: |
+            const { pr_number, agent, body } = context.payload.client_payload;
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: pr_number,
+              body: `**${agent}** (via BecarIA)\n\n${body}`
+            });
+
+      - name: Submit Review
+        if: github.event.action == 'becaria-review'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ steps.app-token.outputs.token }}
+          script: |
+            const { pr_number, event, body, agent } = context.payload.client_payload;
+            await github.rest.pulls.createReview({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: pr_number,
+              event: event,
+              body: `**${agent}** (via BecarIA)\n\n${body}`
+            });

package/templates/workflows/houston-override.yml

@@ -0,0 +1,46 @@
+# Houston Override — allows a human to force-approve a PR by commenting "/houston approve".
+# Bypasses BecarIA's REQUEST_CHANGES review.
+
+name: Houston Override
+
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  override:
+    if: >
+      github.event.issue.pull_request &&
+      contains(github.event.comment.body, '/houston approve')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Dismiss BecarIA review and approve
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+            const pr_number = context.payload.issue.number;
+
+            // Find and dismiss becaria-reviewer reviews
+            const reviews = await github.rest.pulls.listReviews({
+              owner, repo, pull_number: pr_number
+            });
+
+            for (const review of reviews.data) {
+              if (review.user.login.includes('becaria-reviewer') && review.state === 'CHANGES_REQUESTED') {
+                await github.rest.pulls.dismissReview({
+                  owner, repo, pull_number: pr_number, review_id: review.id,
+                  message: `Dismissed by Houston Override (${context.payload.comment.user.login})`
+                });
+              }
+            }
+
+            // Approve the PR
+            await github.rest.pulls.createReview({
+              owner, repo, pull_number: pr_number,
+              event: 'APPROVE',
+              body: `Houston Override by @${context.payload.comment.user.login}`
+            });