karajan-code 1.11.0 → 1.12.0

package/README.md

@@ -30,7 +30,7 @@ Instead of running one AI agent and manually reviewing its output, `kj` chains a
 **Key features:**
 - **Multi-agent pipeline** with 11 configurable roles
 - **4 AI agents supported**: Claude, Codex, Gemini, Aider
-- **MCP server** with 11 tools — use `kj` from Claude, Codex, or any MCP-compatible host without leaving your agent. [See MCP setup](#mcp-server)
+- **MCP server** with 15 tools — use `kj` from Claude, Codex, or any MCP-compatible host without leaving your agent. [See MCP setup](#mcp-server)
 - **TDD enforcement** — test changes required when source files change
 - **SonarQube integration** — static analysis with quality gate enforcement (requires [Docker](#requirements))
 - **Review profiles** — standard, strict, relaxed, paranoid
@@ -44,6 +44,9 @@ Instead of running one AI agent and manually reviewing its output, `kj` chains a
 - **Retry with backoff** — automatic recovery from transient API errors (429, 5xx) with exponential backoff and jitter
 - **Pipeline stage tracker** — cumulative progress view during `kj_run` showing which stages are done, running, or pending — both in CLI and via MCP events for real-time host rendering
 - **Planner observability guardrails** — continuous heartbeat/stall telemetry, configurable max-silence protection (`session.max_agent_silence_minutes`), and hard runtime cap (`session.max_planner_minutes`) to avoid long stuck planner runs
+- **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
 - **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.
@@ -62,16 +65,16 @@ triage? ─> researcher? ─> planner? ─> coder ─> refactorer? ─> sonar?
 
 | Role | Description | Default |
 |------|-------------|---------|
-| **triage** | Classifies task complexity (trivial/simple/medium/complex) and activates only necessary roles | Off |
+| **triage** | Pipeline director — analyzes task complexity and activates roles dynamically | **On** |
 | **researcher** | Investigates codebase context before planning | Off |
 | **planner** | Generates structured implementation plans | Off |
 | **coder** | Writes code and tests following TDD methodology | **Always on** |
 | **refactorer** | Improves code clarity without changing behavior | Off |
 | **sonar** | Runs SonarQube static analysis and quality gate checks | On (if configured) |
 | **reviewer** | Code review with configurable strictness profiles | **Always on** |
-| **tester** | Test quality gate and coverage verification | Off |
-| **security** | OWASP security audit | Off |
-| **solomon** | Conflict resolver when coder and reviewer disagree | Off |
+| **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** |
 | **commiter** | Git commit, push, and PR automation after approval | Off |
 
 Roles marked with `?` are optional and can be enabled per-run or via config.
@@ -272,6 +275,16 @@ Resume a paused session (e.g., after fail-fast).
 kj resume s_2026-02-28T20-47-24-270Z --answer "yes, proceed with the fix"
 ```
 
+### `kj agents`
+
+List or change AI agent assignments per role.
+
+```bash
+kj agents                       # List current agents (with scope column)
+kj agents set coder gemini      # Set coder to gemini (project scope)
+kj agents set reviewer claude --global  # Set reviewer globally
+```
+
 ### `kj roles`
 
 Inspect pipeline roles and their template instructions.
@@ -416,9 +429,12 @@ After `npm install -g karajan-code`, the MCP server is auto-registered in Claude
 | `kj_resume` | Resume a paused session |
 | `kj_report` | Read session reports (supports `--trace`) |
 | `kj_roles` | List roles or show role templates |
-| `kj_code` | Run coder-only mode |
-| `kj_review` | Run reviewer-only mode |
-| `kj_plan` | Generate implementation plan with heartbeat/stall telemetry and clearer diagnostics |
+| `kj_agents` | List or change agent assignments (session/project/global scope) |
+| `kj_preflight` | Human confirms agent config before kj_run/kj_code executes |
+| `kj_code` | Run coder-only mode (with progress notifications) |
+| `kj_review` | Run reviewer-only mode (with progress notifications) |
+| `kj_plan` | Generate implementation plan (with progress notifications) |
+| `kj_status` | Live parsed status of current run (stage, agent, iteration, errors) |
 
 ### MCP restart after version updates
 
@@ -461,7 +477,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 1040+ tests with Vitest
+npm test              # Run 1180+ tests with Vitest
 npm run test:watch    # Watch mode
 npm run validate      # Lint + test
 ```

package/docs/README.es.md

@@ -30,7 +30,7 @@ En lugar de ejecutar un agente de IA y revisar manualmente su output, `kj` encad
 **Caracteristicas principales:**
 - **Pipeline multi-agente** con 11 roles configurables
 - **4 agentes de IA soportados**: Claude, Codex, Gemini, Aider
-- **Servidor MCP** con 11 herramientas — usa `kj` desde Claude, Codex o cualquier host compatible con MCP sin salir de tu agente. [Ver configuracion MCP](#servidor-mcp)
+- **Servidor MCP** con 15 herramientas — usa `kj` desde Claude, Codex o cualquier host compatible con MCP sin salir de tu agente. [Ver configuracion MCP](#servidor-mcp)
 - **TDD obligatorio** — se exigen cambios en tests cuando se modifican ficheros fuente
 - **Integracion con SonarQube** — analisis estatico con quality gates (requiere [Docker](#requisitos))
 - **Perfiles de revision** — standard, strict, relaxed, paranoid
@@ -43,6 +43,9 @@ En lugar de ejecutar un agente de IA y revisar manualmente su output, `kj` encad
 - **Retry con backoff** — recuperacion automatica ante errores transitorios de API (429, 5xx) con backoff exponencial y jitter
 - **Pipeline stage tracker** — vista de progreso acumulativo durante `kj_run` mostrando que stages estan completadas, en ejecucion o pendientes — tanto en CLI como via eventos MCP para renderizado en tiempo real en el host
 - **Guardarrailes de observabilidad del planner** — telemetria continua de heartbeat/stall, proteccion configurable por silencio maximo (`session.max_agent_silence_minutes`) y limite duro de ejecucion (`session.max_planner_minutes`) para evitar bloqueos prolongados en `kj_plan`/planner
+- **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`
 - **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.
@@ -61,16 +64,16 @@ triage? ─> researcher? ─> planner? ─> coder ─> refactorer? ─> sonar?
 
 | Rol | Descripcion | Por defecto |
 |-----|-------------|-------------|
-| **triage** | Clasifica la complejidad de la tarea (trivial/simple/media/compleja) y activa solo los roles necesarios | Off |
+| **triage** | Director de pipeline — analiza la complejidad y activa roles dinamicamente | **On** |
 | **researcher** | Investiga el contexto del codebase antes de planificar | Off |
 | **planner** | Genera planes de implementacion estructurados | Off |
 | **coder** | Escribe codigo y tests siguiendo metodologia TDD | **Siempre activo** |
 | **refactorer** | Mejora la claridad del codigo sin cambiar comportamiento | Off |
 | **sonar** | Ejecuta analisis estatico SonarQube y quality gates | On (si configurado) |
 | **reviewer** | Revision de codigo con perfiles de exigencia configurables | **Siempre activo** |
-| **tester** | Quality gate de tests y verificacion de cobertura | Off |
-| **security** | Auditoria de seguridad OWASP | Off |
-| **solomon** | Resolutor de conflictos cuando coder y reviewer discrepan | Off |
+| **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** |
 | **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.0",
+  "version": "1.12.0",
   "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

@@ -101,10 +101,20 @@ function pickOutput(res) {
   return res.stdout || res.stderr || "";
 }
 
+/**
+ * Default tools to allow for Claude subprocess.
+ * Since claude -p runs non-interactively (stdin: "ignore"), it cannot ask for
+ * permission approval.  Without --allowedTools, it blocks waiting for approval
+ * that never comes.
+ */
+const ALLOWED_TOOLS = [
+  "Read", "Write", "Edit", "Bash", "Glob", "Grep"
+];
+
 export class ClaudeAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
-    const args = ["-p", task.prompt];
+    const args = ["-p", task.prompt, "--allowedTools", ...ALLOWED_TOOLS];
     const model = this.getRoleModel(role);
     if (model) args.push("--model", model);
 
@@ -131,7 +141,7 @@ export class ClaudeAgent extends BaseAgent {
   }
 
   async reviewTask(task) {
-    const args = ["-p", task.prompt, "--output-format", "stream-json"];
+    const args = ["-p", task.prompt, "--allowedTools", ...ALLOWED_TOOLS, "--output-format", "stream-json"];
     const model = this.getRoleModel(task.role || "reviewer");
     if (model) args.push("--model", model);
     const res = await runCommand(resolveBin("claude"), args, cleanExecaOpts({

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,
@@ -489,6 +491,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 +553,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,

package/src/orchestrator/solomon-rules.js

@@ -7,7 +7,8 @@ const DEFAULT_RULES = {
   max_files_per_iteration: 10,
   max_stale_iterations: 3,
   no_new_dependencies_without_task: true,
-  scope_guard: true
+  scope_guard: true,
+  reviewer_overreach: true
 };
 
 export function evaluateRules(context, rulesConfig = {}) {
@@ -59,6 +60,17 @@ export function evaluateRules(context, rulesConfig = {}) {
     });
   }
 
+  // Rule 5: Reviewer overreach — reviewer consistently flags out-of-scope issues
+  if (rules.reviewer_overreach && context.reviewerDemotedCount > 0) {
+    const severity = context.reviewerDemotedCount >= 3 ? "critical" : "warn";
+    alerts.push({
+      rule: "reviewer_overreach",
+      severity,
+      message: `Reviewer flagged ${context.reviewerDemotedCount} out-of-scope issue(s) that were auto-demoted by scope filter.`,
+      detail: { demotedCount: context.reviewerDemotedCount, autoApproved: context.reviewerAutoApproved || false }
+    });
+  }
+
   return {
     alerts,
     hasCritical: alerts.some(a => a.severity === "critical"),
@@ -76,9 +88,20 @@ export async function buildRulesContext({ session, task, iteration }) {
     filesChanged: 0,
     staleIterations: 0,
     newDependencies: [],
-    outOfScopeFiles: []
+    outOfScopeFiles: [],
+    reviewerDemotedCount: 0,
+    reviewerAutoApproved: false
   };
 
+  // Count reviewer scope-filter demotions from session checkpoints
+  const scopeFilterCheckpoints = (session.checkpoints || [])
+    .filter(cp => cp.stage === "reviewer-scope-filter");
+  if (scopeFilterCheckpoints.length > 0) {
+    const latest = scopeFilterCheckpoints.at(-1);
+    context.reviewerDemotedCount = latest.demoted_count || 0;
+    context.reviewerAutoApproved = latest.auto_approved || false;
+  }
+
   // Count files changed via git
   try {
     const { execaCommand } = await import("execa");

package/src/orchestrator.js

@@ -152,7 +152,8 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
     last_sonar_issue_signature: null,
     sonar_repeat_count: 0,
     last_reviewer_issue_signature: null,
-    reviewer_repeat_count: 0
+    reviewer_repeat_count: 0,
+    deferred_issues: []
   };
   if (pgTaskId) sessionInit.pg_task_id = pgTaskId;
   if (pgProject) sessionInit.pg_project_id = pgProject;
@@ -496,7 +497,7 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
     if (reviewerEnabled) {
       const reviewerResult = await runReviewerStage({
         reviewerRole, config, logger, emitter, eventBase, session, trackBudget,
-        iteration: i, reviewRules, task, repeatDetector, budgetSummary
+        iteration: i, reviewRules, task, repeatDetector, budgetSummary, askQuestion
       });
       if (reviewerResult.action === "pause") {
         return reviewerResult.result;
@@ -649,14 +650,17 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
         }
       }
 
+      const deferredIssues = session.deferred_issues || [];
       emitProgress(
         emitter,
         makeEvent("session:end", { ...eventBase, stage: "done" }, {
-          message: "Session approved",
-          detail: { approved: true, iterations: i, stages: stageResults, git: gitResult, budget: budgetSummary() }
+          message: deferredIssues.length > 0
+            ? `Session approved (${deferredIssues.length} deferred issue(s) tracked as tech debt)`
+            : "Session approved",
+          detail: { approved: true, iterations: i, stages: stageResults, git: gitResult, budget: budgetSummary(), deferredIssues }
         })
       );
-      return { approved: true, sessionId: session.id, review, git: gitResult };
+      return { approved: true, sessionId: session.id, review, git: gitResult, deferredIssues };
     }
 
     session.last_reviewer_feedback = review.blocking_issues

package/src/prompts/coder.js

@@ -29,7 +29,7 @@ const SERENA_INSTRUCTIONS = [
   "Fall back to reading files only when Serena tools are not sufficient."
 ].join("\n");
 
-export function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false }) {
+export function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, deferredContext = null }) {
   const sections = [
     serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE,
     `Task:\n${task}`,
@@ -65,5 +65,9 @@ export function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary =
     sections.push(`Reviewer blocking feedback:\n${reviewerFeedback}`);
   }
 
+  if (deferredContext) {
+    sections.push(deferredContext);
+  }
+
   return sections.join("\n\n");
 }

package/src/prompts/reviewer.js

@@ -26,6 +26,8 @@ export function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabl
   const sections = [
     serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE,
     `You are a code reviewer in ${mode} mode.`,
+    "CRITICAL SCOPE RULE: Only review changes that are part of the diff below. Do NOT flag issues in unchanged code, missing features planned for future tasks, or improvements outside the scope of this task. If the diff is correct for what the task asks, approve it — even if the broader codebase has other issues.",
+    "Only block approval for issues IN THE DIFF that are bugs, security vulnerabilities, or clear violations of the review rules.",
     "Return only one valid JSON object and nothing else.",
     "JSON schema:",
     '{"approved":boolean,"blocking_issues":[{"id":string,"severity":"critical|high|medium|low","file":string,"line":number,"description":string,"suggested_fix":string}],"non_blocking_suggestions":[string],"summary":string,"confidence":number}'

package/src/review/scope-filter.js

@@ -0,0 +1,153 @@
+/**
+ * Scope filter — auto-defers reviewer blocking issues that reference
+ * files NOT present in the diff.  This prevents reviewer scope drift
+ * (flagging missing features, unchanged code, future tasks) from
+ * stalling the pipeline.
+ *
+ * Deferred issues are NOT forgotten — they are tracked in the session
+ * as technical debt that should be resolved in future iterations or
+ * follow-up tasks.  The coder and planner receive context about what
+ * was deferred and why.
+ */
+
+/**
+ * Extract the set of changed file paths from a unified diff string.
+ */
+export function extractDiffFiles(diff) {
+  const files = new Set();
+  for (const line of (diff || "").split("\n")) {
+    // Match "+++ b/path" lines in unified diff
+    const m = line.match(/^\+\+\+ b\/(.+)/);
+    if (m) files.add(m[1]);
+  }
+  return files;
+}
+
+/**
+ * Determine whether a blocking issue is within scope of the diff.
+ *
+ * An issue is considered IN scope when:
+ * - It has no `file` field (general concern about the diff)
+ * - Its `file` matches one of the changed files (exact or suffix match)
+ * - It references a pattern present in the diff content itself
+ *
+ * An issue is OUT of scope when:
+ * - It explicitly references a file NOT in the diff
+ */
+export function isIssueInScope(issue, diffFiles, diffContent) {
+  const file = (issue.file || "").trim();
+
+  // No file specified — the reviewer is commenting on the diff generally
+  if (!file) return true;
+
+  // Direct match
+  if (diffFiles.has(file)) return true;
+
+  // Suffix match (reviewer might use full path vs relative)
+  for (const df of diffFiles) {
+    if (df.endsWith(file) || file.endsWith(df)) return true;
+  }
+
+  // Check if the file path appears anywhere in the diff content
+  // (covers cases where the file is referenced in imports/requires)
+  if (diffContent && diffContent.includes(file)) return true;
+
+  return false;
+}
+
+/**
+ * Filter a review result, demoting out-of-scope blocking issues to
+ * non-blocking suggestions.
+ *
+ * Returns { review, demoted, deferred, allDemoted } where:
+ * - review: the filtered review (may flip approved to true)
+ * - demoted: array of original issues that were demoted
+ * - deferred: structured deferred issues with metadata for session tracking
+ * - allDemoted: true if ALL blocking issues were out of scope
+ */
+export function filterReviewScope(review, diff) {
+  if (!review || review.approved) {
+    return { review, demoted: [], deferred: [], allDemoted: false };
+  }
+
+  const diffFiles = extractDiffFiles(diff);
+
+  // If we can't parse diff files, don't filter (safety)
+  if (diffFiles.size === 0) {
+    return { review, demoted: [], deferred: [], allDemoted: false };
+  }
+
+  const inScope = [];
+  const demoted = [];
+
+  for (const issue of review.blocking_issues || []) {
+    if (isIssueInScope(issue, diffFiles, diff)) {
+      inScope.push(issue);
+    } else {
+      demoted.push(issue);
+    }
+  }
+
+  if (demoted.length === 0) {
+    return { review, demoted: [], deferred: [], allDemoted: false };
+  }
+
+  const demotedSuggestions = demoted.map(
+    (issue) => `[auto-demoted] ${issue.file || "unknown"}: ${issue.description || issue.id || "no description"}`
+  );
+
+  const filtered = {
+    ...review,
+    blocking_issues: inScope,
+    non_blocking_suggestions: [
+      ...(review.non_blocking_suggestions || []),
+      ...demotedSuggestions
+    ]
+  };
+
+  // If no in-scope blocking issues remain, auto-approve
+  const allDemoted = inScope.length === 0;
+  if (allDemoted) {
+    filtered.approved = true;
+    filtered.summary = `${review.summary || ""} [Auto-approved: ${demoted.length} out-of-scope issue(s) demoted to suggestions]`.trim();
+  }
+
+  // Build structured deferred issues for session tracking
+  const deferred = demoted.map((issue) => ({
+    id: issue.id || null,
+    file: issue.file || null,
+    severity: issue.severity || "medium",
+    description: issue.description || "no description",
+    suggested_fix: issue.suggested_fix || null,
+    deferred_at: new Date().toISOString(),
+    reason: "out_of_scope"
+  }));
+
+  return { review: filtered, demoted, deferred, allDemoted };
+}
+
+/**
+ * Build a human-readable summary of deferred issues for injection
+ * into coder/planner prompts so they are aware of the tech debt.
+ */
+export function buildDeferredContext(deferredIssues) {
+  if (!deferredIssues?.length) return "";
+
+  const lines = [
+    "## Deferred reviewer concerns (technical debt)",
+    "The following issues were flagged by the reviewer but deferred because they are outside the current diff scope.",
+    "You do NOT need to fix them now, but be aware of them:",
+    ""
+  ];
+
+  for (const issue of deferredIssues) {
+    const file = issue.file ? `\`${issue.file}\`` : "general";
+    const fix = issue.suggested_fix ? ` — Suggestion: ${issue.suggested_fix}` : "";
+    lines.push(`- [${issue.severity}] ${file}: ${issue.description}${fix}`);
+  }
+
+  lines.push("");
+  lines.push("If your current changes naturally address any of these, great. Otherwise, they will be tracked for future resolution.");
+
+  return lines.join("\n");
+}

package/src/roles/coder-role.js

@@ -17,8 +17,8 @@ export class CoderRole extends BaseRole {
   }
 
   async execute(input) {
-    const { task, reviewerFeedback, sonarSummary, onOutput } = typeof input === "string"
-      ? { task: input, reviewerFeedback: null, sonarSummary: null, onOutput: null }
+    const { task, reviewerFeedback, sonarSummary, deferredContext, onOutput } = typeof input === "string"
+      ? { task: input, reviewerFeedback: null, sonarSummary: null, deferredContext: null, onOutput: null }
       : input || {};
 
     const provider = resolveProvider(this.config);
@@ -28,6 +28,7 @@ export class CoderRole extends BaseRole {
       task: task || this.context?.task || "",
       reviewerFeedback: reviewerFeedback || null,
       sonarSummary: sonarSummary || null,
+      deferredContext: deferredContext || null,
       coderRules: this.instructions,
       methodology: this.config?.development?.methodology || "tdd",
       serenaEnabled: Boolean(this.config?.serena?.enabled)