@nathapp/nax 0.49.1 → 0.49.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.49.1",
+  "version": "0.49.6",
   "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {

package/src/agents/acp/adapter.ts

@@ -261,23 +261,37 @@ function acpSessionsPath(workdir: string, featureName: string): string {
   return join(workdir, "nax", "features", featureName, "acp-sessions.json");
 }
 
+/** Sidecar entry — session name + agent name for correct sweep/close. */
+type SidecarEntry = string | { sessionName: string; agentName: string };
+
+/** Extract sessionName from a sidecar entry (handles legacy string format). */
+function sidecarSessionName(entry: SidecarEntry): string {
+  return typeof entry === "string" ? entry : entry.sessionName;
+}
+
+/** Extract agentName from a sidecar entry (defaults to "claude" for legacy entries). */
+function sidecarAgentName(entry: SidecarEntry): string {
+  return typeof entry === "string" ? "claude" : entry.agentName;
+}
+
 /** Persist a session name to the sidecar file. Best-effort — errors are swallowed. */
 export async function saveAcpSession(
   workdir: string,
   featureName: string,
   storyId: string,
   sessionName: string,
+  agentName = "claude",
 ): Promise<void> {
   try {
     const path = acpSessionsPath(workdir, featureName);
-    let data: Record<string, string> = {};
+    let data: Record<string, SidecarEntry> = {};
     try {
       const existing = await Bun.file(path).text();
       data = JSON.parse(existing);
     } catch {
       // File doesn't exist yet — start fresh
     }
-    data[storyId] = sessionName;
+    data[storyId] = { sessionName, agentName };
     await Bun.write(path, JSON.stringify(data, null, 2));
   } catch (err) {
     getSafeLogger()?.warn("acp-adapter", "Failed to save session to sidecar", { error: String(err) });
@@ -307,8 +321,9 @@ export async function readAcpSession(workdir: string, featureName: string, story
   try {
     const path = acpSessionsPath(workdir, featureName);
     const existing = await Bun.file(path).text();
-    const data: Record<string, string> = JSON.parse(existing);
-    return data[storyId] ?? null;
+    const data: Record<string, SidecarEntry> = JSON.parse(existing);
+    const entry = data[storyId];
+    return entry ? sidecarSessionName(entry) : null;
   } catch {
     return null;
   }
@@ -326,10 +341,10 @@ const MAX_SESSION_AGE_MS = 2 * 60 * 60 * 1000; // 2 hours
  */
 export async function sweepFeatureSessions(workdir: string, featureName: string): Promise<void> {
   const path = acpSessionsPath(workdir, featureName);
-  let sessions: Record<string, string>;
+  let sessions: Record<string, SidecarEntry>;
   try {
     const text = await Bun.file(path).text();
-    sessions = JSON.parse(text) as Record<string, string>;
+    sessions = JSON.parse(text) as Record<string, SidecarEntry>;
   } catch {
     return; // No sidecar — nothing to sweep
   }
@@ -340,24 +355,35 @@ export async function sweepFeatureSessions(workdir: string, featureName: string)
   const logger = getSafeLogger();
   logger?.info("acp-adapter", `[sweep] Closing ${entries.length} open sessions for feature: ${featureName}`);
 
-  const cmdStr = "acpx claude";
-  const client = _acpAdapterDeps.createClient(cmdStr, workdir);
-  try {
-    await client.start();
-    for (const [, sessionName] of entries) {
-      try {
-        if (client.loadSession) {
-          const session = await client.loadSession(sessionName, "claude", "approve-reads");
-          if (session) {
-            await session.close().catch(() => {});
+  // Group sessions by agent name so we create one client per agent
+  const byAgent = new Map<string, string[]>();
+  for (const [, entry] of entries) {
+    const agent = sidecarAgentName(entry);
+    const name = sidecarSessionName(entry);
+    if (!byAgent.has(agent)) byAgent.set(agent, []);
+    byAgent.get(agent)?.push(name);
+  }
+
+  for (const [agentName, sessionNames] of byAgent) {
+    const cmdStr = `acpx ${agentName}`;
+    const client = _acpAdapterDeps.createClient(cmdStr, workdir);
+    try {
+      await client.start();
+      for (const sessionName of sessionNames) {
+        try {
+          if (client.loadSession) {
+            const session = await client.loadSession(sessionName, agentName, "approve-reads");
+            if (session) {
+              await session.close().catch(() => {});
+            }
           }
+        } catch (err) {
+          logger?.warn("acp-adapter", `[sweep] Failed to close session ${sessionName}`, { error: String(err) });
         }
-      } catch (err) {
-        logger?.warn("acp-adapter", `[sweep] Failed to close session ${sessionName}`, { error: String(err) });
       }
+    } finally {
+      await client.close().catch(() => {});
     }
-  } finally {
-    await client.close().catch(() => {});
   }
 
   // Clear sidecar after sweep
@@ -554,7 +580,7 @@ export class AcpAgentAdapter implements AgentAdapter {
 
     // 4. Persist for plan→run continuity
     if (options.featureName && options.storyId) {
-      await saveAcpSession(options.workdir, options.featureName, options.storyId, sessionName);
+      await saveAcpSession(options.workdir, options.featureName, options.storyId, sessionName, this.name);
     }
 
     let lastResponse: AcpSessionResponse | null = null;
@@ -635,13 +661,17 @@ export class AcpAgentAdapter implements AgentAdapter {
     } finally {
       // 6. Cleanup — close session and clear sidecar only on success.
       // On failure, keep session open so retry can resume with full context.
-      if (runState.succeeded) {
+      // When keepSessionOpen=true (e.g. rectification loop), skip close even on success
+      // so all attempts share the same conversation context.
+      if (runState.succeeded && !options.keepSessionOpen) {
         await closeAcpSession(session);
         if (options.featureName && options.storyId) {
           await clearAcpSession(options.workdir, options.featureName, options.storyId);
         }
-      } else {
+      } else if (!runState.succeeded) {
         getSafeLogger()?.info("acp-adapter", "Keeping session open for retry", { sessionName });
+      } else {
+        getSafeLogger()?.debug("acp-adapter", "Keeping session open (keepSessionOpen=true)", { sessionName });
       }
       await client.close().catch(() => {});
     }

package/src/agents/acp/spawn-client.ts

@@ -272,7 +272,6 @@ export class SpawnAcpClient implements AcpClient {
   private readonly model: string;
   private readonly cwd: string;
   private readonly timeoutSeconds: number;
-  private readonly permissionMode: string;
   private readonly env: Record<string, string | undefined>;
   private readonly pidRegistry?: PidRegistry;
 
@@ -289,7 +288,6 @@ export class SpawnAcpClient implements AcpClient {
     this.agentName = lastToken;
     this.cwd = cwd || process.cwd();
     this.timeoutSeconds = timeoutSeconds || 1800;
-    this.permissionMode = "approve-reads";
     this.env = buildAllowedEnv();
     this.pidRegistry = pidRegistry;
   }

package/src/agents/claude/execution.ts

@@ -126,6 +126,20 @@ export async function executeOnce(
   const cmd = _runOnceDeps.buildCmd(binary, options);
   const startTime = Date.now();
 
+  // Log session-related options for traceability. CLI adapter doesn't use sessions,
+  // but the pipeline passes these uniformly. Logged so future CLI session support
+  // can verify they're threaded correctly.
+  if (options.sessionRole || options.acpSessionName || options.keepSessionOpen) {
+    const logger = getLogger();
+    logger.debug("agent", "CLI mode: session options received (unused)", {
+      sessionRole: options.sessionRole,
+      acpSessionName: options.acpSessionName,
+      keepSessionOpen: options.keepSessionOpen,
+      featureName: options.featureName,
+      storyId: options.storyId,
+    });
+  }
+
   const proc = Bun.spawn(cmd, {
     cwd: options.workdir,
     stdout: "pipe",

package/src/agents/types.ts

@@ -84,6 +84,13 @@ export interface AgentRunOptions {
   pipelineStage?: import("../config/permissions").PipelineStage;
   /** Full nax config — passed through so adapters can call resolvePermissions() */
   config?: NaxConfig;
+  /**
+   * When true, the adapter will NOT close the session after a successful run.
+   * Use this for rectification loops where the same session must persist across
+   * multiple attempts so the agent retains full conversation context.
+   * The caller is responsible for closing the session when the loop is done.
+   */
+  keepSessionOpen?: boolean;
 }
 
 /**

package/src/cli/prompts-main.ts

@@ -13,7 +13,11 @@ import type { PipelineContext } from "../pipeline";
 import { constitutionStage, contextStage, promptStage, routingStage } from "../pipeline/stages";
 import type { UserStory } from "../prd";
 import { loadPRD } from "../prd";
+// buildFrontmatter lives in prompts-shared to avoid circular import with prompts-tdd.
+// Import for local use + re-export to preserve the public API via prompts.ts.
+import { buildFrontmatter } from "./prompts-shared";
 import { handleThreeSessionTddPrompts } from "./prompts-tdd";
+export { buildFrontmatter };
 
 export interface PromptsCommandOptions {
   /** Feature name */
@@ -177,62 +181,3 @@ export async function promptsCommand(options: PromptsCommandOptions): Promise<st
 
   return processedStories;
 }
-
-/**
- * Build YAML frontmatter for a story prompt.
- *
- * Uses actual token counts from BuiltContext elements (computed by context builder
- * using CHARS_PER_TOKEN=3) rather than re-estimating independently.
- *
- * @param story - User story
- * @param ctx - Pipeline context after running prompt assembly
- * @param role - Optional role for three-session TDD (test-writer, implementer, verifier)
- * @returns YAML frontmatter string (without delimiters)
- */
-export function buildFrontmatter(story: UserStory, ctx: PipelineContext, role?: string): string {
-  const lines: string[] = [];
-
-  lines.push(`storyId: ${story.id}`);
-  lines.push(`title: "${story.title}"`);
-  lines.push(`testStrategy: ${ctx.routing.testStrategy}`);
-  lines.push(`modelTier: ${ctx.routing.modelTier}`);
-
-  if (role) {
-    lines.push(`role: ${role}`);
-  }
-
-  // Use actual token counts from BuiltContext if available
-  const builtContext = ctx.builtContext;
-  const contextTokens = builtContext?.totalTokens ?? 0;
-  const promptTokens = ctx.prompt ? Math.ceil(ctx.prompt.length / 3) : 0;
-
-  lines.push(`contextTokens: ${contextTokens}`);
-  lines.push(`promptTokens: ${promptTokens}`);
-
-  // Dependencies
-  if (story.dependencies && story.dependencies.length > 0) {
-    lines.push(`dependencies: [${story.dependencies.join(", ")}]`);
-  }
-
-  // Context elements breakdown from actual BuiltContext
-  lines.push("contextElements:");
-
-  if (builtContext) {
-    for (const element of builtContext.elements) {
-      lines.push(`  - type: ${element.type}`);
-      if (element.storyId) {
-        lines.push(`    storyId: ${element.storyId}`);
-      }
-      if (element.filePath) {
-        lines.push(`    filePath: ${element.filePath}`);
-      }
-      lines.push(`    tokens: ${element.tokens}`);
-    }
-  }
-
-  if (builtContext?.truncated) {
-    lines.push("truncated: true");
-  }
-
-  return `${lines.join("\n")}\n`;
-}

package/src/cli/prompts-shared.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared Prompts Utilities
+ *
+ * Functions shared between prompts-main and prompts-tdd to avoid circular imports.
+ * Both modules need buildFrontmatter; keeping it here breaks the cycle:
+ *   prompts-main → prompts-tdd (was circular)
+ *   now both → prompts-shared
+ */
+
+import type { PipelineContext } from "../pipeline";
+import type { UserStory } from "../prd";
+
+/**
+ * Build YAML frontmatter for a prompt file.
+ *
+ * Token counts use actual BuiltContext values (computed during pipeline execution,
+ * using CHARS_PER_TOKEN=3) rather than re-estimating independently.
+ *
+ * @param story - User story
+ * @param ctx - Pipeline context after running prompt assembly
+ * @param role - Optional role for three-session TDD (test-writer, implementer, verifier)
+ * @returns YAML frontmatter string (without delimiters)
+ */
+export function buildFrontmatter(story: UserStory, ctx: PipelineContext, role?: string): string {
+  const lines: string[] = [];
+
+  lines.push(`storyId: ${story.id}`);
+  lines.push(`title: "${story.title}"`);
+  lines.push(`testStrategy: ${ctx.routing.testStrategy}`);
+  lines.push(`modelTier: ${ctx.routing.modelTier}`);
+
+  if (role) {
+    lines.push(`role: ${role}`);
+  }
+
+  // Use actual token counts from BuiltContext if available
+  const builtContext = ctx.builtContext;
+  const contextTokens = builtContext?.totalTokens ?? 0;
+  const promptTokens = ctx.prompt ? Math.ceil(ctx.prompt.length / 3) : 0;
+
+  lines.push(`contextTokens: ${contextTokens}`);
+  lines.push(`promptTokens: ${promptTokens}`);
+
+  // Dependencies
+  if (story.dependencies && story.dependencies.length > 0) {
+    lines.push(`dependencies: [${story.dependencies.join(", ")}]`);
+  }
+
+  // Context elements breakdown from actual BuiltContext
+  lines.push("contextElements:");
+
+  if (builtContext) {
+    for (const element of builtContext.elements) {
+      lines.push(`  - type: ${element.type}`);
+      if (element.storyId) {
+        lines.push(`    storyId: ${element.storyId}`);
+      }
+      if (element.filePath) {
+        lines.push(`    filePath: ${element.filePath}`);
+      }
+      lines.push(`    tokens: ${element.tokens}`);
+    }
+  }
+
+  if (builtContext?.truncated) {
+    lines.push("truncated: true");
+  }
+
+  return `${lines.join("\n")}\n`;
+}

package/src/cli/prompts-tdd.ts

@@ -9,7 +9,7 @@ import type { getLogger } from "../logger";
 import type { PipelineContext } from "../pipeline";
 import type { UserStory } from "../prd";
 import { PromptBuilder } from "../prompts";
-import { buildFrontmatter } from "./prompts-main";
+import { buildFrontmatter } from "./prompts-shared";
 
 /**
  * Handle three-session TDD prompts by building separate prompts for each role.

package/src/config/merge.ts

@@ -55,6 +55,24 @@ export function mergePackageConfig(root: NaxConfig, packageOverride: Partial<Nax
       ...packageOverride.review,
       commands: {
         ...root.review.commands,
+        // PKG-006: Bridge quality.commands → review.commands for per-package overrides.
+        // Users naturally put per-package commands in quality.commands (the intuitive
+        // place), but the review runner reads review.commands. Bridge them here so
+        // packages don't need to define the same commands in two places.
+        // Explicit review.commands still take precedence (applied after).
+        ...(packageOverride.quality?.commands?.lint !== undefined && {
+          lint: packageOverride.quality.commands.lint,
+        }),
+        ...(packageOverride.quality?.commands?.lintFix !== undefined && {
+          lintFix: packageOverride.quality.commands.lintFix,
+        }),
+        ...(packageOverride.quality?.commands?.typecheck !== undefined && {
+          typecheck: packageOverride.quality.commands.typecheck,
+        }),
+        ...(packageOverride.quality?.commands?.test !== undefined && {
+          test: packageOverride.quality.commands.test,
+        }),
+        // Explicit review.commands override bridged quality values
         ...packageOverride.review?.commands,
       },
     },

package/src/config/test-strategy.ts

@@ -53,10 +53,10 @@ regardless of LOC count. These require at minimum "tdd-simple" test strategy.`;
 
 export const TEST_STRATEGY_GUIDE = `## Test Strategy Guide
 
-- test-after: Simple changes with well-understood behavior. Write tests after implementation.
-- tdd-simple: Medium complexity. Write key tests first, implement, then fill coverage.
-- three-session-tdd: Complex stories. Full TDD cycle with separate test-writer and implementer sessions.
-- three-session-tdd-lite: Expert/high-risk stories. Full TDD with additional verifier session.`;
+- test-after: Simple changes with well-understood behavior. Write tests after implementation in a single session.
+- tdd-simple: Medium complexity. Write failing tests first, then implement to pass them — all in one session.
+- three-session-tdd: Complex stories. 3 sessions: (1) test-writer writes failing tests — no src/ changes allowed, (2) implementer makes them pass without modifying test files, (3) verifier confirms correctness.
+- three-session-tdd-lite: Expert/high-risk stories. 3 sessions: (1) test-writer writes failing tests and may create minimal src/ stubs for imports, (2) implementer makes tests pass and may add missing coverage or replace stubs, (3) verifier confirms correctness.`;
 
 export const GROUPING_RULES = `## Grouping Rules
 

package/src/execution/iteration-runner.ts

@@ -142,7 +142,7 @@ export async function runIteration(
   return {
     prd: r.prd,
     storiesCompletedDelta: 0,
-    costDelta: 0,
+    costDelta: r.costDelta,
     prdDirty: r.prdDirty,
     finalAction: pipelineResult.finalAction,
     reason: pipelineResult.reason,

package/src/execution/pipeline-result-handler.ts

@@ -102,6 +102,7 @@ export async function handlePipelineSuccess(
 export interface PipelineFailureResult {
   prd: PRD;
   prdDirty: boolean;
+  costDelta: number;
 }
 
 export async function handlePipelineFailure(
@@ -111,6 +112,8 @@ export async function handlePipelineFailure(
   const logger = getSafeLogger();
   let prd = ctx.prd;
   let prdDirty = false;
+  // Always capture cost even for failed stories — agent ran and spent tokens
+  const costDelta = pipelineResult.context.agentResult?.estimatedCost || 0;
 
   switch (pipelineResult.finalAction) {
     case "pause":
@@ -185,5 +188,5 @@ export async function handlePipelineFailure(
     }
   }
 
-  return { prd, prdDirty };
+  return { prd, prdDirty, costDelta };
 }

package/src/execution/story-selector.ts

@@ -39,7 +39,8 @@ export function selectNextStories(
         s.status !== "skipped" &&
         s.status !== "blocked" &&
         s.status !== "failed" &&
-        s.status !== "paused",
+        s.status !== "paused" &&
+        s.status !== "decomposed",
     );
 
     if (storiesToExecute.length === 0) {

package/src/interaction/plugins/webhook.ts

@@ -11,8 +11,8 @@ import { z } from "zod";
 import type { InteractionPlugin, InteractionRequest, InteractionResponse } from "../types";
 
 /**
- * Injectable sleep for WebhookInteractionPlugin.receive() polling loop.
- * Replace in tests to avoid real backoff delays.
+ * Injectable sleep — kept for backward compat with existing tests that override it.
+ * No longer used internally by receive() (replaced by event-driven delivery).
  * @internal
  */
 export const _webhookPluginDeps = {
@@ -56,7 +56,10 @@ export class WebhookInteractionPlugin implements InteractionPlugin {
   private config: WebhookConfig = {};
   private server: Server | null = null;
   private serverStartPromise: Promise<void> | null = null;
+  /** Legacy map for responses that arrive before receive() is called */
   private pendingResponses = new Map<string, InteractionResponse>();
+  /** Event-driven callbacks: requestId → resolve fn (set by receive(), called by handleRequest) */
+  private receiveCallbacks = new Map<string, (response: InteractionResponse) => void>();
 
   async init(config: Record<string, unknown>): Promise<void> {
     const cfg = WebhookConfigSchema.parse(config);
@@ -117,33 +120,49 @@ export class WebhookInteractionPlugin implements InteractionPlugin {
     // Start HTTP server to receive callback
     await this.startServer();
 
-    const startTime = Date.now();
-    let backoffMs = 100; // Initial poll interval
-    const maxBackoffMs = 2000; // Max 2 seconds between polls
-
-    // Poll for response with exponential backoff
-    while (Date.now() - startTime < timeout) {
-      const response = this.pendingResponses.get(requestId);
-      if (response) {
-        this.pendingResponses.delete(requestId);
-        return response;
-      }
-      await _webhookPluginDeps.sleep(backoffMs);
-      // Exponential backoff: double interval up to max
-      backoffMs = Math.min(backoffMs * 2, maxBackoffMs);
+    // Check if a response already arrived before receive() was called
+    const early = this.pendingResponses.get(requestId);
+    if (early) {
+      this.pendingResponses.delete(requestId);
+      return early;
     }
 
-    // Timeout
-    return {
-      requestId,
-      action: "skip",
-      respondedBy: "timeout",
-      respondedAt: Date.now(),
-    };
+    // Event-driven: resolve immediately when handleRequest delivers the response
+    return new Promise<InteractionResponse>((resolve) => {
+      const timer = setTimeout(() => {
+        this.receiveCallbacks.delete(requestId);
+        resolve({
+          requestId,
+          action: "skip",
+          respondedBy: "timeout",
+          respondedAt: Date.now(),
+        });
+      }, timeout);
+
+      this.receiveCallbacks.set(requestId, (response) => {
+        clearTimeout(timer);
+        this.receiveCallbacks.delete(requestId);
+        resolve(response);
+      });
+    });
   }
 
   async cancel(requestId: string): Promise<void> {
     this.pendingResponses.delete(requestId);
+    this.receiveCallbacks.delete(requestId);
+  }
+
+  /**
+   * Deliver a response to a waiting receive() callback, or store for later pickup.
+   */
+  private deliverResponse(requestId: string, response: InteractionResponse): void {
+    const cb = this.receiveCallbacks.get(requestId);
+    if (cb) {
+      cb(response);
+    } else {
+      // receive() hasn't been called yet — store for early-pickup path
+      this.pendingResponses.set(requestId, response);
+    }
   }
 
   /**
@@ -220,7 +239,7 @@ export class WebhookInteractionPlugin implements InteractionPlugin {
       try {
         const parsed = JSON.parse(body);
         const response = InteractionResponseSchema.parse(parsed);
-        this.pendingResponses.set(requestId, response);
+        this.deliverResponse(requestId, response);
       } catch {
         // Sanitize error - do not leak parse/validation details
         return new Response("Bad Request: Invalid response format", { status: 400 });
@@ -230,7 +249,7 @@ export class WebhookInteractionPlugin implements InteractionPlugin {
       try {
         const parsed = await req.json();
         const response = InteractionResponseSchema.parse(parsed);
-        this.pendingResponses.set(requestId, response);
+        this.deliverResponse(requestId, response);
       } catch {
         // Sanitize error - do not leak parse/validation details
         return new Response("Bad Request: Invalid response format", { status: 400 });

package/src/pipeline/stages/autofix.ts

@@ -61,12 +61,22 @@ export const autofixStage: PipelineStage = {
     // Effective workdir for running commands (scoped to package if monorepo)
     const effectiveWorkdir = ctx.story.workdir ? join(ctx.workdir, ctx.story.workdir) : ctx.workdir;
 
-    // Phase 1: Mechanical fix (if commands are configured)
-    if (lintFixCmd || formatFixCmd) {
+    // Identify which checks failed
+    const failedCheckNames = new Set((reviewResult.checks ?? []).filter((c) => !c.success).map((c) => c.check));
+    const hasLintFailure = failedCheckNames.has("lint");
+
+    logger.info("autofix", "Starting autofix", {
+      storyId: ctx.story.id,
+      failedChecks: [...failedCheckNames],
+      workdir: effectiveWorkdir,
+    });
+
+    // Phase 1: Mechanical fix — only for lint failures (lintFix/formatFix cannot fix typecheck errors)
+    if (hasLintFailure && (lintFixCmd || formatFixCmd)) {
       if (lintFixCmd) {
         pipelineEventBus.emit({ type: "autofix:started", storyId: ctx.story.id, command: lintFixCmd });
         const lintResult = await _autofixDeps.runCommand(lintFixCmd, effectiveWorkdir);
-        logger.debug("autofix", `lintFix exit=${lintResult.exitCode}`, { storyId: ctx.story.id });
+        logger.debug("autofix", `lintFix exit=${lintResult.exitCode}`, { storyId: ctx.story.id, command: lintFixCmd });
         if (lintResult.exitCode !== 0) {
           logger.warn("autofix", "lintFix command failed — may not have fixed all issues", {
             storyId: ctx.story.id,
@@ -78,7 +88,10 @@ export const autofixStage: PipelineStage = {
       if (formatFixCmd) {
         pipelineEventBus.emit({ type: "autofix:started", storyId: ctx.story.id, command: formatFixCmd });
         const fmtResult = await _autofixDeps.runCommand(formatFixCmd, effectiveWorkdir);
-        logger.debug("autofix", `formatFix exit=${fmtResult.exitCode}`, { storyId: ctx.story.id });
+        logger.debug("autofix", `formatFix exit=${fmtResult.exitCode}`, {
+          storyId: ctx.story.id,
+          command: formatFixCmd,
+        });
         if (fmtResult.exitCode !== 0) {
           logger.warn("autofix", "formatFix command failed — may not have fixed all issues", {
             storyId: ctx.story.id,
@@ -91,10 +104,13 @@ export const autofixStage: PipelineStage = {
       pipelineEventBus.emit({ type: "autofix:completed", storyId: ctx.story.id, fixed: recheckPassed });
 
       if (recheckPassed) {
-        if (ctx.reviewResult) ctx.reviewResult = { ...ctx.reviewResult, success: true };
         logger.info("autofix", "Mechanical autofix succeeded — retrying review", { storyId: ctx.story.id });
         return { action: "retry", fromStage: "review" };
       }
+
+      logger.info("autofix", "Mechanical autofix did not resolve all failures — proceeding to agent rectification", {
+        storyId: ctx.story.id,
+      });
     }
 
     // Phase 2: Agent rectification — spawn agent with review error context
@@ -134,8 +150,11 @@ async function recheckReview(ctx: PipelineContext): Promise<boolean> {
   // Import reviewStage lazily to avoid circular deps
   const { reviewStage } = await import("./review");
   if (!reviewStage.enabled(ctx)) return true;
-  const result = await reviewStage.execute(ctx);
-  return result.action === "continue";
+  // reviewStage.execute updates ctx.reviewResult in place.
+  // We cannot use result.action here because review returns "continue" for BOTH
+  // pass and built-in-check-failure (to hand off to autofix). Check success directly.
+  await reviewStage.execute(ctx);
+  return ctx.reviewResult?.success === true;
 }
 
 function collectFailedChecks(ctx: PipelineContext): ReviewCheckResult[] {

package/src/pipeline/stages/routing.ts

@@ -196,7 +196,7 @@ export const routingStage: PipelineStage = {
 
     // SD-004: Oversized story detection and decomposition
     const decomposeConfig = ctx.config.decompose;
-    if (decomposeConfig) {
+    if (decomposeConfig && ctx.story.status !== "decomposed") {
       const acCount = ctx.story.acceptanceCriteria.length;
       const complexity = ctx.routing.complexity;
       const isOversized =

package/src/review/runner.ts

@@ -99,6 +99,9 @@ const SIGKILL_GRACE_PERIOD_MS = 5_000;
  */
 async function runCheck(check: ReviewCheckName, command: string, workdir: string): Promise<ReviewCheckResult> {
   const startTime = Date.now();
+  const logger = getSafeLogger();
+
+  logger?.info("review", `Running ${check} check`, { check, command, workdir });
 
   try {
     // Parse command into executable and args
@@ -152,6 +155,18 @@ async function runCheck(check: ReviewCheckName, command: string, workdir: string
     const stderr = await new Response(proc.stderr).text();
     const output = [stdout, stderr].filter(Boolean).join("\n");
 
+    if (exitCode !== 0) {
+      logger?.warn("review", `${check} check failed`, {
+        check,
+        command,
+        workdir,
+        exitCode,
+        output: output.slice(0, 2000),
+      });
+    } else {
+      logger?.debug("review", `${check} check passed`, { check, command, durationMs: Date.now() - startTime });
+    }
+
     return {
       check,
       command,