karajan-code 4.70.3 → 5.0.0

package/src/review/git-stash-helper.js

@@ -1,104 +0,0 @@
-// Surgical stash helper for the TDD discipline gate (KJC-TSK-0398 PR2).
-// Stashes only the source files we want to hide for the "red" run and
-// restores them afterwards. Tracked files use `git stash push -- <paths>`;
-// untracked files (not yet known to git) are moved aside to a private
-// `.karajan/tmp/stash-<id>/` tree because `git stash` would ignore them.
-
-import { mkdir, rename, rm } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { runCommand } from "../utils/process.js";
-
-function defaultRunner(cmd, args, opts) {
-  return runCommand(cmd, args, opts);
-}
-
-async function isTracked(runner, projectDir, file) {
-  const res = await runner("git", ["ls-files", "--error-unmatch", "--", file], { cwd: projectDir });
-  return res.exitCode === 0;
-}
-
-async function stashRefForToken(runner, projectDir, marker) {
-  const res = await runner("git", ["stash", "list"], { cwd: projectDir });
-  if (res.exitCode !== 0) return null;
-  for (const line of String(res.stdout || "").split("\n")) {
-    if (line.includes(marker)) {
-      const m = line.match(/^(stash@\{\d+\})/);
-      if (m) return m[1];
-    }
-  }
-  return null;
-}
-
-// Move `files` aside so a test run sees them as missing. Returns a token to
-// pass to `restoreFiles()`. Throws on failure with the partial token attached.
-export async function stashFilesAside(files, { projectDir = process.cwd(), runner = defaultRunner, tmpRoot } = {}) {
-  if (!Array.isArray(files) || files.length === 0) {
-    return { trackedStashRef: null, untrackedMoves: [], marker: null };
-  }
-  const tracked = [];
-  const untracked = [];
-  for (const f of files) {
-    if (await isTracked(runner, projectDir, f)) tracked.push(f);
-    else if (existsSync(resolve(projectDir, f))) untracked.push(f);
-  }
-
-  const marker = `kj-tdd-discipline-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-  const stashRoot = tmpRoot || join(projectDir, ".karajan", "tmp", marker);
-  const untrackedMoves = [];
-  let trackedStashRef = null;
-
-  if (tracked.length > 0) {
-    const args = ["stash", "push", "--keep-index", "-m", marker, "--", ...tracked];
-    const res = await runner("git", args, { cwd: projectDir });
-    if (res.exitCode !== 0) {
-      throw new Error(`git stash push failed: ${res.stderr || res.stdout}`);
-    }
-    trackedStashRef = await stashRefForToken(runner, projectDir, marker);
-  }
-
-  for (const f of untracked) {
-    const src = resolve(projectDir, f);
-    const dst = join(stashRoot, f);
-    await mkdir(dirname(dst), { recursive: true });
-    await rename(src, dst);
-    untrackedMoves.push({ src, dst });
-  }
-
-  return { trackedStashRef, untrackedMoves, marker, stashRoot };
-}
-
-// Reverse a `stashFilesAside` token. Idempotent: a restored token becomes a no-op.
-export async function restoreFiles(token, { projectDir = process.cwd(), runner = defaultRunner } = {}) {
-  if (!token || (token.trackedStashRef == null && token.untrackedMoves.length === 0)) return;
-
-  for (const { src, dst } of token.untrackedMoves) {
-    if (existsSync(dst)) {
-      await mkdir(dirname(src), { recursive: true });
-      await rename(dst, src);
-    }
-  }
-  if (token.stashRoot && existsSync(token.stashRoot)) {
-    await rm(token.stashRoot, { recursive: true, force: true });
-  }
-
-  if (token.trackedStashRef) {
-    const res = await runner("git", ["stash", "pop", token.trackedStashRef], { cwd: projectDir });
-    if (res.exitCode !== 0) {
-      throw new Error(`git stash pop failed: ${res.stderr || res.stdout}`);
-    }
-  }
-  token.trackedStashRef = null;
-  token.untrackedMoves = [];
-}
-
-// Run `body` with `files` stashed aside, always restoring them — even when
-// `body` throws. The TDD discipline stage wraps its "red" run with this.
-export async function withStashedFiles(files, body, opts = {}) {
-  const token = await stashFilesAside(files, opts);
-  try {
-    return await body(token);
-  } finally {
-    await restoreFiles(token, opts).catch(() => { /* swallow: surface body error */ });
-  }
-}

package/src/review/schema.js

@@ -1,31 +0,0 @@
-export function validateReviewResult(reviewResult) {
-  if (!reviewResult || typeof reviewResult !== "object") {
-    throw new TypeError("Reviewer output must be a JSON object");
-  }
-
-  if (typeof reviewResult.approved !== "boolean") {
-    throw new TypeError("Reviewer output missing boolean field: approved");
-  }
-
-  if (!Array.isArray(reviewResult.blocking_issues)) {
-    throw new TypeError("Reviewer output missing array field: blocking_issues");
-  }
-
-  if (!Array.isArray(reviewResult.non_blocking_suggestions)) {
-    reviewResult.non_blocking_suggestions = [];
-  }
-
-  if (typeof reviewResult.summary !== "string") {
-    reviewResult.summary = "";
-  }
-
-  if (typeof reviewResult.confidence !== "number") {
-    reviewResult.confidence = 0.5;
-  }
-
-  if (reviewResult.approved && reviewResult.blocking_issues.length > 0) {
-    throw new Error("Invalid reviewer output: approved=true with blocking issues");
-  }
-
-  return reviewResult;
-}

package/src/review/scope-filter.js

@@ -1,152 +0,0 @@
-/**
- * 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 = /^\+\+\+ b\/(.+)/.exec(line);
-    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?.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("", "If your current changes naturally address any of these, great. Otherwise, they will be tracked for future resolution.");
-
-  return lines.join("\n");
-}

package/src/review/snapshot-diff.js

@@ -1,122 +0,0 @@
-/**
- * Git-free diff generation using filesystem snapshots.
- *
- * Takes a snapshot of project files (path → content hash), then compares
- * a later snapshot to generate a unified diff. Works on any OS, no git needed.
- */
-
-import { readdir, readFile, stat } from "node:fs/promises";
-import { join, relative } from "node:path";
-import { createHash } from "node:crypto";
-
-const DEFAULT_IGNORE = new Set([
-  "node_modules", ".git", ".kj", ".karajan", "dist", "build",
-  ".next", ".nuxt", ".svelte-kit", "__pycache__", ".venv",
-  "coverage", ".nyc_output", ".reviews"
-]);
-
-const MAX_FILE_SIZE = 512 * 1024; // 512KB — skip large files
-
-/**
- * Scan a directory recursively and return a Map of relative path → content hash.
- * @param {string} rootDir
- * @returns {Promise<Map<string, string>>} path → sha256 hash
- */
-export async function takeSnapshot(rootDir) {
-  const snapshot = new Map();
-  await scanDir(rootDir, rootDir, snapshot);
-  return snapshot;
-}
-
-async function scanDir(dir, rootDir, snapshot) {
-  let entries;
-  try {
-    entries = await readdir(dir, { withFileTypes: true });
-  } catch { return; }
-
-  for (const entry of entries) {
-    if (DEFAULT_IGNORE.has(entry.name) || entry.name.startsWith(".")) continue;
-
-    const fullPath = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      await scanDir(fullPath, rootDir, snapshot);
-    } else if (entry.isFile()) {
-      try {
-        const s = await stat(fullPath);
-        if (s.size > MAX_FILE_SIZE) continue;
-        const content = await readFile(fullPath);
-        const hash = createHash("sha256").update(content).digest("hex");
-        snapshot.set(relative(rootDir, fullPath), hash);
-      } catch { /* skip unreadable files */ }
-    }
-  }
-}
-
-/**
- * Compare two snapshots and generate a unified diff string.
- * @param {Map<string, string>} before — snapshot before coder
- * @param {Map<string, string>|null} after — snapshot after coder (null = read from disk)
- * @param {string} rootDir — project root (for reading file contents)
- * @returns {Promise<string>} unified diff text
- */
-export async function generateSnapshotDiff(before, after, rootDir) {
-  if (!after) {
-    after = await takeSnapshot(rootDir);
-  }
-
-  const lines = [];
-
-  // New files (in after but not before)
-  for (const [path, _hash] of after) {
-    if (!before.has(path)) {
-      const content = await safeRead(join(rootDir, path));
-      if (content !== null) {
-        lines.push(`diff --snapshot a/${path} b/${path}`);
-        lines.push("new file");
-        lines.push(`--- /dev/null`);
-        lines.push(`+++ b/${path}`);
-        for (const line of content.split("\n")) {
-          lines.push(`+${line}`);
-        }
-        lines.push("");
-      }
-    }
-  }
-
-  // Modified files (in both, different hash)
-  for (const [path, hash] of after) {
-    if (before.has(path) && before.get(path) !== hash) {
-      const content = await safeRead(join(rootDir, path));
-      if (content !== null) {
-        lines.push(`diff --snapshot a/${path} b/${path}`);
-        lines.push("modified file");
-        lines.push(`--- a/${path}`);
-        lines.push(`+++ b/${path}`);
-        // Show full new content (we don't have the old content)
-        for (const line of content.split("\n")) {
-          lines.push(`+${line}`);
-        }
-        lines.push("");
-      }
-    }
-  }
-
-  // Deleted files (in before but not after)
-  for (const [path] of before) {
-    if (!after.has(path)) {
-      lines.push(`diff --snapshot a/${path} b/${path}`);
-      lines.push("deleted file");
-      lines.push(`--- a/${path}`);
-      lines.push(`+++ /dev/null`);
-      lines.push("");
-    }
-  }
-
-  return lines.join("\n");
-}
-
-async function safeRead(filePath) {
-  try {
-    return await readFile(filePath, "utf-8");
-  } catch { return null; }
-}

package/src/review/tdd-discipline.js

@@ -1,90 +0,0 @@
-// TDD discipline gate (KJC-TSK-0398 PR1).
-// PR1 ships the pure decision logic with injected runTests/stashFiles
-// helpers. PR2 ships the real surgical stash. PR3 wires the gate into
-// the pipeline behind `development.require_red_then_green`.
-
-const PARSERS = {
-  vitest: parseVitestFailures,
-  jest: parseVitestFailures,
-  pytest: parsePytestFailures,
-};
-
-function parseVitestFailures(output) {
-  const failures = new Set();
-  for (const line of String(output || "").split("\n")) {
-    const m = line.match(/^\s*(?:FAIL|×|✖)\s+(\S+)/);
-    if (m) failures.add(m[1].trim());
-  }
-  return failures;
-}
-
-function parsePytestFailures(output) {
-  const failures = new Set();
-  for (const line of String(output || "").split("\n")) {
-    const m = line.match(/^FAILED\s+(\S+)/);
-    if (m) failures.add(m[1].trim());
-  }
-  return failures;
-}
-
-function anyNewTestIn(failures, testFiles) {
-  return [...failures].some((f) => testFiles.some((t) => f.includes(t) || t.includes(f)));
-}
-
-export async function verifyTddDiscipline({
-  projectDir,
-  sourceFiles = [],
-  testFiles = [],
-  framework = null,
-  runTests,
-  stashFiles,
-  restoreFiles,
-} = {}) {
-  if (sourceFiles.length === 0) {
-    return { ok: true, reason: "no_source_changes", sourceFiles, testFiles };
-  }
-  if (testFiles.length === 0) {
-    return { ok: true, reason: "no_test_changes", sourceFiles, testFiles };
-  }
-
-  const parser = framework ? PARSERS[framework] : null;
-  if (!parser) {
-    return {
-      ok: true,
-      reason: "framework_unsupported",
-      sourceFiles,
-      testFiles,
-      warning: `tdd-discipline: framework "${framework || "unknown"}" has no failure parser; gate skipped`,
-    };
-  }
-
-  let stashToken = null;
-  try {
-    stashToken = await stashFiles(sourceFiles);
-    const before = await runTests(projectDir);
-    if (!anyNewTestIn(parser(before.output), testFiles)) {
-      return {
-        ok: false,
-        reason: "tests_pass_without_impl",
-        sourceFiles,
-        testFiles,
-        message:
-          "TDD discipline violation: new tests pass without the implementation. Tests must fail first (red), then pass (green).",
-      };
-    }
-  } finally {
-    if (stashToken) await restoreFiles(stashToken);
-  }
-
-  const after = await runTests(projectDir);
-  if (anyNewTestIn(parser(after.output), testFiles)) {
-    return {
-      ok: false,
-      reason: "tests_fail_with_impl",
-      sourceFiles,
-      testFiles,
-      message: "TDD discipline violation: new tests still fail with the implementation present.",
-    };
-  }
-  return { ok: true, reason: "red_then_green_verified", sourceFiles, testFiles };
-}

package/src/review/tdd-policy.js

@@ -1,69 +0,0 @@
-function extractChangedFiles(diff) {
-  const files = new Set();
-  const lines = String(diff || "").split("\n");
-  for (const line of lines) {
-    // Support both git diff and snapshot diff formats
-    if (!line.startsWith("diff --git ") && !line.startsWith("diff --snapshot ")) continue;
-    const parts = line.split(" ");
-    const b = parts[3] || "";
-    if (b.startsWith("b/")) files.add(b.slice(2));
-  }
-  return [...files];
-}
-
-function isTestFile(file, patterns = []) {
-  const normalized = `/${file}`;
-  return patterns.some((pattern) => normalized.includes(pattern));
-}
-
-function isSourceFile(file, extensions = []) {
-  return extensions.some((ext) => file.endsWith(ext));
-}
-
-const SKIP_TDD_TASK_TYPES = new Set(["doc", "infra", "no-code"]);
-
-const DEFAULT_TEST_PATTERNS = ["/tests/", "/__tests__/", ".test.", ".spec.", "/src/test/", "/test/", "Test.java", "Test.kt", "test_", "_test.py", "_test.go", "Test.cs", "_spec.rb", "Test.php", "_test.dart", "Tests.swift"];
-const DEFAULT_SOURCE_EXTENSIONS = [".js", ".jsx", ".ts", ".tsx", ".py", ".go", ".java", ".kt", ".rb", ".php", ".cs", ".rs", ".swift", ".dart"];
-
-export function evaluateTddPolicy(diff, developmentConfig = {}, untrackedFiles = [], taskType = null) {
-  if (taskType && SKIP_TDD_TASK_TYPES.has(taskType)) {
-    return { ok: true, reason: "tdd_not_applicable_for_task_type", sourceFiles: [], testFiles: [] };
-  }
-
-  const requireTestChanges = developmentConfig.require_test_changes !== false;
-  const patterns = developmentConfig.test_file_patterns || DEFAULT_TEST_PATTERNS;
-  const extensions = developmentConfig.source_file_extensions || DEFAULT_SOURCE_EXTENSIONS;
-
-  const diffFiles = extractChangedFiles(diff);
-  const extra = Array.isArray(untrackedFiles) ? untrackedFiles : [];
-  const files = [...new Set([...diffFiles, ...extra])];
-  const sourceFiles = files.filter((f) => isSourceFile(f, extensions) && !isTestFile(f, patterns));
-  const testFiles = files.filter((f) => isTestFile(f, patterns));
-
-  if (!requireTestChanges) {
-    return {
-      ok: true,
-      reason: "test_changes_not_required",
-      sourceFiles,
-      testFiles
-    };
-  }
-
-  if (sourceFiles.length === 0) {
-    const reason = files.length === 0 ? "no_diff_available" : "no_source_changes";
-    return { ok: true, reason, sourceFiles, testFiles };
-  }
-
-  if (testFiles.length === 0) {
-    return {
-      ok: false,
-      reason: "source_changes_without_tests",
-      sourceFiles,
-      testFiles,
-      message:
-        "TDD policy violation: source code changed without test changes. Add/adjust tests first, then implementation."
-    };
-  }
-
-  return { ok: true, reason: "tests_present", sourceFiles, testFiles };
-}

package/src/roles/acceptance-coverage-role.js

@@ -1,78 +0,0 @@
-// KJC-TSK-0987 (issue #1894): AcceptanceCoverageRole, the judge that reads each
-// acceptance criterion of the card against the diff before the run is approved.
-// Judged by a different AI than the coder (the reviewer's provider by default).
-// Role + helpers ship here; the stage wires it (same PR), the loops next.
-
-import { AgentRole } from "./agent-role.js";
-import { buildAcceptanceCoveragePrompt } from "../prompts/acceptance-coverage.js";
-import { extractFirstJson } from "../utils/json-extract.js";
-
-/**
- * The card's acceptance criteria as plain sentences, one per criterion.
- * Structured Given/When/Then first; else the free text, one per line or bullet.
- * @param {object|null} card
- * @returns {string[]}
- */
-export function criteriaOfCard(card) {
-  const structured = Array.isArray(card?.acceptanceCriteriaStructured) ? card.acceptanceCriteriaStructured : [];
-  const fromStructured = structured
-    .map((ac) => (ac?.given && ac?.when && ac?.then ? `Given ${ac.given}, when ${ac.when}, then ${ac.then}` : String(ac?.raw || "").trim()))
-    .filter(Boolean);
-  if (fromStructured.length > 0) return fromStructured;
-  return String(card?.acceptanceCriteria || "")
-    .split("\n")
-    .map((line) => line.replace(/^\s*(?:[-*•]|\d+[.)])\s*/, "").trim())
-    .filter(Boolean);
-}
-
-const normalizeVerdicts = (parsed, criteria) => criteria.map((text, i) => {
-  const v = Array.isArray(parsed?.criteria) ? parsed.criteria.find((c) => Number(c?.index) === i + 1) : null;
-  return {
-    index: i + 1,
-    text,
-    // No entry for a criterion is no evidence for it: not covered, never assumed.
-    covered: v ? Boolean(v.covered) : false,
-    evidence: typeof v?.evidence === "string" ? v.evidence.trim() : "",
-  };
-});
-
-export class AcceptanceCoverageRole extends AgentRole {
-  constructor(opts) {
-    super({ ...opts, name: "acceptance-coverage" });
-  }
-
-  // A different AI than the coder: the reviewer's, unless the role has its own.
-  resolveProvider() {
-    return this.config?.roles?.["acceptance-coverage"]?.provider
-      || this.config?.roles?.reviewer?.provider
-      || this.config?.reviewer
-      || "codex";
-  }
-
-  extractInput(input) {
-    return { ...super.extractInput(input), criteria: Array.isArray(input?.criteria) ? input.criteria : [], diff: String(input?.diff || "") };
-  }
-
-  async buildPrompt({ task, criteria, diff }) {
-    this._criteria = criteria;
-    return { prompt: buildAcceptanceCoveragePrompt({ criteria, diff, task, instructions: this.instructions }) };
-  }
-
-  parseOutput(raw) { return extractFirstJson(raw); }
-
-  // A verdict with no `criteria` array is not a verdict: the reviewer's failure.
-  isSuccessful(parsed) { return Array.isArray(parsed?.criteria); }
-
-  buildSuccessResult(parsed, provider) {
-    const criteria = normalizeVerdicts(parsed, this._criteria || []);
-    const uncovered = criteria.filter((c) => !c.covered);
-    return { criteria, uncovered, provider, error: Array.isArray(parsed?.criteria) ? undefined : "no criteria array in the verdict" };
-  }
-
-  buildSummary(parsed) {
-    if (!Array.isArray(parsed?.criteria)) return "acceptance-coverage: unreadable verdict (no criteria array)";
-    const total = (this._criteria || []).length;
-    const uncovered = normalizeVerdicts(parsed, this._criteria || []).filter((c) => !c.covered).length;
-    return uncovered === 0 ? `acceptance-coverage: ${total}/${total} criteria covered` : `acceptance-coverage: ${uncovered} of ${total} criteria NOT covered`;
-  }
-}