@nathapp/nax 0.26.0 → 0.27.1

package/.gitlab-ci.yml

@@ -60,6 +60,7 @@ release:
     NPM_RELEASE_TOKEN: $NPM_TOKEN
   before_script:
     - apk add --no-cache git
+    - git config --global safe.directory '*'
     - git config --global user.name "$GITLAB_USER_NAME"
     - git config --global user.email "$GITLAB_USER_EMAIL"
   script:

package/CLAUDE.md

@@ -92,16 +92,46 @@ Runner.run()  [src/execution/runner.ts — thin orchestrator only]
 2. **Plan complex tasks**: for multi-file changes, write a short plan before implementing.
 3. **Implement in small chunks**: one logical concern per commit.
 
-## Code Intelligence (Solograph MCP)
+## Code Intelligence (Solograph MCP) — MANDATORY
 
-Use **solograph** MCP tools on-demand — do not use `web_search` or `kb_search`.
+**Always use solograph MCP tools before writing code or analyzing architecture.** Do NOT use `web_search` or `kb_search` as substitutes.
 
-| Tool | When |
-|:-----|:-----|
-| `project_code_search` | Find existing patterns before writing new code |
-| `codegraph_explain` | Architecture overview before tackling unfamiliar areas |
-| `codegraph_query` | Dependency/impact analysis (Cypher) |
-| `project_code_reindex` | After creating or deleting source files |
+### Tool Selection Guide
+
+| Tool | Capability | When to Use | Availability |
+|:-----|:-----------|:-----------|:-------------|
+| `codegraph_query` | Structural queries (Cypher) — find calls, dependencies, imports | **Preferred for dependency analysis, call tracing, symbol lookup** | ✅ Always works (in-memory graph) |
+| `project_code_search` | Semantic search (Redis vector DB) — pattern matching by meaning | Natural language queries like "find auth patterns" | ⚠️ Requires explicit `project_code_reindex` + Redis daemon |
+| `codegraph_explain` | Architecture overview for unfamiliar subsystems | Understand module relationships before major changes | ✅ Always works |
+| `project_code_reindex` | Index project for semantic search | After creating/deleting source files | ✅ Always works |
+
+### Recommended Workflow
+
+For nax, **prefer `codegraph_query`** for routine tasks:
+- Finding where functions are called (`calculateAggregateMetrics` called by `status-cost.ts`)
+- Analyzing dependencies before refactoring
+- Tracing import/export chains
+- Querying symbol definitions and relationships
+
+**Use `project_code_search` only if:**
+- You need semantic similarity ("find authentication patterns")
+- Redis is indexed and running (not guaranteed in all sessions)
+
+### Example Queries
+
+```cypher
+-- Find files calling calculateAggregateMetrics
+MATCH (f:File)-[:CALLS]->(s:Symbol {name: "calculateAggregateMetrics"})
+RETURN f.path
+
+-- Find all imports of aggregator.ts
+MATCH (f:File)-[:IMPORTS]->(target:File {path: "src/metrics/aggregator.ts"})
+RETURN f.path
+
+-- Find symbols defined in a file
+MATCH (f:File {path: "src/metrics/aggregator.ts"})-[:DEFINES]->(s:Symbol)
+RETURN s.name, s.type
+```
 
 ## Coding Standards & Forbidden Patterns
 

package/docs/ROADMAP.md

@@ -135,6 +135,19 @@
 
 ---
 
+## v0.27.0 — Review Quality ✅ Shipped (2026-03-08)
+
+**Theme:** Fix review stage reliability — dirty working tree false-positive, stale precheck, dead config fields
+**Status:** ✅ Shipped (2026-03-08)
+**Spec:** `nax/features/review-quality/prd.json`
+
+### Stories
+- [x] **RQ-001:** Assert clean working tree before running review typecheck/lint (BUG-049)
+- [x] **RQ-002:** Fix `checkOptionalCommands` precheck to use correct config resolution path (BUG-050)
+- [x] **RQ-003:** Consolidate dead `quality.commands.typecheck/lint` into review resolution chain (BUG-051)
+
+---
+
 ## v0.26.0 — Routing Persistence ✅ Shipped (2026-03-08)
 
 - **RRP-001:** Persist initial routing classification to `prd.json` on first classification
@@ -148,16 +161,16 @@
 ## v0.25.0 — Trigger Completion ✅ Shipped (2026-03-07)
 
 **Theme:** Wire all 8 unwired interaction triggers, 3 missing hook events, and add plugin integration tests
-**Status:** 🔲 Planned
+**Status:** ✅ Shipped (2026-03-07)
 **Spec:** [docs/specs/trigger-completion.md](specs/trigger-completion.md)
 
 ### Stories
-- [ ] **TC-001:** Wire `cost-exceeded` + `cost-warning` triggers — fire at 80%/100% of cost limit in sequential-executor.ts
-- [ ] **TC-002:** Wire `max-retries` trigger — fire on permanent story failure via `story:failed` event in wireInteraction
-- [ ] **TC-003:** Wire `security-review`, `merge-conflict`, `pre-merge` triggers — review rejection, git conflict detection, pre-completion gate
-- [ ] **TC-004:** Wire `story-ambiguity` + `review-gate` triggers — ambiguity keyword detection, per-story human checkpoint
-- [ ] **TC-005:** Wire missing hook events — `on-resume`, `on-session-end`, `on-error` to pipeline events
-- [ ] **TC-006:** Auto plugin + Telegram + Webhook integration tests — mock LLM/network, cover approve/reject/HMAC flows
+- [x] **TC-001:** Wire `cost-exceeded` + `cost-warning` triggers — fire at 80%/100% of cost limit in sequential-executor.ts
+- [x] **TC-002:** Wire `max-retries` trigger — fire on permanent story failure via `story:failed` event in wireInteraction
+- [x] **TC-003:** Wire `security-review`, `merge-conflict`, `pre-merge` triggers — review rejection, git conflict detection, pre-completion gate
+- [x] **TC-004:** Wire `story-ambiguity` + `review-gate` triggers — ambiguity keyword detection, per-story human checkpoint
+- [x] **TC-005:** Wire missing hook events — `on-resume`, `on-session-end`, `on-error` to pipeline events
+- [x] **TC-006:** Auto plugin + Telegram + Webhook integration tests — mock LLM/network, cover approve/reject/HMAC flows
 
 ---
 
@@ -308,17 +321,21 @@
 - [x] ~~**BUG-022:** Story interleaving — `getNextStory()` round-robins instead of exhausting retries on current story → fixed in v0.18.0~~
 - [x] ~~**BUG-023:** Agent failure silent — no exitCode/stderr in JSONL → fixed in v0.18.0~~
 - [x] ~~**BUG-025:** `needsHumanReview` not triggering interactive plugin → fixed in v0.18.0~~
-
-- [x] **BUG-029:** Escalation resets story to `pending` → bypasses BUG-022 retry priority. `handleTierEscalation()` sets `status: "pending"` after escalation, but `getNextStory()` Priority 1 only checks `status === "failed"`. Result: after BUG-026 escalated (iter 1), nax moved to BUG-028 (iter 2) instead of retrying BUG-026 immediately. **Location:** `src/prd/index.ts:getNextStory()` + `src/execution/escalation/tier-escalation.ts`. **Fix:** `getNextStory()` should also prioritize stories with `story.routing.modelTier` that changed since last attempt (escalation marker), or `handleTierEscalation` should use a distinct status like `"retry-pending"` that Priority 1 recognizes.
-- [x] **BUG-030:** Review lint failure → hard `"fail"`, no rectification or retry. `src/pipeline/stages/review.ts:92` returns `{ action: "fail" }` for all review failures including lint. In `pipeline-result-handler.ts`, `"fail"` calls `markStoryFailed()` — permanently dead. But lint errors are auto-fixable (agent can run `biome check --fix`). Contrast with verify stage which returns `"escalate"` on test failure, allowing retry. SFC-001 and SFC-002 both hit this — tests passed but 5 Biome lint errors killed the stories permanently. **Fix:** Review stage should return `"escalate"` (not `"fail"`) for lint/typecheck failures, or add a review-rectification loop (like verify has) that gives the agent one retry with the lint output as context. Reserve `"fail"` for unfixable review issues (e.g. plugin reviewer rejection).
-- [x] **BUG-031:** Keyword fallback classifier gives inconsistent strategy across retries for same story. BUG-026 was classified as `test-after` on iter 1 (keyword fallback), but `three-session-tdd-lite` on iter 5 (same keyword fallback). The keyword classifier in `src/routing/strategies/keyword.ts:classifyComplexity()` may be influenced by `priorErrors` text added between attempts, shifting the keyword match result. **Location:** `src/routing/strategies/keyword.ts`. **Fix:** Keyword classifier should only consider the story's original title + description + acceptance criteria, not accumulated `priorErrors` or `priorFailures`. Alternatively, once a strategy is set in `story.routing.testStrategy`, the routing stage should preserve it across retries (already partially done in `routing.ts:40-41` but may not apply when LLM falls back to keyword).
-- [x] **BUG-032:** Routing stage overrides escalated `modelTier` with complexity-derived tier. `src/pipeline/stages/routing.ts:43` always runs `complexityToModelTier(routing.complexity, config)` even when `story.routing.modelTier` was explicitly set by `handleTierEscalation()`. BUG-026 was escalated to `balanced` (logged in iteration header), but `Task classified` shows `modelTier=fast` because `complexityToModelTier("simple", config)` → `"fast"`. Related to BUG-013 (escalation routing not applied) which was marked fixed, but the fix in `applyCachedRouting()` in `pipeline-result-handler.ts:295-310` runs **after** the routing stage — too late. **Location:** `src/pipeline/stages/routing.ts:43`. **Fix:** When `story.routing.modelTier` is explicitly set (by escalation), skip `complexityToModelTier()` and use the cached tier directly. Only derive from complexity when `story.routing.modelTier` is absent.
-- [x] **BUG-033:** LLM routing has no retry on timeout — single attempt with hardcoded 15s default. All 5 LLM routing attempts in the v0.18.3 run timed out at 15s, forcing keyword fallback every time. `src/routing/strategies/llm.ts:63` reads `llmConfig?.timeoutMs ?? 15000` but there's no retry logic — one timeout = immediate fallback. **Location:** `src/routing/strategies/llm.ts:callLlm()`. **Fix:** Add `routing.llm.retries` config (default: 1) with backoff. Also surface `routing.llm.timeoutMs` in `nax config --explain` and consider raising default to 30s for batch routing which processes multiple stories.
-
-- [x] ~~**BUG-037:** Test output summary (verify stage) captures precheck boilerplate instead of actual `bun test` failure. Fixed: `.slice(-20)` tail — shipped in v0.22.1 (re-arch phase 2).~~
-- [x] ~~**BUG-038:** `smart-runner` over-matching when global defaults change. Fixed by FEAT-010 (v0.21.0) — per-attempt `storyGitRef` baseRef tracking; `git diff <baseRef>..HEAD` prevents cross-story file pollution.~~
-- [x] ~~**BUG-043:** Scoped test command appends files instead of replacing path — `runners.ts:scoped()` concatenates `scopedTestPaths` to full-suite command, resulting in `bun test test/ --timeout=60000 /path/to/file.ts` (runs everything). Fix: use `testScoped` config with `{{files}}` template, fall back to `buildSmartTestCommand()` heuristic. **Location:** `src/verification/runners.ts:scoped()`
-- [x] ~~**BUG-044:** Scoped/full-suite test commands not logged — no visibility into what command was actually executed during verify stage. Fix: log at info level before execution.
+- [x] ~~**BUG-029:** Escalation resets story to `pending`. Fixed.~~
+- [x] ~~**BUG-030:** Review lint failure resets. Fixed.~~
+- [x] ~~**BUG-031:** Keyword fallback classifier inconsistency. Fixed.~~
+- [x] ~~**BUG-032:** Routing stage overrides escalated modelTier. Fixed.~~
+- [x] ~~**BUG-033:** LLM routing timeout/retry. Fixed.~~
+- [x] ~~**BUG-037:** Test output summary (verify stage) tail. Fixed.~~
+- [x] ~~**BUG-038:** smart-runner over-matching. Fixed.~~
+- [x] ~~**BUG-043:** Scoped test command construction. Fixed.~~
+- [x] ~~**BUG-044:** Scoped/full-suite test command logging. Fixed.~~
+- [x] ~~**BUG-049:** Review typecheck runs on dirty working tree. Fixed in v0.27.0.~~
+- [x] ~~**BUG-050:** `checkOptionalCommands` precheck uses legacy config fields. Fixed in v0.27.0.~~
+- [x] ~~**BUG-051:** `quality.commands.typecheck/lint` are dead config. Fixed in v0.27.0.~~
+- [x] ~~**BUG-052:** `console.warn` in runtime pipeline code bypasses JSONL logger. Fixed in v0.26.0.~~
+- [ ] **BUG-054:** Redundant scoped verify after TDD full-suite gate passes. When rectification gate runs full test suite and passes, the pipeline verify stage re-runs scoped tests (subset). **Fix:** Skip verify if full-suite gate already passed.
+- [ ] **BUG-055:** Pipeline skip messages conflate "not needed" with "disabled". `runner.ts:54` logs "skipped (disabled)" for all stages where `enabled()` returns false, even if just because tests passed. **Fix:** Differentiate log message.
 
 ### Features
 - [x] ~~`nax unlock` command~~
@@ -344,4 +361,4 @@ Sequential canary → stable: `v0.12.0-canary.0` → `canary.N` → `v0.12.0`
 Canary: `npm publish --tag canary`
 Stable: `npm publish` (latest)
 
-*Last updated: 2026-03-07 (v0.22.1 shipped — Pipeline Re-Architecture: VerificationOrchestrator, EventBus, new stages, post-run SSOT)*
+*Last updated: 2026-03-08 (v0.27.0 shipped — Review Quality)*

package/nax/features/review-quality/prd.json

@@ -0,0 +1,55 @@
+{
+  "project": "nax-review-quality",
+  "branchName": "feat/review-quality",
+  "feature": "review-quality",
+  "updatedAt": "2026-03-08T03:03:00.000Z",
+  "userStories": [
+    {
+      "id": "RQ-001",
+      "title": "Assert clean working tree before running review typecheck/lint (BUG-049)",
+      "description": "The review stage runs bun run typecheck and bun run lint on the working tree, not the committed state. If the agent forgets to git add a file (e.g. types.ts with a new interface field), the uncommitted change is still on disk, typecheck passes against the local working tree, but the committed code has a type error. This was observed in the routing-persistence run: RRP-003 committed contentHash refs in routing.ts without the matching StoryRouting.contentHash field in types.ts — typecheck passed because types.ts was locally modified but not staged. Fix: before running built-in checks in review/runner.ts, assert that the working tree has no uncommitted changes to tracked files (git diff --name-only HEAD returns empty). If dirty, fail the review with a clear message listing the uncommitted files so the agent can stage and commit them.",
+      "acceptanceCriteria": [
+        "Before running typecheck or lint in runReview(), call git diff --name-only HEAD (covers both staged and unstaged tracked-file changes)",
+        "If output is non-empty, return a ReviewResult with success: false and failureReason listing the uncommitted files",
+        "Log at warn level via getSafeLogger() with stage 'review' and message 'Uncommitted changes detected before review: <files>'",
+        "If working tree is clean, proceed with typecheck/lint as before — no regression for normal flow",
+        "Unit tests: dirty working tree (mock git diff) returns review failure before running typecheck; clean working tree allows typecheck to run normally",
+        "Unit tests: untracked files only (git diff HEAD returns empty) — review proceeds since only tracked changes matter"
+      ],
+      "complexity": "simple",
+      "status": "pending",
+      "tags": ["bug", "review", "typecheck"]
+    },
+    {
+      "id": "RQ-002",
+      "title": "Fix checkOptionalCommands precheck to use correct config resolution path (BUG-050)",
+      "description": "The precheck check checkOptionalCommands() in src/precheck/checks-warnings.ts checks config.execution.lintCommand and config.execution.typecheckCommand — these are legacy fields that no longer exist in the current config schema. The actual runtime resolution chain used by review/runner.ts is: (1) execution.typecheckCommand, (2) review.commands.typecheck, (3) package.json scripts. As a result, the precheck always warns 'Optional commands not configured: lint, typecheck' even when review.commands.typecheck and review.commands.lint are properly set. Fix: update checkOptionalCommands() to resolve via the same priority chain as review/runner.ts:resolveCommand().",
+      "acceptanceCriteria": [
+        "checkOptionalCommands() resolves typecheck via: execution.typecheckCommand -> review.commands.typecheck -> package.json typecheck script",
+        "checkOptionalCommands() resolves lint via: execution.lintCommand -> review.commands.lint -> package.json lint script",
+        "If config.review.commands.typecheck is set, precheck passes with no warning",
+        "If neither execution field, review.commands, nor package.json script exists, precheck still warns 'not configured'",
+        "Unit tests: config with review.commands.typecheck set -> check passes; config with neither -> check warns; config with package.json script -> check passes"
+      ],
+      "complexity": "simple",
+      "status": "pending",
+      "tags": ["bug", "precheck", "config"]
+    },
+    {
+      "id": "RQ-003",
+      "title": "Consolidate dead quality.commands.typecheck/lint into review resolution chain (BUG-051)",
+      "description": "QualityConfig.commands.typecheck and QualityConfig.commands.lint are declared in src/config/types.ts and documented in nax config --explain, but are never read by runtime code. The review runner reads only review.commands.typecheck/lint. Fix: make review/runner.ts:resolveCommand() also check quality.commands as a fallback after review.commands and before package.json. This gives quality.commands.typecheck semantic meaning without a breaking change. Do NOT remove the fields from QualityConfig — backward compatibility.",
+      "acceptanceCriteria": [
+        "review/runner.ts:resolveCommand() priority chain for typecheck: (1) execution.typecheckCommand, (2) review.commands.typecheck, (3) quality.commands.typecheck, (4) package.json typecheck script",
+        "review/runner.ts:resolveCommand() priority chain for lint: (1) execution.lintCommand, (2) review.commands.lint, (3) quality.commands.lint, (4) package.json lint script",
+        "Setting quality.commands.typecheck in config.json now correctly runs that command in the review stage",
+        "review.commands.typecheck still takes precedence over quality.commands.typecheck when both are set",
+        "CLI config --explain description for quality.commands.typecheck updated to note it is used as fallback in review stage",
+        "Unit tests: quality.commands.typecheck set with review.commands.typecheck absent -> quality command used; both set -> review command takes precedence"
+      ],
+      "complexity": "simple",
+      "status": "pending",
+      "tags": ["bug", "config", "review"]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.26.0",
+  "version": "0.27.1",
   "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {

package/src/optimizer/index.ts

@@ -14,6 +14,7 @@ export { NoopOptimizer } from "./noop.optimizer.js";
 export { RuleBasedOptimizer } from "./rule-based.optimizer.js";
 
 import type { NaxConfig } from "../config/schema.js";
+import { getSafeLogger } from "../logger/index.js";
 import type { PluginRegistry } from "../plugins/registry.js";
 import { NoopOptimizer } from "./noop.optimizer.js";
 import { RuleBasedOptimizer } from "./rule-based.optimizer.js";
@@ -56,7 +57,7 @@ export function resolveOptimizer(config: NaxConfig, pluginRegistry?: PluginRegis
       return new NoopOptimizer();
     default:
       // Unknown strategy, fallback to noop
-      console.warn(`[nax] Unknown optimizer strategy '${strategy}', using noop`);
+      getSafeLogger()?.warn("optimizer", `Unknown optimizer strategy '${strategy}', using noop`);
       return new NoopOptimizer();
   }
 }

package/src/pipeline/runner.ts

@@ -51,7 +51,8 @@ export async function runPipeline(
 
     // Skip disabled stages
     if (!stage.enabled(context)) {
-      logger.debug("pipeline", `Stage "${stage.name}" skipped (disabled)`);
+      const reason = stage.skipReason?.(context) ?? "disabled";
+      logger.debug("pipeline", `Stage "${stage.name}" skipped (${reason})`);
       i++;
       continue;
     }

package/src/pipeline/stages/autofix.ts

@@ -29,6 +29,11 @@ export const autofixStage: PipelineStage = {
     return autofixEnabled;
   },
 
+  skipReason(ctx: PipelineContext): string {
+    if (!ctx.reviewResult || ctx.reviewResult.success) return "not needed (review passed)";
+    return "disabled (autofix not enabled in config)";
+  },
+
   async execute(ctx: PipelineContext): Promise<StageResult> {
     const logger = getLogger();
     const { reviewResult } = ctx;

package/src/pipeline/stages/rectify.ts

@@ -27,6 +27,11 @@ export const rectifyStage: PipelineStage = {
     return ctx.config.execution.rectification?.enabled ?? false;
   },
 
+  skipReason(ctx: PipelineContext): string {
+    if (!ctx.verifyResult || ctx.verifyResult.success) return "not needed (verify passed)";
+    return "disabled (rectification not enabled in config)";
+  },
+
   async execute(ctx: PipelineContext): Promise<StageResult> {
     const logger = getLogger();
     const { verifyResult } = ctx;

package/src/pipeline/stages/regression.ts

@@ -26,12 +26,17 @@ export const regressionStage: PipelineStage = {
     const mode = ctx.config.execution.regressionGate?.mode ?? "deferred";
     if (mode !== "per-story") return false;
     // Only run when verify passed (or was skipped/not set)
-    // Only run when verify passed (or was skipped/not set)
     if (ctx.verifyResult && !ctx.verifyResult.success) return false;
     const gateEnabled = ctx.config.execution.regressionGate?.enabled ?? true;
     return gateEnabled;
   },
 
+  skipReason(ctx: PipelineContext): string {
+    const mode = ctx.config.execution.regressionGate?.mode ?? "deferred";
+    if (mode !== "per-story") return `not needed (regression mode is '${mode}', not 'per-story')`;
+    return "disabled (regression gate not enabled in config)";
+  },
+
   async execute(ctx: PipelineContext): Promise<StageResult> {
     const logger = getLogger();
     const testCommand = ctx.config.review?.commands?.test ?? ctx.config.quality.commands.test ?? "bun test";

package/src/pipeline/stages/verify.ts

@@ -45,7 +45,8 @@ function buildScopedCommand(testFiles: string[], baseCommand: string, testScoped
 
 export const verifyStage: PipelineStage = {
   name: "verify",
-  enabled: () => true,
+  enabled: (ctx: PipelineContext) => !ctx.fullSuiteGatePassed,
+  skipReason: () => "not needed (full-suite gate already passed)",
 
   async execute(ctx: PipelineContext): Promise<StageResult> {
     const logger = getLogger();

package/src/pipeline/types.ts

@@ -108,6 +108,8 @@ export interface PipelineContext {
   retryAsLite?: boolean;
   /** Failure category from TDD orchestrator (set by executionStage on TDD failure) */
   tddFailureCategory?: FailureCategory;
+  /** Set to true when TDD full-suite gate already passed — verify stage skips to avoid redundant run (BUG-054) */
+  fullSuiteGatePassed?: boolean;
 }
 
 /**
@@ -167,6 +169,13 @@ export interface PipelineStage {
    */
   enabled: (ctx: PipelineContext) => boolean;
 
+  /**
+   * Optional human-readable reason why the stage was skipped.
+   * Distinguishes "not needed" (conditions not met) from "disabled" (config).
+   * Used by the pipeline runner for better observability (BUG-055).
+   */
+  skipReason?: (ctx: PipelineContext) => string;
+
   /**
    * Execute the stage logic.
    *

package/src/review/runner.ts

@@ -6,6 +6,7 @@
 
 import { spawn } from "bun";
 import type { ExecutionConfig } from "../config/schema";
+import { getSafeLogger } from "../logger";
 import type { ReviewCheckName, ReviewCheckResult, ReviewConfig, ReviewResult } from "./types";
 
 /** Default commands for each check type */
@@ -159,6 +160,40 @@ async function runCheck(check: ReviewCheckName, command: string, workdir: string
   }
 }
 
+/**
+ * Get uncommitted tracked files via git diff --name-only HEAD.
+ * Returns empty array if git command fails or working tree is clean.
+ */
+async function getUncommittedFilesImpl(workdir: string): Promise<string[]> {
+  try {
+    const proc = spawn({
+      cmd: ["git", "diff", "--name-only", "HEAD"],
+      cwd: workdir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const exitCode = await proc.exited;
+    if (exitCode !== 0) {
+      return [];
+    }
+
+    const output = await new Response(proc.stdout).text();
+    return output.trim().split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Swappable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
+ * RQ-001: getUncommittedFiles enables mocking of the git dirty-tree check.
+ */
+export const _deps = {
+  /** Returns tracked files with uncommitted changes (git diff --name-only HEAD). */
+  getUncommittedFiles: getUncommittedFilesImpl,
+};
+
 /**
  * Run all configured review checks
  */
@@ -168,16 +203,30 @@ export async function runReview(
   executionConfig?: ExecutionConfig,
 ): Promise<ReviewResult> {
   const startTime = Date.now();
+  const logger = getSafeLogger();
   const checks: ReviewCheckResult[] = [];
   let firstFailure: string | undefined;
 
+  // RQ-001: Check for uncommitted tracked files before running checks
+  const uncommittedFiles = await _deps.getUncommittedFiles(workdir);
+  if (uncommittedFiles.length > 0) {
+    const fileList = uncommittedFiles.join(", ");
+    logger?.warn("review", `Uncommitted changes detected before review: ${fileList}`);
+    return {
+      success: false,
+      checks: [],
+      totalDurationMs: Date.now() - startTime,
+      failureReason: `Working tree has uncommitted changes:\n${uncommittedFiles.map((f) => `  - ${f}`).join("\n")}\n\nStage and commit these files before running review.`,
+    };
+  }
+
   for (const checkName of config.checks) {
     // Resolve command using resolution strategy
     const command = await resolveCommand(checkName, config, executionConfig, workdir);
 
     // Skip if explicitly disabled or not found
     if (command === null) {
-      console.warn(`[nax] Skipping ${checkName} check (command not configured or disabled)`);
+      getSafeLogger()?.warn("review", `Skipping ${checkName} check (command not configured or disabled)`);
       continue;
     }
 

package/src/tdd/orchestrator.ts

@@ -255,7 +255,16 @@ export async function runThreeSessionTdd(options: ThreeSessionTddOptions): Promi
   }
 
   // Full-Suite Gate (v0.11 Rectification)
-  await runFullSuiteGate(story, config, workdir, agent, implementerTier, contextMarkdown, lite, logger);
+  const fullSuiteGatePassed = await runFullSuiteGate(
+    story,
+    config,
+    workdir,
+    agent,
+    implementerTier,
+    contextMarkdown,
+    lite,
+    logger,
+  );
 
   // Session 3: Verifier
   const session3Ref = (await captureGitRef(workdir)) ?? "HEAD";
@@ -379,5 +388,6 @@ export async function runThreeSessionTdd(options: ThreeSessionTddOptions): Promi
     verdict,
     totalCost,
     lite,
+    fullSuiteGatePassed,
   };
 }

package/src/tdd/rectification-gate.ts

@@ -34,9 +34,9 @@ export async function runFullSuiteGate(
   contextMarkdown: string | undefined,
   lite: boolean,
   logger: ReturnType<typeof getLogger>,
-): Promise<void> {
+): Promise<boolean> {
   const rectificationEnabled = config.execution.rectification?.enabled ?? false;
-  if (!rectificationEnabled) return;
+  if (!rectificationEnabled) return false;
 
   const rectificationConfig = config.execution.rectification;
   const testCmd = config.quality?.commands?.test ?? "bun test";
@@ -54,7 +54,7 @@ export async function runFullSuiteGate(
     const testSummary = parseBunTestOutput(fullSuiteResult.output);
 
     if (testSummary.failed > 0) {
-      await runRectificationLoop(
+      return await runRectificationLoop(
         story,
         config,
         workdir,
@@ -69,14 +69,18 @@ export async function runFullSuiteGate(
         fullSuiteTimeout,
       );
     }
-  } else if (fullSuitePassed) {
+    // No failures detected despite non-zero exit — treat as passed
+    return true;
+  }
+  if (fullSuitePassed) {
     logger.info("tdd", "Full suite gate passed", { storyId: story.id });
-  } else {
-    logger.warn("tdd", "Full suite gate execution failed (no output)", {
-      storyId: story.id,
-      exitCode: fullSuiteResult.exitCode,
-    });
+    return true;
   }
+  logger.warn("tdd", "Full suite gate execution failed (no output)", {
+    storyId: story.id,
+    exitCode: fullSuiteResult.exitCode,
+  });
+  return false;
 }
 
 /** Run the rectification retry loop when full suite gate detects regressions. */
@@ -93,7 +97,7 @@ async function runRectificationLoop(
   rectificationConfig: NonNullable<NaxConfig["execution"]["rectification"]>,
   testCmd: string,
   fullSuiteTimeout: number,
-): Promise<void> {
+): Promise<boolean> {
   const rectificationState: RectificationState = {
     attempt: 0,
     initialFailures: testSummary.failed,
@@ -156,7 +160,7 @@ async function runRectificationLoop(
         storyId: story.id,
         attempt: rectificationState.attempt,
       });
-      break;
+      return true;
     }
 
     if (retryFullSuite.output) {
@@ -177,7 +181,8 @@ async function runRectificationLoop(
       attempts: rectificationState.attempt,
       remainingFailures: rectificationState.currentFailures,
     });
-  } else {
-    logger.info("tdd", "Full suite gate passed", { storyId: story.id });
+    return false;
   }
+  logger.info("tdd", "Full suite gate passed", { storyId: story.id });
+  return true;
 }

package/src/tdd/types.ts

@@ -78,4 +78,6 @@ export interface ThreeSessionTddResult {
    * undefined = verdict was not attempted (e.g. early-exit before session 3 ran)
    */
   verdict?: import("./verdict").VerifierVerdict | null;
+  /** Whether the TDD full-suite gate passed (used by verify stage to skip redundant run, BUG-054) */
+  fullSuiteGatePassed?: boolean;
 }

package/src/version.ts

@@ -2,7 +2,7 @@
  * Version and build info for nax.
  *
  * GIT_COMMIT is injected at build time via --define in the bun build script.
- * When running from source (bun run dev), it falls back to "dev".
+ * When running from source (bin/nax.ts), falls back to runtime git rev-parse.
  */
 
 import pkg from "../package.json";
@@ -11,13 +11,29 @@ declare const GIT_COMMIT: string;
 
 export const NAX_VERSION: string = pkg.version;
 
-/** Short git commit hash, injected at build time. Falls back to "dev" from source. */
+/** Short git commit hash — injected at build time, or resolved at runtime from git. */
 export const NAX_COMMIT: string = (() => {
+  // Build-time injection (bun build --define GIT_COMMIT=...)
+  // Guard: must be a non-empty string that looks like a real commit hash
   try {
-    return GIT_COMMIT ?? "dev";
+    if (typeof GIT_COMMIT === "string" && /^[0-9a-f]{6,10}$/.test(GIT_COMMIT)) return GIT_COMMIT;
   } catch {
-    return "dev";
+    // not injected — fall through to runtime resolution
   }
+  // Runtime fallback: resolve from the source file's git repo (Bun-native)
+  try {
+    const result = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"], {
+      cwd: import.meta.dir,
+      stderr: "ignore",
+    });
+    if (result.exitCode === 0) {
+      const hash = result.stdout.toString().trim();
+      if (/^[0-9a-f]{6,10}$/.test(hash)) return hash;
+    }
+  } catch {
+    // git not available
+  }
+  return "dev";
 })();
 
 export const NAX_BUILD_INFO = `v${NAX_VERSION} (${NAX_COMMIT})`;

package/test/integration/review/review-plugin-integration.test.ts

@@ -173,7 +173,7 @@ describe("Review Stage - Plugin Integration", () => {
       expect(receivedWorkdir).toBe(tempDir);
     });
 
-    test("reviewer receives list of changed files", async () => {
+    test("review fails when there are uncommitted changes (RQ-001)", async () => {
       const tempDir = mkdtempSync(join(tmpdir(), "nax-review-plugin-"));
 
       // Create a file first
@@ -181,15 +181,16 @@ describe("Review Stage - Plugin Integration", () => {
 
       await initGitRepo(tempDir);
 
-      // Now modify the file after git init
+      // Now modify the file after git init WITHOUT committing
+      // This violates RQ-001 (dirty working tree)
       writeFileSync(join(tempDir, "test.ts"), "// modified");
 
-      let receivedFiles: string[] | undefined;
+      let reviewerCalled = false;
       const mockReviewer: IReviewPlugin = {
         name: "test-reviewer",
         description: "Test reviewer",
-        async check(_workdir, changedFiles) {
-          receivedFiles = changedFiles;
+        async check(_workdir) {
+          reviewerCalled = true;
           return { passed: true, output: "OK" };
         },
       };
@@ -204,9 +205,13 @@ describe("Review Stage - Plugin Integration", () => {
       const registry = new PluginRegistry([mockPlugin]);
       const ctx = createMockContext(tempDir, registry);
 
-      await reviewStage.execute(ctx);
+      const result = await reviewStage.execute(ctx);
 
-      expect(receivedFiles).toContain("test.ts");
+      // RQ-001: Review should fail with dirty working tree
+      expect(result.action).toBe("escalate");
+      expect(result.reason).toContain("Working tree has uncommitted changes");
+      // Reviewer should not be called due to dirty tree check
+      expect(reviewerCalled).toBe(false);
     });
 
     test("reviewer receives empty array when no files changed", async () => {

package/test/unit/review/runner.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Unit tests for src/review/runner.ts
+ * RQ-001: Assert clean working tree before running review typecheck/lint (BUG-049)
+ *
+ * Tests verify that runReview() checks for uncommitted tracked-file changes
+ * (via git diff --name-only HEAD) before running typecheck or lint.
+ */
+
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { _deps, runReview } from "../../../src/review/runner";
+import type { ReviewConfig } from "../../../src/review/types";
+
+/** Minimal ReviewConfig with typecheck enabled but command set to disable via executionConfig */
+const typecheckConfig: ReviewConfig = {
+  enabled: true,
+  checks: ["typecheck"],
+  commands: {},
+};
+
+/** ReviewConfig with no checks — used to isolate the dirty-tree guard logic */
+const noChecksConfig: ReviewConfig = {
+  enabled: true,
+  checks: [],
+  commands: {},
+};
+
+describe("runReview — dirty working tree guard (RQ-001)", () => {
+  let originalGetUncommittedFiles: typeof _deps.getUncommittedFiles;
+
+  beforeEach(() => {
+    originalGetUncommittedFiles = _deps.getUncommittedFiles;
+  });
+
+  afterEach(() => {
+    mock.restore();
+    _deps.getUncommittedFiles = originalGetUncommittedFiles;
+  });
+
+  describe("dirty working tree", () => {
+    test("returns failure with uncommitted files listed in failureReason", async () => {
+      _deps.getUncommittedFiles = mock(async (_workdir: string) => [
+        "src/types.ts",
+        "src/routing.ts",
+      ]);
+
+      const result = await runReview(typecheckConfig, "/tmp/fake-workdir");
+
+      expect(result.success).toBe(false);
+      expect(result.failureReason).toBeDefined();
+      expect(result.failureReason).toContain("src/types.ts");
+      expect(result.failureReason).toContain("src/routing.ts");
+    });
+
+    test("does not run typecheck when working tree is dirty", async () => {
+      _deps.getUncommittedFiles = mock(async (_workdir: string) => ["src/types.ts"]);
+
+      // If typecheck were run it would fail (no real workdir), but we expect
+      // an early return with zero checks executed.
+      const result = await runReview(typecheckConfig, "/tmp/fake-workdir");
+
+      expect(result.checks).toHaveLength(0);
+    });
+
+    test("calls getUncommittedFiles with the provided workdir", async () => {
+      const mockFn = mock(async (_workdir: string) => ["src/types.ts"]);
+      _deps.getUncommittedFiles = mockFn;
+
+      await runReview(typecheckConfig, "/tmp/my-project");
+
+      expect(mockFn).toHaveBeenCalledWith("/tmp/my-project");
+    });
+  });
+
+  describe("clean working tree", () => {
+    test("proceeds past dirty-tree guard when no uncommitted files", async () => {
+      _deps.getUncommittedFiles = mock(async (_workdir: string) => []);
+
+      // typecheckCommand: null disables the check so no real process is spawned.
+      const result = await runReview(typecheckConfig, "/tmp/fake-workdir", {
+        typecheckCommand: null,
+        maxIterations: 5,
+        iterationDelayMs: 0,
+        costLimit: 10,
+        sessionTimeoutSeconds: 300,
+        verificationTimeoutSeconds: 60,
+        maxStoriesPerFeature: 20,
+        contextProviderTokenBudget: 2000,
+        rectification: { enabled: false, maxIterations: 3 },
+        regressionGate: { enabled: false },
+      });
+
+      expect(result.success).toBe(true);
+    });
+
+    test("calls getUncommittedFiles before running checks", async () => {
+      const mockFn = mock(async (_workdir: string) => []);
+      _deps.getUncommittedFiles = mockFn;
+
+      await runReview(noChecksConfig, "/tmp/clean-workdir");
+
+      expect(mockFn).toHaveBeenCalledWith("/tmp/clean-workdir");
+    });
+  });
+
+  describe("untracked files only", () => {
+    test("review proceeds when git diff HEAD returns empty (only untracked files exist)", async () => {
+      // git diff --name-only HEAD only reports tracked files with changes.
+      // Untracked files are invisible to this command — working tree is considered clean.
+      _deps.getUncommittedFiles = mock(async (_workdir: string) => []);
+
+      const result = await runReview(noChecksConfig, "/tmp/fake-workdir");
+
+      // Should succeed — no dirty tracked files, review can proceed
+      expect(result.success).toBe(true);
+    });
+  });
+});