@nathapp/nax 0.46.3 → 0.47.0

package/package.json

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

package/src/cli/generate.ts

@@ -9,7 +9,7 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import chalk from "chalk";
 import { loadConfig } from "../config/loader";
-import { generateAll, generateFor } from "../context/generator";
+import { discoverPackages, generateAll, generateFor, generateForPackage } from "../context/generator";
 import type { AgentType } from "../context/types";
 
 /** Options for `nax generate` */
@@ -24,6 +24,17 @@ export interface GenerateCommandOptions {
   dryRun?: boolean;
   /** Disable auto-injection of project metadata */
   noAutoInject?: boolean;
+  /**
+   * Generate for a specific package directory (relative to repo root).
+   * Reads <package>/nax/context.md, writes <package>/CLAUDE.md.
+   * @example "packages/api"
+   */
+  package?: string;
+  /**
+   * Generate for all discovered packages.
+   * Auto-discovers packages with nax/context.md up to 2 levels deep.
+   */
+  allPackages?: boolean;
 }
 
 const VALID_AGENTS: AgentType[] = ["claude", "codex", "opencode", "cursor", "windsurf", "aider", "gemini"];
@@ -33,10 +44,70 @@ const VALID_AGENTS: AgentType[] = ["claude", "codex", "opencode", "cursor", "win
  */
 export async function generateCommand(options: GenerateCommandOptions): Promise<void> {
   const workdir = process.cwd();
+  const dryRun = options.dryRun ?? false;
+
+  // Load config early — needed for all paths
+  let config: Awaited<ReturnType<typeof loadConfig>>;
+  try {
+    config = await loadConfig(workdir);
+  } catch {
+    config = {} as Awaited<ReturnType<typeof loadConfig>>;
+  }
+
+  // --all-packages: discover and generate for all packages
+  if (options.allPackages) {
+    if (dryRun) {
+      console.log(chalk.yellow("⚠ Dry run — no files will be written"));
+    }
+    console.log(chalk.blue("→ Discovering packages with nax/context.md..."));
+    const packages = await discoverPackages(workdir);
+
+    if (packages.length === 0) {
+      console.log(chalk.yellow("  No packages found (no */nax/context.md or */*/nax/context.md)"));
+      return;
+    }
+
+    console.log(chalk.blue(`→ Generating CLAUDE.md for ${packages.length} package(s)...`));
+    let errorCount = 0;
+
+    for (const pkgDir of packages) {
+      const result = await generateForPackage(pkgDir, config, dryRun);
+      if (result.error) {
+        console.error(chalk.red(`✗ ${pkgDir}: ${result.error}`));
+        errorCount++;
+      } else {
+        const suffix = dryRun ? " (dry run)" : "";
+        console.log(chalk.green(`✓ ${pkgDir}/${result.outputFile} (${result.content.length} bytes${suffix})`));
+      }
+    }
+
+    if (errorCount > 0) {
+      console.error(chalk.red(`\n✗ ${errorCount} generation(s) failed`));
+      process.exit(1);
+    }
+    return;
+  }
+
+  // --package: generate for a specific package
+  if (options.package) {
+    const packageDir = join(workdir, options.package);
+    if (dryRun) {
+      console.log(chalk.yellow("⚠ Dry run — no files will be written"));
+    }
+    console.log(chalk.blue(`→ Generating CLAUDE.md for package: ${options.package}`));
+    const result = await generateForPackage(packageDir, config, dryRun);
+    if (result.error) {
+      console.error(chalk.red(`✗ ${result.error}`));
+      process.exit(1);
+    }
+    const suffix = dryRun ? " (dry run)" : "";
+    console.log(chalk.green(`✓ ${options.package}/${result.outputFile} (${result.content.length} bytes${suffix})`));
+    return;
+  }
+
   const contextPath = options.context ? join(workdir, options.context) : join(workdir, "nax/context.md");
   const outputDir = options.output ? join(workdir, options.output) : workdir;
   const autoInject = !options.noAutoInject;
-  const dryRun = options.dryRun ?? false;
 
   // Validate context file
   if (!existsSync(contextPath)) {
@@ -61,15 +132,6 @@ export async function generateCommand(options: GenerateCommandOptions): Promise<
     console.log(chalk.dim("  Auto-injecting project metadata..."));
   }
 
-  // Load config for metadata injection (best-effort, use defaults if not found)
-  let config: Awaited<ReturnType<typeof loadConfig>>;
-  try {
-    config = await loadConfig(workdir);
-  } catch {
-    // Config not required for generate — use empty defaults
-    config = {} as Awaited<ReturnType<typeof loadConfig>>;
-  }
-
   const genOptions = {
     contextPath,
     outputDir,

package/src/cli/init-context.ts

@@ -312,6 +312,63 @@ Keep it under 2000 tokens. Use markdown formatting. Be specific to the detected
   }
 }
 
+/**
+ * Generate a minimal package context.md template.
+ *
+ * @param packagePath - Relative path of the package (e.g. "packages/api")
+ */
+export function generatePackageContextTemplate(packagePath: string): string {
+  const packageName = packagePath.split("/").pop() ?? packagePath;
+  return `# ${packageName} — Context
+
+<!-- Package-specific conventions. Root context.md provides shared rules. -->
+
+## Tech Stack
+
+<!-- TODO: Document this package's tech stack -->
+
+## Commands
+
+| Command | Purpose |
+|:--------|:--------|
+| \`bun test\` | Unit tests |
+
+## Development Guidelines
+
+<!-- TODO: Document package-specific guidelines -->
+`;
+}
+
+/**
+ * Initialize per-package nax/context.md scaffold.
+ *
+ * Creates \`<packageDir>/nax/context.md\` with a minimal template.
+ * Does not overwrite an existing file unless force is set.
+ *
+ * @param repoRoot - Absolute path to repo root
+ * @param packagePath - Relative path of the package (e.g. "packages/api")
+ * @param force - Overwrite existing file
+ */
+export async function initPackage(repoRoot: string, packagePath: string, force = false): Promise<void> {
+  const logger = getLogger();
+  const packageDir = join(repoRoot, packagePath);
+  const naxDir = join(packageDir, "nax");
+  const contextPath = join(naxDir, "context.md");
+
+  if (existsSync(contextPath) && !force) {
+    logger.info("init", "Package context.md already exists (use --force to overwrite)", { path: contextPath });
+    return;
+  }
+
+  if (!existsSync(naxDir)) {
+    await mkdir(naxDir, { recursive: true });
+  }
+
+  const content = generatePackageContextTemplate(packagePath);
+  await Bun.write(contextPath, content);
+  logger.info("init", "Created package context.md", { path: contextPath });
+}
+
 /**
  * Initialize context.md for a project
  */

package/src/cli/init.ts

@@ -9,7 +9,7 @@ import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { globalConfigDir, projectConfigDir } from "../config/paths";
 import { getLogger } from "../logger";
-import { initContext } from "./init-context";
+import { initContext, initPackage } from "./init-context";
 import { buildInitConfig, detectStack } from "./init-detect";
 import type { ProjectStack } from "./init-detect";
 import { promptsInitCommand } from "./prompts";
@@ -20,6 +20,11 @@ export interface InitOptions {
   global?: boolean;
   /** Project root (default: cwd) */
   projectRoot?: string;
+  /**
+   * Initialize a per-package nax/context.md scaffold.
+   * Relative path from repo root, e.g. "packages/api".
+   */
+  package?: string;
 }
 
 /** Options for initProject */
@@ -277,6 +282,14 @@ export async function initProject(projectRoot: string, options?: InitProjectOpti
 export async function initCommand(options: InitOptions = {}): Promise<void> {
   if (options.global) {
     await initGlobal();
+  } else if (options.package) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    await initPackage(projectRoot, options.package);
+    console.log("\n[OK] Package scaffold created.");
+    console.log(`  Created: ${options.package}/nax/context.md`);
+    console.log("\nNext steps:");
+    console.log(`  1. Review ${options.package}/nax/context.md and fill in TODOs`);
+    console.log(`  2. Run: nax generate --package ${options.package}`);
   } else {
     const projectRoot = options.projectRoot ?? process.cwd();
     await initProject(projectRoot);

package/src/cli/plan.ts

@@ -17,6 +17,7 @@ import type { CodebaseScan } from "../analyze/types";
 import type { NaxConfig } from "../config";
 import { resolvePermissions } from "../config/permissions";
 import { COMPLEXITY_GUIDE, GROUPING_RULES, TEST_STRATEGY_GUIDE } from "../config/test-strategy";
+import { discoverPackages } from "../context/generator";
 import { PidRegistry } from "../execution/pid-registry";
 import { getLogger } from "../logger";
 import { validatePlanOutput } from "../prd/schema";
@@ -41,6 +42,7 @@ export const _deps = {
   },
   mkdirp: (path: string): Promise<void> => Bun.spawn(["mkdir", "-p", path]).exited.then(() => {}),
   existsSync: (path: string): boolean => existsSync(path),
+  discoverPackages: (repoRoot: string): Promise<string[]> => discoverPackages(repoRoot),
 };
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -85,11 +87,17 @@ export async function planCommand(workdir: string, config: NaxConfig, options: P
 
   // Scan codebase for context
   logger?.info("plan", "Scanning codebase...");
-  const scan = await _deps.scanCodebase(workdir);
+  const [scan, discoveredPackages, pkg] = await Promise.all([
+    _deps.scanCodebase(workdir),
+    _deps.discoverPackages(workdir),
+    _deps.readPackageJson(workdir),
+  ]);
   const codebaseContext = buildCodebaseContext(scan);
 
+  // MW-007: convert absolute paths to repo-relative for prompt readability
+  const relativePackages = discoveredPackages.map((p) => p.replace(`${workdir}/`, ""));
+
   // Auto-detect project name
-  const pkg = await _deps.readPackageJson(workdir);
   const projectName = detectProjectName(workdir, pkg);
 
   // Compute output path early — needed for interactive file-write prompt
@@ -107,7 +115,7 @@ export async function planCommand(workdir: string, config: NaxConfig, options: P
   let rawResponse: string;
   if (options.auto) {
     // One-shot: use CLI adapter directly — simple completion doesn't need ACP session overhead
-    const prompt = buildPlanningPrompt(specContent, codebaseContext);
+    const prompt = buildPlanningPrompt(specContent, codebaseContext, undefined, relativePackages);
     const cliAdapter = _deps.getAgent(agentName);
     if (!cliAdapter) throw new Error(`[plan] No agent adapter found for '${agentName}'`);
     rawResponse = await cliAdapter.complete(prompt, { jsonMode: true, workdir, config });
@@ -122,7 +130,7 @@ export async function planCommand(workdir: string, config: NaxConfig, options: P
     }
   } else {
     // Interactive: agent writes PRD JSON directly to outputPath (avoids output truncation)
-    const prompt = buildPlanningPrompt(specContent, codebaseContext, outputPath);
+    const prompt = buildPlanningPrompt(specContent, codebaseContext, outputPath, relativePackages);
     const adapter = _deps.getAgent(agentName, config);
     if (!adapter) throw new Error(`[plan] No agent adapter found for '${agentName}'`);
     const interactionBridge = createCliInteractionBridge();
@@ -278,8 +286,23 @@ function buildCodebaseContext(scan: CodebaseScan): string {
  * - Output schema (exact prd.json JSON structure)
  * - Complexity classification guide
  * - Test strategy guide
+ * - MW-007: Monorepo hint and package list when packages are detected
  */
-function buildPlanningPrompt(specContent: string, codebaseContext: string, outputFilePath?: string): string {
+function buildPlanningPrompt(
+  specContent: string,
+  codebaseContext: string,
+  outputFilePath?: string,
+  packages?: string[],
+): string {
+  const isMonorepo = packages && packages.length > 0;
+  const monorepoHint = isMonorepo
+    ? `\n## Monorepo Context\n\nThis is a monorepo. Detected packages:\n${packages.map((p) => `- ${p}`).join("\n")}\n\nFor each user story, set the "workdir" field to the relevant package path (e.g. "packages/api"). Stories that span the root should omit "workdir".`
+    : "";
+
+  const workdirField = isMonorepo
+    ? `\n      "workdir": "string — optional, relative path to package (e.g. \\"packages/api\\"). Omit for root-level stories.",`
+    : "";
+
   return `You are a senior software architect generating a product requirements document (PRD) as JSON.
 
 ## Spec
@@ -288,7 +311,7 @@ ${specContent}
 
 ## Codebase Context
 
-${codebaseContext}
+${codebaseContext}${monorepoHint}
 
 ## Output Schema
 
@@ -307,7 +330,7 @@ Generate a JSON object with this exact structure (no markdown, no explanation
       "description": "string — detailed description of the story",
       "acceptanceCriteria": ["string — each AC line"],
       "tags": ["string — routing tags, e.g. feature, security, api"],
-      "dependencies": ["string — story IDs this story depends on"],
+      "dependencies": ["string — story IDs this story depends on"],${workdirField}
       "status": "pending",
       "passes": false,
       "routing": {

package/src/config/loader.ts

@@ -5,9 +5,10 @@
  */
 
 import { existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { getLogger } from "../logger";
 import { loadJsonFile } from "../utils/json-file";
+import { mergePackageConfig } from "./merge";
 import { deepMergeConfig } from "./merger";
 import { MAX_DIRECTORY_DEPTH } from "./path-security";
 import { globalConfigDir } from "./paths";
@@ -108,3 +109,35 @@ export async function loadConfig(projectDir?: string, cliOverrides?: Record<stri
 
   return result.data as NaxConfig;
 }
+
+/**
+ * Load config for a specific working directory (monorepo package).
+ *
+ * Resolution order:
+ * 1. Load root nax/config.json via loadConfig()
+ * 2. If packageDir is set, check <repoRoot>/<packageDir>/nax/config.json
+ * 3. If package config exists → merge quality.commands over root
+ * 4. Return merged config
+ *
+ * @param rootConfigPath - Absolute path to the root nax/config.json
+ * @param packageDir - Package directory relative to repo root (e.g. "packages/api")
+ */
+export async function loadConfigForWorkdir(rootConfigPath: string, packageDir?: string): Promise<NaxConfig> {
+  const rootNaxDir = dirname(rootConfigPath);
+  const rootConfig = await loadConfig(rootNaxDir);
+
+  if (!packageDir) {
+    return rootConfig;
+  }
+
+  const repoRoot = dirname(rootNaxDir);
+  const packageConfigPath = join(repoRoot, packageDir, "nax", "config.json");
+
+  const packageOverride = await loadJsonFile<Partial<NaxConfig>>(packageConfigPath, "config");
+
+  if (!packageOverride) {
+    return rootConfig;
+  }
+
+  return mergePackageConfig(rootConfig, packageOverride);
+}

package/src/config/merge.ts

@@ -0,0 +1,37 @@
+/**
+ * Per-Package Config Merge Utility (MW-008)
+ *
+ * Only quality.commands is mergeable — routing, plugins, execution,
+ * and agents stay root-only.
+ */
+
+import type { NaxConfig } from "./schema";
+
+/**
+ * Merge a package-level partial config override into a root config.
+ *
+ * Only quality.commands keys are merged. All other sections remain
+ * unchanged from the root config.
+ *
+ * @param root - Full root NaxConfig (already validated)
+ * @param packageOverride - Partial package-level override (only quality.commands honored)
+ * @returns New merged NaxConfig (immutable — does not mutate inputs)
+ */
+export function mergePackageConfig(root: NaxConfig, packageOverride: Partial<NaxConfig>): NaxConfig {
+  const packageCommands = packageOverride.quality?.commands;
+
+  if (!packageCommands) {
+    return root;
+  }
+
+  return {
+    ...root,
+    quality: {
+      ...root.quality,
+      commands: {
+        ...root.quality.commands,
+        ...packageCommands,
+      },
+    },
+  };
+}

package/src/context/generator.ts

@@ -129,5 +129,90 @@ async function generateAll(options: GenerateOptions, config: NaxConfig): Promise
   return results;
 }
 
+/** Result from generateForPackage */
+export interface PackageGenerationResult {
+  packageDir: string;
+  outputFile: string;
+  content: string;
+  written: boolean;
+  error?: string;
+}
+
+/**
+ * Discover packages that have nax/context.md files.
+ *
+ * Scans up to 2 levels deep (one-level and two-level patterns).
+ *
+ * @param repoRoot - Absolute repo root to scan
+ * @returns Array of package directory paths (absolute)
+ */
+export async function discoverPackages(repoRoot: string): Promise<string[]> {
+  const packages: string[] = [];
+  const seen = new Set<string>();
+
+  for (const pattern of ["*/nax/context.md", "*/*/nax/context.md"]) {
+    const glob = new Bun.Glob(pattern);
+    for await (const match of glob.scan(repoRoot)) {
+      // match is e.g. "packages/api/nax/context.md" — strip trailing /nax/context.md
+      const pkgRelative = match.replace(/\/nax\/context\.md$/, "");
+      const pkgAbsolute = join(repoRoot, pkgRelative);
+      if (!seen.has(pkgAbsolute)) {
+        seen.add(pkgAbsolute);
+        packages.push(pkgAbsolute);
+      }
+    }
+  }
+
+  return packages;
+}
+
+/**
+ * Generate the claude CLAUDE.md for a specific package.
+ *
+ * Reads `<packageDir>/nax/context.md` and writes `<packageDir>/CLAUDE.md`.
+ * Per-package CLAUDE.md contains only package-specific content — Claude Code's
+ * native directory hierarchy merges root CLAUDE.md + package CLAUDE.md at runtime.
+ */
+export async function generateForPackage(
+  packageDir: string,
+  config: NaxConfig,
+  dryRun = false,
+): Promise<PackageGenerationResult> {
+  const contextPath = join(packageDir, "nax", "context.md");
+
+  if (!existsSync(contextPath)) {
+    return {
+      packageDir,
+      outputFile: "CLAUDE.md",
+      content: "",
+      written: false,
+      error: `context.md not found: ${contextPath}`,
+    };
+  }
+
+  try {
+    const options: GenerateOptions = {
+      contextPath,
+      outputDir: packageDir,
+      workdir: packageDir,
+      dryRun,
+      autoInject: true,
+    };
+
+    const result = await generateFor("claude", options, config);
+
+    return {
+      packageDir,
+      outputFile: result.outputFile,
+      content: result.content,
+      written: result.written,
+      error: result.error,
+    };
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    return { packageDir, outputFile: "CLAUDE.md", content: "", written: false, error };
+  }
+}
+
 export { generateFor, generateAll };
 export type { AgentType };

package/src/execution/story-context.ts

@@ -127,14 +127,33 @@ export async function buildStoryContext(prd: PRD, story: UserStory, _config: Nax
   }
 }
 
+/**
+ * Load package-level context.md content if it exists.
+ *
+ * Reads <packageWorkdir>/nax/context.md and returns its content, or null
+ * if the file does not exist.
+ *
+ * @internal
+ */
+async function loadPackageContextMd(packageWorkdir: string): Promise<string | null> {
+  const contextPath = `${packageWorkdir}/nax/context.md`;
+  const file = Bun.file(contextPath);
+  if (!(await file.exists())) return null;
+  return file.text();
+}
+
 /**
  * Build story context returning both markdown and element-level data.
  * Used by `nax prompts` CLI for accurate frontmatter token counts.
+ *
+ * When `packageWorkdir` is provided (absolute path of story.workdir),
+ * appends the package-level nax/context.md after the root context.
  */
 export async function buildStoryContextFull(
   prd: PRD,
   story: UserStory,
   config: NaxConfig,
+  packageWorkdir?: string,
 ): Promise<{ markdown: string; builtContext: BuiltContext } | undefined> {
   try {
     const storyContext: StoryContext = {
@@ -152,11 +171,23 @@ export async function buildStoryContextFull(
 
     const built = await buildContext(storyContext, budget);
 
-    if (built.elements.length === 0) {
+    // MW-003: append package-level context.md if workdir is set
+    let packageSection = "";
+    if (packageWorkdir) {
+      const pkgContent = await loadPackageContextMd(packageWorkdir);
+      if (pkgContent) {
+        packageSection = `\n---\n\n${pkgContent.trim()}`;
+      }
+    }
+
+    if (built.elements.length === 0 && !packageSection) {
       return undefined;
     }
 
-    return { markdown: formatContextAsMarkdown(built), builtContext: built };
+    const baseMarkdown = built.elements.length > 0 ? formatContextAsMarkdown(built) : "";
+    const markdown = packageSection ? `${baseMarkdown}${packageSection}` : baseMarkdown;
+
+    return { markdown, builtContext: built };
   } catch (error) {
     const logger = getSafeLogger();
     logger?.warn("context", "Context builder failed", {

package/src/pipeline/stages/context.ts

@@ -20,6 +20,7 @@
  * ```
  */
 
+import { join } from "node:path";
 import type { ContextElement } from "../../context/types";
 import { buildStoryContextFull } from "../../execution/helpers";
 import { getLogger } from "../../logger";
@@ -33,8 +34,11 @@ export const contextStage: PipelineStage = {
   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);
+    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

package/src/pipeline/stages/execution.ts

@@ -30,6 +30,8 @@
  * ```
  */
 
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { getAgent, validateAgentForTier } from "../../agents";
 import { resolveModel } from "../../config";
 import { resolvePermissions } from "../../config/permissions";
@@ -40,6 +42,22 @@ 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
@@ -128,11 +146,13 @@ export const executionStage: PipelineStage = {
         lite: isLiteMode,
       });
 
+      const effectiveWorkdir = _executionDeps.resolveStoryWorkdir(ctx.workdir, ctx.story.workdir);
+
       const tddResult = await runThreeSessionTdd({
         agent,
         story: ctx.story,
         config: ctx.config,
-        workdir: ctx.workdir,
+        workdir: effectiveWorkdir,
         modelTier: ctx.routing.modelTier,
         featureName: ctx.prd.feature,
         contextMarkdown: ctx.contextMarkdown,
@@ -212,9 +232,11 @@ export const executionStage: PipelineStage = {
       });
     }
 
+    const storyWorkdir = _executionDeps.resolveStoryWorkdir(ctx.workdir, ctx.story.workdir);
+
     const result = await agent.run({
       prompt: ctx.prompt,
-      workdir: ctx.workdir,
+      workdir: storyWorkdir,
       modelTier: ctx.routing.modelTier,
       modelDef: resolveModel(ctx.config.models[ctx.routing.modelTier]),
       timeoutSeconds: ctx.config.execution.sessionTimeoutSeconds,
@@ -258,7 +280,7 @@ export const executionStage: PipelineStage = {
     ctx.agentResult = result;
 
     // BUG-058: Auto-commit if agent left uncommitted changes (single-session/test-after)
-    await autoCommitIfDirty(ctx.workdir, "execution", "single-session", ctx.story.id);
+    await autoCommitIfDirty(storyWorkdir, "execution", "single-session", ctx.story.id);
 
     // merge-conflict trigger: detect CONFLICT markers in agent output
     const combinedOutput = (result.output ?? "") + (result.stderr ?? "");
@@ -327,4 +349,5 @@ export const _executionDeps = {
   checkMergeConflict,
   isAmbiguousOutput,
   checkStoryAmbiguity,
+  resolveStoryWorkdir,
 };

package/src/pipeline/stages/review.ts

@@ -11,6 +11,7 @@
  */
 
 // RE-ARCH: rewrite
+import { join } from "node:path";
 import { checkSecurityReview, isTriggerEnabled } from "../../interaction/triggers";
 import { getLogger } from "../../logger";
 import { reviewOrchestrator } from "../../review/orchestrator";
@@ -25,12 +26,16 @@ export const reviewStage: PipelineStage = {
 
     logger.info("review", "Running review phase", { storyId: ctx.story.id });
 
+    // MW-010: scope review to package directory when story.workdir is set
+    const effectiveWorkdir = ctx.story.workdir ? join(ctx.workdir, ctx.story.workdir) : ctx.workdir;
+
     const result = await reviewOrchestrator.review(
       ctx.config.review,
-      ctx.workdir,
+      effectiveWorkdir,
       ctx.config.execution,
       ctx.plugins,
       ctx.storyGitRef,
+      ctx.story.workdir, // MW-010: scope changed-file checks to package
     );
 
     ctx.reviewResult = result.builtIn;