@nomos-arc/arc 0.1.0

package/src/core/plan-file-manager.ts

@@ -0,0 +1,66 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import type { Logger } from 'winston';
+
+/**
+ * Manages all file I/O for plan artifacts: logs, diffs, plan summaries.
+ * The Orchestrator delegates ALL file reads/writes to this class.
+ * It NEVER touches state JSON (that's StateManager's job).
+ */
+export class PlanFileManager {
+  constructor(
+    private projectRoot: string,
+    private logger: Logger,
+  ) {}
+
+  private resolve(...segments: string[]): string {
+    return path.join(this.projectRoot, 'tasks-management', ...segments);
+  }
+
+  saveRawLog(taskId: string, version: number, content: string): void {
+    const filePath = this.resolve('logs', `${taskId}-v${version}-raw.log`);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content);
+  }
+
+  saveStrippedLog(taskId: string, version: number, content: string): void {
+    const filePath = this.resolve('logs', `${taskId}-v${version}.log`);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content);
+  }
+
+  saveDiff(taskId: string, version: number, diff: string): void {
+    const filePath = this.resolve('plans', `${taskId}-v${version}.diff`);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, diff);
+  }
+
+  saveReviewRawLog(taskId: string, version: number, content: string): void {
+    const filePath = this.resolve('logs', `${taskId}-v${version}-review-raw.log`);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content);
+  }
+
+  loadDiff(taskId: string, version: number): string {
+    return fs.readFileSync(this.resolve('plans', `${taskId}-v${version}.diff`), 'utf8');
+  }
+
+  loadPlanSummary(taskId: string, version: number): string | null {
+    const filePath = this.resolve('plans', `${taskId}-v${version}.md`);
+    return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : null;
+  }
+
+  /** Returns the list of relative paths to commit per Execution Rule #14 */
+  getCommitFileList(taskId: string, version: number, includeLogs: boolean): string[] {
+    const files = [`tasks-management/plans/${taskId}-v${version}.diff`];
+    if (includeLogs) {
+      files.push(`tasks-management/logs/${taskId}-v${version}.log`);
+    }
+    return files;
+  }
+
+  deleteSessionRule(taskId: string): void {
+    const filePath = this.resolve('rules', 'session', `${taskId}.md`);
+    if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+  }
+}

package/src/core/preflight.ts

@@ -0,0 +1,64 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { execFile } from 'child_process';
+import type { Logger } from 'winston';
+import { NomosError } from './errors.js';
+import type { NomosConfig } from '../types/index.js';
+
+const WIN_EXTENSIONS = ['.exe', '.cmd', '.bat'];
+
+async function isExecutable(filePath: string): Promise<boolean> {
+  return new Promise(resolve => {
+    fs.access(filePath, fs.constants.X_OK, err => resolve(!err));
+  });
+}
+
+export async function resolveBinary(cmd: string): Promise<string> {
+  // Absolute path — check directly
+  if (path.isAbsolute(cmd)) {
+    if (await isExecutable(cmd)) return cmd;
+    throw new NomosError('binary_not_found', `Binary "${cmd}" not found or not executable`);
+  }
+
+  const dirs = process.env.PATH?.split(path.delimiter) ?? [];
+  const candidates = process.platform === 'win32'
+    ? [cmd, ...WIN_EXTENSIONS.map(ext => cmd + ext)]
+    : [cmd];
+
+  for (const dir of dirs) {
+    for (const name of candidates) {
+      const full = path.join(dir, name);
+      if (await isExecutable(full)) return full;
+    }
+  }
+
+  throw new NomosError('binary_not_found', `Binary "${cmd}" not found in PATH`);
+}
+
+export async function runPreflight(
+  config: NomosConfig,
+  logger: Logger,
+): Promise<{ planner: string; reviewer: string }> {
+  const [planner, reviewer] = await Promise.all([
+    resolveBinary(config.binaries.planner.cmd),
+    resolveBinary(config.binaries.reviewer.cmd),
+  ]);
+
+  // Optionally probe each binary with --version (non-fatal)
+  for (const [name, resolved] of [['planner', planner], ['reviewer', reviewer]] as const) {
+    await new Promise<void>(resolve => {
+      const timer = setTimeout(resolve, 5000);
+      execFile(resolved, ['--version'], { timeout: 5000 }, (err, stdout) => {
+        clearTimeout(timer);
+        if (err) {
+          logger.warn(`${name} binary "${resolved}" --version failed: ${err.message}`);
+        } else {
+          logger.debug(`${name} binary version: ${stdout.trim()}`);
+        }
+        resolve();
+      });
+    });
+  }
+
+  return { planner, reviewer };
+}

package/src/core/prompt.ts

@@ -0,0 +1,173 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { createHash } from 'crypto';
+import { NomosError } from './errors.js';
+import type { PromptOptions, ReviewPromptOptions } from '../types/index.js';
+
+export function assemblePrompt(options: PromptOptions): string {
+  const sections: string[] = [];
+
+  sections.push(`[SYSTEM RULES]\n${options.globalRules}`);
+
+  if (options.domainRules.trim()) {
+    sections.push(`[DOMAIN RULES]\n${options.domainRules}`);
+  }
+
+  if (options.sessionRules !== null) {
+    sections.push(`[SESSION CONSTRAINTS]\n${options.sessionRules}`);
+  }
+
+  sections.push(`[TASK REQUIREMENTS]\n${options.taskBody}`);
+
+  // BLK-3 fix: contextFiles section
+  if (options.contextFiles.length > 0) {
+    const fileList = options.contextFiles.map(f => `- ${f}`).join('\n');
+    sections.push(
+      `[CONTEXT FILES]\n` +
+      `The following files are relevant to this task. Read and understand them before planning:\n` +
+      fileList
+    );
+  }
+
+  if (options.architecturalConstraints !== null) {
+    sections.push(
+      `[ARCHITECTURAL CONSTRAINTS]\n` +
+      `The following symbols from your context files are consumed by other modules. ` +
+      `Your implementation MUST preserve their signatures and contracts:\n` +
+      options.architecturalConstraints
+    );
+  }
+
+  if (options.previousFeedback !== null && options.previousFeedback.length > 0) {
+    const issueLines = options.previousFeedback
+      .map(i => `- [${i.severity}] ${i.description}: ${i.suggestion}`)
+      .join('\n');
+    sections.push(
+      `[PREVIOUS REVIEW FEEDBACK]\n` +
+      `The following issues were identified in v${options.previousVersion} and MUST be addressed:\n` +
+      issueLines
+    );
+  }
+
+  sections.push(
+    `[INSTRUCTION]\n` +
+    `Generate a detailed implementation plan for the above task.\n` +
+    `Output your plan in Markdown format.`
+  );
+
+  return sections.join('\n\n');
+}
+
+export function assembleReviewPrompt(options: ReviewPromptOptions): string {
+  const sections: string[] = [];
+
+  sections.push(
+    `[REVIEW REQUEST]\n` +
+    `You are a code review expert. Review the following implementation plan diff.\n` +
+    `Evaluate quality, security, architecture, and correctness.`
+  );
+
+  sections.push(`[PLAN DIFF]\n${options.planDiff}`);
+
+  if (options.affectedFileSnippets && options.affectedFileSnippets.length > 0) {
+    const snippets = options.affectedFileSnippets
+      .map(({ file, snippet }) => `// ${file}\n${snippet}`)
+      .join('\n\n---\n\n');
+    sections.push(
+      `[AFFECTED FILES]\n` +
+      `The following files reference code changed in this diff. ` +
+      `Use them to assess side-effects and dependency impact:\n\n` +
+      snippets
+    );
+  }
+
+  if (options.planSummary) {
+    sections.push(`[DEVELOPER NOTES]\n${options.planSummary}`);
+  }
+
+  if (options.globalRules.trim()) {
+    sections.push(`[SYSTEM RULES]\n${options.globalRules}`);
+  }
+
+  if (options.domainRules.trim()) {
+    sections.push(`[DOMAIN RULES]\n${options.domainRules}`);
+  }
+
+  if (options.mode === 'auto') {
+    sections.push(
+      `[ZERO-TOLERANCE CLAUSE]\n` +
+      `You are operating in auto mode. Any high-severity security issue MUST result in ` +
+      `a score below 0.5, regardless of other positive qualities.`
+    );
+  }
+
+  sections.push(
+    `[INSTRUCTION]\n` +
+    `Respond ONLY with a JSON object matching this exact schema. ` +
+    `Do not include any other text, explanation, or markdown fences:\n` +
+    `{\n` +
+    `  "score": <number between 0.0 and 1.0>,\n` +
+    `  "summary": "<string, minimum 10 characters describing the overall quality>",\n` +
+    `  "issues": [\n` +
+    `    {\n` +
+    `      "severity": "<high|medium|low>",\n` +
+    `      "category": "<security|performance|architecture|correctness|maintainability>",\n` +
+    `      "description": "<string, minimum 5 characters>",\n` +
+    `      "suggestion": "<string, minimum 5 characters>"\n` +
+    `    }\n` +
+    `  ]\n` +
+    `}\n\n` +
+    `Scoring guide:\n` +
+    `- 0.9–1.0: Excellent, approved for merge\n` +
+    `- 0.7–0.9: Good, minor issues\n` +
+    `- 0.5–0.7: Needs improvement\n` +
+    `- 0.0–0.5: Significant problems requiring rework`
+  );
+
+  return sections.join('\n\n');
+}
+
+export async function loadRules(
+  projectRoot: string,
+  taskId: string,
+): Promise<{ global: string; domain: string; session: string | null; rulesHash: string; rulesList: string[] }> {
+  const rulesDir = path.join(projectRoot, 'tasks-management', 'rules');
+
+  // global.md is required
+  const globalPath = path.join(rulesDir, 'global.md');
+  let globalContent: string;
+  try {
+    globalContent = await fs.readFile(globalPath, 'utf8');
+  } catch {
+    throw new NomosError(
+      'rules_missing',
+      `Required rules file not found: ${globalPath}. ` +
+      `Run: arc init to scaffold the project structure.`,
+    );
+  }
+
+  // backend.md is optional
+  let domainContent = '';
+  try {
+    domainContent = await fs.readFile(path.join(rulesDir, 'backend.md'), 'utf8');
+  } catch { /* not found — that's ok */ }
+
+  // session/{taskId}.md is optional
+  let sessionContent: string | null = null;
+  try {
+    sessionContent = await fs.readFile(
+      path.join(rulesDir, 'session', `${taskId}.md`), 'utf8');
+  } catch { /* not found — that's ok */ }
+
+  const rulesHash = `sha256:${createHash('sha256')
+    .update(globalContent + domainContent + (sessionContent ?? ''))
+    .digest('hex')}`;
+
+  const rulesList = [
+    'global.md',
+    ...(domainContent ? ['backend.md'] : []),
+    ...(sessionContent !== null ? [`session/${taskId}.md`] : []),
+  ];
+
+  return { global: globalContent, domain: domainContent, session: sessionContent, rulesHash, rulesList };
+}

package/src/core/review.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+import type { ReviewResult, ExecutionMode } from '../types/index.js';
+
+// Stage 1 — JSON extraction
+
+function extractFirstJsonBlock(raw: string): string | null {
+  let depth = 0;
+  let start = -1;
+  let inString = false;
+  let escape = false;
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i];
+    if (escape) { escape = false; continue; }
+    if (ch === '\\') { escape = true; continue; }
+    if (ch === '"') { inString = !inString; continue; }
+    if (inString) continue;
+    if (ch === '{') { if (depth === 0) start = i; depth++; }
+    if (ch === '}') {
+      depth--;
+      if (depth === 0 && start !== -1) return raw.slice(start, i + 1);
+    }
+  }
+  return null;
+}
+
+export function extractJson(raw: string): object | null {
+  // Try 1: direct parse
+  try { return JSON.parse(raw); } catch {}
+  // Try 2: markdown fence extraction
+  const fenceMatch = raw.match(/```(?:json)?\s*([\s\S]*?)```/);
+  if (fenceMatch) {
+    try { return JSON.parse(fenceMatch[1].trim()); } catch {}
+  }
+  // Try 3: brace-depth extraction
+  const block = extractFirstJsonBlock(raw);
+  if (block) {
+    try { return JSON.parse(block); } catch {}
+  }
+  return null;
+}
+
+// Stage 2 — Schema validation
+
+const ReviewResultSchema = z.object({
+  score: z.number().min(0).max(2),      // clamp handled in stage 3
+  summary: z.string().min(10),
+  issues: z.array(z.object({
+    severity: z.enum(['high', 'medium', 'low']),
+    category: z.enum(['security', 'performance', 'architecture', 'correctness', 'maintainability']),
+    description: z.string().min(5),
+    suggestion: z.string().min(5),
+  })),
+});
+
+// RT2-4.2 fix: Accept the actual execution mode as a parameter instead of
+// hardcoding 'auto'. The previous version baked mode: 'auto' into every
+// persisted HistoryEntry, corrupting history from the first supervised run.
+export function validateReviewSchema(obj: object, mode: ExecutionMode): ReviewResult | null {
+  const result = ReviewResultSchema.safeParse(obj);
+  if (!result.success) return null;
+  return { ...result.data, mode } as ReviewResult;
+}
+
+// Stage 3 — Semantic validation
+
+export function semanticValidation(review: ReviewResult): { valid: boolean; reason?: string } {
+  // Clamp score
+  if (review.score > 1.0) {
+    review.score = 1.0;
+  }
+  if (review.score < 0.0) {
+    review.score = 0.0;
+  }
+  if (review.score < 0.5 && review.issues.length === 0) {
+    return { valid: false, reason: 'Low score must have supporting issues.' };
+  }
+  if (review.score >= 0.9 && review.issues.some(i => i.severity === 'high')) {
+    return { valid: false, reason: 'High severity issues cannot pass with score >= 0.9.' };
+  }
+  return { valid: true };
+}
+
+// RT2-4.2 fix: mode parameter threaded through the entire pipeline
+export function parseReviewOutput(
+  raw: string,
+  mode: ExecutionMode,
+): { result: ReviewResult | null; error?: string } {
+  const obj = extractJson(raw);
+  if (!obj) return { result: null, error: 'Stage 1 failed: no JSON found in reviewer output.' };
+  const validated = validateReviewSchema(obj, mode);
+  if (!validated) return { result: null, error: 'Stage 2 failed: JSON does not match ReviewResult schema.' };
+  const semantic = semanticValidation(validated);
+  if (!semantic.valid) return { result: null, error: `Stage 3 failed: ${semantic.reason}` };
+  return { result: validated };
+}

package/src/core/state.ts

@@ -0,0 +1,294 @@
+import { z } from 'zod';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as lockfile from 'proper-lockfile';
+import type { Logger } from 'winston';
+import { NomosError } from './errors.js';
+import type { TaskState, TaskStatus, StateTransitionOptions } from '../types/index.js';
+
+// ── Zod Schema ────────────────────────────────────────────────────────────────
+
+const ReviewIssueSchema = z.object({
+  severity: z.enum(['high', 'medium', 'low']),
+  category: z.enum(['security', 'performance', 'architecture', 'correctness', 'maintainability']),
+  description: z.string().min(5),
+  suggestion: z.string().min(5),
+});
+
+const ReviewResultSchema = z.object({
+  score: z.number().min(0).max(1),
+  mode: z.enum(['supervised', 'auto', 'dry-run']),
+  issues: z.array(ReviewIssueSchema),
+  summary: z.string().min(10),
+});
+
+const HistoryEntrySchema = z.object({
+  version: z.number().int().nonnegative(),
+  step: z.enum(['planning', 'reviewing']),
+  mode: z.enum(['supervised', 'auto', 'dry-run']),
+  binary: z.string(),
+  started_at: z.string().datetime(),
+  completed_at: z.string().datetime(),
+  raw_output: z.string(),
+  output_hash: z.string(),
+  input_tokens: z.number().nonnegative(),     // RT2-4.2 fix: separate input tokens
+  output_tokens: z.number().nonnegative(),    // RT2-4.2 fix: separate output tokens
+  tokens_used: z.number().nonnegative(),      // total (input + output)
+  tokens_source: z.enum(['metered', 'estimated']),
+  rules_snapshot: z.array(z.string()),
+  review: ReviewResultSchema.nullable(),
+});
+
+const TaskMetaSchema = z.object({
+  status: z.enum([
+    'init', 'planning', 'pending_review', 'reviewing',
+    'refinement', 'approved', 'merged', 'discarded',
+    'failed', 'merge_conflict', 'stalled',
+  ]),
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+  approval_reason: z.enum(['score_threshold', 'max_iterations_reached']).optional(),
+});
+
+const TaskStateSchema = z.object({
+  schema_version: z.number().int().nonnegative(),
+  task_id: z.string(),
+  current_version: z.number().int().nonnegative(),
+  meta: TaskMetaSchema,
+  orchestration: z.object({
+    planner_bin: z.string(),
+    reviewer_bin: z.string(),
+  }),
+  shadow_branch: z.object({
+    branch: z.string(),
+    worktree: z.string(),
+    base_commit: z.string(),
+    status: z.enum(['active', 'merged', 'discarded']),
+  }),
+  context: z.object({
+    files: z.array(z.string()),
+    rules: z.array(z.string()),
+    rules_hash: z.string(),
+  }),
+  budget: z.object({
+    tokens_used: z.number().nonnegative(),
+    estimated_cost_usd: z.number().nonnegative(),
+  }),
+  history: z.array(HistoryEntrySchema),
+});
+
+// ── Schema migration ──────────────────────────────────────────────────────────
+
+const CURRENT_SCHEMA_VERSION = 1;
+
+// Migrations map: key is the FROM version. Add entries for future schema bumps.
+// Phase 1a: v0 → v1 is a no-op identity migration. Files written before schema_version
+// was introduced have the same data format as v1; we just stamp the version field.
+// Infrastructure must exist from day one (W5 fix).
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const migrations: Record<number, (state: any) => any> = {
+  0: (state: any) => state,   // v0 → v1: no data transformation needed (Phase 1a)
+  // Future: 1: migrateV1toV2,
+};
+
+function migrateState(raw: any): any {
+  let version: number = raw.schema_version ?? 0;
+  while (version < CURRENT_SCHEMA_VERSION) {
+    const migrator = migrations[version];
+    if (!migrator) {
+      throw new NomosError(
+        'state_migration_failed',
+        `No migration path from schema_version ${version} to ${CURRENT_SCHEMA_VERSION}`,
+      );
+    }
+    raw = migrator(raw);
+    version++;
+  }
+  raw.schema_version = CURRENT_SCHEMA_VERSION;
+  return raw;
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+// ── Valid FSM transitions ─────────────────────────────────────────────────────
+
+const VALID_TRANSITIONS: Record<TaskStatus, TaskStatus[]> = {
+  init:            ['planning', 'discarded'],
+  planning:        ['pending_review', 'failed', 'stalled', 'discarded'],
+  pending_review:  ['reviewing', 'discarded'],
+  reviewing:       ['refinement', 'approved', 'failed', 'discarded'],
+  refinement:      ['planning', 'discarded'],
+  approved:        ['merged', 'merge_conflict', 'discarded'],
+  merge_conflict:  ['approved', 'discarded'],
+  stalled:         ['planning', 'discarded'],
+  failed:          ['planning', 'discarded'],
+  merged:          [],
+  discarded:       [],
+};
+
+// ── StateManager ──────────────────────────────────────────────────────────────
+
+export class StateManager {
+  constructor(
+    private readonly stateDir: string,
+    private readonly logger: Logger,
+  ) {}
+
+  private statePath(taskId: string): string {
+    return path.join(this.stateDir, `${taskId}.json`);
+  }
+
+  // ── read ────────────────────────────────────────────────────────────────────
+
+  async read(taskId: string): Promise<TaskState> {
+    const filePath = this.statePath(taskId);
+    if (!fs.existsSync(filePath)) {
+      throw new NomosError('task_not_found', `No state file found for task "${taskId}"`);
+    }
+
+    let raw: unknown;
+    try {
+      raw = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    } catch (err) {
+      throw new NomosError('state_migration_failed', `Failed to parse state file: ${String(err)}`);
+    }
+
+    const migrated = migrateState(raw);
+    const result = TaskStateSchema.safeParse(migrated);
+    if (!result.success) {
+      const issues = result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ');
+      throw new NomosError('state_migration_failed', `State validation failed for "${taskId}": ${issues}`);
+    }
+
+    return result.data as TaskState;
+  }
+
+  // ── write ───────────────────────────────────────────────────────────────────
+
+  async write(taskId: string, state: TaskState): Promise<void> {
+    const filePath = this.statePath(taskId);
+    const tmpPath = `${filePath}.tmp`;
+
+    // Ensure state dir exists
+    fs.mkdirSync(this.stateDir, { recursive: true });
+
+    // Acquire lock — realpath: false so locking works even before file exists
+    const release = await lockfile.lock(filePath, {
+      retries: { retries: 5, minTimeout: 200, maxTimeout: 5000 },
+      stale: 30000,   // C2 fix: auto-break locks older than 30s from crashed processes
+      realpath: false,
+    });
+
+    try {
+      const json = JSON.stringify(state, null, 2);
+      fs.writeFileSync(tmpPath, json, 'utf-8');
+
+      // fsync: flush OS write buffer to disk before rename for crash safety
+      const fd = fs.openSync(tmpPath, 'r+');
+      try {
+        fs.fsyncSync(fd);
+      } finally {
+        fs.closeSync(fd);
+      }
+
+      // Atomic rename: tmp → final
+      fs.renameSync(tmpPath, filePath);
+    } finally {
+      await release();
+    }
+  }
+
+  // ── create ──────────────────────────────────────────────────────────────────
+
+  async create(taskId: string, initialState: TaskState): Promise<void> {
+    const filePath = this.statePath(taskId);
+    if (fs.existsSync(filePath)) {
+      throw new NomosError('task_exists', `Task "${taskId}" already exists`);
+    }
+    await this.write(taskId, initialState);
+  }
+
+  // ── transition ──────────────────────────────────────────────────────────────
+
+  async transition(
+    taskId: string,
+    newStatus: TaskStatus,
+    options?: StateTransitionOptions,
+  ): Promise<TaskState> {
+    const state = await this.read(taskId);
+    const currentStatus = state.meta.status;
+    const allowed = VALID_TRANSITIONS[currentStatus];
+
+    if (!allowed.includes(newStatus)) {
+      throw new NomosError(
+        'invalid_transition',
+        `Cannot transition task "${taskId}" from "${currentStatus}" to "${newStatus}". ` +
+        `Allowed: [${allowed.join(', ')}]`,
+      );
+    }
+
+    state.meta.status = newStatus;
+    state.meta.updated_at = new Date().toISOString();
+
+    if (options?.reason) {
+      this.logger.warn(`[nomos:transition] task=${taskId} reason=${options.reason}`);
+    }
+
+    if (options?.version_increment) {
+      state.current_version++;
+    }
+
+    if (options?.history_entry) {
+      state.history.push(options.history_entry);
+    }
+
+    if (options?.review_result && state.history.length > 0) {
+      state.history[state.history.length - 1]!.review = options.review_result;
+    }
+
+    if (options?.approval_reason) {
+      state.meta.approval_reason = options.approval_reason;
+    }
+
+    await this.write(taskId, state);
+    return state;
+  }
+
+  // ── cleanupTempFiles ────────────────────────────────────────────────────────
+
+  cleanupTempFiles(stateDir: string): void {
+    if (!fs.existsSync(stateDir)) return;
+
+    const entries = fs.readdirSync(stateDir);
+    for (const entry of entries) {
+      if (entry.endsWith('.json.tmp')) {
+        const tmpPath = path.join(stateDir, entry);
+        this.logger.warn(`[nomos:cleanup] Removing orphaned temp file: ${tmpPath}`);
+        fs.rmSync(tmpPath, { force: true });
+      }
+      // NOTE: Do NOT remove .lock files — proper-lockfile's stale: 30000 handles that.
+      // Manual removal races with lock ownership tracking (L-3 fix).
+    }
+  }
+
+  // ── listTasks ───────────────────────────────────────────────────────────────
+
+  async listTasks(): Promise<TaskState[]> {
+    if (!fs.existsSync(this.stateDir)) return [];
+
+    const entries = fs.readdirSync(this.stateDir);
+    const tasks: TaskState[] = [];
+
+    for (const entry of entries) {
+      if (!entry.endsWith('.json') || entry.endsWith('.json.tmp')) continue;
+      const taskId = entry.replace(/\.json$/, '');
+      try {
+        const task = await this.read(taskId);
+        tasks.push(task);
+      } catch (err) {
+        this.logger.warn(`[nomos:listTasks] Skipping unreadable state file "${entry}": ${String(err)}`);
+      }
+    }
+
+    return tasks;
+  }
+}