@nathapp/nax 0.50.3 → 0.51.2

package/src/routing/router.ts

@@ -1,305 +0,0 @@
-/**
- * Task Router
- *
- * Routes stories using pluggable strategy system.
- * Falls back to keyword-based classification for backward compatibility.
- */
-
-import type { Complexity, ModelTier, NaxConfig, TddStrategy, TestStrategy } from "../config";
-import type { UserStory } from "../prd/types";
-import { buildStrategyChain } from "./builder";
-import type { RoutingContext } from "./strategy";
-
-/** Routing decision for a story */
-export interface RoutingDecision {
-  /** Classified complexity */
-  complexity: Complexity;
-  /** Model tier to use */
-  modelTier: ModelTier;
-  /** Test strategy to apply */
-  testStrategy: TestStrategy;
-  /** Reasoning for the classification */
-  reasoning: string;
-}
-
-/** Keywords that indicate higher complexity */
-const COMPLEX_KEYWORDS = [
-  "refactor",
-  "redesign",
-  "architecture",
-  "migration",
-  "breaking change",
-  "public api",
-  "security",
-  "auth",
-  "encryption",
-  "permission",
-  "rbac",
-  "casl",
-  "jwt",
-  "grpc",
-  "microservice",
-  "event-driven",
-  "saga",
-];
-
-const EXPERT_KEYWORDS = [
-  "cryptograph",
-  "zero-knowledge",
-  "distributed consensus",
-  "real-time",
-  "websocket",
-  "streaming",
-  "performance critical",
-];
-
-const SECURITY_KEYWORDS = [
-  "auth",
-  "security",
-  "permission",
-  "jwt",
-  "oauth",
-  "token",
-  "encryption",
-  "secret",
-  "credential",
-  "password",
-  "rbac",
-  "casl",
-];
-
-const PUBLIC_API_KEYWORDS = [
-  "public api",
-  "breaking change",
-  "external",
-  "consumer",
-  "sdk",
-  "npm publish",
-  "release",
-  "endpoint",
-];
-
-/**
- * Classify a story's complexity based on keywords and acceptance criteria count.
- *
- * Classification rules:
- * - expert: matches expert keywords (cryptography, distributed consensus, real-time)
- * - complex: matches complex keywords or >8 acceptance criteria
- * - medium: >4 acceptance criteria
- * - simple: default
- *
- * @param title - Story title
- * @param description - Story description
- * @param acceptanceCriteria - Array of acceptance criteria
- * @param tags - Optional story tags
- * @returns Classified complexity level
- *
- * @example
- * ```ts
- * classifyComplexity(
- *   "Add JWT authentication",
- *   "Implement JWT auth with refresh tokens",
- *   ["Secure token storage", "Token refresh", "Expiry handling"],
- *   ["security", "auth"]
- * );
- * // "complex" (matches security keywords)
- *
- * classifyComplexity(
- *   "Fix typo in README",
- *   "Correct spelling mistake",
- *   ["Update README.md"],
- *   []
- * );
- * // "simple"
- * ```
- */
-export function classifyComplexity(
-  title: string,
-  description: string,
-  acceptanceCriteria: string[],
-  tags: string[] = [],
-): Complexity {
-  const text = [title, description, ...(acceptanceCriteria ?? []), ...(tags ?? [])].join(" ").toLowerCase();
-
-  // Expert: matches expert keywords
-  if (EXPERT_KEYWORDS.some((kw) => text.includes(kw))) {
-    return "expert";
-  }
-
-  // Complex: matches complex keywords or has many criteria
-  if (COMPLEX_KEYWORDS.some((kw) => text.includes(kw)) || acceptanceCriteria.length > 8) {
-    return "complex";
-  }
-
-  // Medium: moderate criteria or some structural keywords
-  if (acceptanceCriteria.length > 4) {
-    return "medium";
-  }
-
-  return "simple";
-}
-
-/** Tags that indicate a lite-mode story (UI, layout, CLI, integration, polyglot) */
-const LITE_TAGS = ["ui", "layout", "cli", "integration", "polyglot"];
-
-/**
- * Determine test strategy using decision tree logic.
- *
- * When tddStrategy is provided:
- * - 'strict' → always three-session-tdd
- * - 'lite'   → always three-session-tdd-lite
- * - 'off'    → always test-after
- * - 'auto'   → existing heuristic logic, plus:
- *              if tags include ui/layout/cli/integration/polyglot → three-session-tdd-lite
- *              if security/public-api/complex/expert → three-session-tdd
- *              simple → tdd-simple, medium → three-session-tdd-lite
- *
- * @param complexity - Pre-classified complexity level
- * @param title - Story title
- * @param description - Story description
- * @param tags - Optional story tags
- * @param tddStrategy - TDD strategy override from config (default: 'auto')
- * @returns Test strategy
- *
- * @example
- * ```ts
- * determineTestStrategy("complex", "Add OAuth", "Implement OAuth 2.0", ["security", "auth"], "strict");
- * // "three-session-tdd"
- *
- * determineTestStrategy("simple", "Update button", "Change primary button", ["ui"], "auto");
- * // "three-session-tdd-lite"
- * ```
- */
-
-export function determineTestStrategy(
-  complexity: Complexity,
-  title: string,
-  description: string,
-  tags: string[] = [],
-  tddStrategy: TddStrategy = "auto",
-): TestStrategy {
-  // Explicit overrides — ignore all heuristics
-  if (tddStrategy === "strict") return "three-session-tdd";
-  if (tddStrategy === "lite") return "three-session-tdd-lite";
-  if (tddStrategy === "simple") return "tdd-simple";
-  if (tddStrategy === "off") return "test-after";
-
-  // auto mode: apply heuristics
-  const text = [title, description, ...(tags ?? [])].join(" ").toLowerCase();
-
-  // Public API or security → three-session-tdd (strict)
-  const isSecurityCritical = SECURITY_KEYWORDS.some((kw) => text.includes(kw));
-  const isPublicApi = PUBLIC_API_KEYWORDS.some((kw) => text.includes(kw));
-
-  if (isSecurityCritical || isPublicApi) {
-    return "three-session-tdd";
-  }
-
-  // Complex/expert heuristic
-  if (complexity === "complex" || complexity === "expert") {
-    const normalizedTags = (tags ?? []).map((t) => t.toLowerCase());
-    const hasLiteTag = LITE_TAGS.some((tag) => normalizedTags.includes(tag));
-    return hasLiteTag ? "three-session-tdd-lite" : "three-session-tdd";
-  }
-
-  // TS-001: simple → tdd-simple (TDD discipline, 1 session), medium → tdd-lite (3 sessions)
-  if (complexity === "simple") return "tdd-simple";
-  return "three-session-tdd-lite";
-}
-
-/** Map complexity to model tier */
-export function complexityToModelTier(complexity: Complexity, config: NaxConfig): ModelTier {
-  const mapping = config.autoMode.complexityRouting;
-  return (mapping[complexity] ?? "balanced") as ModelTier;
-}
-
-/**
- * Route a story using the pluggable strategy system.
- *
- * This is the new main entry point for the routing system. It:
- * 1. Builds the strategy chain based on config
- * 2. Routes the story through the chain
- * 3. Returns the first non-null decision
- *
- * @param story - User story to route
- * @param context - Routing context (config, codebase, metrics)
- * @param workdir - Working directory for resolving custom strategy paths
- * @param plugins - Optional plugin registry for plugin-provided routers
- * @returns Routing decision from the strategy chain
- *
- * @example
- * ```ts
- * const decision = await routeStory(story, { config }, "/path/to/project", plugins);
- * // {
- * //   complexity: "complex",
- * //   modelTier: "balanced",
- * //   testStrategy: "three-session-tdd",
- * //   reasoning: "three-session-tdd: security-critical, complexity:complex"
- * // }
- * ```
- */
-export async function routeStory(
-  story: UserStory,
-  context: RoutingContext,
-  workdir: string,
-  plugins?: import("../plugins/registry").PluginRegistry,
-): Promise<RoutingDecision> {
-  const chain = await buildStrategyChain(context.config, workdir, plugins);
-  return await chain.route(story, context);
-}
-
-/**
- * Route a task through complexity classification, model tier selection, and test strategy.
- *
- * DEPRECATED: Use routeStory() instead. This function is kept for backward compatibility
- * and uses only the keyword strategy.
- *
- * @param title - Story title
- * @param description - Story description
- * @param acceptanceCriteria - Array of acceptance criteria
- * @param tags - Story tags
- * @param config - nax configuration with complexity routing mappings
- * @returns Routing decision with complexity, model tier, test strategy, and reasoning
- *
- * @deprecated Use routeStory() with a UserStory object instead
- */
-export function routeTask(
-  title: string,
-  description: string,
-  acceptanceCriteria: string[],
-  tags: string[],
-  config: NaxConfig,
-): RoutingDecision {
-  const complexity = classifyComplexity(title, description, acceptanceCriteria, tags);
-  const modelTier = complexityToModelTier(complexity, config);
-  const tddStrategy: TddStrategy = config.tdd?.strategy ?? "auto";
-  const testStrategy = determineTestStrategy(complexity, title, description, tags, tddStrategy);
-
-  const reasons: string[] = [];
-  const text = [title, description, ...(tags ?? [])].join(" ").toLowerCase();
-  const normalizedTags = (tags ?? []).map((t) => t.toLowerCase());
-  const hasLiteTag = LITE_TAGS.some((tag) => normalizedTags.includes(tag));
-
-  if (SECURITY_KEYWORDS.some((kw) => text.includes(kw))) reasons.push("security-critical");
-  if (PUBLIC_API_KEYWORDS.some((kw) => text.includes(kw))) reasons.push("public-api");
-
-  // Only add complexity reason if it's the primary reason for strict/lite TDD
-  if (complexity === "complex" || complexity === "expert") {
-    if (reasons.length === 0) {
-      reasons.push(`complexity:${complexity}`);
-    }
-  }
-
-  if (tddStrategy !== "auto") reasons.push(`strategy:${tddStrategy}`);
-  if (hasLiteTag && (complexity === "complex" || complexity === "expert")) {
-    reasons.push("lite-tags");
-  }
-
-  const prefix = testStrategy;
-  return {
-    complexity,
-    modelTier,
-    testStrategy,
-    reasoning: reasons.length > 0 ? `${prefix}: ${reasons.join(", ")}` : `test-after: simple task (${complexity})`,
-  };
-}

package/src/routing/strategies/adaptive.ts

@@ -1,215 +0,0 @@
-/**
- * Adaptive Routing Strategy
- *
- * Uses historical metrics to optimize model tier selection based on cost-effectiveness.
- * Routes to the cheapest tier that maintains acceptable success rates, accounting for
- * escalation costs.
- */
-
-import type { Complexity, ModelTier } from "../../config";
-import type { AggregateMetrics } from "../../metrics/types";
-import type { UserStory } from "../../prd/types";
-import type { RoutingContext, RoutingDecision, RoutingStrategy } from "../strategy";
-import { keywordStrategy } from "./keyword";
-
-/**
- * Estimated costs per model tier (USD per story, approximate).
- * These are rough estimates based on typical story complexity.
- * Actual costs vary based on input/output tokens.
- */
-const ESTIMATED_TIER_COSTS: Record<ModelTier, number> = {
-  fast: 0.005, // ~$0.005 per simple story
-  balanced: 0.02, // ~$0.02 per medium story
-  powerful: 0.08, // ~$0.08 per complex story
-};
-
-/**
- * Calculate effective cost for a model tier given historical metrics.
- *
- * effectiveCost = baseCost + (failRate × escalationCost)
- *
- * Where:
- * - baseCost = cost of using this tier
- * - failRate = probability of failure (requiring escalation)
- * - escalationCost = cost of escalating to next tier
- *
- * @param tier - Model tier to evaluate
- * @param complexity - Story complexity level
- * @param metrics - Historical aggregate metrics
- * @param tierOrder - Escalation tier order
- * @returns Effective cost (USD)
- */
-function calculateEffectiveCost(
-  tier: ModelTier,
-  complexity: Complexity,
-  metrics: AggregateMetrics,
-  tierOrder: ModelTier[],
-): number {
-  const baseCost = ESTIMATED_TIER_COSTS[tier];
-
-  // Get historical pass rate for this tier on this complexity level
-  const complexityStats = metrics.complexityAccuracy[complexity];
-  if (!complexityStats || complexityStats.predicted < 1) {
-    // No data for this complexity level — assume base cost (no escalation)
-    return baseCost;
-  }
-
-  // Calculate fail rate (stories that needed escalation)
-  // mismatchRate = percentage of stories where initial tier != final tier
-  const failRate = complexityStats.mismatchRate;
-
-  // Find next tier in escalation chain
-  const currentIndex = tierOrder.indexOf(tier);
-  const nextTier = currentIndex < tierOrder.length - 1 ? tierOrder[currentIndex + 1] : null;
-
-  if (!nextTier) {
-    // Already at highest tier — no escalation possible
-    return baseCost;
-  }
-
-  // Escalation cost = cost of trying this tier + cost of next tier
-  const escalationCost = ESTIMATED_TIER_COSTS[nextTier];
-
-  return baseCost + failRate * escalationCost;
-}
-
-/**
- * Find the most cost-effective tier for a given complexity level.
- *
- * Evaluates all tiers in the escalation chain and selects the one with
- * the lowest effective cost (including escalation probability).
- *
- * @param complexity - Story complexity
- * @param metrics - Historical metrics
- * @param tierOrder - Escalation tier order
- * @param costThreshold - Switch threshold (0-1)
- * @returns Best tier and reasoning
- */
-function selectOptimalTier(
-  complexity: Complexity,
-  metrics: AggregateMetrics,
-  tierOrder: ModelTier[],
-  costThreshold: number,
-): { tier: ModelTier; reasoning: string } {
-  // Calculate effective cost for each tier
-  const costs = tierOrder.map((tier) => ({
-    tier,
-    effectiveCost: calculateEffectiveCost(tier, complexity, metrics, tierOrder),
-  }));
-
-  // Sort by effective cost (lowest first)
-  costs.sort((a, b) => a.effectiveCost - b.effectiveCost);
-
-  const optimal = costs[0];
-  const complexityStats = metrics.complexityAccuracy[complexity];
-
-  // If the cheapest tier's effective cost is within threshold of next tier, use it
-  const reasoning = complexityStats
-    ? `adaptive: ${complexity} → ${optimal.tier} (cost: $${optimal.effectiveCost.toFixed(4)}, ` +
-      `samples: ${complexityStats.predicted}, mismatch: ${(complexityStats.mismatchRate * 100).toFixed(1)}%)`
-    : `adaptive: ${complexity} → ${optimal.tier} (insufficient data, using base cost: $${optimal.effectiveCost.toFixed(4)})`;
-
-  return { tier: optimal.tier, reasoning };
-}
-
-/**
- * Check if there's sufficient data for adaptive routing.
- *
- * @param complexity - Story complexity
- * @param metrics - Historical metrics
- * @param minSamples - Minimum samples required
- * @returns True if sufficient data exists
- */
-function hasSufficientData(complexity: Complexity, metrics: AggregateMetrics, minSamples: number): boolean {
-  const complexityStats = metrics.complexityAccuracy[complexity];
-  return Boolean(complexityStats && complexityStats.predicted >= minSamples);
-}
-
-/**
- * Adaptive routing strategy.
- *
- * Uses historical metrics to select the most cost-effective model tier.
- * Falls back to configured strategy when insufficient data is available.
- *
- * Algorithm:
- * 1. Check if sufficient historical data exists (>= minSamples)
- * 2. If yes: Calculate effective cost for each tier (base + fail × escalation)
- * 3. Select tier with lowest effective cost
- * 4. If no: Delegate to fallback strategy
- *
- * @example
- * ```ts
- * const decision = adaptiveStrategy.route(story, context);
- * // With sufficient data:
- * // {
- * //   complexity: "medium",
- * //   modelTier: "fast",
- * //   reasoning: "adaptive: medium → fast (cost: $0.0078, samples: 23, mismatch: 12.5%)"
- * // }
- * //
- * // Without sufficient data:
- * // {
- * //   complexity: "medium",
- * //   modelTier: "balanced",
- * //   reasoning: "adaptive: insufficient data (7/10 samples) → fallback to llm"
- * // }
- * ```
- */
-export const adaptiveStrategy: RoutingStrategy = {
-  name: "adaptive",
-
-  async route(story: UserStory, context: RoutingContext): Promise<RoutingDecision | null> {
-    const { config, metrics } = context;
-
-    // Require metrics to be present - use keyword as ultimate fallback
-    if (!metrics) {
-      const fallbackStrategy = config.routing.adaptive?.fallbackStrategy || "llm";
-      const decision = await keywordStrategy.route(story, context); // keyword never returns null
-      if (!decision) return null;
-
-      return {
-        ...decision,
-        reasoning: `adaptive: no metrics available → fallback to ${fallbackStrategy}`,
-      };
-    }
-
-    // Get adaptive config
-    const adaptiveConfig = config.routing.adaptive || {
-      minSamples: 10,
-      costThreshold: 0.8,
-      fallbackStrategy: "llm" as const,
-    };
-
-    // First, classify complexity using fallback strategy
-    // (We need to know complexity before checking metrics)
-    // Always use keyword as the classification source since it never returns null
-    const fallbackDecision = await keywordStrategy.route(story, context);
-    if (!fallbackDecision) return null;
-
-    const complexity = fallbackDecision.complexity;
-
-    // Check if we have sufficient historical data for this complexity
-    if (!hasSufficientData(complexity, metrics, adaptiveConfig.minSamples)) {
-      const complexityStats = metrics.complexityAccuracy[complexity];
-      const sampleCount = complexityStats?.predicted || 0;
-
-      return {
-        ...fallbackDecision,
-        reasoning:
-          `adaptive: insufficient data (${sampleCount}/${adaptiveConfig.minSamples} samples) ` +
-          `→ fallback to ${adaptiveConfig.fallbackStrategy}`,
-      };
-    }
-
-    // We have sufficient data — calculate optimal tier
-    const tierOrder = config.autoMode.escalation.tierOrder.map((t) => t.tier);
-    const { tier, reasoning } = selectOptimalTier(complexity, metrics, tierOrder, adaptiveConfig.costThreshold);
-
-    return {
-      complexity,
-      modelTier: tier,
-      testStrategy: fallbackDecision.testStrategy, // Use fallback's test strategy decision
-      reasoning,
-    };
-  },
-};

package/src/routing/strategies/index.ts

@@ -1,8 +0,0 @@
-/**
- * Built-in Routing Strategies
- */
-
-export { keywordStrategy } from "./keyword";
-export { llmStrategy } from "./llm";
-export { manualStrategy } from "./manual";
-export { adaptiveStrategy } from "./adaptive";

package/src/routing/strategies/keyword.ts

@@ -1,180 +0,0 @@
-/**
- * Keyword-Based Routing Strategy
- *
- * Routes stories based on keyword matching and acceptance criteria count.
- * This is the default fallback strategy — always returns a decision (never null).
- */
-
-import type { Complexity, ModelTier, TestStrategy } from "../../config";
-import type { UserStory } from "../../prd/types";
-import type { RoutingContext, RoutingDecision, RoutingStrategy } from "../strategy";
-
-/** Keywords that indicate higher complexity */
-const COMPLEX_KEYWORDS = [
-  "refactor",
-  "redesign",
-  "architecture",
-  "migration",
-  "breaking change",
-  "public api",
-  "security",
-  "auth",
-  "encryption",
-  "permission",
-  "rbac",
-  "casl",
-  "jwt",
-  "grpc",
-  "microservice",
-  "event-driven",
-  "saga",
-];
-
-const EXPERT_KEYWORDS = [
-  "cryptograph",
-  "zero-knowledge",
-  "distributed consensus",
-  "real-time",
-  "websocket",
-  "streaming",
-  "performance critical",
-];
-
-const SECURITY_KEYWORDS = [
-  "auth",
-  "security",
-  "permission",
-  "jwt",
-  "oauth",
-  "token",
-  "encryption",
-  "secret",
-  "credential",
-  "password",
-  "rbac",
-  "casl",
-];
-
-const PUBLIC_API_KEYWORDS = [
-  "public api",
-  "breaking change",
-  "external",
-  "consumer",
-  "sdk",
-  "npm publish",
-  "release",
-  "endpoint",
-];
-
-/**
- * Classify complexity based on keywords and criteria count.
- */
-function classifyComplexity(
-  title: string,
-  _description: string,
-  acceptanceCriteria: string[],
-  tags: string[] = [],
-): Complexity {
-  // BUG-031: Exclude description — it accumulates priorErrors across retries and
-  // causes classification drift. Only use stable, immutable story fields.
-  const text = [title, ...acceptanceCriteria, ...tags].join(" ").toLowerCase();
-
-  if (EXPERT_KEYWORDS.some((kw) => text.includes(kw))) {
-    return "expert";
-  }
-
-  if (COMPLEX_KEYWORDS.some((kw) => text.includes(kw)) || acceptanceCriteria.length > 8) {
-    return "complex";
-  }
-
-  if (acceptanceCriteria.length > 4) {
-    return "medium";
-  }
-
-  return "simple";
-}
-
-/**
- * Determine test strategy using decision tree.
- */
-function determineTestStrategy(
-  complexity: Complexity,
-  title: string,
-  _description: string,
-  tags: string[] = [],
-): TestStrategy {
-  // BUG-031: Exclude description — only use stable, immutable story fields.
-  const text = [title, ...tags].join(" ").toLowerCase();
-
-  const isSecurityCritical = SECURITY_KEYWORDS.some((kw) => text.includes(kw));
-  const isPublicApi = PUBLIC_API_KEYWORDS.some((kw) => text.includes(kw));
-
-  if (isSecurityCritical || isPublicApi) {
-    return "three-session-tdd";
-  }
-
-  if (complexity === "complex" || complexity === "expert") {
-    return "three-session-tdd";
-  }
-
-  // TS-001: simple → tdd-simple (TDD discipline, 1 session), medium → tdd-lite (3 sessions)
-  if (complexity === "simple") return "tdd-simple";
-  return "three-session-tdd-lite";
-}
-
-/** Map complexity to model tier */
-function complexityToModelTier(complexity: Complexity, context: RoutingContext): ModelTier {
-  const mapping = context.config.autoMode.complexityRouting;
-  return (mapping[complexity] ?? "balanced") as ModelTier;
-}
-
-/**
- * Keyword-based routing strategy.
- *
- * This strategy:
- * - Classifies complexity based on keywords and criteria count
- * - Maps complexity to model tier via config
- * - Applies test strategy decision tree
- * - ALWAYS returns a decision (never null)
- *
- * Use as the final fallback strategy in a chain.
- */
-export const keywordStrategy: RoutingStrategy = {
-  name: "keyword",
-
-  route(story: UserStory, context: RoutingContext): RoutingDecision {
-    const { title, description, acceptanceCriteria, tags } = story;
-
-    const complexity = classifyComplexity(title, description, acceptanceCriteria, tags);
-    const modelTier = complexityToModelTier(complexity, context);
-    const testStrategy = determineTestStrategy(complexity, title, description, tags);
-
-    const reasons: string[] = [];
-    const text = [title, description, ...tags].join(" ").toLowerCase();
-
-    if (testStrategy === "three-session-tdd") {
-      if (SECURITY_KEYWORDS.some((kw) => text.includes(kw))) reasons.push("security-critical");
-      if (PUBLIC_API_KEYWORDS.some((kw) => text.includes(kw))) reasons.push("public-api");
-      if (complexity === "complex" || complexity === "expert") reasons.push(`complexity:${complexity}`);
-    }
-
-    let reasoning = "";
-    if (testStrategy === "three-session-tdd") {
-      reasoning =
-        reasons.length > 0 ? `three-session-tdd: ${reasons.join(", ")}` : `three-session-tdd: ${complexity} task`;
-    } else if (testStrategy === "three-session-tdd-lite") {
-      reasoning = `three-session-tdd-lite: simple task (${complexity})`;
-    } else if (testStrategy === "tdd-simple") {
-      reasoning = `tdd-simple: simple task (${complexity})`;
-    } else {
-      reasoning = `${testStrategy}: ${complexity} task`;
-    }
-
-    return {
-      complexity,
-      modelTier,
-      testStrategy,
-      reasoning,
-    };
-  },
-};