nexus-agents 2.95.0 → 2.97.0

package/dist/chunk-P2BKWVKF.js

@@ -0,0 +1,1095 @@
+import {
+  createSecureHandler,
+  getToolAnnotations,
+  getToolTimeout,
+  toSdkCallback,
+  toolStructuredError,
+  toolSuccessStructured,
+  wrapToolWithTimeout
+} from "./chunk-5LGAPYX7.js";
+import {
+  createLogger,
+  formatZodError,
+  getErrorMessage,
+  getOutcomeStore,
+  getPipelineEventBus,
+  getTimeProvider
+} from "./chunk-JTQLV374.js";
+import {
+  getNexusDataDir
+} from "./chunk-CH7QIDHQ.js";
+
+// src/mcp/tools/improvement-review.ts
+import { execFile as execFile2 } from "child_process";
+import { readFile } from "fs/promises";
+import { promisify as promisify2 } from "util";
+import { z } from "zod";
+
+// src/mcp/middleware/tool-prerequisites.ts
+import { execFile } from "child_process";
+import { access, constants } from "fs/promises";
+import { dirname } from "path";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+async function ghCliAvailable() {
+  try {
+    await execFileAsync("gh", ["--version"], { timeout: 5e3 });
+    return { ok: true };
+  } catch (err) {
+    return {
+      ok: false,
+      remediation: `the 'gh' CLI is not available (${getErrorMessage(err)}) \u2014 install GitHub CLI and authenticate (\`gh auth login\`)`
+    };
+  }
+}
+async function dataDirWritable() {
+  const dir = getNexusDataDir();
+  try {
+    await access(dir, constants.W_OK);
+    return { ok: true };
+  } catch {
+    try {
+      await access(dirname(dir), constants.W_OK);
+      return { ok: true };
+    } catch (err) {
+      return {
+        ok: false,
+        remediation: `NEXUS_DATA_DIR (${dir}) is not writable or creatable (${getErrorMessage(err)}) \u2014 fix its permissions; run \`nexus-agents doctor\` to diagnose`
+      };
+    }
+  }
+}
+var TOOL_PREREQUISITES = {
+  improvement_review: {
+    name: "gh-cli-available",
+    rationale: "improvement_review's fileIssues mode shells out to `gh` to file candidate issues; without it the write path fails mid-operation",
+    check: ghCliAvailable
+  },
+  memory_write: {
+    name: "data-dir-writable",
+    rationale: "memory_write persists entries under NEXUS_DATA_DIR \u2014 an unwritable data dir fails the write confusingly mid-operation",
+    check: dataDirWritable
+  },
+  registry_import: {
+    name: "data-dir-writable",
+    rationale: "registry_import persists a draft registry entry under NEXUS_DATA_DIR when not in dryRun mode",
+    check: dataDirWritable
+  }
+};
+function applyPrerequisite(toolName, prereq, handler) {
+  return async (args, ctx) => {
+    let result;
+    try {
+      result = await prereq.check();
+    } catch (err) {
+      result = { ok: false, remediation: `prerequisite check threw: ${getErrorMessage(err)}` };
+    }
+    if (!result.ok) {
+      return toolStructuredError({
+        errorCategory: "permission",
+        message: `${toolName} blocked: prerequisite '${prereq.name}' not satisfied`,
+        detail: {
+          failedPrerequisite: prereq.name,
+          rationale: prereq.rationale,
+          remediation: result.remediation ?? "see .rules/tool-prerequisites.md"
+        }
+      });
+    }
+    return handler(args, ctx);
+  };
+}
+function withPrerequisite(toolName, handler) {
+  const prereq = TOOL_PREREQUISITES[toolName];
+  if (prereq === void 0) return handler;
+  return applyPrerequisite(toolName, prereq, handler);
+}
+
+// src/governance/fitness-score.ts
+import { existsSync, readFileSync, readdirSync, statSync } from "fs";
+import { join } from "path";
+function findPkgRoot() {
+  let dir = import.meta.dirname;
+  for (let i = 0; i < 10; i++) {
+    const pkgPath = join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      const content = readFileSync(pkgPath, "utf-8");
+      if (content.includes('"nexus-agents"')) return dir;
+    }
+    dir = join(dir, "..");
+  }
+  return join(import.meta.dirname, "../..");
+}
+var PKG_ROOT = findPkgRoot();
+var SRC_ROOT = join(PKG_ROOT, "src");
+var REPO_ROOT = join(PKG_ROOT, "../..");
+var DOCS_ROOT = join(REPO_ROOT, "docs");
+var DETERMINISM_EXCLUDES = [
+  /\.test\.ts$/,
+  /\.spec\.ts$/,
+  /random-provider\.ts$/,
+  /time-provider\.ts$/
+];
+function countFiles(dir, pattern) {
+  if (!existsSync(dir)) return 0;
+  let count = 0;
+  for (const entry of readdirSync(dir)) {
+    const fullPath = join(dir, entry);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory() && !entry.startsWith(".")) {
+      count += countFiles(fullPath, pattern);
+    } else if (pattern.test(entry)) {
+      count++;
+    }
+  }
+  return count;
+}
+function fileContains(filePath, pattern) {
+  if (!existsSync(filePath)) return false;
+  return pattern.test(readFileSync(filePath, "utf-8"));
+}
+function isExcluded(entry, excludePatterns) {
+  return excludePatterns?.some((p) => p.test(entry)) ?? false;
+}
+function countMatchesInFile(fullPath, contentPattern) {
+  const matches = readFileSync(fullPath, "utf-8").match(contentPattern);
+  return matches?.length ?? 0;
+}
+function countPatternInDir(dir, filePattern, contentPattern, excludePatterns) {
+  if (!existsSync(dir)) return 0;
+  let count = 0;
+  for (const entry of readdirSync(dir)) {
+    const fullPath = join(dir, entry);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory() && !entry.startsWith(".") && entry !== "node_modules") {
+      count += countPatternInDir(fullPath, filePattern, contentPattern, excludePatterns);
+    } else if (filePattern.test(entry) && !isExcluded(entry, excludePatterns)) {
+      count += countMatchesInFile(fullPath, contentPattern);
+    }
+  }
+  return count;
+}
+function clamp(score, max) {
+  return Math.max(0, Math.min(max, score));
+}
+var FitnessScoreCalculator = class {
+  logger;
+  checks = [];
+  constructor(logger) {
+    this.logger = logger ?? createLogger({ component: "FitnessScoreCalculator" });
+    this.registerDefaultChecks();
+  }
+  /** Register default fitness checks. */
+  registerDefaultChecks() {
+    const reg = (dimension, maxPoints, name, check) => {
+      this.checks.push({ dimension, maxPoints, name, check });
+    };
+    reg("canonicalPaths", 20, "Canonical Paths", () => this.checkCanonicalPaths());
+    reg("explicitBehavior", 15, "Explicit Behavior", () => this.checkExplicitBehavior());
+    reg("determinism", 15, "Determinism", () => this.checkDeterminism());
+    reg("observability", 15, "Observability", () => this.checkObservability());
+    reg("configSimplicity", 10, "Config Simplicity", () => this.checkConfigSimplicity());
+    reg("layerSeparation", 10, "Layer Separation", () => this.checkLayerSeparation());
+    reg("operatorErgonomics", 10, "Operator Ergonomics", () => this.checkOperatorErgonomics());
+    reg(
+      "governanceIntegration",
+      5,
+      "Governance Integration",
+      () => this.checkGovernanceIntegration()
+    );
+  }
+  /** Run full fitness audit. */
+  audit(version) {
+    const findings = [];
+    const dimensions = {};
+    const cliAdaptersDir = join(SRC_ROOT, "cli-adapters");
+    if (!existsSync(cliAdaptersDir)) {
+      return this.notSourceRepoResult(version);
+    }
+    for (const check of this.checks) {
+      this.logger.debug(`Running fitness check: ${check.name}`);
+      const result = check.check();
+      dimensions[check.dimension] = result.score;
+      findings.push(...result.findings);
+    }
+    const score = Object.values(dimensions).reduce((sum, val) => sum + val, 0);
+    this.logger.info("Fitness audit complete", { score, version });
+    const safeDim = (k) => dimensions[k] ?? 0;
+    const typedDimensions = {
+      canonicalPaths: safeDim("canonicalPaths"),
+      explicitBehavior: safeDim("explicitBehavior"),
+      determinism: safeDim("determinism"),
+      observability: safeDim("observability"),
+      configSimplicity: safeDim("configSimplicity"),
+      layerSeparation: safeDim("layerSeparation"),
+      operatorErgonomics: safeDim("operatorErgonomics"),
+      governanceIntegration: safeDim("governanceIntegration")
+    };
+    return {
+      score,
+      dimensions: typedDimensions,
+      findings,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      version
+    };
+  }
+  /**
+   * Return when the runtime SRC_ROOT doesn't look like the nexus-agents
+   * source tree (#2716). One finding, score 0 — distinct from "the source
+   * tree is broken" because every existsSync would falsely report missing.
+   */
+  notSourceRepoResult(version) {
+    const finding = {
+      dimension: "governanceIntegration",
+      severity: "info",
+      description: `fitness-audit must run against the nexus-agents source repo, but ${SRC_ROOT}/cli-adapters does not exist. You are likely running the installed npm package via \`npx nexus-agents\`, which ships only the bundled dist/. Clone the source repo and run \`node packages/nexus-agents/dist/cli.js fitness-audit\` (or invoke \`pnpm fitness-audit\` from the workspace root).`,
+      pointsDeducted: 0
+    };
+    return {
+      score: 0,
+      dimensions: {
+        canonicalPaths: 0,
+        explicitBehavior: 0,
+        determinism: 0,
+        observability: 0,
+        configSimplicity: 0,
+        layerSeparation: 0,
+        operatorErgonomics: 0,
+        governanceIntegration: 0
+      },
+      findings: [finding],
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      version
+    };
+  }
+  // =========================================================================
+  // Individual Checks — real filesystem analysis
+  // =========================================================================
+  /**
+   * Check canonical paths: penalize duplicate router implementations.
+   *
+   * The current minimum is 6 (raised from 5 in #2063 after an audit):
+   *   1. composite-router — pipeline orchestrator
+   *   2. budget-router — budget/cost filtering
+   *   3. zero-router — hard-constraint exclusion
+   *   4. preference-router — user/task preference application
+   *   5. topsis-router — TOPSIS multi-criteria scoring
+   *   6. agreement-cascade-router — agreement-based cascade retry
+   *
+   * Each stage is distinct per CLAUDE.md's documented pipeline:
+   * Task → BudgetRouter → ZeroRouter → PreferenceRouter → TopsisRouter → Agreement → Model
+   */
+  checkCanonicalPaths() {
+    const findings = [];
+    let score = 20;
+    const routerCount = countFiles(join(SRC_ROOT, "cli-adapters"), /router\.ts$/);
+    const ROUTER_COUNT_THRESHOLD = 6;
+    if (routerCount > ROUTER_COUNT_THRESHOLD) {
+      const excess = routerCount - ROUTER_COUNT_THRESHOLD;
+      const deduction = Math.min(5, excess);
+      score -= deduction;
+      findings.push(
+        this.finding(
+          "canonicalPaths",
+          "warning",
+          `${String(routerCount)} router implementations found (target: <=${String(ROUTER_COUNT_THRESHOLD)})`,
+          deduction,
+          "Consolidate duplicate routers into CompositeRouter"
+        )
+      );
+    }
+    if (existsSync(join(SRC_ROOT, "cli-adapters/composite-router.ts"))) {
+      score += 2;
+    } else {
+      score -= 3;
+      findings.push(
+        this.finding(
+          "canonicalPaths",
+          "critical",
+          "CompositeRouter missing \u2014 no unified routing entry point",
+          3
+        )
+      );
+    }
+    score = this.checkOrchestratorInterface(score, findings);
+    return { score: clamp(score, 20), findings };
+  }
+  /** Sub-check for IOrchestrator interface and adapter wiring. */
+  checkOrchestratorInterface(score, findings) {
+    const orchPath = join(SRC_ROOT, "core/types/orchestrator.ts");
+    if (existsSync(orchPath) && fileContains(orchPath, /interface IOrchestrator/)) {
+      score += 3;
+    } else {
+      score -= 2;
+      findings.push(
+        this.finding("canonicalPaths", "warning", "No IOrchestrator interface in core/types", 2)
+      );
+    }
+    const adapterPath = join(SRC_ROOT, "orchestration/orchestrator-adapters.ts");
+    if (existsSync(adapterPath) && fileContains(adapterPath, /TechLeadAdapter|PuppeteerAdapter/)) {
+      score += 2;
+    }
+    return score;
+  }
+  /**
+   * Check explicit behavior: penalize hidden/magic behavior.
+   *
+   * Implementation is intentionally filesystem-signal-based (no AST parse).
+   * The `NEXUS_ALLOW_MOCK_ORCHESTRATION` guard and magic-routing pattern
+   * grep capture the observable failure modes that historically slipped
+   * past review. AST-based detection of implicit fallbacks was considered
+   * but not pursued — it would significantly widen this function's
+   * footprint and the filesystem signals already catch the recurring
+   * regressions. Revisit only if a new class of hidden-behavior bug
+   * surfaces that this grep-over-source approach can't catch.
+   */
+  checkExplicitBehavior() {
+    const findings = [];
+    let score = 15;
+    const mockGuardCount = countPatternInDir(
+      SRC_ROOT,
+      /\.ts$/,
+      /NEXUS_ALLOW_MOCK_ORCHESTRATION/g,
+      DETERMINISM_EXCLUDES
+    );
+    if (mockGuardCount === 0) {
+      score -= 3;
+      findings.push(
+        this.finding(
+          "explicitBehavior",
+          "warning",
+          "No NEXUS_ALLOW_MOCK_ORCHESTRATION guard found \u2014 mock fallback may be implicit",
+          3,
+          "Require explicit env var for mock orchestration"
+        )
+      );
+    }
+    const magicRouting = countPatternInDir(
+      SRC_ROOT,
+      /\.ts$/,
+      /fallback.*=.*true|implicitRoute/g,
+      DETERMINISM_EXCLUDES
+    );
+    if (magicRouting > 5) {
+      const deduction = Math.min(3, Math.floor(magicRouting / 3));
+      score -= deduction;
+      findings.push(
+        this.finding(
+          "explicitBehavior",
+          "info",
+          `${String(magicRouting)} implicit fallback/routing patterns detected`,
+          deduction
+        )
+      );
+    }
+    return { score: clamp(score, 15), findings };
+  }
+  /** Check determinism: penalize unseeded random and raw Date.now(). */
+  checkDeterminism() {
+    const findings = [];
+    let score = 15;
+    score = this.checkRandomDeterminism(score, findings);
+    score = this.checkTimeDeterminism(score, findings);
+    return { score: clamp(score, 15), findings };
+  }
+  /** Sub-check for Math.random() and injectable random provider. */
+  checkRandomDeterminism(score, findings) {
+    const randomCount = countPatternInDir(
+      SRC_ROOT,
+      /\.ts$/,
+      /Math\.random\(\)/g,
+      DETERMINISM_EXCLUDES
+    );
+    if (randomCount > 10) {
+      const deduction = Math.min(5, Math.floor(randomCount / 5));
+      score -= deduction;
+      findings.push(
+        this.finding(
+          "determinism",
+          "warning",
+          `${String(randomCount)} unseeded Math.random() calls in production code`,
+          deduction,
+          "Use getRandomProvider() for injectable randomness"
+        )
+      );
+    } else if (randomCount === 0) {
+      score += 2;
+    }
+    if (existsSync(join(SRC_ROOT, "core/random-provider.ts"))) {
+      score += 1;
+    }
+    const randomUsage = countPatternInDir(
+      SRC_ROOT,
+      /\.ts$/,
+      /getRandomProvider\(\)/g,
+      DETERMINISM_EXCLUDES
+    );
+    if (randomUsage > 5) {
+      score += 1;
+    }
+    return score;
+  }
+  /** Sub-check for Date.now() and injectable time provider. */
+  checkTimeDeterminism(score, findings) {
+    const dateNowCount = countPatternInDir(
+      SRC_ROOT,
+      /\.ts$/,
+      /Date\.now\(\)/g,
+      DETERMINISM_EXCLUDES
+    );
+    if (dateNowCount > 50) {
+      score -= 2;
+      findings.push(
+        this.finding(
+          "determinism",
+          "info",
+          `${String(dateNowCount)} Date.now() calls in production code`,
+          2,
+          "Use getTimeProvider() for injectable time"
+        )
+      );
+    }
+    if (existsSync(join(SRC_ROOT, "core/time-provider.ts"))) {
+      score += 1;
+    }
+    const timeUsage = countPatternInDir(
+      SRC_ROOT,
+      /\.ts$/,
+      /getTimeProvider\(\)/g,
+      DETERMINISM_EXCLUDES
+    );
+    if (timeUsage > 10) {
+      score += 1;
+    }
+    return score;
+  }
+  /** Check observability: reward tracing, logging, and audit coverage. */
+  checkObservability() {
+    const findings = [];
+    let score = 15;
+    if (existsSync(join(SRC_ROOT, "observability/swarm-observer.ts"))) {
+      score += 3;
+    } else {
+      score -= 3;
+      findings.push(
+        this.finding(
+          "observability",
+          "warning",
+          "No SwarmObserver found",
+          3,
+          "Add observability/swarm-observer.ts"
+        )
+      );
+    }
+    if (existsSync(join(SRC_ROOT, "core/trace.ts"))) {
+      score += 2;
+    }
+    const loggerCount = countPatternInDir(SRC_ROOT, /\.ts$/, /createLogger\(/g);
+    if (loggerCount > 50) {
+      score += 2;
+    } else {
+      findings.push(
+        this.finding(
+          "observability",
+          "info",
+          `Only ${String(loggerCount)} createLogger() calls (target: >50)`,
+          0
+        )
+      );
+    }
+    if (existsSync(join(SRC_ROOT, "audit"))) {
+      score += 2;
+    }
+    return { score: clamp(score, 15), findings };
+  }
+  /** Check config simplicity: penalize excessive schema sprawl. */
+  checkConfigSimplicity() {
+    const findings = [];
+    let score = 10;
+    const schemaCount = countFiles(join(SRC_ROOT, "config"), /schema.*\.ts$/);
+    if (schemaCount > 10) {
+      score -= 2;
+      findings.push(
+        this.finding(
+          "configSimplicity",
+          "info",
+          `${String(schemaCount)} config schemas (target: <=10)`,
+          2,
+          "Consolidate related schemas"
+        )
+      );
+    } else {
+      score += 1;
+    }
+    if (existsSync(join(SRC_ROOT, "config/config-loader.ts"))) {
+      score += 2;
+    }
+    if (existsSync(join(SRC_ROOT, "config/config-manager.ts"))) {
+      score += 1;
+    }
+    return { score: clamp(score, 10), findings };
+  }
+  /** Check layer separation: penalize cross-layer imports. */
+  checkLayerSeparation() {
+    const findings = [];
+    let score = 10;
+    const adapterAgentImports = countPatternInDir(
+      join(SRC_ROOT, "adapters"),
+      /\.ts$/,
+      /from ['"]\.\.\/agents\//g
+    );
+    if (adapterAgentImports > 0) {
+      const deduction = Math.min(5, adapterAgentImports);
+      score -= deduction;
+      findings.push(
+        this.finding(
+          "layerSeparation",
+          "warning",
+          `${String(adapterAgentImports)} adapter->agent import violations`,
+          deduction,
+          "Adapters should not import from agents layer"
+        )
+      );
+    } else {
+      score += 2;
+    }
+    const coreMcpImports = countPatternInDir(
+      join(SRC_ROOT, "core"),
+      /\.ts$/,
+      /from ['"]\.\.\/mcp\//g
+    );
+    if (coreMcpImports > 0) {
+      const deduction = Math.min(3, coreMcpImports);
+      score -= deduction;
+      findings.push(
+        this.finding(
+          "layerSeparation",
+          "critical",
+          `${String(coreMcpImports)} core->MCP import violations`,
+          deduction,
+          "Core must not depend on MCP layer"
+        )
+      );
+    } else {
+      score += 1;
+    }
+    return { score: clamp(score, 10), findings };
+  }
+  /** Check operator ergonomics: reward rich CLI commands. */
+  checkOperatorErgonomics() {
+    const findings = [];
+    let score = 10;
+    const commandCount = countFiles(join(SRC_ROOT, "cli"), /\.ts$/);
+    if (commandCount >= 20) {
+      score += 3;
+    } else {
+      findings.push(
+        this.finding(
+          "operatorErgonomics",
+          "info",
+          `${String(commandCount)} CLI commands (target: >=20)`,
+          0
+        )
+      );
+    }
+    score = this.checkCliCommands(score, findings);
+    return { score: clamp(score, 10), findings };
+  }
+  /** Sub-check for essential CLI commands (doctor, setup, demo, config). */
+  checkCliCommands(score, findings) {
+    const commands = [
+      ["cli/doctor.ts", "Doctor command", 2],
+      ["cli/setup-command.ts", "Setup wizard", 2],
+      ["cli/demo-command.ts", "Demo command", 1],
+      ["cli/config-command.ts", "Config command", 1]
+    ];
+    for (const [path, name, bonus] of commands) {
+      if (existsSync(join(SRC_ROOT, path))) {
+        score += bonus;
+      } else {
+        findings.push(this.finding("operatorErgonomics", "info", `Missing ${name} (${path})`, 0));
+      }
+    }
+    return score;
+  }
+  /** Check governance integration: policy firewall, rate limiter, docs. */
+  checkGovernanceIntegration() {
+    const findings = [];
+    let score = 5;
+    score = this.checkGovernanceDocs(score, findings);
+    score = this.checkGovernanceInfra(score, findings);
+    return { score: clamp(score, 5), findings };
+  }
+  /** Sub-check for governance documentation artifacts. */
+  checkGovernanceDocs(score, findings) {
+    if (!existsSync(join(REPO_ROOT, "CLAUDE.md"))) {
+      score -= 3;
+      findings.push(
+        this.finding("governanceIntegration", "critical", "No CLAUDE.md governance document", 3)
+      );
+    } else {
+      score += 1;
+    }
+    if (existsSync(join(DOCS_ROOT, "architecture/wiring-graph.json"))) {
+      score += 1;
+    }
+    if (existsSync(join(DOCS_ROOT, "adr"))) {
+      score += 1;
+    } else {
+      findings.push(this.finding("governanceIntegration", "info", "No ADR directory", 0));
+    }
+    return score;
+  }
+  /** Sub-check for governance runtime infrastructure. */
+  checkGovernanceInfra(score, findings) {
+    const hasPolicyFirewall = countPatternInDir(join(SRC_ROOT, "security"), /\.ts$/, /PolicyGate|policyFirewall/g) > 0;
+    if (hasPolicyFirewall) {
+      score += 1;
+    } else {
+      findings.push(
+        this.finding(
+          "governanceIntegration",
+          "warning",
+          "No policy firewall detected in security layer",
+          0
+        )
+      );
+    }
+    const hasRateLimiter = countPatternInDir(SRC_ROOT, /\.ts$/, /RateLimiter|rateLimiter/g) > 0;
+    if (hasRateLimiter) {
+      score += 1;
+    }
+    return score;
+  }
+  /** Helper to create a FitnessFinding with defaults. */
+  finding(dimension, severity, description2, pointsDeducted, suggestion) {
+    const base = { dimension, severity, description: description2, pointsDeducted };
+    if (suggestion !== void 0) {
+      return { ...base, suggestion };
+    }
+    return base;
+  }
+};
+function createFitnessScoreCalculator(logger) {
+  return new FitnessScoreCalculator(logger);
+}
+function calculateFitnessScore(version) {
+  const calculator = createFitnessScoreCalculator();
+  return calculator.audit(version);
+}
+
+// src/mcp/tools/improvement-review-signals.ts
+function worstDimension(audit) {
+  let worst;
+  for (const finding of audit.findings) {
+    if (worst === void 0 || finding.pointsDeducted > worst.pointsDeducted) {
+      worst = { dimension: finding.dimension, pointsDeducted: finding.pointsDeducted };
+    }
+  }
+  return worst?.dimension;
+}
+function emitFitnessDeclinedSignal(audit, fitnessFloor, bus, logger) {
+  if (audit.score >= fitnessFloor) return;
+  try {
+    const dimension = worstDimension(audit);
+    bus.emit({
+      type: "signal.fitness_declined",
+      timestamp: getTimeProvider().now(),
+      score: audit.score,
+      floor: fitnessFloor,
+      ...dimension !== void 0 ? { dimension } : {}
+    });
+  } catch (error) {
+    logger.warn("Failed to emit signal.fitness_declined", { error: getErrorMessage(error) });
+  }
+}
+
+// src/mcp/tools/improvement-review.ts
+var execFileAsync2 = promisify2(execFile2);
+var ImprovementReviewInputSchema = z.object({
+  lookbackDays: z.number().int().min(1).max(90).optional().default(7).describe("Lookback window for outcome data, in days. Default 7."),
+  fileIssues: z.boolean().optional().default(false).describe(
+    "When true, file candidate issues via `gh issue create` for crossed thresholds (rate-limited to 5 per run, deduped against open issues). When false (default), return signals only."
+  ),
+  minSampleSize: z.number().int().min(1).max(1e3).optional().default(5).describe("Minimum sample size before a CLI/category signal can fire."),
+  fitnessFloor: z.number().int().min(0).max(100).optional().default(90).describe("Fitness score below this threshold triggers a tech-debt signal."),
+  selfEvalReportPath: z.string().optional().describe(
+    "Optional path to a self-eval JSON report (from `self-eval --json`). When set, high-confidence unanimous deprecate/refactor findings are surfaced as tech-debt signals through the same deduped/rate-limited issue path (#3224). Unreadable/malformed reports are skipped (no signal). Absent \u2192 no self-eval signals."
+  )
+});
+var MAX_ISSUES_PER_RUN = 5;
+var HOUR_MS = 60 * 60 * 1e3;
+var DAY_MS = 24 * HOUR_MS;
+function filterByLookback(outcomes, lookbackDays, now) {
+  const cutoff = now - lookbackDays * DAY_MS;
+  return outcomes.filter((o) => {
+    const t = Date.parse(o.timestamp);
+    return Number.isFinite(t) && t >= cutoff;
+  });
+}
+function detectCliPerformanceFloor(outcomes, minSamples, windowLabel) {
+  const buckets = /* @__PURE__ */ new Map();
+  for (const o of outcomes) {
+    const key = `${o.cli}::${o.category}`;
+    const bucket = buckets.get(key) ?? { cli: o.cli, category: o.category, ok: 0, total: 0 };
+    bucket.total += 1;
+    if (o.success) bucket.ok += 1;
+    buckets.set(key, bucket);
+  }
+  const signals = [];
+  for (const b of buckets.values()) {
+    if (b.total < minSamples) continue;
+    const rate = b.ok / b.total;
+    if (rate >= 0.6) continue;
+    const ratePct = Math.round(rate * 100);
+    signals.push({
+      category: "routing",
+      signalKey: `routing:cli-floor:${b.cli}:${b.category}`,
+      severity: rate < 0.4 ? "critical" : "warning",
+      title: `routing: ${b.cli} success rate ${String(ratePct)}% on ${b.category} (${windowLabel})`,
+      body: [
+        `Observed performance floor breach in the ${windowLabel} window.`,
+        "",
+        `- CLI: \`${b.cli}\``,
+        `- Category: \`${b.category}\``,
+        `- Success rate: ${String(ratePct)}% (${String(b.ok)}/${String(b.total)})`,
+        `- Threshold: 60% with \u2265${String(minSamples)} samples`,
+        "",
+        "Consider routing this category away from this CLI, or investigating the failure pattern via `weather_report` and the OutcomeStore."
+      ].join("\n"),
+      evidence: {
+        samples: b.total,
+        window: windowLabel,
+        observedValue: rate,
+        threshold: 0.6
+      }
+    });
+  }
+  return signals;
+}
+function detectFailureCategoryConcentration(outcomes, windowLabel) {
+  const failures = outcomes.filter((o) => !o.success);
+  if (failures.length < 10) return [];
+  const byCategory = /* @__PURE__ */ new Map();
+  for (const f of failures) {
+    const cat = f.failureCategory ?? "unknown";
+    byCategory.set(cat, (byCategory.get(cat) ?? 0) + 1);
+  }
+  const signals = [];
+  for (const [cat, count] of byCategory) {
+    const share = count / failures.length;
+    if (share <= 0.5) continue;
+    const sharePct = Math.round(share * 100);
+    signals.push({
+      category: "bug",
+      signalKey: `bug:failure-concentration:${cat}`,
+      severity: "warning",
+      title: `bug: ${String(sharePct)}% of failures in ${windowLabel} share category \`${cat}\``,
+      body: [
+        `Failure-category concentration breach in the ${windowLabel} window.`,
+        "",
+        `- Category: \`${cat}\``,
+        `- Share: ${String(sharePct)}% (${String(count)}/${String(failures.length)} failures)`,
+        `- Threshold: > 50% with \u226510 failures`,
+        "",
+        "A single failure mode dominating the error budget usually means a systemic bug or routing miss. Investigate via `query_trace` and the OutcomeStore."
+      ].join("\n"),
+      evidence: {
+        samples: failures.length,
+        window: windowLabel,
+        observedValue: share,
+        threshold: 0.5
+      }
+    });
+  }
+  return signals;
+}
+function buildFloorSignal(audit, fitnessFloor) {
+  return {
+    category: "tech-debt",
+    signalKey: `tech-debt:fitness-below-floor`,
+    severity: audit.score < 70 ? "critical" : "warning",
+    title: `tech-debt: fitness score ${String(audit.score)}/100 below floor ${String(fitnessFloor)}`,
+    body: [
+      `Code fitness score has dropped below the governance floor.`,
+      "",
+      `- Score: ${String(audit.score)} / 100`,
+      `- Floor: ${String(fitnessFloor)} (governance threshold per CLAUDE.md)`,
+      `- Findings: ${String(audit.findings.length)} total`,
+      "",
+      "Run `nexus-agents fitness-audit` for the full breakdown. Critical findings:",
+      ...audit.findings.filter((f) => f.severity === "critical").slice(0, 5).map((f) => `- ${f.dimension}: ${f.description}`)
+    ].join("\n"),
+    evidence: { observedValue: audit.score, threshold: fitnessFloor }
+  };
+}
+function buildCriticalFindingSignal(finding) {
+  return {
+    category: "tech-debt",
+    signalKey: `tech-debt:fitness-critical:${finding.dimension}`,
+    severity: "critical",
+    title: `tech-debt: critical fitness finding in ${finding.dimension}`,
+    body: [
+      `Fitness audit returned a CRITICAL finding.`,
+      "",
+      `- Dimension: \`${finding.dimension}\``,
+      `- Description: ${finding.description}`,
+      `- Points deducted: ${String(finding.pointsDeducted)}`,
+      finding.location !== void 0 ? `- Location: ${finding.location}` : "",
+      finding.suggestion !== void 0 ? `- Suggestion: ${finding.suggestion}` : ""
+    ].filter((line) => line.length > 0).join("\n"),
+    evidence: { observedValue: -finding.pointsDeducted }
+  };
+}
+function detectFitnessSignals(audit, fitnessFloor) {
+  const signals = [];
+  if (audit.score < fitnessFloor) signals.push(buildFloorSignal(audit, fitnessFloor));
+  for (const finding of audit.findings) {
+    if (finding.severity === "critical") signals.push(buildCriticalFindingSignal(finding));
+  }
+  return signals;
+}
+var SELF_EVAL_CONFIDENCE_FLOOR = 0.8;
+var SelfEvalReportSchema = z.object({
+  results: z.array(
+    z.object({
+      component: z.string(),
+      finalRecommendation: z.string(),
+      confidence: z.number(),
+      dissent: z.array(z.unknown()).optional().default([]),
+      evidenceQuality: z.number().optional()
+    })
+  )
+});
+function detectSelfEvalSignals(report, windowLabel) {
+  const signals = [];
+  for (const r of report.results) {
+    const actionable = r.finalRecommendation === "deprecate" || r.finalRecommendation === "refactor";
+    if (!actionable || r.dissent.length > 0 || r.confidence < SELF_EVAL_CONFIDENCE_FLOOR) continue;
+    signals.push({
+      category: "tech-debt",
+      signalKey: `tech-debt:self-eval:${r.component}:${r.finalRecommendation}`,
+      severity: r.finalRecommendation === "deprecate" ? "warning" : "info",
+      title: `tech-debt: self-eval recommends ${r.finalRecommendation} for ${r.component}`,
+      body: [
+        `All self-eval evaluators agreed (no dissent) on **${r.finalRecommendation}** for \`${r.component}\``,
+        `with confidence ${(r.confidence * 100).toFixed(0)}%${r.evidenceQuality !== void 0 ? ` (evidence quality ${(r.evidenceQuality * 100).toFixed(0)}%)` : ""}.`,
+        "",
+        "This is a RECOMMENDATION surfaced for human review \u2014 not an automatic change."
+      ].join("\n"),
+      evidence: {
+        observedValue: r.confidence,
+        threshold: SELF_EVAL_CONFIDENCE_FLOOR,
+        window: windowLabel
+      }
+    });
+  }
+  return signals;
+}
+async function loadSelfEvalSignals(reportPath, windowLabel, logger) {
+  try {
+    const raw = await readFile(reportPath, "utf8");
+    const parsed = SelfEvalReportSchema.safeParse(JSON.parse(raw));
+    if (!parsed.success) {
+      logger.warn("Self-eval report ignored \u2014 schema mismatch", {
+        reportPath,
+        error: formatZodError(parsed.error)
+      });
+      return [];
+    }
+    return detectSelfEvalSignals(parsed.data, windowLabel);
+  } catch (error) {
+    logger.warn("Self-eval report ignored \u2014 unreadable/invalid JSON", {
+      reportPath,
+      error: getErrorMessage(error)
+    });
+    return [];
+  }
+}
+async function existingIssueForSignal(signalKey) {
+  try {
+    const searchTerm = signalKey.replace(/"/g, "");
+    const { stdout } = await execFileAsync2("gh", [
+      "issue",
+      "list",
+      "--state",
+      "open",
+      "--search",
+      `"${searchTerm}" in:body`,
+      "--json",
+      "number,url",
+      "--limit",
+      "5"
+    ]);
+    const parsed = JSON.parse(stdout);
+    if (parsed.length > 0 && typeof parsed[0]?.url === "string") {
+      return parsed[0].url;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function fileIssueForSignal(signal) {
+  const body = `${signal.body}
+
+---
+
+_Signal key (do not edit): \`${signal.signalKey}\` \xB7 Generated by \`improvement_review\` (#2402) \xB7 Severity: ${signal.severity}_`;
+  const labels = signal.category === "security" ? "security" : signal.category;
+  try {
+    const { stdout } = await execFileAsync2("gh", [
+      "issue",
+      "create",
+      "--title",
+      signal.title,
+      "--body",
+      body,
+      "--label",
+      labels
+    ]);
+    const url = stdout.trim();
+    if (!url.startsWith("https://")) {
+      return { ok: false, error: `gh returned unexpected output: ${stdout.slice(0, 200)}` };
+    }
+    return { ok: true, url };
+  } catch (caught) {
+    const message = caught instanceof Error ? caught.message : String(caught);
+    return { ok: false, error: message };
+  }
+}
+function safeFitnessAudit(now, ctx) {
+  try {
+    return calculateFitnessScore("improvement-review");
+  } catch (caught) {
+    ctx.logger.warn("fitness audit failed; skipping fitness signals", {
+      error: caught instanceof Error ? caught.message : String(caught)
+    });
+    return {
+      score: 100,
+      dimensions: {},
+      findings: [],
+      timestamp: new Date(now).toISOString(),
+      version: "improvement-review-fallback"
+    };
+  }
+}
+var SEVERITY_ORDER = {
+  critical: 0,
+  warning: 1,
+  info: 2
+};
+async function fileSignalsAsIssues(signals, ctx) {
+  const issuesFiled = [];
+  const issuesSkipped = [];
+  for (const signal of signals) {
+    if (issuesFiled.length >= MAX_ISSUES_PER_RUN) {
+      issuesSkipped.push({ signalKey: signal.signalKey, reason: "rate-limit" });
+      continue;
+    }
+    const existing = await existingIssueForSignal(signal.signalKey);
+    if (existing !== null) {
+      issuesSkipped.push({ signalKey: signal.signalKey, reason: `dup:${existing}` });
+      continue;
+    }
+    const result = await fileIssueForSignal(signal);
+    if (result.ok) {
+      issuesFiled.push({ signalKey: signal.signalKey, issueUrl: result.url });
+      ctx.logger.info("improvement signal filed", {
+        signalKey: signal.signalKey,
+        url: result.url
+      });
+    } else {
+      issuesSkipped.push({ signalKey: signal.signalKey, reason: `error:${result.error}` });
+    }
+  }
+  return { issuesFiled, issuesSkipped };
+}
+async function runImprovementReview(input, deps = {}) {
+  const logger = deps.logger ?? createLogger({ component: "improvement_review" });
+  const { lookbackDays, fileIssues, minSampleSize, fitnessFloor, selfEvalReportPath } = input;
+  const now = Date.now();
+  const windowLabel = `${String(lookbackDays)}d`;
+  const allOutcomes = getOutcomeStore().query();
+  const windowed = filterByLookback(allOutcomes, lookbackDays, now);
+  const audit = safeFitnessAudit(now, { logger });
+  const selfEvalSignals = selfEvalReportPath !== void 0 ? await loadSelfEvalSignals(selfEvalReportPath, windowLabel, logger) : [];
+  const signals = [
+    ...detectCliPerformanceFloor(windowed, minSampleSize, windowLabel),
+    ...detectFailureCategoryConcentration(windowed, windowLabel),
+    ...detectFitnessSignals(audit, fitnessFloor),
+    ...selfEvalSignals
+  ];
+  signals.sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
+  emitFitnessDeclinedSignal(audit, fitnessFloor, getPipelineEventBus(), logger);
+  const { issuesFiled, issuesSkipped } = fileIssues ? await fileSignalsAsIssues(signals, { logger }) : { issuesFiled: [], issuesSkipped: [] };
+  return {
+    window: windowLabel,
+    totalOutcomes: windowed.length,
+    signals,
+    issuesFiled,
+    issuesSkipped
+  };
+}
+async function reviewHandler(args, ctx) {
+  const parsed = ImprovementReviewInputSchema.safeParse(args);
+  if (!parsed.success) {
+    return toolStructuredError({
+      errorCategory: "validation",
+      message: `Validation error: ${formatZodError(parsed.error)}`
+    });
+  }
+  const response = await runImprovementReview(parsed.data, { logger: ctx.logger });
+  return toolSuccessStructured(response);
+}
+var description = "Periodic threshold-gated observability-driven improvement loop. Reads OutcomeStore + fitness audit, surfaces patterns crossing documented thresholds as candidate findings. When fileIssues=true, files candidate GitHub issues via `gh issue create` (rate-limited to 5 per run, deduped against open issues). Never auto-merges. Replaces the deleted self-development engine (#2402).";
+var TOOL_INPUT_SCHEMA = {
+  lookbackDays: z.number().int().min(1).max(90).optional().describe("Lookback window for outcome data, in days. Default 7."),
+  fileIssues: z.boolean().optional().describe(
+    "When true, file candidate issues for crossed thresholds (default false \u2014 return signals only)"
+  ),
+  minSampleSize: z.number().int().min(1).max(1e3).optional().describe("Minimum sample size before a CLI/category signal fires (default 5)."),
+  fitnessFloor: z.number().int().min(0).max(100).optional().describe("Fitness score below this threshold triggers a tech-debt signal (default 90)."),
+  selfEvalReportPath: z.string().optional().describe(
+    "Optional path to a self-eval JSON report. High-confidence unanimous deprecate/refactor findings surface as tech-debt signals (#3224)."
+  )
+};
+function registerImprovementReviewTool(server, deps) {
+  const logger = deps.logger ?? createLogger({ tool: "improvement_review" });
+  const secureHandler = createSecureHandler(reviewHandler, {
+    toolName: "improvement_review",
+    rateLimiter: deps.rateLimiter,
+    logger
+  });
+  const guardedHandler = withPrerequisite("improvement_review", secureHandler);
+  const timeoutMs = getToolTimeout("improvement_review", deps.security);
+  const wrappedHandler = wrapToolWithTimeout("improvement_review", guardedHandler, {
+    timeoutMs,
+    logger
+  });
+  server.registerTool(
+    "improvement_review",
+    {
+      description,
+      inputSchema: TOOL_INPUT_SCHEMA,
+      annotations: getToolAnnotations("improvement_review")
+    },
+    toSdkCallback(wrappedHandler)
+  );
+  logger.info("Registered improvement_review tool");
+}
+
+export {
+  withPrerequisite,
+  createFitnessScoreCalculator,
+  calculateFitnessScore,
+  ImprovementReviewInputSchema,
+  filterByLookback,
+  detectCliPerformanceFloor,
+  detectFailureCategoryConcentration,
+  detectFitnessSignals,
+  detectSelfEvalSignals,
+  loadSelfEvalSignals,
+  runImprovementReview,
+  registerImprovementReviewTool
+};
+//# sourceMappingURL=chunk-P2BKWVKF.js.map