@karajan-family/code 4.21.0

package/src/roles/solomon-role.js

@@ -0,0 +1,265 @@
+import { BaseRole } from "./base-role.js";
+import { createAgent as defaultCreateAgent } from "../agents/index.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
+
+const SUBAGENT_PREAMBLE = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
+  "Do NOT use any MCP tools. Focus only on resolving the conflict between agents."
+].join(" ");
+
+function resolveProvider(config) {
+  return (
+    config?.roles?.solomon?.provider ||
+    config?.roles?.coder?.provider ||
+    "claude"
+  );
+}
+
+function formatHistory(history) {
+  if (!history || history.length === 0) return "No previous interactions recorded.";
+
+  return history
+    .map((entry, i) => {
+      const agent = entry.agent || "unknown";
+      const feedback = entry.feedback || entry.message || "(no feedback)";
+      return `### Interaction ${i + 1} [${agent}]\n${feedback}`;
+    })
+    .join("\n\n");
+}
+
+function buildPrompt({ conflict, task, instructions }) {
+  const sections = [SUBAGENT_PREAMBLE];
+
+  if (instructions) {
+    sections.push(instructions);
+  }
+
+  sections.push(
+    "You are Solomon, the autonomous pipeline boss in a multi-agent AI coding orchestrator.",
+    "You are activated whenever ANYTHING deviates from normal flow: rate limits, agent failures, conflicts, max iterations, quality gate issues.",
+    "",
+    "## Core principle",
+    "The pipeline NEVER skips a quality stage (review, tests, sonar, security) without exhausting alternatives first.",
+    "NEVER approve skipping a stage as your first option. Follow the recovery hierarchy below.",
+    "",
+    "## ABSOLUTE RULE: Security issues from reviewer are NEVER overridable",
+    "If the reviewer's blocking_issues contain security-related issues (categories: authentication, authorization, injection, XSS, CSRF, exposed secrets/credentials, cryptography, session management, input validation), you MUST:",
+    "- Set ruling to \"continue\" (NOT \"approve\")",
+    "- Return the reviewer feedback to the coder for fixing",
+    "- NEVER approve or skip security issues regardless of task complexity or deadline",
+    "This rule overrides all other rules including the recovery hierarchy.",
+    "",
+    "## Recovery hierarchy (STRICT ORDER — follow top to bottom)",
+    "When a stage fails or an agent is unavailable:",
+    "1. **wait** — If there is a known cooldown (cooldownUntil), and it is less than 10 minutes, WAIT. Set ruling to 'approve_with_conditions' with condition 'wait for cooldown' and set waitUntil.",
+    "2. **retry_with_alternative** — Try the same stage with a DIFFERENT agent. The pipeline has multiple agents (claude, codex, gemini). Set ruling to 'approve_with_conditions' with condition specifying the alternative agent.",
+    "3. **evaluate_risk** — Only if no alternatives are available, evaluate the risk of skipping. Consider: task complexity, what the stage would catch, security implications.",
+    "   - If risk is LOW (trivial task, no security impact, style-only review): approve with a clear justification.",
+    "   - If risk is HIGH (complex task, security changes, new dependencies): escalate_human.",
+    "4. **escalate_human** — When you cannot resolve it safely. Always prefer this over blindly approving.",
+    "",
+    "## Quality hierarchy",
+    "Security > Correctness > Tests > Architecture > Maintainability > Style",
+    "- Green tests are sacred. Never dismiss a failing test.",
+    "- Style preferences NEVER block approval.",
+    "- Sonar INFO/MINOR issues are always dismissable.",
+    "- Sonar BLOCKER/CRITICAL must be fixed unless they are proven false positives.",
+    "",
+    "## Classification rules",
+    "For each issue, classify as:",
+    "1. **critical** (security, correctness, tests broken) — action: must_fix",
+    "2. **important** (architecture, maintainability) — action: should_fix",
+    "3. **style** (naming, formatting, preferences, false positives) — action: dismiss",
+    "",
+    "## Ruling options",
+    '1. **approve** — FORBIDDEN when a quality stage (review, tests, sonar, security) was skipped or failed. You MUST try alternatives first (wait for cooldown, use different agent). Only allowed when all stages completed successfully and remaining issues are style/false positives.',
+    '2. **approve_with_conditions** — Fixable issues or recovery actions needed. Include exact conditions (wait, retry with alternative agent, specific fix instructions). Set extraIterations and/or alternativeAgent.',
+    '3. **escalate_human** — Cannot resolve safely. Critical issues, ambiguous requirements, architecture decisions, high-risk skip.',
+    '4. **create_subtask** — A prerequisite task must be completed first.',
+    "",
+    "Return a single valid JSON object with your ruling and nothing else.",
+    'JSON schema: {"ruling":"approve"|"approve_with_conditions"|"escalate_human"|"create_subtask","classification":[{"issue":string,"category":"critical"|"important"|"style","action":"must_fix"|"should_fix"|"dismiss"}],"conditions":[string],"dismissed":[string],"escalate":boolean,"escalate_reason":string|null,"extraIterations":number|null,"alternativeAgent":string|null,"waitUntil":string|null,"subtask":{"title":string,"description":string,"reason":string}|null}',
+    "When ruling is approve_with_conditions, set extraIterations (1-5) and/or alternativeAgent (claude|codex|gemini) as appropriate."
+  );
+
+  const stage = conflict?.stage || "unknown";
+  const iterationCount = conflict?.iterationCount ?? "?";
+  const maxIterations = conflict?.maxIterations ?? "?";
+
+  const isFirstRejection = conflict?.isFirstRejection ?? false;
+  const isRepeat = conflict?.isRepeat ?? false;
+
+  const budgetUsd = conflict?.budget_usd;
+  const budgetLine = typeof budgetUsd === "number" ? `Budget spent so far: $${budgetUsd.toFixed(2)}` : "";
+
+  sections.push(
+    `## Conflict context`,
+    `Stage: ${stage}`,
+    `Iterations exhausted: ${iterationCount}/${maxIterations}`,
+    `isFirstRejection: ${isFirstRejection}`,
+    `isRepeat: ${isRepeat}`,
+    budgetLine,
+    "",
+    "## Budget awareness",
+    "Consider the cost-benefit ratio when deciding. If significant budget has been spent with little progress,",
+    "prefer approving the current work or escalating to human. If progress is good and budget is low,",
+    "prefer continuing with conditions. Never waste budget on style-only iterations."
+  );
+
+  if (conflict?.previousSolomonRulings?.length > 0) {
+    const rulingLines = conflict.previousSolomonRulings.map((r, idx) =>
+      `${idx + 1}. Stage: ${r.conflictStage}, Ruling: ${r.ruling}${r.alternativeAgent ? `, agent: ${r.alternativeAgent}` : ""}${r.error ? ` (FAILED: ${r.error})` : ""}`
+    ).join("\n");
+    sections.push(
+      "## Your previous rulings in this session (DO NOT repeat failed strategies)",
+      rulingLines,
+      "If a previous ruling failed (e.g., alternative agent also rate-limited), do NOT suggest the same strategy again. Escalate or try a different approach."
+    );
+  }
+
+  // Rate limit specific instruction
+  if (stage?.includes("rate_limit")) {
+    const rateLimitedAgent = conflict?.history?.[0]?.feedback?.match(/Agent "(\w+)"/)?.[1] || "unknown";
+    sections.push(
+      "## CRITICAL: Agent rate-limited",
+      `Agent "${rateLimitedAgent}" is rate-limited. You MUST NOT approve skipping this stage.`,
+      "Your ONLY valid options are:",
+      `1. approve_with_conditions + alternativeAgent: pick a different agent (available: claude, codex, gemini — NOT "${rateLimitedAgent}")`,
+      "2. approve_with_conditions + waitUntil: if cooldown is known and <10min",
+      "3. escalate_human: if no alternatives work",
+      `DO NOT set ruling to "approve". The stage MUST be completed by some agent.`
+    );
+  }
+
+  if (conflict?.issueCategories) {
+    sections.push(`## Issue categories\n${JSON.stringify(conflict.issueCategories, null, 2)}`);
+  }
+
+  if (conflict?.blockingIssues?.length) {
+    const issueList = conflict.blockingIssues
+      .map((issue, i) => `${i + 1}. [${issue.severity || "unknown"}] ${issue.description || issue}`)
+      .join("\n");
+    sections.push(`## Blocking issues\n${issueList}`);
+  }
+
+  if (task) {
+    sections.push(`## Original task\n${task}`);
+  }
+
+  if (conflict?.diff) {
+    sections.push(`## Current diff\n${conflict.diff}`);
+  }
+
+  sections.push(`## Agent interaction history\n${formatHistory(conflict?.history)}`);
+
+  return sections.join("\n\n");
+}
+
+function parseSolomonOutput(raw) {
+  return extractFirstJson(raw);
+}
+
+function buildSummary(parsed) {
+  const ruling = parsed.ruling || "unknown";
+  const conditions = parsed.conditions || [];
+  const dismissed = parsed.dismissed || [];
+  const subtask = parsed.subtask || null;
+
+  if (ruling === "approve") {
+    const parts = ["Approved"];
+    if (dismissed.length > 0) parts.push(`${dismissed.length} dismissed`);
+    return parts.join("; ");
+  }
+
+  if (ruling === "approve_with_conditions") {
+    const parts = [`Approved with ${conditions.length} condition${conditions.length === 1 ? "" : "s"}`];
+    if (dismissed.length > 0) parts.push(`${dismissed.length} dismissed`);
+    return parts.join("; ");
+  }
+
+  if (ruling === "escalate_human") {
+    return `Escalated to human: ${parsed.escalate_reason || "ambiguous conflict"}`;
+  }
+
+  if (ruling === "create_subtask") {
+    return `Subtask created: ${subtask?.title || "unnamed subtask"}`;
+  }
+
+  return `Solomon ruling: ${ruling}`;
+}
+
+export class SolomonRole extends BaseRole {
+  constructor({ config, logger, emitter = null, createAgentFn = null }) {
+    super({ name: "solomon", config, logger, emitter });
+    this._createAgent = createAgentFn || defaultCreateAgent;
+  }
+
+  async execute(input) {
+    const conflict = input?.conflict || {};
+
+    const provider = resolveProvider(this.config);
+    const agent = this._createAgent(provider, this.config, this.logger);
+
+    const prompt = buildPrompt({
+      conflict,
+      task: this.context?.task || "",
+      instructions: this.instructions
+    });
+
+    // KJC-TSK-0413 step C: Solomon es BaseRole (no AgentRole) — wrap explícito.
+    const result = await withBrainRecovery({
+      agent, taskArgs: { prompt, role: "solomon" }, role: "solomon", provider,
+      emitter: this.emitter, logger: this.logger,
+    });
+
+    if (!result.ok) {
+      const recoveryNote = result.recovery?.class ? ` [${result.recovery.class}]` : "";
+      return {
+        ok: false,
+        result: {
+          error: result.error || result.output || `Solomon arbitration failed${recoveryNote}`,
+          provider, recovery: result.recovery, action: result.action,
+        },
+        summary: `Solomon failed${recoveryNote}: ${result.recovery?.message || result.error || "unknown error"}`
+      };
+    }
+
+    try {
+      const parsed = parseSolomonOutput(result.output);
+      if (!parsed) {
+        return {
+          ok: false,
+          result: { error: "Failed to parse Solomon output: no JSON found", provider },
+          summary: "Solomon output parse error: no JSON found"
+        };
+      }
+
+      const ruling = parsed.ruling || "approve";
+      const escalate = Boolean(parsed.escalate);
+      const ok = ruling !== "escalate_human";
+
+      return {
+        ok,
+        result: {
+          ruling,
+          classification: parsed.classification || [],
+          conditions: parsed.conditions || [],
+          dismissed: parsed.dismissed || [],
+          escalate,
+          escalate_reason: parsed.escalate_reason || null,
+          subtask: parsed.subtask || null,
+          provider
+        },
+        summary: buildSummary(parsed)
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        result: { error: `Failed to parse Solomon output: ${err.message}`, provider },
+        summary: `Solomon output parse error: ${err.message}`
+      };
+    }
+  }
+}

package/src/roles/sonar-role.js

@@ -0,0 +1,70 @@
+import { BaseRole } from "./base-role.js";
+import { runSonarScan } from "../sonar/scanner.js";
+import { getQualityGateStatus, getOpenIssues } from "../sonar/api.js";
+import { shouldBlockByProfile, summarizeIssues } from "../sonar/enforcer.js";
+
+function normalizeIssues(rawIssues) {
+  return rawIssues.map((issue) => ({
+    severity: issue.severity || "UNKNOWN",
+    type: issue.type || "UNKNOWN",
+    file: issue.component || "",
+    line: issue.line || 0,
+    rule: issue.rule || "",
+    message: issue.message || ""
+  }));
+}
+
+export class SonarRole extends BaseRole {
+  constructor({ config, logger, emitter = null }) {
+    super({ name: "sonar", config, logger, emitter });
+  }
+
+  async execute(_input) {
+    const scan = await runSonarScan(this.config);
+
+    if (!scan.ok) {
+      return {
+        ok: false,
+        result: {
+          projectKey: scan.projectKey || null,
+          gateStatus: null,
+          issues: [],
+          openIssuesTotal: 0,
+          issuesSummary: "",
+          blocking: false,
+          error: scan.stderr || scan.stdout || "Scan failed"
+        },
+        summary: `Sonar scan failed: ${scan.stderr || scan.stdout || "unknown error"}`
+      };
+    }
+
+    const gate = await getQualityGateStatus(this.config, scan.projectKey);
+    const openIssues = await getOpenIssues(this.config, scan.projectKey);
+    const issues = normalizeIssues(openIssues.issues || []);
+    const issuesSummary = summarizeIssues(openIssues.issues || []);
+
+    const profile = this.config.sonarqube?.enforcement_profile || "pragmatic";
+    const blocking = shouldBlockByProfile({
+      gateStatus: gate.status,
+      profile
+    });
+
+    return {
+      ok: !blocking,
+      result: {
+        projectKey: scan.projectKey,
+        gateStatus: gate.status,
+        conditions: gate.conditions || [],
+        issues,
+        openIssuesTotal: openIssues.total || 0,
+        issuesSummary,
+        blocking
+      },
+      summary: (() => {
+        const issuesPart = issuesSummary ? ` (${issuesSummary})` : "";
+        const blockingPart = blocking ? " [BLOCKING]" : "";
+        return `Quality gate: ${gate.status}; Issues: ${openIssues.total || 0}${issuesPart}${blockingPart}`;
+      })()
+    };
+  }
+}

package/src/roles/spec-reviewer-role.js

@@ -0,0 +1,106 @@
+// Spec Reviewer role (KJC-PCS-0048 PR 1). Runs BEFORE intent/triage/planner;
+// audits the user's spec and returns structured findings. Does NOT execute.
+
+import { AgentRole } from "./agent-role.js";
+import { buildSpecReviewerPrompt, buildSpecRefinerPrompt, VALID_CATEGORIES } from "../prompts/spec-reviewer.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
+
+const F_SEVS = new Set(["info", "warn", "fail"]);
+const T_SEVS = new Set(["ok", "info", "warn", "fail"]);
+const CATS = new Set(VALID_CATEGORIES);
+const ORDER = { ok: 0, info: 1, warn: 2, fail: 3 };
+
+function normalise(findings) {
+  if (!Array.isArray(findings)) return [];
+  return findings.map((f, i) => ({
+    id: typeof f?.id === "string" && f.id.trim() ? f.id.trim() : `F-${String(i + 1).padStart(3, "0")}`,
+    severity: F_SEVS.has(f?.severity) ? f.severity : "warn",
+    category: CATS.has(f?.category) ? f.category : "ambiguity",
+    message: String(f?.message || "").trim() || "(no description)",
+    suggestion: typeof f?.suggestion === "string" && f.suggestion.trim() ? f.suggestion.trim() : null,
+  }));
+}
+
+const worstOf = (findings) => findings.reduce((m, f) => (ORDER[f.severity] > ORDER[m] ? f.severity : m), "ok");
+
+export class SpecReviewerRole extends AgentRole {
+  constructor(opts) { super({ ...opts, name: "spec-reviewer" }); }
+
+  extractInput(input) {
+    if (typeof input === "string") return { spec: input, onOutput: null };
+    return {
+      spec: input?.spec || input?.task || this.context?.task || "",
+      onOutput: input?.onOutput || null,
+      sessionState: input?.sessionState || null,
+    };
+  }
+
+  async buildPrompt({ spec }) {
+    return { prompt: buildSpecReviewerPrompt({ spec, instructions: this.instructions }) };
+  }
+
+  parseOutput(raw) { return extractFirstJson(raw); }
+
+  buildSuccessResult(parsed, provider) {
+    const findings = normalise(parsed?.findings);
+    const declared = T_SEVS.has(parsed?.severity) ? parsed.severity : null;
+    const derived = worstOf(findings);
+    // Trust the worse of declared vs derived — agents sometimes report
+    // `severity: "ok"` while still listing fail-level findings.
+    const severity = !declared || ORDER[derived] > ORDER[declared] ? derived : declared;
+    return { severity, findings, reasoning: String(parsed?.reasoning || "").trim() || null, provider };
+  }
+
+  buildSummary(parsed) {
+    const findings = normalise(parsed?.findings);
+    if (findings.length === 0) return "Spec OK (no findings)";
+    return `Spec ${worstOf(findings)}: ${findings.length} finding${findings.length === 1 ? "" : "s"}`;
+  }
+
+  // Parse failures degrade to a soft warning so the pipeline never blocks.
+  handleParseNull(r, p) { return this.#degraded(r, p, "parse-null", "LLM output was unstructured"); }
+  handleParseError(e, r, p) { return this.#degraded(r, p, "parse-error", e?.message || "unknown"); }
+
+  /**
+   * Refine mode (KJC-PCS-0048 PR 3). Bypasses the JSON-only `execute()`
+   * flow: returns the LLM output verbatim as the rewritten spec, so the
+   * refine loop can persist it as `spec-v2.md`.
+   * @returns {Promise<{ ok:boolean, refinedSpec?:string, error?:string, provider:string, usage?:object }>}
+   */
+  async refineSpec({ spec, findings }) {
+    if (!this._initialized) await this.init({ task: spec });
+    const provider = this.resolveProvider();
+    const agent = this.createAgentInstance(provider);
+    const prompt = buildSpecRefinerPrompt({ originalSpec: spec, findings, instructions: this.instructions });
+    const result = await withBrainRecovery({
+      agent: { runTask: (a) => agent.runTask(a), provider },
+      taskArgs: { prompt, role: this.name },
+      role: this.name, provider, emitter: this.emitter, logger: this.logger,
+    });
+    if (!result.ok) {
+      return { ok: false, error: result.error || "refine failed", provider, usage: result.usage };
+    }
+    const refinedSpec = String(result.output || "").replace(/^```[a-z]*\n?|```$/g, "").trim();
+    if (!refinedSpec) return { ok: false, error: "empty refined spec", provider, usage: result.usage };
+    return { ok: true, refinedSpec, provider, usage: result.usage };
+  }
+
+  #degraded(agentResult, provider, reason, detail) {
+    return {
+      ok: true,
+      result: {
+        severity: "warn",
+        findings: [{
+          id: "F-DEG", severity: "warn", category: "assumptions",
+          message: `[spec-reviewer] degraded (${reason}): ${detail}`,
+          suggestion: "Re-run with --skip-spec-review if this keeps failing.",
+        }],
+        reasoning: "Spec reviewer could not parse the LLM output; treating as a soft warning.",
+        provider, degraded: true,
+      },
+      summary: `Spec reviewer degraded: ${reason}`,
+      usage: agentResult?.usage,
+    };
+  }
+}

package/src/roles/tester-role.js

@@ -0,0 +1,235 @@
+import { AgentRole } from "./agent-role.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+import { detectTestFramework } from "../utils/project-detect.js";
+import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
+
+const SUBAGENT_PREAMBLE = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
+  "Do NOT use any MCP tools. Focus only on evaluating test quality."
+].join(" ");
+
+/**
+ * Map test framework to the command that runs tests with coverage.
+ */
+const COVERAGE_COMMANDS = {
+  vitest: "npx vitest run --coverage --reporter=verbose 2>&1",
+  jest: "npx jest --coverage --verbose 2>&1",
+  mocha: "npx c8 mocha 2>&1",
+  playwright: "npx playwright test 2>&1",
+  pytest: "pytest --cov --tb=short 2>&1",
+  "go-test": "go test -cover -v ./... 2>&1",
+  "cargo-test": "cargo test --verbose 2>&1",
+  junit: "mvn test 2>&1",
+  rspec: "bundle exec rspec 2>&1",
+  phpunit: "vendor/bin/phpunit --coverage-text 2>&1",
+  "dotnet-test": "dotnet test --collect:\"XPlat Code Coverage\" 2>&1",
+  "dart-test": "dart test 2>&1",
+  // INF-B: the basic suite ALWAYS runs first; checkov is the additive deep
+  // scan. If checkov is missing this chain fails and the brief falls back to
+  // the basic suite alone (declared degradation, never green-by-omission).
+  "terraform-validate": "terraform init -backend=false -input=false 2>&1 && terraform validate 2>&1 && checkov -d . --compact --quiet 2>&1",
+  "helm-lint": "helm lint . 2>&1 && checkov -d . --compact --quiet 2>&1",
+  "kustomize-build": "kustomize build . > /dev/null && checkov -d . --compact --quiet 2>&1",
+  "ansible-lint": "ansible-lint 2>&1 && checkov -d . --compact --quiet 2>&1"
+};
+
+const TEST_COMMANDS = {
+  vitest: "npx vitest run --reporter=verbose 2>&1",
+  jest: "npx jest --verbose 2>&1",
+  mocha: "npx mocha 2>&1",
+  playwright: "npx playwright test 2>&1",
+  pytest: "pytest --tb=short 2>&1",
+  "go-test": "go test -v ./... 2>&1",
+  "cargo-test": "cargo test --verbose 2>&1",
+  junit: "mvn test 2>&1",
+  rspec: "bundle exec rspec 2>&1",
+  phpunit: "vendor/bin/phpunit 2>&1",
+  "dotnet-test": "dotnet test 2>&1",
+  "dart-test": "dart test 2>&1",
+  // INF-B (KJC-TSK-0759): infra suites — validity IS the test floor.
+  "terraform-validate": "terraform init -backend=false -input=false 2>&1 && terraform validate 2>&1",
+  "helm-lint": "helm lint . 2>&1",
+  "kustomize-build": "kustomize build . > /dev/null && echo kustomize build: OK",
+  "ansible-lint": "ansible-lint 2>&1"
+};
+
+export class TesterRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "tester" });
+  }
+
+  extractInput(input) {
+    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, pendingGherkinTests, shellTestResults }) {
+    const projectDir = this.config?.projectDir || process.cwd();
+    const detection = await detectTestFramework(projectDir);
+
+    const sections = [SUBAGENT_PREAMBLE];
+    if (this.instructions) sections.push(this.instructions);
+
+    sections.push(
+      "You are a test quality gate. Your job is to EXECUTE the test suite, measure REAL coverage, and evaluate quality.",
+      "You MUST run the actual test command — do NOT guess or estimate results."
+    );
+
+    if (detection.hasTests && detection.framework) {
+      const coverageCmd = COVERAGE_COMMANDS[detection.framework];
+      const testCmd = TEST_COMMANDS[detection.framework];
+      // INF-B: infra suites have no node_modules — the step-0 contract is
+      // "the tool exists or you SAY which one is missing", never a fake green.
+      const step0 = detection.language === "infra"
+        ? "**Step 0**: Verify the SUITE tool is installed (`which terraform`/`helm`/`kustomize`/`ansible-lint`). If the suite tool is MISSING, do NOT fake a green: report it in `failures` with the exact install command and set tests_pass: false. `checkov` (the deep scan below) is OPTIONAL: if it is missing, run the basic suite as the fallback and SAY the deep scan was skipped (degraded, never green-by-omission)."
+        : "**Step 0**: If node_modules/ does not exist, run `npm install` (or `pnpm install`) first.";
+      sections.push(
+        `## Detected test framework: ${detection.framework} (${detection.language})`,
+        step0,
+        `**Step 1**: Run the test suite with coverage:`,
+        "```bash",
+        coverageCmd || testCmd,
+        "```",
+        "If the coverage command fails (missing dependency), fall back to:",
+        "```bash",
+        testCmd,
+        "```",
+        "**Step 2**: Parse the output to extract: pass/fail count, coverage percentages, any failures.",
+        "**Step 3**: Return a single JSON object with REAL numbers from the test output."
+      );
+    } else {
+      sections.push(
+        "## No test framework detected",
+        "**Step 0**: If package.json exists but node_modules/ does not, run `npm install` first.",
+        "**Step 1**: Look at package.json or project files to find test scripts.",
+        "**Step 2**: Try running `npm test` or detect the framework from config files.",
+        "**Step 3**: If tests exist, run them. If no tests exist, report tests_pass: false with verdict: 'fail'.",
+        "**Step 4**: Return a JSON object with your findings."
+      );
+    }
+
+    // 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],"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}`);
+    if (sonarIssues) sections.push(`## Sonar test issues\n${sonarIssues}`);
+
+    // Inject test-relevant skills (filtered by role=tester to only include
+    // testing patterns like pytest-patterns, vitest-patterns, etc.)
+    const skills = await loadAvailableSkills(projectDir);
+    const skillSection = buildSkillSection(skills, {
+      provider: this._resolvedProvider || (typeof this.resolveProvider === "function" ? this.resolveProvider() : null),
+      role: "tester",
+    });
+    if (skillSection) sections.push(skillSection);
+
+    return { prompt: sections.join("\n\n") };
+  }
+
+  parseOutput(raw) { return extractFirstJson(raw); }
+
+  isSuccessful(parsed) {
+    const verdict = parsed.verdict || (parsed.tests_pass ? "pass" : "fail");
+    return verdict === "pass";
+  }
+
+  buildSuccessResult(parsed, provider) {
+    const verdict = parsed.verdict || (parsed.tests_pass ? "pass" : "fail");
+    return {
+      tests_pass: Boolean(parsed.tests_pass),
+      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
+    };
+  }
+
+  buildSummary(parsed) {
+    const verdict = parsed.verdict || (parsed.tests_pass ? "pass" : "fail");
+    const coverage = parsed.coverage || {};
+    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)` : "";
+    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}`;
+  }
+}