@nathapp/nax 0.27.0 → 0.27.1

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

@@ -321,22 +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.
-- [ ] **BUG-049:** Review typecheck runs on dirty working tree — false-positive pass when agent commits partial changes. If the agent stages only some files (e.g. forgets `git add types.ts`), the working tree retains the uncommitted fix and `bun run typecheck` passes — but the committed state has a type error. Discovered in 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 uncommitted. **Location:** `src/review/runner.ts:runCheck()`. **Fix:** Before running built-in checks, assert working tree is clean (`git diff --name-only` returns empty). If dirty, fail with "uncommitted changes detected" or log a warning and stash/restore.
-- [ ] **BUG-050:** `checkOptionalCommands` precheck uses legacy config fields — misleading "not configured" warning. Checks `config.execution.lintCommand` and `config.execution.typecheckCommand` (stale/legacy fields). Actual config uses `config.review.commands.typecheck` and `config.review.commands.lint`. Result: precheck always warns "Optional commands not configured: lint, typecheck" even when correctly configured, desensitizing operators to real warnings. **Location:** `src/precheck/checks-warnings.ts:checkOptionalCommands()`. **Fix:** Update check to resolve via the same priority chain as `review/runner.ts`: `execution.*Command` → `review.commands.*` → `package.json` scripts.
-- [ ] **BUG-052:** `console.warn` in runtime pipeline code bypasses structured JSONL logger — invisible to log consumers. `src/review/runner.ts` and `src/optimizer/index.ts` used `console.warn()` for skip/fallback events, which print to stderr but are never written to the JSONL log file. This made review stage skip decisions invisible during post-run analysis. **Location:** `src/review/runner.ts:runReview()`, `src/optimizer/index.ts:resolveOptimizer()`. **Fix:** Replace with `getSafeLogger()?.warn()`. ✅ Fixed in feat/routing-persistence.
-- [ ] **BUG-052:** `console.warn` in runtime pipeline code bypasses structured JSONL logger — invisible to log consumers. `src/review/runner.ts` and `src/optimizer/index.ts` used `console.warn()` for skip/fallback events, which print to stderr but are never written to the JSONL log file. This made review stage skip decisions invisible during post-run analysis. **Location:** `src/review/runner.ts:runReview()`, `src/optimizer/index.ts:resolveOptimizer()`. **Fix:** Replace with `getSafeLogger()?.warn()`. ✅ Fixed in feat/routing-persistence.
-- [ ] **BUG-051:** `quality.commands.typecheck` and `quality.commands.lint` are dead config — silently ignored. `QualityConfig.commands.{typecheck,lint}` exist in the type definition and are documented in `nax config --explain`, but are never read by any runtime code. The review runner reads only `review.commands.typecheck/lint`. Users who set `quality.commands.typecheck` get no effect. **Location:** `src/config/types.ts` (QualityConfig), `src/review/runner.ts:resolveCommand()`. **Fix:** Either (A) remove the dead fields from `QualityConfig` and update docs, or (B) consolidate — make review runner read from `quality.commands` and deprecate `review.commands`.
+- [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~~
@@ -362,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/package.json

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

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/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;
 }