karajan-code 1.11.1 → 1.12.0

package/package.json

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