@xera-ai/core 0.1.7 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xera-ai/core",
-  "version": "0.1.7",
+  "version": "0.4.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -17,16 +17,22 @@
     }
   },
   "bin": {
-  "xera-internal": "./dist/bin/internal.js"
-},
-"files": ["dist", "src", "bin"],
-"scripts": {
-  "build": "bun build ./src/index.ts ./bin/internal.ts --outdir ./dist --target bun --external @playwright/test --external @xera-ai/web --external zod",
-  "typecheck": "tsc --noEmit"
-},
-"dependencies": {
-  "zod": "3.23.8",
-  "@xera-ai/web": "^0.1.5",
-  "@playwright/test": "1.48.0"
-}
+    "xera-internal": "./dist/bin/internal.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "bin"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts ./bin/internal.ts --outdir ./dist --target bun --external @playwright/test --external @xera-ai/web --external zod",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "zod": "4.4.3",
+    "@xera-ai/web": "^0.2.0",
+    "@playwright/test": "1.60.0",
+    "fflate": "0.8.3",
+    "yaml": "2.9.0"
+  }
 }

package/src/adapter/types.ts

@@ -1,5 +1,5 @@
-import type { XeraConfig } from '../config/schema';
 import type { Classification } from '../artifact/status';
+import type { XeraConfig } from '../config/schema';
 
 export interface GenerateInput {
   ticketDir: string;
@@ -57,6 +57,9 @@ export interface TestAdapter {
   readonly id: string;
   generate(input: GenerateInput): Promise<GenerateResult>;
   execute(input: ExecuteInput): Promise<RunResult>;
-  classify?(run: RunResult, ctx: ClassifyContext): Partial<{ class: Classification; rationale: string }>;
+  classify?(
+    run: RunResult,
+    ctx: ClassifyContext,
+  ): Partial<{ class: Classification; rationale: string }>;
   doctor(): Promise<DoctorReport>;
 }

package/src/artifact/meta.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { z } from 'zod';
 

package/src/artifact/status.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { z } from 'zod';
 

package/src/auth/encrypt.ts

@@ -1,8 +1,8 @@
-import { randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
 
 const ALGO = 'aes-256-gcm';
 const KEY_LEN = 32; // bytes (256 bits)
-const IV_LEN = 12;  // recommended for GCM
+const IV_LEN = 12; // recommended for GCM
 const TAG_LEN = 16;
 const VERSION = 'v1';
 

package/src/auth/key.ts

@@ -4,8 +4,7 @@ export function resolveAuthKey(): string {
   const key = process.env[AUTH_KEY_ENV];
   if (!key) {
     throw new Error(
-      `${AUTH_KEY_ENV} not set. It is auto-generated by \`xera init\` and saved to .env. ` +
-        `If you deleted .env, regenerate it by running \`xera init --update\` — note that any cached auth state will be invalidated.`,
+      `${AUTH_KEY_ENV} not set. It is auto-generated by \`xera init\` and saved to .env. If you deleted .env, regenerate it by running \`xera init --update\` — note that any cached auth state will be invalidated.`,
     );
   }
   if (!/^[0-9a-f]{64}$/i.test(key)) {

package/src/auth/refresh.ts

@@ -1,4 +1,5 @@
 import type { AuthStateEntry } from './state';
+
 export type { AuthStateEntry } from './state';
 
 const RE = /^(\d+)([hms])$/;
@@ -13,7 +14,10 @@ export function parseDuration(d: string): number {
   return n * 1000;
 }
 
-export interface RefreshPolicy { ttl: string; refreshBuffer: string; }
+export interface RefreshPolicy {
+  ttl: string;
+  refreshBuffer: string;
+}
 
 export function needsRefresh(
   entry: AuthStateEntry | null,

package/src/auth/state.ts

@@ -1,7 +1,7 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { z } from 'zod';
-import { encrypt, decrypt } from './encrypt';
+import { decrypt, encrypt } from './encrypt';
 import { resolveAuthKey } from './key';
 
 export const AuthStateEntrySchema = z.object({

package/src/bin-internal/doctor.ts

@@ -0,0 +1,169 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Stage } from '../eval/types';
+import { summarizeCost } from '../graph/cost';
+import { loadAllEvents } from '../graph/store';
+import { verifyPrompts } from './verify-prompts';
+
+export interface DoctorOpts {
+  cwd?: string;
+}
+
+interface CheckResult {
+  ok: boolean;
+  message: string;
+}
+
+const REQUIRED_FILES_PER_STAGE: Record<Stage, string[]> = {
+  'feature-from-story': ['golden/test.feature'],
+  'script-from-feature': ['golden/spec-requirements.md'],
+  'diagnose-failure': [],
+};
+
+const REQUIRED_SCRIPTS = [
+  'xera:eval-prepare',
+  'xera:eval-deterministic',
+  'xera:eval-report',
+  'xera:verify-prompts',
+  'xera:doctor',
+];
+
+function frontmatterField(content: string, field: string): string | null {
+  const m = content.match(new RegExp(`^${field}:\\s*(\\S+)\\s*$`, 'm'));
+  return m?.[1] ?? null;
+}
+
+function checkGoldenEvalDir(repoRoot: string): CheckResult[] {
+  const root = join(repoRoot, 'fixtures/golden-eval');
+  if (!existsSync(root)) return [{ ok: false, message: 'fixtures/golden-eval/ does not exist' }];
+  const dirs = readdirSync(root, { withFileTypes: true }).filter(
+    (e) => e.isDirectory() && !e.name.startsWith('.'),
+  );
+  const results: CheckResult[] = [];
+  if (dirs.length < 3) {
+    results.push({
+      ok: false,
+      message: `fixtures/golden-eval/ has ${dirs.length} ticket dir(s); need ≥ 3`,
+    });
+  }
+  for (const entry of dirs) {
+    const dir = join(root, entry.name);
+    const metaPath = join(dir, 'meta.json');
+    if (!existsSync(metaPath)) {
+      results.push({ ok: false, message: `${entry.name}: meta.json missing` });
+      continue;
+    }
+    let meta: { id?: string; stages?: unknown[] };
+    try {
+      meta = JSON.parse(readFileSync(metaPath, 'utf8')) as { id?: string; stages?: unknown[] };
+    } catch (err) {
+      results.push({
+        ok: false,
+        message: `${entry.name}: meta.json parse error: ${(err as Error).message}`,
+      });
+      continue;
+    }
+    const stages = Array.isArray(meta.stages) ? (meta.stages as Stage[]) : [];
+    if (stages.length === 0)
+      results.push({ ok: false, message: `${entry.name}: meta.stages is empty` });
+    if (!existsSync(join(dir, 'story.md')))
+      results.push({ ok: false, message: `${entry.name}: story.md missing` });
+    for (const stage of stages) {
+      const required = REQUIRED_FILES_PER_STAGE[stage] ?? [];
+      for (const rel of required) {
+        if (!existsSync(join(dir, rel))) {
+          results.push({
+            ok: false,
+            message: `${meta.id ?? entry.name}: stage "${stage}" declared but ${rel} missing`,
+          });
+        }
+      }
+    }
+  }
+  return results;
+}
+
+function checkRubricPrompt(repoRoot: string): CheckResult[] {
+  const path = join(repoRoot, 'packages/prompts/eval-rubric.md');
+  if (!existsSync(path)) return [{ ok: false, message: 'packages/prompts/eval-rubric.md missing' }];
+  const text = readFileSync(path, 'utf8');
+  const id = frontmatterField(text, 'id');
+  const version = frontmatterField(text, 'version');
+  if (id !== 'eval-rubric')
+    return [{ ok: false, message: 'eval-rubric.md frontmatter "id" must be "eval-rubric"' }];
+  if (!version) return [{ ok: false, message: 'eval-rubric.md frontmatter "version" missing' }];
+  return [];
+}
+
+function checkEvalSkill(repoRoot: string): CheckResult[] {
+  const path = join(repoRoot, 'packages/skills/xera-eval.md');
+  if (!existsSync(path)) return [{ ok: false, message: 'packages/skills/xera-eval.md missing' }];
+  const text = readFileSync(path, 'utf8');
+  if (!frontmatterField(text, 'name'))
+    return [{ ok: false, message: 'xera-eval.md frontmatter "name" missing' }];
+  return [];
+}
+
+function checkPromptInjectionPreamble(repoRoot: string): CheckResult[] {
+  return verifyPrompts(repoRoot);
+}
+
+function checkRootScripts(repoRoot: string): CheckResult[] {
+  const path = join(repoRoot, 'package.json');
+  if (!existsSync(path)) return [{ ok: false, message: 'root package.json missing' }];
+  const pkg = JSON.parse(readFileSync(path, 'utf8'));
+  const scripts = pkg.scripts ?? {};
+  const missing = REQUIRED_SCRIPTS.filter((s) => typeof scripts[s] !== 'string');
+  return missing.map((s) => ({ ok: false, message: `root package.json missing script: ${s}` }));
+}
+
+export async function doctorCmd(_argv: string[], opts: DoctorOpts = {}): Promise<number> {
+  const repoRoot = opts.cwd ?? process.cwd();
+  const results: CheckResult[] = [
+    ...checkGoldenEvalDir(repoRoot),
+    ...checkRubricPrompt(repoRoot),
+    ...checkEvalSkill(repoRoot),
+    ...checkPromptInjectionPreamble(repoRoot),
+    ...checkRootScripts(repoRoot),
+  ];
+  // Cost summary (past 7 days)
+  const cost = summarizeCost(repoRoot, 7);
+  if (cost.totalCalls > 0) {
+    console.log('');
+    console.log('LLM cost (past 7 days):');
+    console.log(`  Total calls: ${cost.totalCalls}`);
+    console.log(`  Estimated:   $${cost.totalUsd.toFixed(2)} USD`);
+    const top = Object.entries(cost.bySkill).sort((a, b) => b[1].usd - a[1].usd)[0];
+    if (top)
+      console.log(`  Top skill:   ${top[0]} (${top[1].calls} calls, $${top[1].usd.toFixed(2)})`);
+  }
+
+  // Backfill detection
+  const xeraDir = join(repoRoot, '.xera');
+  if (existsSync(xeraDir)) {
+    const ticketDirs = readdirSync(xeraDir, { withFileTypes: true }).filter(
+      (e) => e.isDirectory() && /^[A-Z]+-\d+$/.test(e.name),
+    );
+    if (ticketDirs.length > 0) {
+      const events = loadAllEvents(repoRoot);
+      const fetchedTickets = new Set(
+        events.filter((e) => e.type === 'ticket.fetched').map((e) => e.payload.ticketId),
+      );
+      const unbackfilled = ticketDirs.map((d) => d.name).filter((t) => !fetchedTickets.has(t));
+      if (unbackfilled.length > 0) {
+        console.log('');
+        console.log(`⚠ Graph: ${unbackfilled.length} ticket(s) not yet in graph.`);
+        console.log(`  These won't participate in v0.6.1+ features (TEST_OUTDATED, /xera-impact).`);
+        console.log(`  Run: bun run xera:graph-backfill`);
+        console.log(`  (Use --dry-run to preview.)`);
+      }
+    }
+  }
+
+  if (results.length === 0) {
+    console.log('[xera:doctor] ok');
+    return 0;
+  }
+  for (const r of results) console.error(`[xera:doctor] ${r.message}`);
+  return 1;
+}

package/src/bin-internal/eval-deterministic.ts

@@ -0,0 +1,149 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { validateGherkin } from '@xera-ai/web';
+import { resolveEvalPaths } from '../eval/paths';
+import {
+  type DeterministicEntry,
+  type DeterministicScores,
+  DeterministicScoresSchema,
+  ManifestSchema,
+} from '../eval/types';
+
+export interface EvalDeterministicOpts {
+  cwd?: string;
+}
+
+interface ClassifierScenario {
+  name: string;
+  class: string;
+}
+
+function checkFeatureFromStory(actualFeaturePath: string): {
+  passed: boolean;
+  checks: string[];
+  error?: string;
+} {
+  if (!existsSync(actualFeaturePath)) {
+    return { passed: false, checks: ['validate-feature'], error: 'actual missing: test.feature' };
+  }
+  try {
+    const r = validateGherkin(readFileSync(actualFeaturePath, 'utf8'));
+    if (r.ok) return { passed: true, checks: ['validate-feature'] };
+    return {
+      passed: false,
+      checks: ['validate-feature'],
+      error: r.errors.map((e) => `line ${e.line}: ${e.message}`).join('; '),
+    };
+  } catch (err) {
+    return { passed: false, checks: ['validate-feature'], error: (err as Error).message };
+  }
+}
+
+function checkScriptFromFeature(actualTicketDir: string): {
+  passed: boolean;
+  checks: string[];
+  error?: string;
+} {
+  // v0.2 deviation: file-presence only. Full typecheck/lint hookup is deferred to v0.2.1
+  // because v0.1's lintTicket/typecheckTicket resolve paths from .xera/<TICKET>/ (consumer
+  // project layout), not .xera/eval/<run-id>/actual/<ticket>/. The judge dimensions
+  // "Requirements satisfied", "Wait strategy", "No dead code" cover the lint surface.
+  const specPath = join(actualTicketDir, 'spec.ts');
+  if (!existsSync(specPath)) {
+    return { passed: false, checks: ['file-presence'], error: 'actual missing: spec.ts' };
+  }
+  return { passed: true, checks: ['file-presence'] };
+}
+
+function checkDiagnoseFailure(
+  inputsTicketDir: string,
+  actualTicketDir: string,
+): { passed: boolean; checks: string[]; error?: string } {
+  const inputPath = join(inputsTicketDir, 'classifier-input.json');
+  const actualPath = join(actualTicketDir, 'classification.json');
+  if (!existsSync(actualPath)) {
+    return {
+      passed: false,
+      checks: ['bucket-match'],
+      error: 'actual missing: classification.json',
+    };
+  }
+  if (!existsSync(inputPath)) {
+    return {
+      passed: false,
+      checks: ['bucket-match'],
+      error: 'inputs missing: classifier-input.json',
+    };
+  }
+  const golden = JSON.parse(readFileSync(inputPath, 'utf8'));
+  const actual = JSON.parse(readFileSync(actualPath, 'utf8'));
+  const goldScens: ClassifierScenario[] = golden.scenarios ?? [];
+  const actScens: ClassifierScenario[] = actual.scenarios ?? [];
+  const mismatches: string[] = [];
+  for (const g of goldScens) {
+    const a = actScens.find((s) => s.name === g.name);
+    if (!a) {
+      mismatches.push(`missing scenario "${g.name}"`);
+      continue;
+    }
+    if (a.class !== g.class)
+      mismatches.push(`scenario "${g.name}": expected class ${g.class}, got ${a.class}`);
+  }
+  if (mismatches.length > 0) {
+    return {
+      passed: false,
+      checks: ['bucket-match'],
+      error: `bucket mismatch — ${mismatches.join('; ')}`,
+    };
+  }
+  return { passed: true, checks: ['bucket-match'] };
+}
+
+export async function evalDeterministicCmd(
+  argv: string[],
+  opts: EvalDeterministicOpts = {},
+): Promise<number> {
+  const cwd = opts.cwd ?? process.cwd();
+  const runId = argv[0];
+  if (!runId) {
+    console.error('[xera:eval-deterministic] usage: eval-deterministic <run-id>');
+    return 1;
+  }
+  const paths = resolveEvalPaths(cwd, runId);
+  if (!existsSync(paths.manifest)) {
+    console.error(`[xera:eval-deterministic] missing manifest.json at ${paths.manifest}`);
+    return 1;
+  }
+  const manifest = ManifestSchema.parse(JSON.parse(readFileSync(paths.manifest, 'utf8')));
+
+  const entries: DeterministicEntry[] = [];
+  for (const [ticket, ticketStages] of Object.entries(manifest.ticket_stages)) {
+    for (const stage of ticketStages) {
+      const inputsDir = paths.ticketInputsDir(ticket);
+      const actualDir = paths.ticketActualDir(ticket);
+      let result: { passed: boolean; checks: string[]; error?: string };
+      if (stage === 'feature-from-story') {
+        result = checkFeatureFromStory(join(actualDir, 'test.feature'));
+      } else if (stage === 'script-from-feature') {
+        result = checkScriptFromFeature(actualDir);
+      } else {
+        result = checkDiagnoseFailure(inputsDir, actualDir);
+      }
+
+      const entry: DeterministicEntry = {
+        ticket,
+        stage,
+        passed: result.passed,
+        checks: result.checks,
+      };
+      if (result.error !== undefined) entry.error = result.error;
+      entries.push(entry);
+    }
+  }
+
+  const scores: DeterministicScores = { run_id: runId, entries };
+  DeterministicScoresSchema.parse(scores);
+  writeFileSync(paths.deterministicScores, JSON.stringify(scores, null, 2));
+  console.log(`[xera:eval-deterministic] wrote ${entries.length} entries`);
+  return 0;
+}

package/src/bin-internal/eval-prepare.ts

@@ -0,0 +1,214 @@
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { resolveEvalPaths } from '../eval/paths';
+import { generateRunId } from '../eval/run-id';
+import { type Manifest, ManifestSchema, STAGES, type Stage } from '../eval/types';
+import { acquireLock } from '../lock/file-lock';
+
+export interface EvalPrepareOpts {
+  cwd?: string;
+  now?: () => Date;
+  getGitSha?: () => string | null;
+}
+
+interface ParsedFlags {
+  force: boolean;
+  only_prompt: Stage | null;
+  only_ticket: string | null;
+}
+
+function parseFlags(argv: string[]): ParsedFlags | { error: string } {
+  const flags: ParsedFlags = { force: false, only_prompt: null, only_ticket: null };
+  for (const arg of argv) {
+    if (arg === '--force') flags.force = true;
+    else if (arg.startsWith('--prompt=')) {
+      const v = arg.slice('--prompt='.length);
+      if (!STAGES.includes(v as Stage)) {
+        return { error: `Unknown stage: ${v}. Valid: ${STAGES.join(', ')}.` };
+      }
+      flags.only_prompt = v as Stage;
+    } else if (arg.startsWith('--ticket=')) {
+      flags.only_ticket = arg.slice('--ticket='.length);
+    } else {
+      return { error: `Unknown argument: ${arg}` };
+    }
+  }
+  return flags;
+}
+
+function readPromptVersion(repoRoot: string, name: string): string {
+  const path = join(repoRoot, 'packages/prompts', `${name}.md`);
+  if (!existsSync(path)) return '0.0.0';
+  const text = readFileSync(path, 'utf8');
+  const m = /^version:\s*(\S+)\s*$/m.exec(text);
+  return m?.[1] ?? '0.0.0';
+}
+
+function discoverEvalTickets(repoRoot: string): { id: string; dir: string; stages: Stage[] }[] {
+  const root = join(repoRoot, 'fixtures/golden-eval');
+  if (!existsSync(root)) return [];
+  const out: { id: string; dir: string; stages: Stage[] }[] = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name === 'README.md' || entry.name.startsWith('.')) continue;
+    const dir = join(root, entry.name);
+    const metaPath = join(dir, 'meta.json');
+    if (!existsSync(metaPath)) continue;
+    const meta = JSON.parse(readFileSync(metaPath, 'utf8')) as { id: string; stages: Stage[] };
+    out.push({ id: meta.id, dir, stages: meta.stages });
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+function discoverClassifierTickets(repoRoot: string): { id: string; path: string }[] {
+  const root = join(repoRoot, 'fixtures/golden-tickets');
+  if (!existsSync(root)) return [];
+  const out: { id: string; path: string }[] = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+    const path = join(root, entry.name);
+    const data = JSON.parse(readFileSync(path, 'utf8')) as { ticket?: string };
+    if (typeof data.ticket === 'string') out.push({ id: data.ticket, path });
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export async function evalPrepareCmd(argv: string[], opts: EvalPrepareOpts = {}): Promise<number> {
+  const repoRoot = opts.cwd ?? process.cwd();
+
+  const flags = parseFlags(argv);
+  if ('error' in flags) {
+    console.error(`[xera:eval-prepare] ${flags.error}`);
+    return 1;
+  }
+
+  const evalTickets = discoverEvalTickets(repoRoot);
+  const classifierTickets = discoverClassifierTickets(repoRoot);
+
+  // Determine which stages to run.
+  const stages: Stage[] = flags.only_prompt ? [flags.only_prompt] : [...STAGES];
+
+  // Determine which tickets are relevant.
+  const wantsEval = stages.some((s) => s !== 'diagnose-failure');
+  const wantsClassifier = stages.includes('diagnose-failure');
+
+  let selectedTickets: string[] = [];
+  if (wantsEval) selectedTickets.push(...evalTickets.map((t) => t.id));
+  if (wantsClassifier) selectedTickets.push(...classifierTickets.map((t) => t.id));
+  selectedTickets = [...new Set(selectedTickets)].sort();
+
+  if (flags.only_ticket) {
+    if (!selectedTickets.includes(flags.only_ticket)) {
+      console.error(`[xera:eval-prepare] No golden fixture for ${flags.only_ticket}`);
+      return 1;
+    }
+    selectedTickets = [flags.only_ticket];
+  }
+
+  if (selectedTickets.length === 0) {
+    console.error('[xera:eval-prepare] No tickets selected (after filters).');
+    return 1;
+  }
+
+  // Compute per-ticket stages by intersecting the ticket's declared stages with the
+  // global stages array, then filter out tickets with an empty intersection.
+  const ticket_stages: Record<string, Stage[]> = {};
+  for (const ticket of selectedTickets) {
+    const evalT = evalTickets.find((t) => t.id === ticket);
+    let ticketDeclared: Stage[];
+    if (evalT) {
+      ticketDeclared = evalT.stages;
+    } else {
+      // Classifier/GOLD ticket — always diagnose-failure.
+      ticketDeclared = ['diagnose-failure'];
+    }
+    const intersection = ticketDeclared.filter((s) => stages.includes(s));
+    if (intersection.length > 0) {
+      ticket_stages[ticket] = intersection;
+    }
+  }
+
+  // Filter selectedTickets to only those with applicable stages.
+  selectedTickets = selectedTickets.filter((t) => ticket_stages[t] !== undefined);
+
+  if (selectedTickets.length === 0) {
+    console.error('[xera:eval-prepare] No tickets applicable to requested stages.');
+    return 1;
+  }
+
+  const runId = generateRunId({
+    ...(opts.now ? { now: opts.now } : {}),
+    ...(opts.getGitSha ? { getGitSha: opts.getGitSha } : {}),
+  });
+  const paths = resolveEvalPaths(repoRoot, runId);
+
+  if (existsSync(paths.root) && !flags.force) {
+    console.error(
+      `[xera:eval-prepare] run dir already exists: ${paths.root}. Pass --force to re-run.`,
+    );
+    return 1;
+  }
+  mkdirSync(paths.inputsDir, { recursive: true });
+  mkdirSync(paths.actualDir, { recursive: true });
+
+  // Copy inputs.
+  for (const ticket of selectedTickets) {
+    const ticketInputs = paths.ticketInputsDir(ticket);
+    mkdirSync(ticketInputs, { recursive: true });
+    const evalT = evalTickets.find((t) => t.id === ticket);
+    const classT = classifierTickets.find((t) => t.id === ticket);
+    if (evalT) {
+      copyFileSync(join(evalT.dir, 'story.md'), join(ticketInputs, 'story.md'));
+      const featurePath = join(evalT.dir, 'golden/test.feature');
+      if (existsSync(featurePath)) copyFileSync(featurePath, join(ticketInputs, 'test.feature'));
+    }
+    if (classT) {
+      copyFileSync(classT.path, join(ticketInputs, 'classifier-input.json'));
+    }
+  }
+
+  // Build manifest.
+  const now = (opts.now ?? (() => new Date()))();
+  const manifest: Manifest = {
+    run_id: runId,
+    started_at: now.toISOString(),
+    git_sha: runId.split('-')[2] ?? 'nogit',
+    tickets: selectedTickets,
+    stages,
+    ticket_stages,
+    prompt_versions: {
+      'feature-from-story': readPromptVersion(repoRoot, 'feature-from-story'),
+      'script-from-feature': readPromptVersion(repoRoot, 'script-from-feature'),
+      'diagnose-failure': readPromptVersion(repoRoot, 'diagnose-failure'),
+      'eval-rubric': readPromptVersion(repoRoot, 'eval-rubric'),
+    },
+    flags: {
+      force: flags.force,
+      only_prompt: flags.only_prompt,
+      only_ticket: flags.only_ticket,
+      judge_only: false,
+    },
+  };
+
+  // Validate before writing.
+  ManifestSchema.parse(manifest);
+  writeFileSync(paths.manifest, JSON.stringify(manifest, null, 2));
+
+  if (!acquireLock(paths.lock, runId)) {
+    console.error(`[xera:eval-prepare] failed to acquire lock at ${paths.lock}`);
+    return 4;
+  }
+
+  console.log(
+    `[xera:eval-prepare] prepared ${selectedTickets.length} ticket(s) for stages: ${stages.join(', ')}`,
+  );
+  console.log(`RUN_ID=${runId}`);
+  return 0;
+}