@nathapp/nax 0.49.3 → 0.50.0

package/package.json

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

package/src/acceptance/generator.ts

@@ -114,6 +114,18 @@ IMPORTANT: Output raw TypeScript code only. Do NOT use markdown code fences (\`\
   });
   const testCode = extractTestCode(rawOutput);
 
+  if (!testCode) {
+    logger.warn("acceptance", "LLM returned non-code output for acceptance tests — falling back to skeleton", {
+      outputPreview: rawOutput.slice(0, 200),
+    });
+    const skeletonCriteria: AcceptanceCriterion[] = refinedCriteria.map((c, i) => ({
+      id: `AC-${i + 1}`,
+      text: c.refined,
+      lineNumber: i + 1,
+    }));
+    return { testCode: generateSkeletonTests(options.featureName, skeletonCriteria), criteria: skeletonCriteria };
+  }
+
   const refinedJsonContent = JSON.stringify(
     refinedCriteria.map((c, i) => ({
       acId: `AC-${i + 1}`,
@@ -306,6 +318,16 @@ export async function generateAcceptanceTests(
     // Extract test code from output
     const testCode = extractTestCode(output);
 
+    if (!testCode) {
+      logger.warn("acceptance", "LLM returned non-code output for acceptance tests — falling back to skeleton", {
+        outputPreview: output.slice(0, 200),
+      });
+      return {
+        testCode: generateSkeletonTests(options.featureName, criteria),
+        criteria,
+      };
+    }
+
     return {
       testCode,
       criteria,
@@ -328,21 +350,40 @@ export async function generateAcceptanceTests(
  * @param output - Agent stdout
  * @returns Extracted test code
  */
-function extractTestCode(output: string): string {
+function extractTestCode(output: string): string | null {
+  let code: string | undefined;
+
   // Try to extract from markdown code fence
   const fenceMatch = output.match(/```(?:typescript|ts)?\s*([\s\S]*?)\s*```/);
   if (fenceMatch) {
-    return fenceMatch[1].trim();
+    code = fenceMatch[1].trim();
   }
 
   // If no fence, try to find import statement and take everything from there
-  const importMatch = output.match(/import\s+{[\s\S]+/);
-  if (importMatch) {
-    return importMatch[0].trim();
+  if (!code) {
+    const importMatch = output.match(/import\s+{[\s\S]+/);
+    if (importMatch) {
+      code = importMatch[0].trim();
+    }
+  }
+
+  // If no fence and no import, try to find describe() block
+  if (!code) {
+    const describeMatch = output.match(/describe\s*\([\s\S]+/);
+    if (describeMatch) {
+      code = describeMatch[0].trim();
+    }
+  }
+
+  if (!code) return null;
+
+  // Validate: extracted code must contain at least one test-like keyword
+  const hasTestKeyword = /\b(?:describe|test|it|expect)\s*\(/.test(code);
+  if (!hasTestKeyword) {
+    return null;
   }
 
-  // Fall back to full output
-  return output.trim();
+  return code;
 }
 
 /**

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/plan.ts

@@ -395,15 +395,18 @@ function buildCodebaseContext(scan: CodebaseScan): string {
 /**
  * Build the full planning prompt sent to the LLM.
  *
+ * Structured as 3 explicit steps (ENH-006):
+ *   Step 1: Understand the spec
+ *   Step 2: Analyze codebase (existing) or architecture decisions (greenfield)
+ *   Step 3: Generate implementation stories from analysis
+ *
  * Includes:
- * - Spec content
- * - Codebase context
- * - Output schema (exact prd.json JSON structure)
- * - Complexity classification guide
- * - Test strategy guide
+ * - Spec content + codebase context
+ * - Output schema with analysis + contextFiles fields
+ * - Complexity + test strategy guides
  * - MW-007: Monorepo hint and package list when packages are detected
  */
-function buildPlanningPrompt(
+export function buildPlanningPrompt(
   specContent: string,
   codebaseContext: string,
   outputFilePath?: string,
@@ -423,14 +426,48 @@ function buildPlanningPrompt(
 
   return `You are a senior software architect generating a product requirements document (PRD) as JSON.
 
+## Step 1: Understand the Spec
+
+Read the spec carefully. Identify the goal, scope, constraints, and what "done" looks like.
+
 ## Spec
 
 ${specContent}
 
+## Step 2: Analyze
+
+Examine the codebase context below.
+
+If the codebase has existing code (refactoring, enhancement, bug fix):
+- Which existing files need modification?
+- Which files import from or depend on them?
+- What tests cover the affected code?
+- What are the risks (breaking changes, backward compatibility)?
+- What is the migration path?
+
+If this is a greenfield project (empty or minimal codebase):
+- What is the target architecture?
+- What are the key technical decisions (framework, patterns, conventions)?
+- What should be built first (dependency order)?
+
+Record ALL findings in the "analysis" field of the output JSON. This analysis is provided to every implementation agent as context — be thorough.
+
 ## Codebase Context
 
 ${codebaseContext}${monorepoHint}
 
+## Step 3: Generate Implementation Stories
+
+Based on your Step 2 analysis, create stories that produce CODE CHANGES.
+
+${GROUPING_RULES}
+
+For each story, set "contextFiles" to the key source files the agent should read before implementing (max 5 per story). Use your Step 2 analysis to identify the most relevant files. Leave empty for greenfield stories with no existing files to reference.
+
+${COMPLEXITY_GUIDE}
+
+${TEST_STRATEGY_GUIDE}
+
 ## Output Schema
 
 Generate a JSON object with this exact structure (no markdown, no explanation — JSON only):
@@ -438,6 +475,7 @@ Generate a JSON object with this exact structure (no markdown, no explanation
 {
   "project": "string — project name",
   "feature": "string — feature name",
+  "analysis": "string — your Step 2 analysis: key files, impact areas, risks, architecture decisions, migration notes. All implementation agents will receive this.",
   "branchName": "string — git branch (e.g. feat/my-feature)",
   "createdAt": "ISO 8601 timestamp",
   "updatedAt": "ISO 8601 timestamp",
@@ -447,13 +485,14 @@ Generate a JSON object with this exact structure (no markdown, no explanation
       "title": "string — concise story title",
       "description": "string — detailed description of the story",
       "acceptanceCriteria": ["string — each AC line"],
+      "contextFiles": ["string — key source files the agent should read (max 5, relative paths)"],
       "tags": ["string — routing tags, e.g. feature, security, api"],
       "dependencies": ["string — story IDs this story depends on"],${workdirField}
       "status": "pending",
       "passes": false,
       "routing": {
         "complexity": "simple | medium | complex | expert",
-        "testStrategy": "test-after | tdd-simple | three-session-tdd | three-session-tdd-lite",
+        "testStrategy": "tdd-simple | three-session-tdd-lite | three-session-tdd | test-after",
         "reasoning": "string — brief classification rationale"
       },
       "escalations": [],
@@ -462,12 +501,6 @@ Generate a JSON object with this exact structure (no markdown, no explanation
   ]
 }
 
-${COMPLEXITY_GUIDE}
-
-${TEST_STRATEGY_GUIDE}
-
-${GROUPING_RULES}
-
 ${
   outputFilePath
     ? `Write the PRD JSON directly to this file path: ${outputFilePath}\nDo NOT output the JSON to the conversation. Write the file, then reply with a brief confirmation.`

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

@@ -40,31 +40,32 @@ export function resolveTestStrategy(raw: string | undefined): TestStrategy {
 
 export const COMPLEXITY_GUIDE = `## Complexity Classification Guide
 
-- simple: ≤50 LOC, single-file change, purely additive, no new dependencies → test-after
-- medium: 50–200 LOC, 2–5 files, standard patterns, clear requirements → tdd-simple
+- simple: ≤50 LOC, single-file change, purely additive, no new dependencies → tdd-simple
+- medium: 50–200 LOC, 2–5 files, standard patterns, clear requirements → three-session-tdd-lite
 - complex: 200–500 LOC, multiple modules, new abstractions or integrations → three-session-tdd
-- expert: 500+ LOC, architectural changes, cross-cutting concerns, high risk → three-session-tdd-lite
+- expert: 500+ LOC, architectural changes, cross-cutting concerns, high risk → three-session-tdd
 
 ### Security Override
 
 Security-critical functions (authentication, cryptography, tokens, sessions, credentials,
-password hashing, access control) must be classified at MINIMUM "medium" complexity
-regardless of LOC count. These require at minimum "tdd-simple" test strategy.`;
+password hashing, access control) must use three-session-tdd regardless of complexity.`;
 
 export const TEST_STRATEGY_GUIDE = `## Test Strategy Guide
 
-- 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.`;
+- tdd-simple: Simple stories (≤50 LOC). Write failing tests first, then implement to pass them — all in one session.
+- three-session-tdd-lite: Medium stories, or complex stories involving UI/CLI/integration. 3 sessions: (1) test-writer writes failing tests and may create minimal src/ stubs for imports, (2) implementer makes tests pass and may replace stubs, (3) verifier confirms correctness.
+- three-session-tdd: Complex/expert stories or security-critical code. 3 sessions with strict isolation: (1) test-writer writes failing tests — no src/ changes allowed, (2) implementer makes them pass without modifying test files, (3) verifier confirms correctness.
+- test-after: Only when explicitly configured (tddStrategy: "off"). Write tests after implementation. Not auto-assigned.`;
 
-export const GROUPING_RULES = `## Grouping Rules
+export const GROUPING_RULES = `## Story Rules
 
+- Every story must produce code changes verifiable by tests or review.
+- NEVER create stories for analysis, planning, documentation, or migration plans.
+  Your analysis belongs in the "analysis" field, not in a story.
+- NEVER create stories whose primary purpose is writing tests, achieving coverage
+  targets, or running validation/regression suites. Each story's testStrategy
+  handles test creation as part of implementation. Testing is a built-in pipeline
+  stage, not a user story. No exceptions.
 - Combine small, related tasks into a single "simple" or "medium" story.
-- Do NOT create separate stories for every single file or function unless complex.
-- Do NOT create standalone stories purely for test coverage or testing.
-  Each story's testStrategy already handles testing (tdd-simple writes tests first,
-  three-session-tdd uses separate test-writer session, test-after writes tests after).
-  Only create a dedicated test story for unique integration/E2E test logic that spans
-  multiple stories and cannot be covered by individual story test strategies.
+  Do NOT create separate stories for every single file or function unless complex.
 - Aim for coherent units of value. Maximum recommended stories: 10-15 per feature.`;