@nathapp/nax 0.18.1

package/src/routing/router.ts

@@ -0,0 +1,303 @@
+/**
+ * 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
+ *              otherwise → test-after
+ *
+ * @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 === "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";
+  }
+
+  // Simple/medium → test-after (default)
+  return "test-after";
+}
+
+/** 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

@@ -0,0 +1,215 @@
+/**
+ * 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

@@ -0,0 +1,8 @@
+/**
+ * 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

@@ -0,0 +1,163 @@
+/**
+ * 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 {
+  const text = [title, description, ...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 {
+  const text = [title, description, ...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";
+  }
+
+  return "test-after";
+}
+
+/** 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[] = [];
+    if (testStrategy === "three-session-tdd") {
+      const text = [title, description, ...tags].join(" ").toLowerCase();
+      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}`);
+    }
+
+    return {
+      complexity,
+      modelTier,
+      testStrategy,
+      reasoning:
+        reasons.length > 0 ? `three-session-tdd: ${reasons.join(", ")}` : `test-after: simple task (${complexity})`,
+    };
+  },
+};