karajan-code 2.7.4 → 2.9.0

package/src/roles/tester-role.js

@@ -48,16 +48,26 @@ export class TesterRole extends AgentRole {
   }
 
   extractInput(input) {
-    if (typeof input === "string") return { task: input, diff: null, sonarIssues: null };
+    if (typeof input === "string") return { task: input, diff: null, sonarIssues: null, pendingGherkinTests: null, shellTestResults: null };
     return {
       task: input?.task || this.context?.task || "",
       diff: input?.diff || null,
       sonarIssues: input?.sonarIssues || null,
+      // Tests-first Phase 3 (v2.7.5): the tester now has two extra inputs.
+      //   - pendingGherkinTests: HU-declared Gherkin scenarios that need
+      //     translation into executable code tests in the project's
+      //     framework. The tester writes the test files and includes them
+      //     in the suite run before computing verdict.
+      //   - shellTestResults: results of running the HU's shell-type
+      //     acceptance_tests (already run upstream, passed at this point).
+      //     Passed for context so the tester doesn't re-run them redundantly.
+      pendingGherkinTests: input?.pendingGherkinTests || null,
+      shellTestResults: input?.shellTestResults || null,
       onOutput: input?.onOutput || null
     };
   }
 
-  async buildPrompt({ task, diff, sonarIssues }) {
+  async buildPrompt({ task, diff, sonarIssues, pendingGherkinTests, shellTestResults }) {
     const projectDir = this.config?.projectDir || process.cwd();
     const detection = await detectTestFramework(projectDir);
 
@@ -97,14 +107,65 @@ export class TesterRole extends AgentRole {
       );
     }
 
+    // Tests-first Phase 3 (v2.7.5): include the upstream shell-test results
+    // so the tester knows which part of the contract is already green.
+    if (Array.isArray(shellTestResults) && shellTestResults.length > 0) {
+      const passedCount = shellTestResults.filter((r) => r.passed).length;
+      sections.push(
+        "## Acceptance gate — shell tests",
+        `The HU's shell-type acceptance_tests already ran upstream: ${passedCount}/${shellTestResults.length} passed.`,
+        "Do NOT re-run them. Use the coverage/translation steps below to decide your verdict."
+      );
+    }
+
+    // Gherkin translation block — only when the HU carries Gherkin
+    // scenarios. Tester must produce real test files (in the detected
+    // framework's language) that encode Given/When/Then. This is how
+    // behaviour-level specs become enforceable.
+    if (Array.isArray(pendingGherkinTests) && pendingGherkinTests.length > 0) {
+      sections.push(
+        "## Gherkin acceptance tests to translate",
+        "These Gherkin scenarios are the HU's behavioural contract. They are NOT yet",
+        "executable — your job is to turn each one into a concrete test case in the",
+        "project's test framework, WRITE the test files, and INCLUDE them in the suite",
+        "run that determines your verdict.",
+        "",
+        "For each scenario below:",
+        "1. Pick the appropriate test file (use `target` hint if present; otherwise",
+        "   put the test next to the module it exercises).",
+        "2. Write a test that asserts the Given/When/Then as-is. Do NOT soften the",
+        "   assertion — if it's ambiguous, pick the stricter reading.",
+        "3. Make sure the test runs as part of the normal suite (no separate invocation).",
+        "",
+        "If ANY translated test fails on the current code, return verdict: \"fail\" with",
+        "a failing_scenarios array listing the scenarios that didn't pass. The coder",
+        "will iterate.",
+        ""
+      );
+      pendingGherkinTests.forEach((entry, i) => {
+        const content = typeof entry === "string" ? entry : entry?.content || "";
+        const target = entry && entry.file ? ` · target: \`${entry.file}\`` : "";
+        sections.push(
+          `### Scenario ${i + 1}${target}`,
+          "```gherkin",
+          content,
+          "```",
+          ""
+        );
+      });
+    }
+
     sections.push(
       "",
       "Return ONLY a single valid JSON object:",
-      '{"tests_pass":boolean,"coverage":{"overall":number,"services":number,"utilities":number},"missing_scenarios":[string],"quality_issues":[string],"verdict":"pass"|"fail"}',
+      '{"tests_pass":boolean,"coverage":{"overall":number,"services":number,"utilities":number},"missing_scenarios":[string],"quality_issues":[string],"failing_scenarios":[string],"translated_scenarios":[string],"verdict":"pass"|"fail"}',
       "",
       "- coverage.overall MUST be a real number from the test runner output, NOT an estimate",
       "- If coverage tool is not available, set coverage.overall to null (not 0, not a guess)",
       "- tests_pass must reflect whether the actual test run succeeded",
+      "- failing_scenarios: when Gherkin was given, list the scenarios your translated tests CAUGHT as failing",
+      "- translated_scenarios: when Gherkin was given, list the scenarios you successfully turned into passing tests",
+      "- verdict MUST be \"fail\" if any translated scenario still fails (even if coverage is green)",
       `## Task\n${task}`
     );
     if (diff) sections.push(`## Git diff\n${diff}`);
@@ -136,6 +197,9 @@ export class TesterRole extends AgentRole {
       coverage: parsed.coverage || {},
       missing_scenarios: parsed.missing_scenarios || [],
       quality_issues: parsed.quality_issues || [],
+      // Tests-first Phase 3: Gherkin translation outcomes.
+      failing_scenarios: Array.isArray(parsed.failing_scenarios) ? parsed.failing_scenarios : [],
+      translated_scenarios: Array.isArray(parsed.translated_scenarios) ? parsed.translated_scenarios : [],
       verdict,
       provider
     };
@@ -147,6 +211,8 @@ export class TesterRole extends AgentRole {
     const coverageStr = coverage.overall != null ? `${coverage.overall}%` : "not measured";
     const missingPart = parsed.missing_scenarios?.length ? `; ${parsed.missing_scenarios.length} missing scenario(s)` : "";
     const qualityPart = parsed.quality_issues?.length ? `; ${parsed.quality_issues.length} quality issue(s)` : "";
-    return `Verdict: ${verdict}; Coverage: ${coverageStr}${missingPart}${qualityPart}`;
+    const failingPart = parsed.failing_scenarios?.length ? `; ${parsed.failing_scenarios.length} failing scenario(s)` : "";
+    const translatedPart = parsed.translated_scenarios?.length ? `; ${parsed.translated_scenarios.length} scenario(s) translated` : "";
+    return `Verdict: ${verdict}; Coverage: ${coverageStr}${translatedPart}${failingPart}${missingPart}${qualityPart}`;
   }
 }

package/src/session/mutators.js

@@ -0,0 +1,304 @@
+/**
+ * Session mutators — the single site where the orchestrator mutates a
+ * session object in memory.
+ *
+ * Rationale (TSK-0337, KJC-PCS-0040 Oleada 3): pre-v2.7.5 there were ~68
+ * direct `session.x = value` assignments scattered across 18 files, with
+ * one file (flow-runner.js) alone accounting for 142 touches. The audit
+ * called this out as a HIGH finding: when a reviewer-retry bug landed in
+ * production, a maintainer had to grep the whole tree to find every site
+ * that writes to `session.last_reviewer_feedback` or
+ * `session.reviewer_retry_count`.
+ *
+ * The mutators below are intentionally **mechanical** — each wraps a
+ * single assignment — so the migration from `session.x = y` to
+ * `setX(session, y)` is pure plumbing and preserves exact existing
+ * semantics. The value is NOT validation or side-effects; it's that
+ * grepping `setReviewerFeedback(` finds every writer in seconds. Adding
+ * validation, event emission or persistence hooks later becomes a
+ * one-liner inside the mutator rather than a tree-wide edit.
+ *
+ * Complementary architecture test:
+ *   tests/architecture/session-write-boundary.test.js
+ * enforces a budget on the remaining direct `session.x = y` assignments
+ * outside `src/session/`. The budget only decreases; any new direct
+ * assignment requires either going through a mutator or explicit audit.
+ *
+ * Naming convention:
+ *   - setX          — overwrite field X with a new value.
+ *   - incrementX    — numeric +1 (returns the new value).
+ *   - resetX        — numeric 0 or null.
+ *   - clearX        — delete the field entirely (when `in` matters).
+ *   - appendToX     — push onto an array field.
+ *   - assignX       — shallow-merge object into an object field.
+ *
+ * No mutator persists the session — callers are still responsible for
+ * `await saveSession(session)` afterwards. This keeps the mutator
+ * functions synchronous and cheap.
+ */
+
+// --- Retry counters -------------------------------------------------------
+
+export const RETRY_KINDS = Object.freeze([
+  "reviewer",
+  "sonar",
+  "tester",
+  "security",
+  "standby",
+  "repeated_issue",
+  "auto_resume",
+  "checkpoint_stall",
+]);
+
+const RETRY_FIELD = {
+  reviewer: "reviewer_retry_count",
+  sonar: "sonar_retry_count",
+  tester: "tester_retry_count",
+  security: "security_retry_count",
+  standby: "standby_retry_count",
+  repeated_issue: "repeated_issue_count",
+  auto_resume: "auto_resume_count",
+  checkpoint_stall: "_checkpoint_stall_count",
+};
+
+export function setRetryCount(session, kind, value) {
+  const field = RETRY_FIELD[kind];
+  if (!field) throw new Error(`setRetryCount: unknown retry kind "${kind}"`);
+  session[field] = Number(value) || 0;
+  return session[field];
+}
+
+export function incrementRetryCount(session, kind) {
+  const field = RETRY_FIELD[kind];
+  if (!field) throw new Error(`incrementRetryCount: unknown retry kind "${kind}"`);
+  session[field] = (session[field] || 0) + 1;
+  return session[field];
+}
+
+export function resetRetryCount(session, kind) {
+  return setRetryCount(session, kind, 0);
+}
+
+/**
+ * Reset all well-known retry/repeat counters to 0. Called at the top of
+ * every resume path so a resumed session doesn't inherit the previous
+ * run's stall state.
+ */
+export function resetAllRetryCounters(session) {
+  for (const kind of RETRY_KINDS) {
+    // Skip checkpoint_stall: it's internal state owned by flow-control,
+    // not something resume should touch.
+    if (kind === "checkpoint_stall") continue;
+    setRetryCount(session, kind, 0);
+  }
+}
+
+// --- Feedback -------------------------------------------------------------
+
+export function setReviewerFeedback(session, text) {
+  session.last_reviewer_feedback = text;
+}
+
+export function appendReviewerFeedback(session, text) {
+  session.last_reviewer_feedback = session.last_reviewer_feedback
+    ? `${session.last_reviewer_feedback}\n${text}`
+    : text;
+}
+
+export function setSonarSummary(session, text) {
+  session.last_sonar_summary = text;
+}
+
+export function setSonarIssueSignature(session, sig) {
+  session.last_sonar_issue_signature = sig;
+}
+
+export function setReviewerIssueSignature(session, sig) {
+  session.last_reviewer_issue_signature = sig;
+}
+
+// Issue-signature repetition counters (distinct from retry_count:
+// reset only when the signature changes, not every iteration).
+export function setSonarRepeatCount(session, value) {
+  session.sonar_repeat_count = Number(value) || 0;
+}
+export function setReviewerRepeatCount(session, value) {
+  session.reviewer_repeat_count = Number(value) || 0;
+}
+
+// --- Status ---------------------------------------------------------------
+
+/**
+ * In-memory status change. The persisting variant is `markSessionStatus` in
+ * store.js, which also writes to disk; `setStatus` is for transient mutations
+ * inside the runner (e.g. standby enter/exit) where the caller persists
+ * later via `saveSession`.
+ */
+export function setStatus(session, status) {
+  session.status = status;
+}
+
+// --- Alternative agent (rate-limit recovery) ------------------------------
+
+export function setAlternativeAgent(session, stage, provider) {
+  session._alternative_agent = { stage, provider };
+}
+
+export function clearAlternativeAgent(session) {
+  delete session._alternative_agent;
+}
+
+// --- Standby state --------------------------------------------------------
+
+export function setStandby(session, { agent, cooldownMs, cooldownUntil }) {
+  session.standby_agent = agent;
+  session.standby_cooldown_ms = cooldownMs;
+  session.standby_cooldown_until = cooldownUntil;
+}
+
+export function clearStandby(session) {
+  delete session.standby_agent;
+  delete session.standby_cooldown_ms;
+  delete session.standby_cooldown_until;
+}
+
+// --- CI state -------------------------------------------------------------
+
+export function setCiEarlyPr(session, { prNumber, prUrl, commits }) {
+  session.ci_pr_number = prNumber;
+  session.ci_pr_url = prUrl;
+  session.ci_commits = commits;
+}
+
+export function appendCiCommits(session, commits) {
+  session.ci_commits = [...(session.ci_commits ?? []), ...commits];
+}
+
+// --- Pre-loop & policy metadata -------------------------------------------
+
+export function setPreflight(session, result) {
+  session.preflight = result;
+}
+
+export function setResolvedPolicies(session, policies) {
+  session.resolved_policies = policies;
+}
+
+export function setPgCard(session, card) {
+  session.pg_card = card;
+}
+
+export function setPgTaskId(session, id) {
+  session.pg_task_id = id;
+}
+
+export function appendPgCommits(session, commits) {
+  session.pg_commits = [...(session.pg_commits ?? []), ...commits];
+}
+
+export function setPreLoopContext(session, { research, architect, plan }) {
+  if (research !== undefined) session.research_context = research;
+  if (architect !== undefined) session.architect_context = architect;
+  if (plan !== undefined) session.loaded_plan = plan;
+}
+
+export function setPlanRef(session, ref) {
+  session._planRef = ref;
+}
+
+export function setPlanSyncCallback(session, fn) {
+  session._syncResultsToPlan = fn;
+}
+
+/**
+ * Live status updater: invoked by hu-sub-pipeline after every status
+ * change so the plan JSON gets the new status immediately, not only at
+ * the end of the run. Without this, the board reads an unchanged plan
+ * file during execution and the columns appear frozen until the run
+ * completes (the bug we're fixing in PR1).
+ *
+ * Signature: async (huId, status) => void
+ */
+export function setLiveStatusUpdater(session, fn) {
+  session._liveStatusUpdater = fn;
+}
+
+export function getLiveStatusUpdater(session) {
+  return session._liveStatusUpdater || null;
+}
+
+/**
+ * Live outcome updater (PR3): invoked by hu-sub-pipeline after each
+ * HU's runSingleHu finishes. The plan JSON gets the per-HU outcome
+ * stamped immediately so the board can show a "📄 ver resumen"
+ * indicator next to each card without waiting for the run to end.
+ *
+ * Signature: async (huId, outcome) => void
+ */
+export function setLiveOutcomeUpdater(session, fn) {
+  session._liveOutcomeUpdater = fn;
+}
+
+export function getLiveOutcomeUpdater(session) {
+  return session._liveOutcomeUpdater || null;
+}
+
+// --- Skills ---------------------------------------------------------------
+
+export function setAddyosmaniSkills(session, payload) {
+  session.addyosmaniSkills = payload;
+}
+
+export function setAutoInstalledSkills(session, skills) {
+  session.autoInstalledSkills = skills;
+}
+
+export function setSkillsRecommended(session, skills) {
+  session.skillsRecommended = skills;
+}
+
+// --- Journal breadcrumbs --------------------------------------------------
+
+export function setJournalContext(session, { dir, files, iterations, decisions, startedAt }) {
+  if (dir !== undefined) session._journalDir = dir;
+  if (files !== undefined) session._journalFiles = files;
+  if (iterations !== undefined) session._journalIterations = iterations;
+  if (decisions !== undefined) session._journalDecisions = decisions;
+  if (startedAt !== undefined) session._startedAt = startedAt;
+}
+
+// --- Session outcome ------------------------------------------------------
+
+export function setBudget(session, budget) {
+  session.budget = budget;
+}
+
+export function setDeferredIssues(session, issues) {
+  session.deferred_issues = issues;
+}
+
+export function setRtkSavings(session, savings) {
+  session.rtk_savings = savings;
+}
+
+// --- Paused state (resume) ------------------------------------------------
+
+export function setPausedState(session, state) {
+  session.paused_state = state;
+}
+
+// --- Brain decisions (decisor tracker) -----------------------------------
+
+export function setBrainDecisions(session, decisions) {
+  session.brainDecisions = decisions;
+}
+
+// --- Suggestions (MCP) ----------------------------------------------------
+
+export function setSuggestions(session, suggestions) {
+  session.suggestions = suggestions;
+}
+
+export function touch(session) {
+  session.updated_at = new Date().toISOString();
+}

package/src/session/runtime-overrides.js

@@ -0,0 +1,59 @@
+/**
+ * In-memory runtime overrides (e.g. `roles.coder.provider` set for the
+ * current process session, not persisted to disk).
+ *
+ * Why this lives at the session layer (not under `src/mcp/`):
+ *
+ *   Pre-v2.7.5, the overrides store lived in `src/mcp/preflight.js`. That
+ *   made `src/commands/agents.js` (CLI) do
+ *     `await import("../mcp/preflight.js")`
+ *   which is a **layer violation**: commands are the top layer, MCP is a
+ *   peer interface. A CLI command knowing about the MCP server's
+ *   preflight state coupled two runtimes that should be independent.
+ *
+ *   The "runtime override" concept is runtime-agnostic — both CLI and MCP
+ *   need an in-memory scratchpad for "this process should use this
+ *   provider for role X for the rest of its life". Putting it here makes
+ *   both layers depend on `src/session/` (a neutral module) instead of on
+ *   each other.
+ *
+ * Lifetime: the store lives for as long as the Node process. CLI
+ * invocations are short-lived (override is lost at exit — that's fine,
+ * they write to config if they want persistence). The MCP server process
+ * is long-lived; the override survives across tool calls until
+ * `clearRuntimeOverrides()` is called (typically by `ackPreflight()`).
+ *
+ * Contents: a flat `{ [key]: value }` map. Keys are typically role names
+ * (`coder`, `reviewer`, `planner`), values are provider slugs (`claude`,
+ * `codex`, `gemini`). Consumers shape-validate at read time.
+ */
+
+let overrides = {};
+
+/**
+ * Return a shallow copy of the current overrides. Never returns the
+ * internal reference so callers cannot mutate it by accident.
+ */
+export function getRuntimeOverrides() {
+  return { ...overrides };
+}
+
+/**
+ * Set a single override. Silently rejects nullish keys.
+ *
+ * @param {string} key
+ * @param {unknown} value
+ */
+export function setRuntimeOverride(key, value) {
+  if (!key) return;
+  overrides[key] = value;
+}
+
+/**
+ * Drop all overrides. Used by `ackPreflight()` after it transfers its
+ * configured overrides onto this store, to ensure we start from a clean
+ * slate per MCP session.
+ */
+export function clearRuntimeOverrides() {
+  overrides = {};
+}

package/src/{session-store.js → session/store.js}

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { ensureDir, exists } from "./utils/fs.js";
-import { getSessionRoot } from "./utils/paths.js";
+import { ensureDir, exists } from "../utils/fs.js";
+import { getSessionRoot } from "../utils/paths.js";
 
 const SESSION_ROOT = getSessionRoot();
 

package/src/skills/semantic-detector.js

@@ -129,18 +129,23 @@ export async function refineSkillsSemantically({ task, alreadyDetected = [], con
 
 /**
  * Resolve the effective skills mode from config + flags.
- * Precedence: flags.skillsMode > config.skills.mode > globalThis default > "auto".
+ * Precedence: flags.skillsMode > config.skills.mode > config.testHarness.defaultSkillsMode > "auto".
  *
- * The global default lets the test harness opt out of semantic detection
- * without each orchestrator test having to mock this module (tests/setup.js
- * sets globalThis.__KJ_DEFAULT_SKILLS_MODE = "regex").
+ * The testHarness default lets the test harness opt out of semantic
+ * detection without each orchestrator test having to mock this module.
+ * Production code reads `config.testHarness.defaultSkillsMode` only;
+ * the legacy global override is documented and exclusively read in
+ * src/config/test-harness.js (ESLint rule #557 blocks any reintroduction
+ * of `globalThis.__KJ_*` outside that one file). Legacy callers without
+ * a fully-loaded config still work because `config.testHarness` is
+ * undefined → falls through to `"auto"`.
  *
  * @param {Object} config
  * @param {Object} [flags]
  * @returns {"auto"|"regex"|"semantic"|"none"}
  */
 export function resolveSkillsMode(config, flags = {}) {
-  const defaultMode = globalThis.__KJ_DEFAULT_SKILLS_MODE || "auto";
+  const defaultMode = config?.testHarness?.defaultSkillsMode || "auto";
   const candidate = flags.skillsMode ?? config?.skills?.mode ?? defaultMode;
   const valid = new Set(["auto", "regex", "semantic", "none"]);
   return valid.has(candidate) ? candidate : "auto";

package/src/skills/skill-detector.js

@@ -226,7 +226,7 @@ async function collectPythonDeps(projectDir, needed) {
     for (const line of raw.split("\n")) {
       const trimmed = line.trim().split("#")[0].trim();
       if (!trimmed) continue;
-      const name = trimmed.split(/[<>=!~\[\s]/)[0].toLowerCase();
+      const name = trimmed.split(/[<>=!~[\s]/)[0].toLowerCase();
       const skill = PYTHON_DEPS[name];
       if (skill) needed.add(skill);
     }

package/src/sonar/api.js

@@ -3,7 +3,7 @@ import { withRetry } from "../utils/retry.js";
 import { resolveSonarProjectKey } from "./project-key.js";
 import { resolveSonarToken } from "./config-resolver.js";
 
-export class SonarApiError extends Error {
+class SonarApiError extends Error {
   constructor(message, { url, httpStatus, hint } = {}) {
     super(message);
     this.name = "SonarApiError";

package/src/sonar/cloud-scanner.js

@@ -5,7 +5,6 @@ function buildCloudScannerArgs(projectKey, config) {
   const sc = config.sonarcloud || {};
   const scanner = sc.scanner || {};
   const host = sc.host || "https://sonarcloud.io";
-  const token = process.env.KJ_SONARCLOUD_TOKEN || sc.token;
   const organization = process.env.KJ_SONARCLOUD_ORG || sc.organization;
 
   const args = [

package/src/sonar/credentials.js

@@ -1,13 +1,20 @@
 /**
- * Load SonarQube admin credentials from ~/.karajan/sonar-credentials.json.
+ * Load SonarQube credentials from ~/.karajan/sonar-credentials.json.
  *
- * File format:
+ * File format (any subset):
  * {
  *   "user": "admin",
- *   "password": "your-password"
+ *   "password": "your-password",
+ *   "token": "squ_..."
  * }
  *
- * Returns { user, password } or { user: null, password: null } if file missing.
+ * Returns { user, password, token } with each field null when missing.
+ *
+ * The `token` field is consumed by resolveSonarTokenAsync as the
+ * lowest-priority fallback. Until v2.7.5 it was not extracted here, which
+ * meant a token persisted to the credentials file by `kj init` was never
+ * actually used at scan time — Karajan would silently fall back to the
+ * stale token in kj.config.yml or fail with a 401.
  */
 
 import fs from "node:fs/promises";
@@ -23,10 +30,11 @@ export async function loadSonarCredentials() {
     const data = JSON.parse(raw);
     return {
       user: data.user || null,
-      password: data.password || null
+      password: data.password || null,
+      token: data.token || null
     };
   } catch { /* credentials file may not exist */
-    return { user: null, password: null };
+    return { user: null, password: null, token: null };
   }
 }