@nathapp/nax 0.18.1

package/docs/20260225-phase2-llm-service-layer.md

@@ -0,0 +1,401 @@
+# Phase 2: LLM Service Layer — Merged Architecture Design
+
+*Date: 2026-02-25*
+*Status: Proposed (pending decision)*
+*Supersedes: Original issue #3 design + 2026-02-25 architecture analysis*
+
+---
+
+## Problem
+
+nax v0.10.0 has two coupling issues:
+
+1. **All LLM calls go through Claude Code CLI** — routing, review, acceptance stages spawn `claude -p` just for text reasoning. Wasteful.
+2. **All coding goes through CLI subprocess** — ~350MB RAM each, blocks parallelism.
+
+## Solution: Unified LLM Service Layer + Lightweight Agent Loop
+
+Two execution paths, one provider abstraction:
+
+```
+LlmProvider (interface — normalized across providers)
+  ├── AnthropicProvider        (Messages API)
+  ├── GoogleProvider           (GenerateContent API)
+  └── OpenAiCompatProvider     (Chat Completions — covers OpenAI, Moonshot, DeepSeek, OpenRouter, Groq, etc.)
+
+Used by:
+  ├── LLM Mode (text in → text out) — routing, analyze, review, acceptance
+  │     └── llm/client.ts → callLlm(prompt, tier, config)
+  │
+  └── Agent Mode (text + tools) — coding, TDD
+        ├── DirectApiAdapter — LlmProvider + tool loop (~5MB per session)
+        └── ClaudeCodeAdapter — CLI subprocess (~350MB, for TDD/interactive)
+```
+
+## Architecture
+
+```
+src/
+├── llm/                      # LLM Service Layer (shared by both modes)
+│   ├── types.ts              # LlmProvider interface, Message, ToolCall types
+│   ├── client.ts             # callLlm() with fallback chain logic
+│   ├── registry.ts           # Create provider from config
+│   └── providers/
+│       ├── anthropic.ts      # Anthropic Messages API
+│       ├── openai-compat.ts  # OpenAI-compatible (configurable baseUrl)
+│       └── google.ts         # Google Gemini API
+│
+├── llm/tools/                # Minimal tool set for Direct API coding
+│   ├── types.ts              # ToolDefinition, ToolResult
+│   ├── read-file.ts          # Read file contents
+│   ├── write-file.ts         # Write/create file
+│   ├── list-files.ts         # List directory
+│   ├── search-files.ts       # Grep/ripgrep
+│   └── run-command.ts        # Shell exec (tests, git)
+│
+├── llm/agent-loop.ts         # Tool use cycle: prompt → chat() → execute tools → loop
+│
+├── agents/                   # Agent adapters (implement AgentAdapter interface)
+│   ├── types.ts              # AgentAdapter, AgentResult (unchanged)
+│   ├── claude.ts             # ClaudeCodeAdapter (current — subprocess)
+│   ├── direct-api.ts         # DirectApiAdapter (new — wraps llm/ + tools)
+│   ├── registry.ts           # Resolve backend config → adapter instance
+│   └── cost.ts               # Cost estimation (unchanged for CLI, exact for API)
+│
+├── pipeline/stages/          # Each stage declares its execution mode
+│   ├── routing.ts            # LLM Mode → llm/client.ts
+│   ├── analyze.ts            # LLM Mode → llm/client.ts
+│   ├── coding.ts             # Agent Mode → agents/registry.ts
+│   ├── tdd.ts                # Agent Mode → agents/registry.ts
+│   ├── review.ts             # LLM Mode → llm/client.ts
+│   └── acceptance.ts         # LLM Mode → llm/client.ts
+│
+└── config/schema.ts          # Extended with providers, routing, pipeline overrides
+```
+
+## LlmProvider Interface
+
+```typescript
+interface LlmProvider {
+  readonly name: string;
+
+  chat(options: {
+    model: string;
+    messages: Message[];
+    tools?: ToolDefinition[];   // Optional — omit for LLM Mode (reasoning only)
+    maxTokens?: number;
+    temperature?: number;
+    timeoutMs?: number;
+  }): Promise<LlmResponse>;
+}
+
+interface LlmResponse {
+  content: string;
+  toolCalls: ToolCall[];         // Normalized regardless of provider format
+  stopReason: "end_turn" | "tool_use" | "max_tokens";
+  usage: { inputTokens: number; outputTokens: number };
+}
+```
+
+Single interface serves both modes:
+- **LLM Mode** (routing, review): `chat()` without `tools` → text response
+- **Agent Mode** (coding): `chat()` with `tools` → tool calls → agent loop iterates
+
+## Provider Implementations
+
+| Implementation | Covers | API Format | Tool Use Format |
+|:---------------|:-------|:-----------|:---------------|
+| `AnthropicProvider` | Anthropic (Claude) | Messages API | `tool_use` content blocks |
+| `OpenAiCompatProvider` | OpenAI, Moonshot, DeepSeek, OpenRouter, Groq, Together | Chat Completions | `tool_calls` in message |
+| `GoogleProvider` | Google Gemini | GenerateContent | `functionCall` in parts |
+
+`OpenAiCompatProvider` takes `baseUrl` + `apiKey` — any OpenAI-compatible provider works with zero code.
+
+## Tier-Based Fallback Chains
+
+Each tier is an ordered list of providers. On 429/error, try next in chain:
+
+```
+Stage needs "balanced" tier
+  → Try anthropic/sonnet
+  → Rate limited (429)? → Try openai/gpt-5
+  → Also limited? → Try next in list
+  → All exhausted? → Stage fails with clear error
+```
+
+Both LLM Mode and Agent Mode use the same fallback logic via `llm/client.ts`:
+
+```
+config.models["balanced"]  →  [anthropic/sonnet, openai/gpt-5]
+                                    │
+                  ┌─────────────────┴──────────────────┐
+                  │                                     │
+            LLM Mode stages                      Agent Mode stages
+            (routing, review)                    (coding, TDD)
+                  │                                     │
+          llm/client.ts                         DirectApiAdapter
+          tries providers                       tries providers
+          in order                              in order (with tools)
+```
+
+Single `ModelDef` (not array) is treated as array of one — backward compatible, no fallback.
+
+## Backend Routing
+
+Three-level resolution:
+
+### 1. Per-Stage Pipeline Override (most specific)
+
+```json
+{
+  "pipeline": {
+    "routing": {
+      "primary": { "provider": "google", "model": "gemini-flash", "via": "api" },
+      "fallback": [
+        { "provider": "anthropic", "model": "haiku", "via": "api" },
+        { "via": "keyword" }
+      ]
+    },
+    "implementation": {
+      "primary": { "provider": "anthropic", "model": "sonnet", "via": "api" },
+      "fallback": [
+        { "via": "claude-cli" }
+      ]
+    }
+  }
+}
+```
+
+The `via` field determines execution path:
+- `"api"` → Direct API (LLM Mode or DirectApiAdapter depending on stage)
+- `"claude-cli"` → Claude Code CLI subprocess
+- `"keyword"` → built-in keyword strategy (routing only)
+
+### 2. Strategy Override (tdd/interactive → force backend)
+
+```json
+{
+  "agents": {
+    "overrides": {
+      "tdd": "claude-cli",
+      "interactive": "claude-cli"
+    }
+  }
+}
+```
+
+### 3. Tier Routing (default)
+
+```json
+{
+  "agents": {
+    "routing": {
+      "fast": { "provider": "gemini", "model": "gemini-2.5-flash" },
+      "balanced": { "provider": "anthropic", "model": "claude-sonnet-4-5" },
+      "powerful": { "provider": "anthropic", "model": "claude-opus-4" }
+    }
+  }
+}
+```
+
+### Resolution Logic
+
+```typescript
+function resolveBackend(
+  tier: ModelTier,
+  stage: string,
+  context: { tdd: boolean; interactive: boolean }
+): BackendConfig {
+  const config = loadConfig();
+
+  // 1. Per-stage pipeline override
+  if (config.pipeline?.[stage]?.primary) return config.pipeline[stage];
+
+  // 2. Strategy override
+  if (context.tdd && config.agents?.overrides?.tdd) return config.agents.overrides.tdd;
+  if (context.interactive && config.agents?.overrides?.interactive) return config.agents.overrides.interactive;
+
+  // 3. Tier routing
+  return config.agents?.routing?.[tier] ?? "claude-cli";
+}
+```
+
+## Full Config Example
+
+```json
+{
+  "agents": {
+    "providers": {
+      "anthropic": {
+        "type": "anthropic",
+        "apiKey": "${ANTHROPIC_API_KEY}"
+      },
+      "openai": {
+        "type": "openai-compat",
+        "baseUrl": "https://api.openai.com/v1",
+        "apiKey": "${OPENAI_API_KEY}"
+      },
+      "gemini": {
+        "type": "google",
+        "apiKey": "${GOOGLE_API_KEY}"
+      },
+      "moonshot": {
+        "type": "openai-compat",
+        "baseUrl": "https://api.moonshot.cn/v1",
+        "apiKey": "${MOONSHOT_API_KEY}"
+      },
+      "deepseek": {
+        "type": "openai-compat",
+        "baseUrl": "https://api.deepseek.com/v1",
+        "apiKey": "${DEEPSEEK_API_KEY}"
+      }
+    },
+    "routing": {
+      "fast": { "provider": "gemini", "model": "gemini-2.5-flash" },
+      "balanced": [
+        { "provider": "anthropic", "model": "claude-sonnet-4-5" },
+        { "provider": "openai", "model": "gpt-5" }
+      ],
+      "powerful": { "provider": "anthropic", "model": "claude-opus-4" }
+    },
+    "overrides": {
+      "tdd": "claude-cli",
+      "interactive": "claude-cli"
+    }
+  },
+  "pipeline": {
+    "routing": {
+      "primary": { "provider": "gemini", "model": "gemini-flash", "via": "api" },
+      "fallback": [{ "via": "keyword" }]
+    }
+  }
+}
+```
+
+## Minimal Tool Set (for DirectApiAdapter)
+
+| Tool | What | Lines |
+|:-----|:-----|:------|
+| `read_file` | Read file contents (with line range) | ~15 |
+| `write_file` | Write/create file (with mkdir -p) | ~15 |
+| `list_files` | List directory (recursive option) | ~15 |
+| `search_files` | Grep/ripgrep pattern search | ~20 |
+| `run_command` | Shell exec with timeout + cwd | ~30 |
+
+~95 lines total. Each tool is sandboxed to the project workdir.
+
+## Agent Loop
+
+```typescript
+async function agentLoop(
+  provider: LlmProvider,
+  model: string,
+  prompt: string,
+  workdir: string,
+  maxIterations: number = 50,
+): Promise<AgentResult> {
+  const tools = getToolDefinitions();
+  let messages: Message[] = [{ role: "user", content: prompt }];
+  let totalCost = { input: 0, output: 0 };
+
+  for (let i = 0; i < maxIterations; i++) {
+    const response = await provider.chat({ model, messages, tools });
+    totalCost.input += response.usage.inputTokens;
+    totalCost.output += response.usage.outputTokens;
+
+    if (response.stopReason === "end_turn") {
+      return { success: true, output: response.content, cost: totalCost };
+    }
+
+    // Execute tool calls
+    const toolResults = await Promise.all(
+      response.toolCalls.map(tc => executeTool(tc, workdir))
+    );
+
+    messages.push({ role: "assistant", content: response.content, toolCalls: response.toolCalls });
+    messages.push({ role: "tool", results: toolResults });
+  }
+
+  return { success: false, output: "Max iterations reached", cost: totalCost };
+}
+```
+
+~150 lines with error handling, logging, and token budget checks.
+
+## Comparison: CLI vs Direct API
+
+| Factor | Claude Code CLI | Direct API |
+|:-------|:---------------|:-----------|
+| RAM per session | ~350MB | ~5MB |
+| Parallel stories | OOMs at 3 | 10+ concurrent |
+| Cost tracking | Estimated from duration | Exact token counts from API |
+| Provider flexibility | Anthropic only | Any provider with tool_use |
+| Tool access | ~50 tools (overkill) | 5 tools (minimal, sandboxed) |
+| CLAUDE.md support | ✅ Auto-loaded | ❌ Must inject into prompt |
+| TDD isolation | ✅ PTY-based session isolation | ⚠️ Possible but needs validation |
+| Interactive/TUI | ✅ PTY handle | ❌ Not supported |
+| Dependencies | `claude` binary installed | Just HTTP (fetch) |
+
+## Backward Compatibility
+
+- No `agents` section in config → everything uses `claude-cli` (current behavior)
+- No `pipeline` section → stages inherit from tier routing
+- Single ModelDef (not array) → treated as array of one, no fallback
+- Zero breaking changes
+
+## Component Breakdown
+
+| Component | Est. Lines | What |
+|:----------|:-----------|:-----|
+| `llm/types.ts` | ~60 | LlmProvider, Message, ToolCall, LlmResponse |
+| `llm/providers/anthropic.ts` | ~80 | Messages API + tool_use normalization |
+| `llm/providers/openai-compat.ts` | ~80 | Chat Completions + configurable baseUrl |
+| `llm/providers/google.ts` | ~100 | GenerateContent + functionCall normalization |
+| `llm/registry.ts` | ~40 | Provider factory from config |
+| `llm/client.ts` | ~80 | callLlm() with fallback chain + retry |
+| `llm/tools/*.ts` (5 tools) | ~95 | read, write, list, search, exec |
+| `llm/agent-loop.ts` | ~150 | Tool use cycle with iteration limit |
+| `agents/direct-api.ts` | ~80 | DirectApiAdapter wrapping llm/ layer |
+| `agents/registry.ts` (update) | ~30 | Resolve backend config → adapter |
+| `config/schema.ts` (update) | ~100 | providers, routing, overrides, pipeline |
+| **Total** | **~895** | |
+
+## Implementation Phases
+
+| Phase | Scope | Effort | Enables |
+|:------|:------|:-------|:--------|
+| P1 | LlmProvider interface + AnthropicProvider + callLlm() | Small | LLM Mode for routing/review |
+| P2 | OpenAiCompatProvider + GoogleProvider | Small | Multi-provider support |
+| P3 | Fallback chain logic in client.ts | Medium | Rate limit resilience |
+| P4 | Tool definitions + agent loop + DirectApiAdapter | Medium | API-based coding |
+| P5 | Per-stage pipeline config | Medium | Fine-grained stage control |
+| P6 | Wire LLM Mode into routing, review, acceptance stages | Medium | Remove CLI dependency for reasoning |
+
+P1-P2 can ship independently as a quick win (LLM Mode only). P4 is the big unlock for Phase 3 parallelism.
+
+## Auth/Key Management
+
+Provider keys flow from config with env var expansion:
+
+```json
+{
+  "providers": {
+    "anthropic": { "type": "anthropic", "apiKey": "${ANTHROPIC_API_KEY}" }
+  }
+}
+```
+
+Each provider reads `apiKey` from its config entry. Fallback to `process.env` for backward compat.
+Per-model env overrides via `ModelDef.env` still work (existing behavior).
+
+## Enables Phase 3 (Parallelism)
+
+With DirectApiAdapter (~5MB each), Phase 3 becomes feasible:
+- N stories execute concurrently via parallel HTTP calls
+- Each story gets its own git worktree (from dev-orchestrator pattern)
+- No OOM risk — 10 concurrent stories ≈ 50MB total vs 3.5GB with CLI
+- Exact cost tracking per story from API token counts
+
+---
+
+*Decision pending. This doc captures the merged architecture for future implementation.*

package/docs/20260225-review-v0.10.1.md

@@ -0,0 +1,187 @@
+# Deep Code Review: @nathapp/nax v0.10.1
+
+**Date:** 2026-02-25
+**Reviewer:** Subrina (AI)
+**Scope:** Status File, Failure Categories, Verifier Verdicts (31 files changed, ~5,200 lines added)
+**Commit Range:** v0.10.0..v0.10.1
+
+---
+
+## Overall Grade: A- (87/100)
+
+| Category | Score | Notes |
+|:---|:---:|:---|
+| Security | 17/20 | Solid input validation on verdict; minor path traversal concern |
+| Reliability | 18/20 | Atomic writes, graceful fallbacks, comprehensive error handling |
+| API Design | 18/20 | Clean types, good separation of concerns, extensible verdict schema |
+| Code Quality | 17/20 | Well-structured, good test coverage; runner.ts exceeds 400-line guideline |
+| Best Practices | 17/20 | Good patterns; minor DRY and cleanup opportunities |
+
+---
+
+## Findings
+
+### CRITICAL
+
+*None found.*
+
+### HIGH
+
+#### BUG-1: runner.ts exceeds 400-line guideline at 1,310 lines (HIGH)
+
+**File:** `src/execution/runner.ts`
+**Risk:** Cognitive complexity, harder to test individual paths, merge conflicts.
+**Snippet:** `wc -l src/execution/runner.ts → 1310`
+**Fix:** Extract the status-file write orchestration, the story pipeline dispatch, and the escalation logic into separate modules (as was done with `post-verify.ts`). The `writeStatus` closure and its state vars could become a `StatusFileWriter` class.
+
+#### SEC-1: Status file path not validated for path traversal (HIGH)
+
+**File:** `src/execution/status-file.ts:170`
+```typescript
+export async function writeStatusFile(filePath: string, status: NaxStatusFile): Promise<void> {
+  const tmpPath = `${filePath}.tmp`;
+  await Bun.write(tmpPath, JSON.stringify(status, null, 2));
+  await rename(tmpPath, filePath);
+}
+```
+**Risk:** If `statusFile` option is user-controlled (e.g., via CLI arg), arbitrary file overwrite is possible. Currently mitigated by the fact that the path is derived from `--status-file` CLI arg which is operator-controlled, but no validation exists.
+**Fix:** Add `path.resolve()` + verify the path is within the workdir or a known safe directory.
+
+### MEDIUM
+
+#### ENH-1: `getSafeLogger()` duplicated across files (MEDIUM)
+
+**Files:** `src/execution/runner.ts:71`, `src/execution/post-verify.ts:80`
+```typescript
+function getSafeLogger() {
+  try { return getLogger(); }
+  catch { return null; }
+}
+```
+**Risk:** DRY violation. If logger initialization changes, both copies need updating.
+**Fix:** Export `getSafeLogger()` from `src/logger.ts` or a shared utility.
+
+#### TYPE-1: `captureGitRef()` duplicated with different signatures (MEDIUM)
+
+**Files:** `src/execution/post-verify.ts:17` (returns `string | undefined`), `src/tdd/orchestrator.ts:30` (returns `string`, throws on failure)
+**Risk:** Inconsistent error handling for the same operation. The orchestrator version will throw if git isn't available.
+**Fix:** Consolidate into a single shared function in a git utility module. Prefer the `string | undefined` signature for resilience.
+
+#### BUG-2: `writeStatus` swallows errors silently during critical state transitions (MEDIUM)
+
+**File:** `src/execution/runner.ts:188-193`
+```typescript
+catch (err) {
+  safeLogger?.warn("status-file", "Failed to write status file (non-fatal)", {
+    path: statusFile,
+    error: (err as Error).message,
+  });
+}
+```
+**Risk:** If the status file write fails repeatedly (e.g., disk full), the only signal is a warn log that may be missed. External tooling polling the file would see stale data.
+**Fix:** Consider a counter; after N consecutive failures, emit a more prominent error or set a flag on the run state.
+
+#### ENH-2: Verdict validation could use a schema library (MEDIUM)
+
+**File:** `src/tdd/verdict.ts:85-120` — `isValidVerdict()` is 35 lines of manual validation.
+**Risk:** Verbose and error-prone as the schema evolves. New fields require manual validation additions.
+**Fix:** Consider using `zod` or `valibot` for declarative schema validation. However, the current zero-dependency approach is acceptable for a CLI tool — marking as enhancement, not a bug.
+
+#### MEM-1: Atomic write leaves orphan `.tmp` file on crash between write and rename (MEDIUM)
+
+**File:** `src/execution/status-file.ts:172-175`
+**Risk:** If the process crashes after `Bun.write()` but before `rename()`, a `.tmp` file persists. Not a memory leak but can cause confusion.
+**Fix:** Add cleanup of stale `.tmp` files at runner startup, or use `try/finally` to attempt cleanup.
+
+### LOW
+
+#### STYLE-1: Inconsistent `as FailureCategory` casts in orchestrator (LOW)
+
+**File:** `src/tdd/orchestrator.ts:293, 312`
+```typescript
+failureCategory: "session-failure" as FailureCategory,
+failureCategory: "isolation-violation" as FailureCategory,
+```
+**Risk:** The type is already `FailureCategory`, so the cast is redundant and adds noise.
+**Fix:** Remove the `as FailureCategory` casts — TypeScript already infers the string literal correctly.
+
+#### STYLE-2: Test file duplication — `tdd-verdict.test.ts` and `verdict.test.ts` overlap significantly (LOW)
+
+**Files:** `test/verdict.test.ts` (339 lines), `test/tdd-verdict.test.ts` (290 lines)
+**Risk:** Both test `readVerdict`, `cleanupVerdict`, and `categorizeVerdict` with very similar test cases. Maintenance burden doubles.
+**Fix:** Consolidate into a single test file. If both were generated by different subtasks, merge the more thorough assertions from each.
+
+#### ENH-3: `countProgress` iterates stories 4 times (LOW)
+
+**File:** `src/execution/status-file.ts:101-106`
+```typescript
+const passed = stories.filter((s) => s.status === "passed").length;
+const failed = stories.filter((s) => s.status === "failed").length;
+const paused = stories.filter((s) => s.status === "paused").length;
+const blocked = stories.filter((s) => s.status === "blocked").length;
+```
+**Risk:** Negligible performance impact (PRDs have <50 stories), but could be a single loop.
+**Fix:** Single `reduce()` pass. Low priority — readability is fine as-is.
+
+#### PERF-1: `buildStatusSnapshot` calls `Date.now()` once but creates `new Date()` separately (LOW)
+
+**File:** `src/execution/status-file.ts:154`
+```typescript
+const now = Date.now();
+// ...
+updatedAt: new Date(now).toISOString(),
+```
+**Risk:** None — this is actually correct and efficient. No finding here, just noting the pattern is clean.
+
+#### ENH-4: `resolveMaxAttemptsOutcome` could benefit from exhaustive matching (LOW)
+
+**File:** `src/execution/runner.ts:59-64`
+```typescript
+export function resolveMaxAttemptsOutcome(failureCategory?: FailureCategory): "pause" | "fail" {
+  if (failureCategory === "isolation-violation" || failureCategory === "verifier-rejected") {
+    return "pause";
+  }
+  return "fail";
+}
+```
+**Risk:** If new `FailureCategory` values are added, this function silently defaults to "fail".
+**Fix:** Add a `satisfies never` exhaustive check or use a switch statement.
+
+---
+
+## What Was Done Well
+
+1. **Atomic writes** for the status file — write-to-tmp-then-rename prevents partial reads.
+2. **Verdict validation** is thorough — `isValidVerdict()` checks every required field, returns null on failure (never throws).
+3. **Clean separation** — verdict reading, categorization, and cleanup are separate functions with single responsibilities.
+4. **Fallback paths** — when no verdict file exists, the orchestrator gracefully falls back to independent test verification.
+5. **Test coverage** is excellent — ~6 test files covering all three features with edge cases, error paths, and priority ordering.
+6. **Type design** — `FailureCategory` as a union type, `NaxStatusFile` with version field for forward compat, `ThreeSessionTddResult.verdict` using `null | undefined` distinction.
+7. **Documentation** — JSDoc on all public APIs with clear parameter descriptions.
+8. **`markStoryFailed` backward compatibility** — the `failureCategory` parameter is optional; existing callers don't break.
+
+---
+
+## Priority Fix Order
+
+| Priority | ID | Severity | Effort | Description |
+|:---:|:---|:---:|:---:|:---|
+| 1 | BUG-1 | HIGH | L | Extract runner.ts into smaller modules |
+| 2 | SEC-1 | HIGH | S | Validate status file path |
+| 3 | ENH-1 | MEDIUM | S | Deduplicate `getSafeLogger()` |
+| 4 | TYPE-1 | MEDIUM | S | Consolidate `captureGitRef()` |
+| 5 | STYLE-2 | LOW | M | Merge duplicate verdict test files |
+| 6 | ENH-4 | LOW | S | Exhaustive match in `resolveMaxAttemptsOutcome` |
+| 7 | STYLE-1 | LOW | S | Remove redundant `as FailureCategory` casts |
+
+*Effort: S = <30min, M = 1-2h, L = 2-4h*
+
+---
+
+## Summary
+
+v0.10.1 is a **solid implementation** of three well-scoped features. The code demonstrates good defensive programming (never-throw readers, atomic writes, graceful fallbacks) and strong type design. Test coverage is comprehensive with both happy-path and error-path cases.
+
+The main concern is **runner.ts growing to 1,310 lines** — the status-file integration added more state and write points to an already large file. The next refactoring pass should extract the status-file writer and the story pipeline dispatch into separate modules.
+
+No critical security or reliability issues found. The codebase is production-ready.