@nathapp/nax 0.50.3 → 0.51.2

package/src/pipeline/stages/completion.ts

@@ -1,110 +0,0 @@
-// RE-ARCH: keep
-/**
- * Completion Stage
- *
- * Marks stories as passed, logs progress, emits lifecycle events.
- * This is the final stage in the pipeline for successful executions.
- *
- * Phase 3 (ADR-005): Replaced direct fireHook() calls with event bus emissions.
- * The hooks/reporters subscriber wires those events to actual hook/reporter calls.
- *
- * @returns
- * - `continue`: Stories marked complete, events emitted
- */
-
-import { appendProgress } from "../../execution/progress";
-import { checkReviewGate, isTriggerEnabled } from "../../interaction/triggers";
-import { getLogger } from "../../logger";
-import { collectBatchMetrics, collectStoryMetrics } from "../../metrics";
-import { countStories, markStoryPassed, savePRD } from "../../prd";
-import { pipelineEventBus } from "../event-bus";
-import type { PipelineContext, PipelineStage, StageResult } from "../types";
-
-export const completionStage: PipelineStage = {
-  name: "completion",
-  enabled: () => true,
-
-  async execute(ctx: PipelineContext): Promise<StageResult> {
-    const logger = getLogger();
-    const isBatch = ctx.stories.length > 1;
-    const sessionCost = ctx.agentResult?.estimatedCost || 0;
-
-    // Calculate PRD path
-    const prdPath = ctx.featureDir ? `${ctx.featureDir}/prd.json` : `${ctx.workdir}/nax/features/unknown/prd.json`;
-
-    // Collect story metrics
-    const storyStartTime = ctx.storyStartTime || new Date().toISOString();
-    if (isBatch) {
-      ctx.storyMetrics = collectBatchMetrics(ctx, storyStartTime);
-    } else {
-      ctx.storyMetrics = [collectStoryMetrics(ctx, storyStartTime)];
-    }
-
-    // Mark all stories in batch as passed
-    for (const completedStory of ctx.stories) {
-      markStoryPassed(ctx.prd, completedStory.id);
-
-      const costPerStory = sessionCost / ctx.stories.length;
-      logger.info("completion", "Story passed", {
-        storyId: completedStory.id,
-        cost: costPerStory,
-      });
-
-      // Log progress
-      if (ctx.featureDir) {
-        await appendProgress(
-          ctx.featureDir,
-          completedStory.id,
-          "passed",
-          `${completedStory.title} — Cost: $${costPerStory.toFixed(4)}${isBatch ? " (batched)" : ""}`,
-        );
-      }
-
-      // Emit story:completed event — hooks + reporter subscribers handle the rest
-      const storyMetric = ctx.storyMetrics?.find((m) => m.storyId === completedStory.id) ?? ctx.storyMetrics?.[0];
-      pipelineEventBus.emit({
-        type: "story:completed",
-        storyId: completedStory.id,
-        story: completedStory,
-        passed: true,
-        runElapsedMs: storyMetric?.durationMs ?? 0,
-        cost: costPerStory,
-        modelTier: ctx.routing?.modelTier,
-        testStrategy: ctx.routing?.testStrategy,
-      });
-
-      // review-gate trigger: check if story needs re-review after passing
-      if (ctx.interaction && isTriggerEnabled("review-gate", ctx.config)) {
-        const shouldContinue = await _completionDeps.checkReviewGate(
-          { featureName: ctx.prd.feature, storyId: completedStory.id },
-          ctx.config,
-          ctx.interaction,
-        );
-        if (!shouldContinue) {
-          logger.warn("completion", "Story marked for re-review", { storyId: completedStory.id });
-        }
-      }
-    }
-
-    // Save PRD
-    await savePRD(ctx.prd, prdPath);
-
-    // Display progress
-    const updatedCounts = countStories(ctx.prd);
-    logger.info("completion", "Progress update", {
-      completed: updatedCounts.passed + updatedCounts.failed,
-      total: updatedCounts.total,
-      passed: updatedCounts.passed,
-      failed: updatedCounts.failed,
-    });
-
-    return { action: "continue" };
-  },
-};
-
-/**
- * Swappable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
- */
-export const _completionDeps = {
-  checkReviewGate,
-};

package/src/pipeline/stages/constitution.ts

@@ -1,63 +0,0 @@
-/**
- * Constitution Stage
- *
- * Loads the project constitution (if enabled) and stores it in context.
- * Constitution defines coding standards, architectural rules, and forbidden patterns.
- *
- * @returns
- * - `continue`: Always continues (soft failure if constitution missing)
- *
- * @example
- * ```ts
- * // Constitution enabled and found
- * await constitutionStage.execute(ctx);
- * // ctx.constitution: { content: "...", tokens: 500, truncated: false }
- *
- * // Constitution enabled but not found
- * await constitutionStage.execute(ctx);
- * // ctx.constitution: undefined (stage logs warning and continues)
- * ```
- */
-
-import { dirname } from "node:path";
-import { loadConstitution } from "../../constitution";
-import { getLogger } from "../../logger";
-import type { PipelineContext, PipelineStage, StageResult } from "../types";
-
-export const constitutionStage: PipelineStage = {
-  name: "constitution",
-  enabled: (ctx) => ctx.config.constitution.enabled,
-
-  async execute(ctx: PipelineContext): Promise<StageResult> {
-    const logger = getLogger();
-
-    // Constitution file is in nax/constitution.md
-    // featureDir is nax/features/<name>/, so we need to go up two levels
-    const ngentDir = ctx.featureDir ? dirname(dirname(ctx.featureDir)) : `${ctx.workdir}/nax`;
-
-    const result = await loadConstitution(ngentDir, ctx.config.constitution);
-
-    if (result) {
-      ctx.constitution = result;
-
-      logger.debug("constitution", "Constitution loaded", {
-        tokens: result.tokens,
-        truncated: result.truncated,
-      });
-
-      if (result.truncated) {
-        logger.warn("constitution", "Constitution truncated", {
-          originalTokens: result.originalTokens,
-          tokens: result.tokens,
-          maxTokens: ctx.config.constitution.maxTokens,
-        });
-      }
-    } else {
-      // SOFT FAILURE: Constitution missing or failed to load — continue without it
-      // This is acceptable because constitution is optional project governance
-      logger.debug("constitution", "Constitution not found or failed to load");
-    }
-
-    return { action: "continue" };
-  },
-};

package/src/pipeline/stages/context.ts

@@ -1,122 +0,0 @@
-/**
- * Context Stage
- *
- * Builds contextual information for the agent from the PRD and related stories.
- * After building core context, calls plugin context providers to inject external data.
- * Formats as markdown for inclusion in the prompt.
- *
- * @returns
- * - `continue`: Always continues (soft failure if context empty)
- *
- * @example
- * ```ts
- * // PRD has related stories with context
- * await contextStage.execute(ctx);
- * // ctx.contextMarkdown: "## Related Stories\n- US-001: ..."
- *
- * // No related context found
- * await contextStage.execute(ctx);
- * // ctx.contextMarkdown: "" (empty but continues)
- * ```
- */
-
-import { join } from "node:path";
-import type { ContextElement } from "../../context/types";
-import { buildStoryContextFull } from "../../execution/helpers";
-import { getLogger } from "../../logger";
-import { errorMessage } from "../../utils/errors";
-import type { PipelineContext, PipelineStage, StageResult } from "../types";
-
-export const contextStage: PipelineStage = {
-  name: "context",
-  enabled: () => true,
-
-  async execute(ctx: PipelineContext): Promise<StageResult> {
-    const logger = getLogger();
-
-    // MW-003: resolve package workdir for per-package context.md loading
-    const packageWorkdir = ctx.story.workdir ? join(ctx.workdir, ctx.story.workdir) : undefined;
-
-    // Build context from PRD with element-level tracking
-    const result = await buildStoryContextFull(ctx.prd, ctx.story, ctx.config, packageWorkdir);
-
-    // SOFT FAILURE: Empty context is acceptable — agent can work without PRD context
-    // This happens when no relevant stories/context is found, which is normal
-    if (result) {
-      ctx.contextMarkdown = result.markdown;
-      ctx.builtContext = result.builtContext;
-    } else {
-      // Initialize contextMarkdown to empty string if no PRD context was built
-      ctx.contextMarkdown = ctx.contextMarkdown || "";
-    }
-
-    // Add plugin context if any providers are registered
-    if (ctx.plugins) {
-      const providers = ctx.plugins.getContextProviders();
-      if (providers.length > 0) {
-        logger.info("context", `Running ${providers.length} plugin context provider(s)`);
-
-        const pluginElements: ContextElement[] = [];
-        let pluginTokensUsed = 0;
-        const tokenBudget = ctx.config.execution.contextProviderTokenBudget;
-
-        for (const provider of providers) {
-          // Check if we have budget remaining
-          if (pluginTokensUsed >= tokenBudget) {
-            logger.info("context", "Plugin context budget exhausted, skipping remaining providers");
-            break;
-          }
-
-          try {
-            logger.info("context", `Fetching context from plugin: ${provider.name}`);
-            const providerResult = await provider.getContext(ctx.story);
-
-            // Check if adding this provider's content would exceed budget
-            if (pluginTokensUsed + providerResult.estimatedTokens > tokenBudget) {
-              logger.info("context", `Skipping plugin ${provider.name}: would exceed budget`);
-              break;
-            }
-
-            // Add plugin context as a new element
-            pluginElements.push({
-              type: "file", // Reuse file type for external context
-              content: `## ${providerResult.label}\n\n${providerResult.content}`,
-              priority: 50, // Medium priority (between dependencies and errors)
-              tokens: providerResult.estimatedTokens,
-            });
-
-            pluginTokensUsed += providerResult.estimatedTokens;
-            logger.info(
-              "context",
-              `Added context from plugin ${provider.name} (${providerResult.estimatedTokens} tokens)`,
-            );
-          } catch (error) {
-            logger.error("context", `Plugin context provider error: ${provider.name}`, {
-              error: errorMessage(error),
-            });
-            // Continue with other providers on error (soft failure)
-          }
-        }
-
-        // Append plugin context to existing markdown
-        if (pluginElements.length > 0) {
-          const pluginMarkdown = pluginElements.map((el) => el.content).join("\n\n");
-          ctx.contextMarkdown = ctx.contextMarkdown ? `${ctx.contextMarkdown}\n\n${pluginMarkdown}` : pluginMarkdown;
-
-          // Update built context with plugin elements
-          if (ctx.builtContext) {
-            ctx.builtContext.elements.push(...pluginElements);
-            ctx.builtContext.totalTokens += pluginTokensUsed;
-          }
-
-          logger.info(
-            "context",
-            `Added ${pluginElements.length} plugin context element(s) (${pluginTokensUsed} tokens total)`,
-          );
-        }
-      }
-    }
-
-    return { action: "continue" };
-  },
-};

package/src/pipeline/stages/execution.ts

@@ -1,359 +0,0 @@
-/**
- * Execution Stage
- *
- * Spawns the agent session(s) to execute the story/stories.
- * Handles both single-session (test-after) and three-session TDD.
- *
- * @returns
- * - `continue`: Agent session succeeded
- * - `fail`: Agent not found or prompt missing
- * - `escalate`: Agent session failed (will retry with higher tier)
- * - `pause`: Three-session TDD fallback (backward compatible, no failureCategory)
- *
- * TDD failure routing by failureCategory:
- * - `isolation-violation` (strict mode) → escalate + ctx.retryAsLite=true
- * - `isolation-violation` (lite mode)   → escalate
- * - `session-failure`                   → escalate
- * - `tests-failing`                     → escalate
- * - `verifier-rejected`                 → escalate
- * - `greenfield-no-tests`               → escalate (tier-escalation switches to test-after)
- * - no category / unknown               → pause (backward compatible)
- *
- * @example
- * ```ts
- * // Single session (test-after)
- * await executionStage.execute(ctx);
- * // ctx.agentResult: { success: true, estimatedCost: 0.05, ... }
- *
- * // Three-session TDD
- * await executionStage.execute(ctx);
- * // ctx.agentResult: { success: true, estimatedCost: 0.15, ... }
- * ```
- */
-
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import { getAgent, validateAgentForTier } from "../../agents";
-import { resolveModel } from "../../config";
-import { resolvePermissions } from "../../config/permissions";
-import { checkMergeConflict, checkStoryAmbiguity, isTriggerEnabled } from "../../interaction/triggers";
-import { getLogger } from "../../logger";
-import type { FailureCategory } from "../../tdd";
-import { runThreeSessionTdd } from "../../tdd";
-import { autoCommitIfDirty, detectMergeConflict } from "../../utils/git";
-import type { PipelineContext, PipelineStage, StageResult } from "../types";
-
-/**
- * Resolve the effective working directory for a story.
- * When story.workdir is set, returns join(repoRoot, story.workdir).
- * Otherwise returns the repo root unchanged.
- *
- * MW-001 runtime check: throws if the resolved workdir does not exist on disk.
- */
-export function resolveStoryWorkdir(repoRoot: string, storyWorkdir?: string): string {
-  if (!storyWorkdir) return repoRoot;
-  const resolved = join(repoRoot, storyWorkdir);
-  if (!existsSync(resolved)) {
-    throw new Error(`[execution] story.workdir "${storyWorkdir}" does not exist at "${resolved}"`);
-  }
-  return resolved;
-}
-
-/**
- * Detect if agent output contains ambiguity signals
- * Checks for keywords that indicate the agent is unsure about the implementation
- */
-export function isAmbiguousOutput(output: string): boolean {
-  if (!output) return false;
-
-  const ambiguityKeywords = [
-    "unclear",
-    "ambiguous",
-    "need clarification",
-    "please clarify",
-    "which one",
-    "not sure which",
-  ];
-
-  const lowerOutput = output.toLowerCase();
-  return ambiguityKeywords.some((keyword) => lowerOutput.includes(keyword));
-}
-
-/**
- * Determine the pipeline action for a failed TDD result, based on its failureCategory.
- *
- * This is a pure routing function — it mutates only `ctx.retryAsLite` when needed.
- * Exported for unit testing.
- *
- * @param failureCategory  - Category set by the TDD orchestrator (or undefined)
- * @param isLiteMode       - Whether the story was running in tdd-lite mode
- * @param ctx              - Pipeline context (mutated: ctx.retryAsLite may be set)
- * @param reviewReason     - Human-readable reason string from the TDD result
- */
-export function routeTddFailure(
-  failureCategory: FailureCategory | undefined,
-  isLiteMode: boolean,
-  ctx: Pick<PipelineContext, "retryAsLite">,
-  reviewReason?: string,
-): StageResult {
-  if (failureCategory === "isolation-violation") {
-    // Strict mode: request a lite-mode retry on next attempt
-    if (!isLiteMode) {
-      ctx.retryAsLite = true;
-    }
-    return { action: "escalate" };
-  }
-
-  if (
-    failureCategory === "session-failure" ||
-    failureCategory === "tests-failing" ||
-    failureCategory === "verifier-rejected"
-  ) {
-    return { action: "escalate" };
-  }
-
-  // S5: greenfield-no-tests → escalate so tier-escalation can switch to test-after
-  if (failureCategory === "greenfield-no-tests") {
-    return { action: "escalate" };
-  }
-
-  // Default: no category or unknown — backward-compatible pause for human review
-  return {
-    action: "pause",
-    reason: reviewReason || "Three-session TDD requires review",
-  };
-}
-
-export const executionStage: PipelineStage = {
-  name: "execution",
-  enabled: () => true,
-
-  async execute(ctx: PipelineContext): Promise<StageResult> {
-    const logger = getLogger();
-
-    // HARD FAILURE: No agent available — cannot proceed without an agent
-    const agent = (ctx.agentGetFn ?? _executionDeps.getAgent)(ctx.config.autoMode.defaultAgent);
-    if (!agent) {
-      return {
-        action: "fail",
-        reason: `Agent "${ctx.config.autoMode.defaultAgent}" not found`,
-      };
-    }
-
-    // Three-session TDD path (respect tdd.enabled config)
-    const isTddStrategy =
-      ctx.routing.testStrategy === "three-session-tdd" || ctx.routing.testStrategy === "three-session-tdd-lite";
-    const isLiteMode = ctx.routing.testStrategy === "three-session-tdd-lite";
-
-    // TYPE-2 fix: TddConfig has no enabled field, removed dead code
-    if (isTddStrategy) {
-      logger.info("execution", `Starting three-session TDD${isLiteMode ? " (lite)" : ""}`, {
-        storyId: ctx.story.id,
-        lite: isLiteMode,
-      });
-
-      const effectiveWorkdir = _executionDeps.resolveStoryWorkdir(ctx.workdir, ctx.story.workdir);
-
-      const tddResult = await runThreeSessionTdd({
-        agent,
-        story: ctx.story,
-        config: ctx.config,
-        workdir: effectiveWorkdir,
-        modelTier: ctx.routing.modelTier,
-        featureName: ctx.prd.feature,
-        contextMarkdown: ctx.contextMarkdown,
-        constitution: ctx.constitution?.content,
-        dryRun: false,
-        lite: isLiteMode,
-      });
-
-      ctx.agentResult = {
-        success: tddResult.success,
-        estimatedCost: tddResult.totalCost,
-        rateLimited: false,
-        output: "",
-        exitCode: tddResult.success ? 0 : 1,
-        durationMs: 0, // TDD result doesn't track total duration
-      };
-
-      // Propagate full-suite gate result so verify stage can skip redundant run (BUG-054)
-      if (tddResult.fullSuiteGatePassed) {
-        ctx.fullSuiteGatePassed = true;
-      }
-
-      if (!tddResult.success) {
-        // Store failure category in context for runner to use at max-attempts decision
-        ctx.tddFailureCategory = tddResult.failureCategory;
-
-        // Log and notify when human review is needed
-        if (tddResult.needsHumanReview) {
-          logger.warn("execution", "Human review needed", {
-            storyId: ctx.story.id,
-            reason: tddResult.reviewReason,
-            lite: tddResult.lite,
-            failureCategory: tddResult.failureCategory,
-          });
-          // Send notification via interaction chain (Telegram in headless mode)
-          if (ctx.interaction) {
-            try {
-              await ctx.interaction.send({
-                id: `human-review-${ctx.story.id}-${Date.now()}`,
-                type: "notify",
-                featureName: ctx.featureDir ? (ctx.featureDir.split("/").pop() ?? "unknown") : "unknown",
-                storyId: ctx.story.id,
-                stage: "execution",
-                summary: `⚠️ Human review needed: ${ctx.story.id}`,
-                detail: `Story: ${ctx.story.title}\nReason: ${tddResult.reviewReason ?? "No reason provided"}\nCategory: ${tddResult.failureCategory ?? "unknown"}`,
-                fallback: "continue",
-                createdAt: Date.now(),
-              });
-            } catch (notifyErr) {
-              logger.warn("execution", "Failed to send human review notification", {
-                storyId: ctx.story.id,
-                error: String(notifyErr),
-              });
-            }
-          }
-        }
-
-        return routeTddFailure(tddResult.failureCategory, isLiteMode, ctx, tddResult.reviewReason);
-      }
-
-      return { action: "continue" };
-    }
-
-    // Single/batch session (test-after) path
-    // HARD FAILURE: Missing prompt indicates pipeline misconfiguration
-    if (!ctx.prompt) {
-      return { action: "fail", reason: "Prompt not built (prompt stage skipped?)" };
-    }
-
-    // Validate agent supports the requested tier
-    if (!_executionDeps.validateAgentForTier(agent, ctx.routing.modelTier)) {
-      logger.warn("execution", "Agent tier mismatch", {
-        storyId: ctx.story.id,
-        agentName: agent.name,
-        requestedTier: ctx.routing.modelTier,
-        supportedTiers: agent.capabilities.supportedTiers,
-      });
-    }
-
-    const storyWorkdir = _executionDeps.resolveStoryWorkdir(ctx.workdir, ctx.story.workdir);
-
-    const result = await agent.run({
-      prompt: ctx.prompt,
-      workdir: storyWorkdir,
-      modelTier: ctx.routing.modelTier,
-      modelDef: resolveModel(ctx.config.models[ctx.routing.modelTier]),
-      timeoutSeconds: ctx.config.execution.sessionTimeoutSeconds,
-      dangerouslySkipPermissions: resolvePermissions(ctx.config, "run").skipPermissions,
-      pipelineStage: "run",
-      config: ctx.config,
-      maxInteractionTurns: ctx.config.agent?.maxInteractionTurns,
-      pidRegistry: ctx.pidRegistry,
-      featureName: ctx.prd.feature,
-      storyId: ctx.story.id,
-      // No sessionRole for single-session strategies (no role suffix in session name)
-      interactionBridge: (() => {
-        const plugin = ctx.interaction?.getPrimary();
-        if (!plugin) return undefined;
-        const QUESTION_PATTERNS = [/\?/, /\bwhich\b/i, /\bshould i\b/i, /\bunclear\b/i, /\bplease clarify\b/i];
-        return {
-          detectQuestion: async (text: string) => QUESTION_PATTERNS.some((p) => p.test(text)),
-          onQuestionDetected: async (text: string) => {
-            const requestId = `ix-acp-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
-            await plugin.send({
-              id: requestId,
-              type: "input",
-              featureName: ctx.prd.feature,
-              storyId: ctx.story.id,
-              stage: "execution",
-              summary: text,
-              fallback: "continue",
-              createdAt: Date.now(),
-            });
-            try {
-              const response = await plugin.receive(requestId, 120_000);
-              return response.value ?? "continue";
-            } catch {
-              return "continue";
-            }
-          },
-        };
-      })(),
-    });
-
-    ctx.agentResult = result;
-
-    // BUG-058: Auto-commit if agent left uncommitted changes (single-session/test-after)
-    await autoCommitIfDirty(storyWorkdir, "execution", "single-session", ctx.story.id);
-
-    // merge-conflict trigger: detect CONFLICT markers in agent output
-    const combinedOutput = (result.output ?? "") + (result.stderr ?? "");
-    if (
-      _executionDeps.detectMergeConflict(combinedOutput) &&
-      ctx.interaction &&
-      isTriggerEnabled("merge-conflict", ctx.config)
-    ) {
-      const shouldProceed = await _executionDeps.checkMergeConflict(
-        { featureName: ctx.prd.feature, storyId: ctx.story.id },
-        ctx.config,
-        ctx.interaction,
-      );
-      if (!shouldProceed) {
-        logger.error("execution", "Merge conflict detected — aborting story", { storyId: ctx.story.id });
-        return { action: "fail", reason: "Merge conflict detected" };
-      }
-    }
-
-    // story-ambiguity trigger: detect ambiguity signals in agent output
-    if (
-      result.success &&
-      _executionDeps.isAmbiguousOutput(combinedOutput) &&
-      ctx.interaction &&
-      isTriggerEnabled("story-ambiguity", ctx.config)
-    ) {
-      const shouldContinue = await _executionDeps.checkStoryAmbiguity(
-        { featureName: ctx.prd.feature, storyId: ctx.story.id, reason: "Agent output suggests ambiguity" },
-        ctx.config,
-        ctx.interaction,
-      );
-      if (!shouldContinue) {
-        logger.warn("execution", "Story ambiguity detected — escalating story", { storyId: ctx.story.id });
-        return { action: "escalate", reason: "Story ambiguity detected — needs clarification" };
-      }
-    }
-
-    if (!result.success) {
-      logger.error("execution", "Agent session failed", {
-        exitCode: result.exitCode,
-        stderr: result.stderr || "",
-        rateLimited: result.rateLimited,
-        storyId: ctx.story.id,
-      });
-      if (result.rateLimited) {
-        logger.warn("execution", "Rate limited — will retry", { storyId: ctx.story.id });
-      }
-      return { action: "escalate" };
-    }
-
-    logger.info("execution", "Agent session complete", {
-      storyId: ctx.story.id,
-      cost: result.estimatedCost,
-    });
-    return { action: "continue" };
-  },
-};
-
-/**
- * Swappable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
- */
-export const _executionDeps = {
-  getAgent,
-  validateAgentForTier,
-  detectMergeConflict,
-  checkMergeConflict,
-  isAmbiguousOutput,
-  checkStoryAmbiguity,
-  resolveStoryWorkdir,
-};