karajan-code 4.70.4 → 5.0.1

package/src/skills/skill-detector.js

@@ -1,385 +0,0 @@
-/**
- * Detects needed skills from task description and project files,
- * then auto-installs them via OpenSkills if available.
- */
-
-import fs from "node:fs/promises";
-import path from "node:path";
-import { loadAvailableSkills } from "./skill-loader.js";
-import { isOpenSkillsAvailable, installSkill, removeSkill } from "./openskills-client.js";
-import { isFresh as isCacheFresh, recordInstall as recordSkillInstall } from "./skills-cache.js";
-
-/**
- * Known frameworks detectable from package.json dependencies.
- * Maps dependency name to the skill name to search for.
- */
-const PKG_JSON_FRAMEWORKS = {
-  astro: "astro",
-  next: "nextjs",
-  react: "react",
-  "react-dom": "react",
-  vue: "vue",
-  svelte: "svelte",
-  "@angular/core": "angular",
-  express: "express",
-  fastify: "fastify",
-  "@nestjs/core": "nestjs",
-  // DB / ORM
-  prisma: "prisma",
-  "@prisma/client": "prisma",
-  knex: "sql-analysis",
-  sequelize: "sql-analysis",
-  typeorm: "sql-analysis",
-  mongoose: "mongodb",
-  "better-sqlite3": "sql-analysis",
-  // Testing
-  vitest: "vitest-patterns",
-  jest: "jest-patterns",
-  "@playwright/test": "playwright-patterns",
-  cypress: "cypress-patterns",
-};
-
-/**
- * Python dependency names (from requirements.txt or pyproject.toml) mapping
- * to their canonical skill.
- */
-const PYTHON_DEPS = {
-  pandas: "python-data",
-  numpy: "python-data",
-  scipy: "python-data",
-  "scikit-learn": "python-ml",
-  sklearn: "python-ml",
-  tensorflow: "python-ml",
-  torch: "python-ml",
-  pytorch: "python-ml",
-  pytest: "pytest-patterns",
-  django: "python-django",
-  flask: "python-flask",
-  fastapi: "python-fastapi",
-  sqlalchemy: "sql-analysis",
-};
-
-/**
- * Language markers: file presence maps to a skill name.
- * Reuses the same concept as src/utils/project-detect.js LANGUAGE_MARKERS.
- */
-const LANGUAGE_FILE_MARKERS = [
-  { file: "pom.xml", skill: "java" },
-  { file: "build.gradle", skill: "java" },
-  { file: "build.gradle.kts", skill: "kotlin" },
-  { file: "go.mod", skill: "go" },
-  { file: "Cargo.toml", skill: "rust" },
-  { file: "pyproject.toml", skill: "python" },
-  { file: "requirements.txt", skill: "python" },
-  { file: "setup.py", skill: "python" },
-  { file: "Gemfile", skill: "ruby" },
-  { file: "pubspec.yaml", skill: "flutter" },
-  { file: "Package.swift", skill: "swift" },
-  { file: "phpunit.xml", skill: "php" },
-  { file: "composer.json", skill: "php" },
-  { file: "mix.exs", skill: "elixir" },
-  { file: "rebar.config", skill: "erlang" },
-];
-
-/**
- * File EXTENSIONS whose presence anywhere under projectDir adds a skill.
- * Uses a shallow-recursive glob with a cutoff to avoid walking node_modules.
- */
-const EXTENSION_MARKERS = [
-  { ext: ".csproj", skill: "dotnet" },
-  { ext: ".sln", skill: "dotnet" },
-  { ext: ".ipynb", skill: "python-data" },
-  { ext: ".prisma", skill: "prisma" },
-];
-
-/**
- * Files detected as "SQL / database schema" when they exist at repo root.
- * Used in addition to EXTENSION_MARKERS for *.sql anywhere in the repo.
- */
-const SQL_MARKER_FILES = [
-  "schema.sql",
-  "schema.prisma",
-  "migrations",
-  "db/migrate",
-];
-
-const DIRECTORIES_TO_SKIP = new Set([
-  "node_modules", ".git", ".kj", ".karajan", "dist", "build", ".next", "out",
-  "target", ".venv", "venv", "__pycache__", ".vitest-cache", "coverage",
-]);
-
-/**
- * Patterns to detect framework/skill mentions in the task text.
- * Each entry: regex pattern (case-insensitive) -> skill name.
- */
-const TASK_TEXT_PATTERNS = [
-  { pattern: /\bastro\b/i, skill: "astro" },
-  { pattern: /\bnext\.?js\b/i, skill: "nextjs" },
-  { pattern: /\breact\b/i, skill: "react" },
-  { pattern: /\bvue\b/i, skill: "vue" },
-  { pattern: /\bsvelte\b/i, skill: "svelte" },
-  { pattern: /\bangular\b/i, skill: "angular" },
-  { pattern: /\bexpress\b/i, skill: "express" },
-  { pattern: /\bfastify\b/i, skill: "fastify" },
-  { pattern: /\bnest\.?js\b/i, skill: "nestjs" },
-  { pattern: /\bjava\b/i, skill: "java" },
-  { pattern: /\bkotlin\b/i, skill: "kotlin" },
-  { pattern: /\bgo(?:lang)?\b/i, skill: "go" },
-  { pattern: /\brust\b/i, skill: "rust" },
-  { pattern: /\bpython\b/i, skill: "python" },
-  { pattern: /\bdjango\b/i, skill: "python" },
-  { pattern: /\bflask\b/i, skill: "python" },
-  { pattern: /\bruby\b/i, skill: "ruby" },
-  { pattern: /\bflutter\b/i, skill: "flutter" },
-  { pattern: /\bswift\b/i, skill: "swift" },
-  { pattern: /\bphp\b/i, skill: "php" },
-  { pattern: /\bSQL\b/i, skill: "sql-analysis" },
-  { pattern: /\bquer(?:y|ies)\b/i, skill: "sql-analysis" },
-  { pattern: /\bdatabase\b/i, skill: "sql-analysis" },
-  { pattern: /\bCSV\b/i, skill: "csv-transform" },
-  { pattern: /\btransform\b/i, skill: "csv-transform" },
-  { pattern: /\bparse\b/i, skill: "csv-transform" },
-  { pattern: /\breport\b/i, skill: "data-report" },
-  { pattern: /\banalysis\b/i, skill: "data-report" },
-  { pattern: /\bfindings\b/i, skill: "data-report" },
-  // Frontend/backend broad categories
-  { pattern: /\bfrontend\b/i, skill: "frontend-design" },
-  { pattern: /\bCSS\b/i, skill: "frontend-design" },
-  { pattern: /\bHTML\b/i, skill: "frontend-design" },
-  { pattern: /\bbackend\b/i, skill: "express" },
-  { pattern: /\bnode\.?js\b/i, skill: "express" },
-  { pattern: /\bAPI\b/, skill: "express" },
-  { pattern: /\bwebsocket\b/i, skill: "express" },
-  { pattern: /\breal[- ]time\b/i, skill: "express" },
-];
-
-/**
- * Analyze the task and project to determine what skills might be needed.
- *
- * @param {string} task - The task description text.
- * @param {string} projectDir - Absolute path to project root.
- * @param {{ includeExtensions?: boolean, maxDepth?: number }} [options]
- *   - includeExtensions: scan for file extensions (.csproj, .ipynb, .sql...)
- *     that signal a stack. Default true. Disable to avoid the shallow walk
- *     in very large repos or in tests.
- *   - maxDepth: bound the walk (default 3 directories deep).
- * @returns {Promise<string[]>} Array of unique skill names to search for.
- */
-export async function detectNeededSkills(task, projectDir, options = {}) {
-  const { includeExtensions = true, maxDepth = 3 } = options;
-  const needed = new Set();
-
-  // 1. Scan package.json for known frameworks and JS-ecosystem deps
-  if (projectDir) {
-    try {
-      const pkgRaw = await fs.readFile(path.join(projectDir, "package.json"), "utf8");
-      const pkg = JSON.parse(pkgRaw);
-      const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
-      for (const [dep, skill] of Object.entries(PKG_JSON_FRAMEWORKS)) {
-        if (allDeps[dep]) {
-          needed.add(skill);
-        }
-      }
-    } catch { /* no package.json or parse error — skip */ }
-
-    // 2. Language marker files at repo root
-    for (const marker of LANGUAGE_FILE_MARKERS) {
-      try {
-        await fs.access(path.join(projectDir, marker.file));
-        needed.add(marker.skill);
-      } catch { /* file not found — skip */ }
-    }
-
-    // 3. Python deps from requirements.txt / pyproject.toml
-    await collectPythonDeps(projectDir, needed);
-
-    // 4. File extension markers (.csproj, .ipynb, .prisma, *.sql)
-    if (includeExtensions) {
-      await collectExtensionMarkers(projectDir, maxDepth, needed);
-    }
-
-    // 5. SQL / DB schema markers at well-known paths
-    for (const candidate of SQL_MARKER_FILES) {
-      try {
-        await fs.access(path.join(projectDir, candidate));
-        needed.add("sql-analysis");
-      } catch { /* skip */ }
-    }
-  }
-
-  // 6. Task text patterns
-  if (task) {
-    for (const { pattern, skill } of TASK_TEXT_PATTERNS) {
-      if (pattern.test(task)) {
-        needed.add(skill);
-      }
-    }
-  }
-
-  return Array.from(needed);
-}
-
-async function collectPythonDeps(projectDir, needed) {
-  // requirements.txt — each non-comment line is "name==ver" or "name>=ver"
-  try {
-    const raw = await fs.readFile(path.join(projectDir, "requirements.txt"), "utf8");
-    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 skill = PYTHON_DEPS[name];
-      if (skill) needed.add(skill);
-    }
-  } catch { /* no requirements.txt */ }
-
-  // pyproject.toml — simple heuristic scan for dependency names. A full TOML
-  // parse would need a dep; we just look for quoted names, which is fine.
-  try {
-    const raw = await fs.readFile(path.join(projectDir, "pyproject.toml"), "utf8");
-    const lower = raw.toLowerCase();
-    for (const [name, skill] of Object.entries(PYTHON_DEPS)) {
-      if (lower.includes(`"${name}"`) || lower.includes(`'${name}'`)) {
-        needed.add(skill);
-      }
-    }
-  } catch { /* no pyproject.toml */ }
-}
-
-async function collectExtensionMarkers(projectDir, maxDepth, needed) {
-  // Build a lookup by extension for fast decisions.
-  const byExt = new Map(EXTENSION_MARKERS.map((m) => [m.ext, m.skill]));
-  const extensions = new Set(byExt.keys());
-  extensions.add(".sql");
-  let sqlFound = false;
-
-  async function walk(dir, depth) {
-    if (depth > maxDepth) return;
-    let entries;
-    try {
-      entries = await fs.readdir(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      if (entry.isDirectory()) {
-        if (DIRECTORIES_TO_SKIP.has(entry.name)) continue;
-        if (entry.name.startsWith(".")) continue;
-        await walk(path.join(dir, entry.name), depth + 1);
-        continue;
-      }
-      if (!entry.isFile()) continue;
-      const ext = path.extname(entry.name).toLowerCase();
-      if (!extensions.has(ext)) continue;
-      if (ext === ".sql") {
-        sqlFound = true;
-        continue;
-      }
-      const skill = byExt.get(ext);
-      if (skill) needed.add(skill);
-    }
-  }
-
-  await walk(projectDir, 0);
-  if (sqlFound) needed.add("sql-analysis");
-}
-
-/**
- * Auto-install needed skills that are not yet installed.
- *
- * When the `openskills` CLI is not available, this function degrades
- * gracefully: it returns `osAvailable: false` and `wouldHaveUsed` with the
- * list of skills that would have been installed if the CLI had been present.
- * Callers (e.g. the orchestrator) can surface this info in the session
- * report without blocking execution.
- *
- * @param {string[]} neededSkills - Skill names to ensure are installed.
- * @param {string} projectDir - Absolute path to project root.
- * @returns {Promise<{
- *   installed: string[],
- *   failed: string[],
- *   alreadyInstalled: string[],
- *   wouldHaveUsed: string[],
- *   osAvailable: boolean
- * }>}
- */
-export async function autoInstallSkills(neededSkills, projectDir) {
-  const result = { installed: [], failed: [], alreadyInstalled: [], wouldHaveUsed: [], osAvailable: true };
-
-  if (!neededSkills || neededSkills.length === 0) {
-    return result;
-  }
-
-  // Check which skills are already installed locally
-  const existingSkills = await loadAvailableSkills(projectDir);
-  const existingNames = new Set(existingSkills.map(s => s.name.toLowerCase()));
-
-  // Check if OpenSkills is available
-  const osAvailable = await isOpenSkillsAvailable();
-  if (!osAvailable) {
-    result.osAvailable = false;
-    // Report what we would have installed so the session report can surface
-    // the recommendation — "install openskills globally to enable: X, Y, Z".
-    result.wouldHaveUsed = neededSkills.filter((s) => !existingNames.has(s.toLowerCase()));
-    return result;
-  }
-
-  for (const skillName of neededSkills) {
-    if (existingNames.has(skillName.toLowerCase())) {
-      result.alreadyInstalled.push(skillName);
-      continue;
-    }
-
-    // Cache short-circuit: if we installed this skill in the last 7 days,
-    // assume it's still good and skip the `npx openskills install` call
-    // (which can take 10-30s). Running sessions can opt out by clearing
-    // the cache with `kj skills clear-cache`.
-    if (await isCacheFresh(skillName)) {
-      result.alreadyInstalled.push(skillName);
-      continue;
-    }
-
-    try {
-      const installResult = await installSkill(skillName, { projectDir });
-      if (installResult.ok) {
-        const installedName = installResult.name || skillName;
-        result.installed.push(installedName);
-        await recordSkillInstall(installedName, { source: skillName }).catch(() => {});
-      } else {
-        result.failed.push(skillName);
-      }
-    } catch { /* skill install threw */
-      result.failed.push(skillName);
-    }
-  }
-
-  return result;
-}
-
-/**
- * Remove skills that were auto-installed during this session.
- * @param {string[]} skillNames - Skill names to remove.
- * @param {string} projectDir - Absolute path to project root.
- * @returns {Promise<{removed: string[], failed: string[]}>}
- */
-export async function cleanupAutoInstalledSkills(skillNames, projectDir) {
-  const result = { removed: [], failed: [] };
-
-  if (!skillNames || skillNames.length === 0) {
-    return result;
-  }
-
-  for (const name of skillNames) {
-    try {
-      const removeResult = await removeSkill(name, { projectDir });
-      if (removeResult.ok) {
-        result.removed.push(name);
-      } else {
-        result.failed.push(name);
-      }
-    } catch { /* skill removal threw */
-      result.failed.push(name);
-    }
-  }
-
-  return result;
-}

package/src/sonar/cloud-scanner.js

@@ -1,78 +0,0 @@
-import { runCommand } from "../utils/process.js";
-import { resolveSonarProjectKey } from "./project-key.js";
-
-function buildCloudScannerArgs(projectKey, config) {
-  const sc = config.sonarcloud || {};
-  const scanner = sc.scanner || {};
-  const host = sc.host || "https://sonarcloud.io";
-  const organization = process.env.KJ_SONARCLOUD_ORG || sc.organization;
-
-  const args = [
-    `-Dsonar.host.url=${host}`,
-    `-Dsonar.projectKey=${projectKey}`
-  ];
-
-  // Token passed via SONAR_TOKEN env var, not CLI args (invisible in `ps aux`)
-  if (organization) args.push(`-Dsonar.organization=${organization}`);
-  if (scanner.sources) args.push(`-Dsonar.sources=${scanner.sources}`);
-  if (scanner.exclusions) args.push(`-Dsonar.exclusions=${scanner.exclusions}`);
-  if (scanner.test_inclusions) args.push(`-Dsonar.test.inclusions=${scanner.test_inclusions}`);
-
-  return args;
-}
-
-export async function runSonarCloudScan(config, projectKey = null) {
-  const sc = config.sonarcloud || {};
-  const token = process.env.KJ_SONARCLOUD_TOKEN || sc.token;
-  const organization = sc.organization || process.env.KJ_SONARCLOUD_ORG;
-
-  if (!token) {
-    return {
-      ok: false,
-      projectKey: null,
-      stdout: "",
-      stderr: "SonarCloud token not configured. Set sonarcloud.token in kj.config.yml or KJ_SONARCLOUD_TOKEN env var.",
-      exitCode: 1
-    };
-  }
-
-  if (!organization) {
-    return {
-      ok: false,
-      projectKey: null,
-      stdout: "",
-      stderr: "SonarCloud organization not configured. Set sonarcloud.organization in kj.config.yml or KJ_SONARCLOUD_ORG env var.",
-      exitCode: 1
-    };
-  }
-
-  let effectiveProjectKey;
-  try {
-    effectiveProjectKey = projectKey || sc.project_key || await resolveSonarProjectKey(config, { projectKey });
-  } catch (error) {
-    return {
-      ok: false,
-      projectKey: null,
-      stdout: "",
-      stderr: error?.message || String(error),
-      exitCode: 1
-    };
-  }
-
-  const scannerTimeout = 15 * 60 * 1000;
-  const args = buildCloudScannerArgs(effectiveProjectKey, config);
-
-  // Pass token via process env, not CLI args — invisible in `ps aux`
-  const env = { ...process.env };
-  if (token) env.SONAR_TOKEN = token;
-
-  const result = await runCommand("npx", ["@sonar/scan", ...args], { timeout: scannerTimeout, env });
-
-  return {
-    ok: result.exitCode === 0,
-    projectKey: effectiveProjectKey,
-    stdout: result.stdout,
-    stderr: result.stderr,
-    exitCode: result.exitCode
-  };
-}

package/src/tracker-bootstrap.js

@@ -1,44 +0,0 @@
-/**
- * Tracker bootstrap — registers the configured task-tracker adapter into
- * the orchestrator's integrations registry at runtime.
- *
- * This module exists so that `src/orchestrator/` never imports
- * `src/planning-game/` (or any other tracker) directly — the architecture
- * invariant `tests/architecture/tracker-coupling.test.js` enforces that.
- * `runFlow` calls `ensureTrackerRegistered(config)` from here; this
- * module owns the conditional import of each adapter.
- *
- * Adding a new tracker:
- *   1. Write `src/adapters/<name>/adapter.js` with the hook surface
- *      documented in `src/orchestrator/integrations.js`.
- *   2. Add a branch below that imports and registers it when the relevant
- *      config flag is true.
- *
- * The function is idempotent: once registered, subsequent calls are
- * no-ops (the registry already has an entry for the slot).
- */
-
-import { getIntegration, registerIntegration } from "./orchestrator/integrations.js";
-
-/**
- * Ensure the tracker adapter configured by `config` is registered under
- * the `"tracker"` slot. Safe to call on every `runFlow` invocation.
- *
- * @param {object|null} config
- * @returns {Promise<void>}
- */
-export async function ensureTrackerRegistered(config) {
-  if (getIntegration("tracker")) return; // Already registered.
-
-  if (config?.planning_game?.enabled) {
-    try {
-      const { planningGameAdapter } = await import("./planning-game/pipeline-adapter.js");
-      registerIntegration("tracker", planningGameAdapter);
-    } catch { /* registration failed — non-blocking, adapter stays absent */ }
-    return;
-  }
-
-  // No tracker enabled — the orchestrator's `getIntegration("tracker")`
-  // calls will return undefined and every hook becomes an optional-chain
-  // no-op. That's the intended behavior for "tracker disabled" runs.
-}

package/src/types/index.js

@@ -1,38 +0,0 @@
-/**
- * Central JSDoc typedef registry. Import typedefs via:
- *
- *   /** @typedef {import("../types/index.js").KarajanConfig} KarajanConfig *\/
- *
- * This module re-exports every type so consumers have a single import path.
- * The actual typedef bodies live in the focused files under src/types/.
- *
- * Intentionally a runtime-empty module: it only carries JSDoc annotations,
- * nothing to execute.
- */
-
-/**
- * @typedef {import("./config.js").KarajanConfig} KarajanConfig
- * @typedef {import("./config.js").RoleConfig} RoleConfig
- * @typedef {import("./config.js").PipelineFlags} PipelineFlags
- *
- * @typedef {import("./session.js").Session} Session
- * @typedef {import("./session.js").Checkpoint} Checkpoint
- *
- * @typedef {import("./stage.js").StageContext} StageContext
- * @typedef {import("./stage.js").StageResult} StageResult
- *
- * @typedef {import("./agent.js").AgentResult} AgentResult
- * @typedef {import("./agent.js").AgentResponse} AgentResponse
- *
- * @typedef {import("./hu.js").HUStory} HUStory
- * @typedef {import("./hu.js").HUBatch} HUBatch
- *
- * @typedef {import("./policy.js").ResolvedPolicies} ResolvedPolicies
- * @typedef {import("./policy.js").QualityGateResult} QualityGateResult
- *
- * @typedef {import("./solomon.js").Conflict} SolomonConflict
- * @typedef {import("./solomon.js").ConflictHistoryEntry} SolomonConflictHistoryEntry
- * @typedef {import("./solomon.js").SolomonResult} SolomonResult
- */
-
-export {};

package/src/types/policy.js

@@ -1,43 +0,0 @@
-/**
- * Policy + quality-gate typedefs. Policies are resolved once per session
- * from config + task type; quality gates are the outputs of each gate
- * (sonar, perf, tests, review).
- */
-
-/**
- * @typedef {Object} ResolvedPolicies
- * @property {boolean} [tdd]                    - whether TDD is enforced
- * @property {boolean} [sonar]                  - Sonar gate enabled
- * @property {boolean} [tests]                  - tester gate enabled
- * @property {boolean} [security]               - security audit enabled
- * @property {boolean} [reviewer]               - reviewer gate enabled
- * @property {boolean} [planner]                - planner enabled
- * @property {boolean} [researcher]             - researcher enabled
- * @property {boolean} [architect]              - architect enabled
- * @property {boolean} [refactorer]             - refactorer enabled
- * @property {boolean} [impeccable]             - impeccable audit enabled
- * @property {boolean} [triage]                 - triage enabled
- * @property {boolean} [discover]               - discover phase enabled
- * @property {boolean} [hu_reviewer]            - HU certification enabled
- * @property {number} [reviewer_retries]
- * @property {number} [tester_retries]
- * @property {string} [reason]                  - why these policies (task type + config chain)
- */
-
-/**
- * Result of a quality gate evaluation — Sonar, perf, tester, reviewer, etc.
- *
- * @typedef {Object} QualityGateResult
- * @property {boolean} ok                       - did the gate pass
- * @property {"OK"|"FAIL"|"WARN"|"ERROR"} gateStatus
- * @property {string} [summary]
- * @property {Object[]} [blocking_issues]       - for reviewer/security gates
- * @property {number} [openIssues]              - sonar
- * @property {number} [issuesInitial]
- * @property {number} [issuesFinal]
- * @property {number} [issuesResolved]
- * @property {string} [provider]                - which agent produced the verdict (when relevant)
- * @property {Object} [details]                 - gate-specific payload
- */
-
-export {};

package/src/types/solomon.js

@@ -1,87 +0,0 @@
-/**
- * Typedefs for Solomon — the AI judge consulted by Brain on genuine dilemmas.
- *
- * Architectural invariant (enforced by convention, see docs/ARCHITECTURE.md):
- *   Solomon is **NEVER** invoked directly from stages, rules or roles.
- *   The only legitimate entry points are:
- *     - `src/brain/solomon-consult.js#consultSolomonForRouting`
- *     - `src/orchestrator/solomon-escalation.js#invokeSolomon`
- *   Both are called by Brain (or by the orchestrator on Brain's behalf).
- *   The v2.3.0 audit fixed 21 violations where stages bypassed Brain and
- *   called Solomon directly. Don't reintroduce that pattern.
- *
- * This module is runtime-empty — it only carries JSDoc annotations.
- *
- * @module types/solomon
- */
-
-/**
- * A single turn of feedback attributed to a pipeline agent. Used to build
- * `Conflict.history` when Brain escalates a decision to Solomon.
- *
- * @typedef {Object} ConflictHistoryEntry
- * @property {string} agent     - slug of the agent that produced the feedback
- *                                (e.g. "reviewer", "sonar", "tester",
- *                                "coder_rate_limit").
- * @property {string} feedback  - raw textual feedback to be weighted by Solomon.
- */
-
-/**
- * The bundle of context Brain hands to Solomon when it cannot decide on its
- * own. Solomon reads only this object + the stage + task; it never sees
- * session internals beyond what is packed here.
- *
- * Historical shape: this matches the argument already used by
- * `invokeSolomon({ ..., conflict })` — the typedef formalizes the contract
- * so future drift is caught by `npm run typecheck`.
- *
- * @typedef {Object} Conflict
- * @property {string} stage
- *           Pipeline stage that triggered escalation (e.g. "reviewer",
- *           "sonar", "tester", "init_error", "coder_rate_limit").
- * @property {string} task
- *           Original user task (denormalized so Solomon sees what the user
- *           actually asked for, not just the stage context).
- * @property {number} iterationCount
- *           Current iteration number inside the escalating sub-loop.
- * @property {number} maxIterations
- *           Configured cap for that sub-loop (reviewer retries, tester
- *           retries, full pipeline iterations, etc.). Hitting this cap is
- *           the canonical trigger for Solomon consultation.
- * @property {string|null} [cooldownUntil]
- *           ISO timestamp for rate-limit / standby escalations. Null when
- *           the conflict is not a rate-limit.
- * @property {number|null} [cooldownMs]
- *           Remaining cooldown in milliseconds. Null outside rate-limit
- *           escalations.
- * @property {ConflictHistoryEntry[]} history
- *           Ordered list of agent feedback Solomon should weigh. Most
- *           recent last. Must be non-empty — Solomon should always see at
- *           least one piece of evidence.
- */
-
-/**
- * Solomon's ruling on a `Conflict`. Returned by `invokeSolomon()` and
- * consumed by the orchestrator to decide what happens next.
- *
- * @typedef {Object} SolomonResult
- * @property {"continue"|"pause"|"subtask"} action
- *           - `continue`: retry the sub-loop with optional `humanGuidance`
- *             appended to the next feedback round.
- *           - `pause`: stop the pipeline and surface a question to the
- *             human operator (`SolomonResult.question`).
- *           - `subtask`: bifurcate into a named sub-task defined in
- *             `SolomonResult.subtask`.
- * @property {string} [rationale]         - human-readable reasoning for the
- *                                          chosen action. Logged to the
- *                                          decisions journal.
- * @property {string} [humanGuidance]     - text to merge into the next
- *                                          coder/reviewer prompt when
- *                                          action === "continue".
- * @property {string} [question]          - prompt shown to the human when
- *                                          action === "pause".
- * @property {Object} [subtask]           - sub-task descriptor when
- *                                          action === "subtask".
- */
-
-export {};